isPointOnEdge3d

 Test if a 3D point belongs to an edge.

   Usage
   B = isPointOnEdge3d(POINT, EDGE)
   B = isPointOnEdge3d(POINT, EDGE, TOL)

   Description
   B = isPointOnEdge3d(POINT, EDGE)
   with POINT being [xp yp zp], and EDGE being [x1 y1 z1  x2 y2 z2],
   returns TRUE if the point is located on the edge, and FALSE otherwise.

   B = isPointOnEdge3d(POINT, EDGE, TOL)
   Specify an optilonal tolerance value TOL. The tolerance is given as a
   fraction of the norm of the edge direction vector. Default is 1e-14. 

   B = isPointOnEdge3d(POINTARRAY, EDGE)
   B = isPointOnEdge3d(POINT, EDGEARRAY)
   When one of the inputs has several rows, return the result of the test
   for each element of the array tested against the single parameter.

   B = isPointOnEdge3d(POINTARRAY, EDGEARRAY)
   When both POINTARRAY and EDGEARRAY have the same number of rows,
   returns a column vector with the same number of rows.
   When the number of rows are different and both greater than 1, returns
   a Np-by-Ne matrix of booleans, containing the result for each couple of
   point and edge.

   Examples
   % create a point array
   points = [10 10 20;15 10 20; 30 10 20];
   % create an edge array
   vertices = [10 10 20;20 10 20;20 20 20;10 20 20];
   edges = [vertices vertices([2:end 1], :)];

   % Test one point and one edge
   isPointOnEdge3d(points(1,:), edges(1,:))
   ans = 
       1
   isPointOnEdge3d(points(3,:), edges(1,:))
   ans = 
       0

   % Test one point and several edges
   isPointOnEdge3d(points(1,:), edges)'
   ans =
        1     0     0     1

   % Test several points and one edge
   isPointOnEdge3d(points, edges(1,:))'
   ans =
        1     1     0

   % Test N points and N edges
   isPointOnEdge3d(points, edges(1:3,:))'
   ans =
        1     0     0

   % Test NP points and NE edges
   isPointOnEdge3d(points, edges)
   ans =
        1     0     0     1
        1     0     0     0
        0     0     0     0


   See also
   edges3d, points3d, isPointOnLine3d

0001 function b = isPointOnEdge3d(point, edge, varargin)
0002 % Test if a 3D point belongs to an edge.
0003 %
0004 %   Usage
0005 %   B = isPointOnEdge3d(POINT, EDGE)
0006 %   B = isPointOnEdge3d(POINT, EDGE, TOL)
0007 %
0008 %   Description
0009 %   B = isPointOnEdge3d(POINT, EDGE)
0010 %   with POINT being [xp yp zp], and EDGE being [x1 y1 z1  x2 y2 z2],
0011 %   returns TRUE if the point is located on the edge, and FALSE otherwise.
0012 %
0013 %   B = isPointOnEdge3d(POINT, EDGE, TOL)
0014 %   Specify an optilonal tolerance value TOL. The tolerance is given as a
0015 %   fraction of the norm of the edge direction vector. Default is 1e-14.
0016 %
0017 %   B = isPointOnEdge3d(POINTARRAY, EDGE)
0018 %   B = isPointOnEdge3d(POINT, EDGEARRAY)
0019 %   When one of the inputs has several rows, return the result of the test
0020 %   for each element of the array tested against the single parameter.
0021 %
0022 %   B = isPointOnEdge3d(POINTARRAY, EDGEARRAY)
0023 %   When both POINTARRAY and EDGEARRAY have the same number of rows,
0024 %   returns a column vector with the same number of rows.
0025 %   When the number of rows are different and both greater than 1, returns
0026 %   a Np-by-Ne matrix of booleans, containing the result for each couple of
0027 %   point and edge.
0028 %
0029 %   Examples
0030 %   % create a point array
0031 %   points = [10 10 20;15 10 20; 30 10 20];
0032 %   % create an edge array
0033 %   vertices = [10 10 20;20 10 20;20 20 20;10 20 20];
0034 %   edges = [vertices vertices([2:end 1], :)];
0035 %
0036 %   % Test one point and one edge
0037 %   isPointOnEdge3d(points(1,:), edges(1,:))
0038 %   ans =
0039 %       1
0040 %   isPointOnEdge3d(points(3,:), edges(1,:))
0041 %   ans =
0042 %       0
0043 %
0044 %   % Test one point and several edges
0045 %   isPointOnEdge3d(points(1,:), edges)'
0046 %   ans =
0047 %        1     0     0     1
0048 %
0049 %   % Test several points and one edge
0050 %   isPointOnEdge3d(points, edges(1,:))'
0051 %   ans =
0052 %        1     1     0
0053 %
0054 %   % Test N points and N edges
0055 %   isPointOnEdge3d(points, edges(1:3,:))'
0056 %   ans =
0057 %        1     0     0
0058 %
0059 %   % Test NP points and NE edges
0060 %   isPointOnEdge3d(points, edges)
0061 %   ans =
0062 %        1     0     0     1
0063 %        1     0     0     0
0064 %        0     0     0     0
0065 %
0066 %
0067 %   See also
0068 %   edges3d, points3d, isPointOnLine3d
0069 %
0070 
0071 
0072 
0073 % extract computation tolerance
0074 tol = 1e-14;
0075 if ~isempty(varargin)
0076     tol = varargin{1};
0077 end
0078 
0079 % supporting line of the edge
0080 line = edgeToLine3d(edge);
0081 
0082 % check if point belong to supporting line
0083 onLine = isPointOnLine3d(point, line, tol);
0084 
0085 % check if position is within the [0 1] bounds
0086 pos = linePosition3d(point, line);
0087 withinBounds = pos > -tol & pos < 1+tol;
0088 
0089 b = onLine & withinBounds;