projPointOnPolyline

PROJPOINTONPOLYLINE Compute position of a point projected on a polyline.

   POS = projPointOnPolyline(POINT, POLYLINE)
   Compute the position of the orthogonal projection of a point on a
   polyline.
   POINT is a 1-by-2 row vector containing point coordinates
   POLYLINE is a N-by-2 array containing coordinates of polyline vertices
   POS is the position of the point on the polyline, between 0 and the
   number of vertices of the polyline. POS can be a non-integer value, in
   this case, the integer part corresponds to the polyline edge index
   (between 0 and Nv-1), and the floating-point part corresponds to the
   relative position on i-th edge (between 0 and 1, 0: edge start, 1: edge
   end).

   When POINT is an array of points, returns a column vector with as many
   rows as the number of points.

   POS = projPointOnPolyline(POINT, POLYLINE, CLOSED)
   Specifies if the polyline is closed or not. CLOSED can be one of:
     'closed' -> the polyline is closed
     'open' -> the polyline is open
     a column vector of logical with the same number of elements as the
       number of points -> specify individually if each polyline is
       closed (true=closed).

   [POS, DIST] = projPointOnPolyline(...)
   Also returns the distance between POINT and POLYLINE.

   Example
     poly = [10 10; 20 10;20 20;10 20];
     projPointOnPolyline([15 0], poly)
     ans =
         0.5000
     projPointOnPolyline([0 16], poly)
     ans =
         3.0000

   See also
   points2d, polygons2d, polylinePoint, projPointOnPolygon
   distancePointPolyline

0001 function varargout = projPointOnPolyline(point, poly, varargin)
0002 %PROJPOINTONPOLYLINE Compute position of a point projected on a polyline.
0003 %
0004 %   POS = projPointOnPolyline(POINT, POLYLINE)
0005 %   Compute the position of the orthogonal projection of a point on a
0006 %   polyline.
0007 %   POINT is a 1-by-2 row vector containing point coordinates
0008 %   POLYLINE is a N-by-2 array containing coordinates of polyline vertices
0009 %   POS is the position of the point on the polyline, between 0 and the
0010 %   number of vertices of the polyline. POS can be a non-integer value, in
0011 %   this case, the integer part corresponds to the polyline edge index
0012 %   (between 0 and Nv-1), and the floating-point part corresponds to the
0013 %   relative position on i-th edge (between 0 and 1, 0: edge start, 1: edge
0014 %   end).
0015 %
0016 %   When POINT is an array of points, returns a column vector with as many
0017 %   rows as the number of points.
0018 %
0019 %   POS = projPointOnPolyline(POINT, POLYLINE, CLOSED)
0020 %   Specifies if the polyline is closed or not. CLOSED can be one of:
0021 %     'closed' -> the polyline is closed
0022 %     'open' -> the polyline is open
0023 %     a column vector of logical with the same number of elements as the
0024 %       number of points -> specify individually if each polyline is
0025 %       closed (true=closed).
0026 %
0027 %   [POS, DIST] = projPointOnPolyline(...)
0028 %   Also returns the distance between POINT and POLYLINE.
0029 %
0030 %   Example
0031 %     poly = [10 10; 20 10;20 20;10 20];
0032 %     projPointOnPolyline([15 0], poly)
0033 %     ans =
0034 %         0.5000
0035 %     projPointOnPolyline([0 16], poly)
0036 %     ans =
0037 %         3.0000
0038 %
0039 %   See also
0040 %   points2d, polygons2d, polylinePoint, projPointOnPolygon
0041 %   distancePointPolyline
0042 %
0043 
0044 % ------
0045 % Author: David Legland
0046 % e-mail: david.legland@nantes.inra.fr
0047 % Created: 2009-04-30,    using Matlab 7.7.0.471 (R2008b)
0048 % Copyright 2009 INRA - Cepia Software Platform.
0049 
0050 % check if input polyline is closed or not
0051 closed = false;
0052 if ~isempty(varargin)
0053     var = varargin{1};
0054     if strcmp('closed', var)
0055         closed = true;
0056     elseif strcmp('open', var)
0057         closed = false;
0058     elseif islogical(var)
0059         closed = var;
0060     end
0061 end
0062 
0063 % closes the polyline if necessary
0064 if closed
0065     poly = [poly ; poly(1,:)];
0066 end
0067 
0068 % number of points
0069 Np = size(point, 1);
0070 
0071 % allocate memory results
0072 pos     = zeros(Np, 1);
0073 minDist = inf*ones(Np, 1);
0074 
0075 % iterate on points
0076 for p = 1:Np
0077     % build set of edges
0078     edges = [poly(1:end-1, :) poly(2:end, :)];
0079     
0080     % compute distance between current point and all edges
0081     [dist, edgePos] = distancePointEdge(point(p, :), edges);
0082     
0083     % update distance and position if necessary
0084     [minDist(p), edgeIndex] = min(dist);
0085     pos(p) = edgeIndex - 1 + edgePos(edgeIndex);   
0086 end
0087 
0088 % process output arguments
0089 if nargout <= 1
0090     varargout{1} = pos;
0091 elseif nargout == 2
0092     varargout{1} = pos;
0093     varargout{2} = minDist;
0094 end
0095