% -*- texinfo -*-
% @deftypefn {Function File} {[@var{n}] =} isonormals (@var{val}, @var{v})
% @deftypefnx {Function File} {[@var{n}] =} isonormals (@var{val}, @var{p})
% @deftypefnx {Function File} {[@var{n}] =} isonormals (@var{x}, @var{y}, @var{z}, @var{val}, @var{v})
% @deftypefnx {Function File} {[@var{n}] =} isonormals (@var{x}, @var{y}, @var{z}, @var{val}, @var{p})
% @deftypefnx {Function File} {[@var{n}] =} isonormals (@dots{}, 'negate')
% @deftypefnx {Function File} isonormals (@dots{}, @var{p})
%
% If called with one output argument and the first input argument
% @var{val} is a three--dimensional array that contains the data for an
% isosurface geometry and the second input argument @var{v} keeps the
% vertices of an isosurface then return the normals @var{n} in form of
% a matrix with the same size than @var{v} at computed points
% @command{[x, y, z] = meshgrid (1:l, 1:m, 1:n)}. The output argument
% @var{n} can be taken to manually set @var{VertexNormals} of a patch.
%
% If called with further input arguments @var{x}, @var{y} and @var{z}
% which are three--dimensional arrays with the same size than @var{val}
% then the volume data is taken at those given points. Instead of the
% vertices data @var{v} a patch handle @var{p} can be passed to this
% function.
%
% If given the string input argument 'negate' as last input argument
% then compute the reverse vector normals of an isosurface geometry.
%
% If no output argument is given then directly redraw the patch that is
% given by the patch handle @var{p}.
%
% For example,
% @example
% function [] = isofinish (p)
% set (gca, 'DataAspectRatioMode','manual','DataAspectRatio',[1 1 1]);
% set (p, 'VertexNormals', -get(p,'VertexNormals')); %% Revert normals
% set (p, 'FaceColor', 'interp');
% %% set (p, 'FaceLighting', 'phong');
% %% light ('Position', [1 1 5]); %% Available with JHandles
%
%
% N = 15; %% Increase number of vertices in each direction
% iso = .4; %% Change isovalue to .1 to display a sphere
% lin = linspace (0, 2, N);
% [x, y, z] = meshgrid (lin, lin, lin);
% c = abs ((x-.5).^2 + (y-.5).^2 + (z-.5).^2);
% figure ; %% Open another figure window
%
% subplot (2, 2, 1); view (-38, 20);
% [f, v, cdat] = isosurface (x, y, z, c, iso, y);
% p = patch ('Faces', f, 'Vertices', v, 'FaceVertexCData', cdat, ...
% 'FaceColor', 'interp', 'EdgeColor', 'none');
% isofinish (p); %% Call user function isofinish
%
% subplot (2, 2, 2); view (-38, 20);
% p = patch ('Faces', f, 'Vertices', v, 'FaceVertexCData', cdat, ...
% 'FaceColor', 'interp', 'EdgeColor', 'none');
% isonormals (x, y, z, c, p); %% Directly modify patch
% isofinish (p);
%
% subplot (2, 2, 3); view (-38, 20);
% p = patch ('Faces', f, 'Vertices', v, 'FaceVertexCData', cdat, ...
% 'FaceColor', 'interp', 'EdgeColor', 'none');
% n = isonormals (x, y, z, c, v); %% Compute normals of isosurface
% set (p, 'VertexNormals', n); %% Manually set vertex normals
% isofinish (p);
%
% subplot (2, 2, 4); view (-38, 20);
% p = patch ('Faces', f, 'Vertices', v, 'FaceVertexCData', cdat, ...
% 'FaceColor', 'interp', 'EdgeColor', 'none');
% isonormals (x, y, z, c, v, 'negate'); %% Use reverse directly
% isofinish (p);
% @end example
%
% @seealso {isosurface, isocolors, isocaps, marching_cube}
%
% @end deftypefn