point2trimesh( ) — Distance Between Point and Triangulated Surface

point2trimesh - Distance between a point and a triangulated surface in 3D

The shortest line connecting a point and a triangulation in 3D is
computed. The nearest point on the surface as well as the distance
is returned. The distance is signed according to face normals to
identify on which side of the surface the query point resides.
The implementation is optimized for speed, and depending on your
application you can use linear or parallel computation.

Point insertion functionality
(this feature is experimental and not optimized for speed):
If the function is called with more than two output arguments,
the surface points are included into the given triangulation
and Delaunay conditions are restored locally. If triangles with small
angles occur, additional vertices are inserted to eliminate them
if possible.

Algorithm: From every query point,
- the nearest vertex
- the nearest point on the edges and
- the nearest point on the triangle's surfaces
is calculated and the minimum distance out of these three is returned.

------------------------------------------------------

[ distances, surface_points, normal_vectors,
faces2, vertices2, corresponding_vertices_ID, new_faces_ID ]
= point2trimesh( varargin )

Inputs:
Pairs of parameter names and corresponding values.
Structure arrays are expanded into separate inputs,
where each field name corresponds to an input parameter name.
Parameters:
- 'Faces' (#faces x 3)
Triangulation connectivity list. Each row defines a face, elements are vertex IDs.
- 'Vertices' (#vertices x 3)
Point matrix. Columns are x,y,z coordinates, row numbers are vertex IDs.
- 'QueryPoints' (#qPoints x 3)
Columns are x,y,z coordinates; each row defines a query point. Can be empty.
- 'UseSubSurface' (1 x 1)
Logical. If true (default), the distance to edges and surfaces is only calculated
for faces that are connected to the vertex nearest to the query point.
This speeds up the calculation but if the distance between two opposite parts
of the surface is less than the spacing of the vertices, wrong results are produced.
In the vectorized algorithm, 'SubSurface' is always false.
- 'MaxDistance' (1 x 1)
If the distance between a surface_point and its nearest vertex is within this range,
no new vertex is inserted into the mesh. This helps avoiding
triangles with small angles. (default: 1/10 the smallest inradius)

Outputs:
- distances (#qPoints x 1)
Vector with the point-surface distances; sign depends on normal vectors.
- surface_points (#qPoints x 3)
Matrix with the corresponding nearest points on the surface.
- normal_vectors (#qPoints x 3)
Normal vectors of the surface_points
- faces2 (#faces2 x 3)
Connectivity matrix of the triangulation including the surface_points as dedicated vertices
- vertices2 (#vertices2 x 3)
Point/Vertex matrix of the triangulation including the surface_points as dedicated vertices
- corresponding_vertices_ID (#qPoints x 1)
Vector with the IDs of the vertices corresponding to the query points
- new_faces_ID
Vector with the IDs of the new or modified faces (to give them a different color, for example)

Usage example:
FV.faces = [5 3 1; 3 2 1; 3 4 2; 4 6 2];
FV.vertices = [2.5 8.0 1; 6.5 8.0 2; 2.5 5.0 1; 6.5 5.0 0; 1.0 6.5 1; 8.0 6.5 1.5];
points = [2 4 2; 4 6 2; 5 6 2];
[distances,surface_points] = point2trimesh(FV, 'QueryPoints', points);
patch(FV,'FaceAlpha',.5); xlabel('x'); ylabel('y'); zlabel('z'); axis equal; hold on
plot3M = @(XYZ,varargin) plot3(XYZ(:,1),XYZ(:,2),XYZ(:,3),varargin{:});
plot3M(points,'*r')
plot3M(surface_points,'*k')
plot3M(reshape([shiftdim(points,-1);shiftdim(surface_points,-1);shiftdim(points,-1)*NaN],[],3),'k')