drawEdge

DRAWEDGE Draw an edge defined by its two extremities.
   
   drawEdge(x1, y1, x2, y2);
   draw an edge between the points (x1 y1) and  (x2 y2).

   drawEdge([x1 y1 x2 y2]) ;
   drawEdge([x1 y1], [x2 y2]);
   specify data either as bundled edge, or as 2 points

   The function supports 3D edges:
   drawEdge([x1 y1 z1 x2 y2 z2]);
   drawEdge([x1 y1 z1], [x2 y2 z2]);
   drawEdge(x1, y1, z1, x2, y2, z2);

   Arguments can be single values or array of size [N*1]. In this case,
   the function draws multiple edges.

   H = drawEdge(..., OPT), with OPT being a set of pairwise options, can
   specify color, line width and so on...

   H = drawEdge(...) return handle(s) to created edges(s)

   See also
   edges2d, drawCenteredEdge, drawLine

0001 function varargout = drawEdge(varargin)
0002 %DRAWEDGE Draw an edge defined by its two extremities.
0003 %
0004 %   drawEdge(x1, y1, x2, y2);
0005 %   draw an edge between the points (x1 y1) and  (x2 y2).
0006 %
0007 %   drawEdge([x1 y1 x2 y2]) ;
0008 %   drawEdge([x1 y1], [x2 y2]);
0009 %   specify data either as bundled edge, or as 2 points
0010 %
0011 %   The function supports 3D edges:
0012 %   drawEdge([x1 y1 z1 x2 y2 z2]);
0013 %   drawEdge([x1 y1 z1], [x2 y2 z2]);
0014 %   drawEdge(x1, y1, z1, x2, y2, z2);
0015 %
0016 %   Arguments can be single values or array of size [N*1]. In this case,
0017 %   the function draws multiple edges.
0018 %
0019 %   H = drawEdge(..., OPT), with OPT being a set of pairwise options, can
0020 %   specify color, line width and so on...
0021 %
0022 %   H = drawEdge(...) return handle(s) to created edges(s)
0023 %
0024 %   See also
0025 %   edges2d, drawCenteredEdge, drawLine
0026 %
0027 
0028 % ------
0029 % Author: David Legland
0030 % E-mail: david.legland@inrae.fr
0031 % Created: 2003-10-31
0032 % Copyright 2003-2024 INRA - TPV URPOI - BIA IMASTE
0033 
0034 % separate edge and optional arguments
0035 [ax, edge, options] = parseInputArguments(varargin{:});
0036 
0037 % save hold state
0038 holdState = ishold(ax);
0039 hold(ax, 'on');
0040 
0041 % draw the edges
0042 if size(edge, 2) == 4
0043     h = drawEdge_2d(ax, edge, options);
0044 else
0045     h = drawEdge_3d(ax, edge, options);
0046 end
0047 
0048 % restore hold state
0049 if ~holdState
0050     hold(ax, 'off');
0051 end
0052 
0053 % eventually return handle to created edges
0054 if nargout > 0
0055     varargout = {h};
0056 end
0057 
0058 
0059 function h = drawEdge_2d(ax, edge, options)
0060 
0061 h = -1 * ones(size(edge, 1), 1);
0062 
0063 for i = 1:size(edge, 1)
0064     if isnan(edge(i,1))
0065         continue;
0066     end
0067     
0068     h(i) = plot(ax, edge(i, [1 3]), edge(i, [2 4]), options{:});
0069 end
0070 
0071 
0072 function h = drawEdge_3d(ax, edge, options)
0073 
0074 h = -1 * ones(size(edge, 1), 1);
0075 
0076 for i = 1:size(edge, 1)
0077     if isnan(edge(i,1))
0078         continue;
0079     end
0080     
0081     h(i) = plot3(ax, edge(i, [1 4]), edge(i, [2 5]), edge(i, [3 6]), options{:});
0082 end
0083 
0084     
0085 function [ax, edge, options] = parseInputArguments(varargin)
0086 
0087 % extract handle of axis to draw on
0088 [ax, varargin] = parseAxisHandle(varargin{:});
0089 
0090 % find the number of arguments defining edges
0091 nbVal = 0;
0092 for i = 1:length(varargin)
0093     if isnumeric(varargin{i})
0094         nbVal = nbVal+1;
0095     else
0096         % stop at the first non-numeric value
0097         break;
0098     end
0099 end
0100 
0101 % extract drawing options
0102 options = varargin(nbVal+1:end);
0103 
0104 % ensure drawing options have correct format
0105 if isscalar(options)
0106     options = [{'color'}, options];
0107 end
0108 
0109 % extract edges characteristics
0110 switch nbVal
0111     case 1
0112         % all parameters in a single array
0113         edge = varargin{1};
0114         
0115     case 2
0116         % parameters are two points, or two arrays of points, of size N*2.
0117         p1 = varargin{1};
0118         p2 = varargin{2};
0119         edge = [p1 p2];
0120         
0121     case 4
0122         % parameters are 4 parameters of the edge : x1 y1 x2 and y2
0123         edge = [varargin{1} varargin{2} varargin{3} varargin{4}];
0124         
0125     case 6
0126         % parameters are 6 parameters of the edge : x1 y1 z1 x2 y2 and z2
0127         edge = [varargin{1} varargin{2} varargin{3} varargin{4} varargin{5} varargin{6}];
0128         
0129     otherwise
0130         error('drawEdge:WrongNumberOfParameters', 'Wrong number of parameters');
0131 end