octave_packages/m/geometry/delaunay3.m

   1 ## Copyright (C) 1999-2012 Kai Habel
   2 ##
   3 ## This file is part of Octave.
   4 ##
   5 ## Octave is free software; you can redistribute it and/or modify it
   6 ## under the terms of the GNU General Public License as published by
   7 ## the Free Software Foundation; either version 3 of the License, or (at
   8 ## your option) any later version.
   9 ##
  10 ## Octave is distributed in the hope that it will be useful, but
  11 ## WITHOUT ANY WARRANTY; without even the implied warranty of
  12 ## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13 ## General Public License for more details.
  14 ##
  15 ## You should have received a copy of the GNU General Public License
  16 ## along with Octave; see the file COPYING.  If not, see
  17 ## <http://www.gnu.org/licenses/>.
  18
  19 ## -*- texinfo -*-
  20 ## @deftypefn  {Function File} {@var{tetr} =} delaunay3 (@var{x}, @var{y}, @var{z})
  21 ## @deftypefnx {Function File} {@var{tetr} =} delaunay3 (@var{x}, @var{y}, @var{z}, @var{options})
  22 ## Compute the Delaunay triangulation for a 3-D set of points.
  23 ## The return value @var{tetr} is a set of tetrahedrons which satisfies the
  24 ## Delaunay circum-circle criterion, i.e., only a single data point from
  25 ## [@var{x}, @var{y}, @var{z}] is within the circum-circle of the defining
  26 ## tetrahedron.
  27 ##
  28 ## The set of tetrahedrons @var{tetr} is a matrix of size [n, 4].  Each
  29 ## row defines a tetrahedron and the four columns are the four vertices
  30 ## of the tetrahedron.  The value of @code{@var{tetr}(i,j)} is an index into
  31 ## @var{x}, @var{y}, @var{z} for the location of the j-th vertex of the i-th
  32 ## tetrahedron.
  33 ##
  34 ## An optional fourth argument, which must be a string or cell array of strings,
  35 ## contains options passed to the underlying qhull command.
  36 ## See the documentation for the Qhull library for details
  37 ## @url{http://www.qhull.org/html/qh-quick.htm#options}.
  38 ## The default options are @code{@{"Qt", "Qbb", "Qc", "Qz"@}}.
  39 ##
  40 ## If @var{options} is not present or @code{[]} then the default arguments are
  41 ## used.  Otherwise, @var{options} replaces the default argument list.
  42 ## To append user options to the defaults it is necessary to repeat the
  43 ## default arguments in @var{options}.  Use a null string to pass no arguments.
  44 ##
  45 ## @seealso{delaunay, delaunayn, convhull, voronoi}
  46 ## @end deftypefn
  47
  48 ## Author: Kai Habel <kai.habel@gmx.de>
  49
  50 function tetr = delaunay3 (x, y, z, options)
  51
  52   if (nargin < 3 || nargin > 4)
  53     print_usage ();
  54   endif
  55
  56   if (! (isvector (x) && isvector (y) && isvector (z)
  57          && length (x) == length (y) && length(x) == length (z)))
  58     error ("delaunay: X, Y, and Z must be the same size");
  59   elseif (nargin == 4 && ! (ischar (options) || iscellstr (options)))
  60     error ("delaunay3: OPTIONS must be a string or cell array of strings");
  61   endif
  62
  63   if (nargin == 3)
  64     tetr = delaunayn ([x(:), y(:), z(:)]);
  65   else
  66     tetr = delaunayn ([x(:), y(:), z(:)], options);
  67   endif
  68
  69 endfunction
  70
  71
  72 %!testif HAVE_QHULL
  73 %! x = [-1, -1, 1, 0, -1]; y = [-1, 1, 1, 0, -1]; z = [0, 0, 0, 1, 1];
  74 %! assert (sortrows (sort (delaunay3 (x, y, z), 2)), [1,2,3,4;1,2,4,5])
  75
  76 %% FIXME: Need input validation tests
  77