% -*- texinfo -*-
% @deftypefn {Function File} {[@var{fv}] =} isosurface (@var{val}, @var{iso})
% @deftypefnx {Function File} {[@var{fv}] =} isosurface (@var{x}, @var{y}, @var{z}, @var{val}, @var{iso})
% @deftypefnx {Function File} {[@var{fv}] =} isosurface (@dots{}, 'noshare', 'verbose')
% @deftypefnx {Function File} {[@var{fvc}] =} isosurface (@dots{}, @var{col})
% @deftypefnx {Function File} {[@var{f}, @var{v}] =} isosurface (@var{x}, @var{y}, @var{z}, @var{val}, @var{iso})
% @deftypefnx {Function File} {[@var{f}, @var{v}, @var{c}] =} isosurface (@var{x}, @var{y}, @var{z}, @var{val}, @var{iso}, @var{col})
% @deftypefnx {Function File} {} isosurface (@var{x}, @var{y}, @var{z}, @var{val}, @var{iso}, @var{col}, @var{opt})
%
% If called with one output argument and the first input argument
% @var{val} is a three--dimensional array that contains the data of an
% isosurface geometry and the second input argument @var{iso} keeps the
% isovalue as a scalar value then return a structure array @var{fv}
% that contains the fields @var{Faces} and @var{Vertices} at computed
% points @command{[x, y, z] = meshgrid (1:l, 1:m, 1:n)}. The output
% argument @var{fv} can directly be taken as an input argument for the
% @command{patch} function.
%
% 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.
%
% The string input argument 'noshare' is only for compatibility and
% has no effect. If given the string input argument
% 'verbose' then print messages to the command line interface about the
% current progress.
%
% If called with the input argument @var{col} which is a
% three-dimensional array of the same size than @var{val} then take
% those values for the interpolation of coloring the isosurface
% geometry. Add the field @var{FaceVertexCData} to the structure
% array @var{fv}.
%
% If called with two or three output arguments then return the
% information about the faces @var{f}, vertices @var{v} and color data
% @var{c} as seperate arrays instead of a single structure array.
%
% If called with no output argument then directly process the
% isosurface geometry with the @command{patch} command.
%
% For example
%
% @example
% [x, y, z] = meshgrid (1:5, 1:5, 1:5);
% val = rand (5, 5, 5);
% isosurface (x, y, z, val, .5);
% @end example
%
% will directly draw a random isosurface geometry in a graphics window.
% Another example for an isosurface geometry with different additional
% coloring
%
% @example
% 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] = isosurface (x, y, z, c, iso);
% p = patch ('Faces', f, 'Vertices', v, 'EdgeColor', 'none');
% set (gca, 'DataAspectRatioMode','manual', 'DataAspectRatio', [1 1 1]);
% % set (p, 'FaceColor', 'green', 'FaceLighting', 'phong');
% % light ('Position', [1 1 5]); %% Available with the JHandles package
%
% subplot (2, 2, 2); view (-38, 20);
% p = patch ('Faces', f, 'Vertices', v, 'EdgeColor', 'blue');
% set (gca, 'DataAspectRatioMode','manual', 'DataAspectRatio', [1 1 1]);
% % set (p, 'FaceColor', 'none', 'FaceLighting', 'phong');
% % light ('Position', [1 1 5]);
%
% subplot (2, 2, 3); view (-38, 20);
% [f, v, c] = isosurface (x, y, z, c, iso, y);
% p = patch ('Faces', f, 'Vertices', v, 'FaceVertexCData', c, ...
% 'FaceColor', 'interp', 'EdgeColor', 'none');
% set (gca, 'DataAspectRatioMode','manual', 'DataAspectRatio', [1 1 1]);
% % set (p, 'FaceLighting', 'phong');
% % light ('Position', [1 1 5]);
%
% subplot (2, 2, 4); view (-38, 20);
% p = patch ('Faces', f, 'Vertices', v, 'FaceVertexCData', c, ...
% 'FaceColor', 'interp', 'EdgeColor', 'blue');
% set (gca, 'DataAspectRatioMode','manual', 'DataAspectRatio', [1 1 1]);
% % set (p, 'FaceLighting', 'phong');
% % light ('Position', [1 1 5]);
% @end example
%
% @seealso{isocolors, isonormals, isocaps}
%
% @end deftypefn