surfnorm

% -*- texinfo -*-
% @deftypefn {Function File} {} surfnorm (@var{x}, @var{y}, @var{z})
% @deftypefnx {Function File} {} surfnorm (@var{z})
% @deftypefnx {Function File} {[@var{nx}, @var{ny}, @var{nz}] =} surfnorm (@dots{})
% @deftypefnx {Function File} {} surfnorm (@var{h}, @dots{})
% Find the vectors normal to a meshgridded surface.  The meshed gridded 
% surface is defined by @var{x}, @var{y}, and @var{z}.  If @var{x} and 
% @var{y} are not defined, then it is assumed that they are given by
%
% @example
% @group
% [@var{x}, @var{y}] = meshgrid (1:size(@var{z}, 1), 
%                      1:size(@var{z}, 2));
% @end group
% @end example
%
% If no return arguments are requested, a surface plot with the normal 
% vectors to the surface is plotted.  Otherwise the components of the normal
% vectors at the mesh gridded points are returned in @var{nx}, @var{ny},
% and @var{nz}.
%
% The normal vectors are calculated by taking the cross product of the 
% diagonals of each of the quadrilaterals in the meshgrid to find the 
% normal vectors of the centers of these quadrilaterals.  The four nearest
% normal vectors to the meshgrid points are then averaged to obtain the 
% normal to the surface at the meshgridded points.
%
% An example of the use of @code{surfnorm} is
%
% @example
% surfnorm (peaks (25));
% @end example
% @seealso{surf, quiver3}
% @end deftypefn