## Copyright (C) 2012 Martin Helm
##
## This file is part of Octave.
##
## Octave is free software; you can redistribute it and/or modify it
## under the terms of the GNU General Public License as published by
## the Free Software Foundation; either version 3 of the License, or (at
## your option) any later version.
##
## Octave is distributed in the hope that it will be useful, but
## WITHOUT ANY WARRANTY; without even the implied warranty of
## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
## General Public License for more details.
##
## You should have received a copy of the GNU General Public License
## along with Octave; see the file COPYING.  If not, see
## <http://www.gnu.org/licenses/>.

## -*- texinfo -*-
## @deftypefn  {Function File} tetramesh (@var{T}, @var{X})
## @deftypefnx {Function File} tetramesh (@var{T}, @var{X}, @var{C})
## @deftypefnx {Function File} address@hidden =} tetramesh (...)
## @deftypefnx {Function File} address@hidden =} tetramesh (..., @var{PROP}, @var{VAL})
##
## The function displays the tetrahedrons defined in the m by 4 matrix @var{T} as 3D patches. 
## @var{T} is usually the output of a Delaunay triangulation of a 3D set of points. 
## Every row of @var{T} contains four indices into the n by 3 matrix @var{X} of the vertices of a tetrahedron. 
## Every row in @var{X} represents one point in 3D space. 
##
## If the vector @var{C} is supplied it must contain indices into the current colormap.
## Called without @var{C} it is set to 1:m, where m is the number of tetrahedrons, the indices are 
## scaled to map to the full range of the colormap. If more tetrahedrons than entries in the colormap 
## are given the entries of @var{C} are cyclic repeated.
## 
## When called with one output argument @var{H} it returns a vector of patch handles, 
## each representing one tetrahedron in the order given by @var{T}. 
## One use case for @var{H} is to turn the respective patch 'Visible' property 'on' or 'off'.
##
## Calling tetramesh(...,'param','value','param','value'...) passes all option/value pairs directly
## as additional arguments to the patch function for every tetrahedron.
##
## The command
##
address@hidden
## @group
## demo tetramesh
## @end group
## @end example
##
## @noindent
## will show some examples how to use it.
#### @seealso{patch}
## @end deftypefn

## Author: Martin Helm <address@hidden>

function [h] = tetramesh (varargin)

  [reg, prop] = parseparams (varargin);

  if (length (reg) < 2 || length (reg) > 3)
    print_usage ()
  endif

  T = reg{1};
  X = reg{2};

  if (! ismatrix (T) || size (T, 2) != 4)
    error ("tetramesh: T must be a n by 4 matrix")
  endif
  if (! ismatrix (X) || size (X, 2) != 3)
    error ("tetramesh: X must be a n by 3 matrix")
  endif

  sT = size (T, 1);
  cm = colormap ();

  if (length (reg) < 3)
    scm = size (cm, 1);
    C = mod ((1:sT)' - 1, scm) + 1;
    if (sT < scm && sT > 1) # expand to the available range of colors
      C = floor ((C - 1) * (scm - 1) / (sT - 1)) + 1;
    endif
  else
    C = reg{3};
    if (! isvector (C) || size (T, 1) != length (C))
      error ("tetramesh: C must be a vector of the same length as T")
    endif
  endif

  h = zeros(1, sT);
  for ii = 1:sT
    thi = [T(ii, 1) T(ii, 2) T(ii, 3) T(ii, 4)];
    th = [1 2 3; 2 3 4; 3 4 1; 4 1 2];
    h(ii) = patch ("Faces", th, "Vertices", X(thi, :), "FaceVertexCData", ...
	            repmat(cm(C(ii), :), 4, 1), prop{:});
  endfor

  if (nargout == 0) #return nothing
    clear h;
  endif
endfunction

%!demo
%! d = [-1 1];
%! [x,y,z] = meshgrid (d, d, d);
%! x = [x(:); 0];
%! y = [y(:); 0];
%! z = [z(:); 0];
%! tetra = delaunay3 (x, y, z);
%! X = [x(:) y(:) z(:)];
%! clf ()
%! colormap (jet (64))
%! h = tetramesh (tetra, X);
%! axis equal
%! view (30,20)
%! title ("Using jet (64)")

%!demo
%! d = [-1 1];
%! [x,y,z] = meshgrid (d, d, d);
%! x = [x(:); 0];
%! y = [y(:); 0];
%! z = [z(:); 0];
%! tetra = delaunay3 (x, y, z);
%! X = [x(:) y(:) z(:)];
%! clf ()
%! colormap (gray (256));
%! tetramesh (tetra, X, 1:20:221, "EdgeColor", "w")
%! axis equal
%! view (30, 20)
%! title ("Using gray (256) and white edges")