Update Geometry3D.get_triangle_barycentric_coords() docs

[PrecisionRender]

Resolves comment #71233 (comment)

Updates the Geometry3D.get_triangle_barycentric_coords() documentation to explain what happens when the parameters are invalid.

[kleonc]

Added some suggestions, feedback welcomed as always. 🙂

[kleonc]

Coplanar / not coplanar is kinda fluid using floats. This should clarify this a little:

Suggested change

[param a], [param b] and [param c] must form a valid triangle and [param point] must be coplanar with the [param a][param b][param c] triangle. Returns an empty [Vector3] if [param a][param b][param c] does not form a valid triangle. Returns invalid weights if [param point] is not coplanar with the [param a][param b][param c] triangle.

[param a], [param b] and [param c] must form a valid triangle and [param point] must be coplanar with the [param a][param b][param c] triangle. Returns an empty [Vector3] if [param a][param b][param c] does not form a valid triangle. Returns invalid weights if [param point] is not coplanar with the [param a][param b][param c] triangle. However, the closer [param point] is to the triangle's plane, the smaller the error is. Hence floating-point precision errors and alike should not affect the correctness of the result much.

[PrecisionRender]

Will add.

[kleonc]

Moved the link into the description.

Suggested change

[url=https://en.wikipedia.org/wiki/Barycentric_coordinate_system]Here is a more detailed explanation of barycentric coordinates.[/url]

[PrecisionRender]

I'm fairly certain the way it is now is more consistent with the rest of the API docs.

[kleonc]

I think this equation should be mentioned somewhere. Also reworded this a little to move the wiki link in here (and link directly to the section relevant for triangles):

Suggested change

Returns a [Vector3] containing weights based on how close a 3D position ([param point]) is to a triangle's different vertices ([param a], [param b] and [param c]). This is useful for interpolating between the data of different vertices in a triangle. One example use case is using this to smoothly rotate over a mesh instead of relying solely on face normals.

Returns a [Vector3] containing a 3D [param point]'s [url=https://en.wikipedia.org/wiki/Barycentric_coordinate_system#Barycentric_coordinates_on_triangles]barycentric coordinates within a triangle[/url] formed by [param a], [param b], [param c] vertices (such that [code]result.x * a + result.y * b + result.z * c[/code] approximately equals [param point]). This is useful for interpolating between the data of different vertices in a triangle. One example use case is using this to smoothly rotate over a mesh instead of relying solely on face normals.

Edit: Oh, now I see it was intentionally written like that (#71233 (comment)). Oh, well. 🙃

[PrecisionRender]

I'll incorporate something like this.

[kleonc]

WDYT about something like:

Suggested change

	var point = Vector3(1.5, 1, 0.5)
	var w = get_triangle_barycentric_coords(point, a, b, c)
	# w is Vector3(0, 0.5, 0.5)
	# w contains valid weights
	var point = Vector3(1.5, 1, 0.5) # Coplanar with abc triangle (valid input)
	var w = get_triangle_barycentric_coords(point, a, b, c) # w is Vector3(0, 0.5, 0.5)
	point.is_equal_approx(w.x * a + w.y * b + w.z * c) # True, w contains valid weights

?
(if it's good then applicable to the other examples)

[PrecisionRender]

Thanks for your suggestions!

When I have time, I'll add them.

[PrecisionRender]

Yes, I like this.