% -*- texinfo -*-
% @deftypefn {Function File} {[@var{cd}] =} isocolors (@var{c}, @var{v})
% @deftypefnx {Function File} {[@var{cd}] =} isocolors (@var{x}, @var{y}, @var{z}, @var{c}, @var{v})
% @deftypefnx {Function File} {[@var{cd}] =} isocolors (@var{x}, @var{y}, @var{z}, @var{r}, @var{g}, @var{b}, @var{v})
% @deftypefnx {Function File} {[@var{cd}] =} isocolors (@var{r}, @var{g}, @var{b}, @var{v})
% @deftypefnx {Function File} {[@var{cd}] =} isocolors (@dots{}, @var{p})
% @deftypefnx {Function File} isocolors (@dots{})
%
% If called with one output argument and the first input argument
% @var{c} is a three--dimensional array that contains color values and
% the second input argument @var{v} keeps the vertices of a geometry
% then return a matrix @var{cd} with color data information for the
% geometry at computed points
% @command{[x, y, z] = meshgrid (1:l, 1:m, 1:n)}. The output argument
% @var{cd} can be taken to manually set FaceVertexCData of a patch.
%
% If called with further input arguments @var{x}, @var{y} and @var{z}
% which are three--dimensional arrays of the same size than @var{c}
% then the color data is taken at those given points. Instead of the
% color data @var{c} this function can also be called with RGB values
% @var{r}, @var{g}, @var{b}. If input argumnets @var{x}, @var{y},
% @var{z} are not given then again @command{meshgrid} computed values
% are taken.
%
% Optionally, the patch handle @var{p} can be given as the last input
% argument to all variations of function calls instead of the vertices
% data @var{v}. Finally, if no output argument is given then directly
% change the colors of a 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, 'FaceColor', 'interp');
% %% set (p, 'FaceLighting', 'flat');
% %% 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] = isosurface (x, y, z, c, iso);
% p = patch ('Faces', f, 'Vertices', v, 'EdgeColor', 'none');
% cdat = rand (size (c)); %% Compute random patch color data
% isocolors (x, y, z, cdat, p); %% Directly set colors of patch
% isofinish (p); %% Call user function isofinish
%
% subplot (2, 2, 2); view (-38, 20);
% p = patch ('Faces', f, 'Vertices', v, 'EdgeColor', 'none');
% [r, g, b] = meshgrid (lin, 2-lin, 2-lin);
% cdat = isocolors (x, y, z, c, v); %% Compute color data vertices
% set (p, 'FaceVertexCData', cdat); %% Set color data manually
% isofinish (p);
%
% subplot (2, 2, 3); view (-38, 20);
% p = patch ('Faces', f, 'Vertices', v, 'EdgeColor', 'none');
% cdat = isocolors (r, g, b, c, p); %% Compute color data patch
% set (p, 'FaceVertexCData', cdat); %% Set color data manually
% isofinish (p);
%
% subplot (2, 2, 4); view (-38, 20);
% p = patch ('Faces', f, 'Vertices', v, 'EdgeColor', 'none');
% r = g = b = repmat ([1:N] / N, [N, 1, N]); %% Black to white
% cdat = isocolors (x, y, z, r, g, b, v);
% set (p, 'FaceVertexCData', cdat);
% isofinish (p);
% @end example
%
% @seealso{isosurface, isonormals, isocaps}
%
% @end deftypefn