drawPlane3d

DRAWPLANE3D Draw a plane clipped by the current axes.

   drawPlane3d(PLANE) draws a plane of the format:
       [x0 y0 z0  dx1 dy1 dz1  dx2 dy2 dz2]

   drawPlane3d(..., 'PropertyName', PropertyValue,...)
   Sets the value of the specified patch property. Multiple property
   values can be set with a single statement. See the function "patch" for
   details. 

   drawPlane3d(AX,...) 
   plots into AX instead of GCA.

   H = drawPlane3d(...) 
   returns a handle H to the patch object.

   Example
     % Draw a plane, its main axes, and its normal vector
     p0 = [1 2 3];
     v1 = [1 0 1];
     v2 = [0 -1 1];
     plane = [p0 v1 v2];
     figure; axis([-10 10 -10 10 -10 10]); hold on; view(3);
     drawPlane3d(plane);
     drawLine3d([p0 v1]);
     drawLine3d([p0 v2]);
     set(gcf, 'renderer', 'zbuffer');
     vn = crossProduct3d(v1, v2);
     drawVector3d(p0, vn);

   See also
     planes3d, createPlane, clipPlane, patch

0001 function h = drawPlane3d(plane, varargin)
0002 %DRAWPLANE3D Draw a plane clipped by the current axes.
0003 %
0004 %   drawPlane3d(PLANE) draws a plane of the format:
0005 %       [x0 y0 z0  dx1 dy1 dz1  dx2 dy2 dz2]
0006 %
0007 %   drawPlane3d(..., 'PropertyName', PropertyValue,...)
0008 %   Sets the value of the specified patch property. Multiple property
0009 %   values can be set with a single statement. See the function "patch" for
0010 %   details.
0011 %
0012 %   drawPlane3d(AX,...)
0013 %   plots into AX instead of GCA.
0014 %
0015 %   H = drawPlane3d(...)
0016 %   returns a handle H to the patch object.
0017 %
0018 %   Example
0019 %     % Draw a plane, its main axes, and its normal vector
0020 %     p0 = [1 2 3];
0021 %     v1 = [1 0 1];
0022 %     v2 = [0 -1 1];
0023 %     plane = [p0 v1 v2];
0024 %     figure; axis([-10 10 -10 10 -10 10]); hold on; view(3);
0025 %     drawPlane3d(plane);
0026 %     drawLine3d([p0 v1]);
0027 %     drawLine3d([p0 v2]);
0028 %     set(gcf, 'renderer', 'zbuffer');
0029 %     vn = crossProduct3d(v1, v2);
0030 %     drawVector3d(p0, vn);
0031 %
0032 %   See also
0033 %     planes3d, createPlane, clipPlane, patch
0034 
0035 % ------
0036 % Author: David Legland
0037 % E-mail: david.legland@inrae.fr
0038 % Created: 2005-02-17
0039 % Copyright 2005-2024 INRA - TPV URPOI - BIA IMASTE
0040 
0041 % add support for drawing multiple planes at once
0042 if size(plane, 1) > 1
0043     nPlanes = size(plane, 1);
0044     hp = zeros(nPlanes, 1);
0045     for iPlane = 1:nPlanes
0046         hp(iPlane) = drawPlane3d(plane(iPlane, :), varargin{:});
0047     end
0048     
0049     if nargout > 0
0050         h = hp;
0051     end
0052     
0053     return;
0054 end
0055 
0056 % Parse and check inputs
0057 valFun = @(x) size(x,1)==1 && isPlane(x);
0058 defOpts.FaceColor = 'm';
0059 [hAx, plane, varargin] = ...
0060     parseDrawInput(plane, valFun, 'patch', defOpts, varargin{:});
0061 
0062 % extract axis bounds to crop plane
0063 lim = get(hAx, 'xlim');
0064 xmin = lim(1);
0065 xmax = lim(2);
0066 lim = get(hAx, 'ylim');
0067 ymin = lim(1);
0068 ymax = lim(2);
0069 lim = get(hAx, 'zlim');
0070 zmin = lim(1);
0071 zmax = lim(2);
0072 
0073 % allocate array of handles
0074 nPlanes = size(plane, 1);
0075 hp = gobjects(1, nPlanes);
0076 
0077 % save hold state
0078 holdState = ishold(hAx);
0079 hold(hAx, 'on');
0080 
0081 % iterate over planes
0082 for iPlane = 1:nPlanes
0083     % clip plane with current axis bounds
0084     poly = clipPlane(plane(iPlane,:), [xmin xmax ymin ymax zmin zmax]);
0085     
0086     % draw only non-empty intersections
0087     if ~isempty(poly)
0088         hp(iPlane) = patch( ...
0089             'XData', poly(:, 1), ...
0090             'YData', poly(:, 2), ...
0091             'ZData', poly(:, 3), ...
0092             'Parent', hAx, varargin{:});
0093     end
0094 end
0095 
0096 % restore hold state
0097 if ~holdState
0098     hold(hAx, 'off');
0099 end
0100 
0101 % Do not return axis if not requested
0102 % avoids output when called without semicolon
0103 if nargout > 0
0104     h = hp;
0105 end