trimesh.points.project_to_plane does not project correctly in most cases.

[zecastelo]

Greetings, I have been working with trimesh a lot recently and noticed the function trimesh.points.project_to_plane does not do what I expected it would from my interpretation of the (short) documentation on it. Then by reading the implementation, as well as how it is used in the rest of the codebase, it seems either its name is unfortunate or the implementation is simply wrong and this has never been brought up.

Just so its clear, I assume the projection of a point in a plane should be the intersection of the line that crosses that point and has the orientation matching the normal of the plane.

With the above in mind, consider the following piece of code, as well its output, for an example on why I think this function is currently not working as intended:

import trimesh
import numpy as np

points = [
	[1, 0, 0],
	[0, 1, 0],
	[0, 0, 1],
]

plane_normal = [0, 0, 1]
plane_origin = [0, 0, 100]

current = trimesh.points.project_to_plane(points, plane_normal, plane_origin, return_planar=False)
correct = trimesh.intersections.plane_lines(plane_origin, plane_normal, np.stack([points, points + np.asarray(plane_normal)]), line_segments=False)[0]

print(f"Project the following points:\n{points}")
print(f"On plane with normal={plane_normal} and origin={plane_origin}")
print(f"Current project_to_plane implementation\n{current}")
print(f'"Correct" implementation\n{correct}')

And the respective output:

Project the following points:
[[1, 0, 0], [0, 1, 0], [0, 0, 1]]
On plane with normal=[0, 0, 1] and origin=[0, 0, 100]
Current project_to_plane implementation
[[   1.    0. -100.]
 [   0.    1. -100.]
 [   0.    0.  -99.]]
"Correct" implementation
[[  1.   0. 100.]
 [  0.   1. 100.]
 [  0.   0. 100.]]

Am I interpreting the purpose of this function wrong? If so, what is the use case?

[mikedh]

Ah yeah it looks like it is actually just applying the plane transform to the points. A better name might be transform_to_plane. If it returns them as 2D points it's "projecting" them but in 3D it's really just rotating them.