drawLine3d

DRAWLINE3D Draw a 3D line clipped by the current axes.

   drawLine3d(LINE) draws the line LINE on the current axis, by clipping 
   with the current axis.

   drawLine3d(LINE, PARAM, VALUE) accepts parameter/value pairs, like 
   for plot function. Color of the line can also be given as a single 
   parameter.

   drawLine3d(AX,...) plots into AX instead of GCA.
   
   H = drawLine3d(...) returns a handle to the created line object. 
   If the line is not clipped by the axis, function returns -1.

   Example
     % draw a sphere together with the three main axes
     figure; hold on;
     drawSphere([40 30 20 30]);
     view(3); axis equal; axis([-20 80 -20 80 -20 80])
     drawLine3d([0 0 0   1 0 0], 'k');
     drawLine3d([0 0 0   0 1 0], 'k');
     drawLine3d([0 0 0   0 0 1], 'k');
     light;


   See also:
     lines3d, createLine3d, clipLine3d, drawRay3d, drawEdge3d

0001 function h = drawLine3d(lin, varargin)
0002 %DRAWLINE3D Draw a 3D line clipped by the current axes.
0003 %
0004 %   drawLine3d(LINE) draws the line LINE on the current axis, by clipping
0005 %   with the current axis.
0006 %
0007 %   drawLine3d(LINE, PARAM, VALUE) accepts parameter/value pairs, like
0008 %   for plot function. Color of the line can also be given as a single
0009 %   parameter.
0010 %
0011 %   drawLine3d(AX,...) plots into AX instead of GCA.
0012 %
0013 %   H = drawLine3d(...) returns a handle to the created line object.
0014 %   If the line is not clipped by the axis, function returns -1.
0015 %
0016 %   Example
0017 %     % draw a sphere together with the three main axes
0018 %     figure; hold on;
0019 %     drawSphere([40 30 20 30]);
0020 %     view(3); axis equal; axis([-20 80 -20 80 -20 80])
0021 %     drawLine3d([0 0 0   1 0 0], 'k');
0022 %     drawLine3d([0 0 0   0 1 0], 'k');
0023 %     drawLine3d([0 0 0   0 0 1], 'k');
0024 %     light;
0025 %
0026 %
0027 %   See also:
0028 %     lines3d, createLine3d, clipLine3d, drawRay3d, drawEdge3d
0029 %
0030 
0031 % ---------
0032 % author : David Legland
0033 % INRA - TPV URPOI - BIA IMASTE
0034 % created the 17/02/2005.
0035 
0036 
0037 % Parse and check inputs
0038 isLine3d = @(x) validateattributes(x,{'numeric'},...
0039     {'nonempty','nonnan','real','finite','size',[nan,6]});
0040 defOpts.Color = 'b';
0041 [hAx, lin, varargin] = ...
0042     parseDrawInput(lin, isLine3d, 'line', defOpts, varargin{:});
0043 
0044 % extract limits of the bounding box
0045 box = [get(hAx, 'xlim') get(hAx, 'ylim') get(hAx, 'zlim')];
0046 
0047 % clip the line with the limits of the current axis
0048 edge = clipLine3d(lin, box);
0049 
0050 % draw the clipped line
0051 if sum(isnan(edge)) == 0
0052     hh = drawEdge3d(hAx, edge);
0053     if ~isempty(varargin)
0054         set(hh, varargin{:});
0055     end
0056 else
0057     hh = [];
0058 end
0059 
0060 % process output
0061 if nargout > 0
0062     h = hh;
0063 end