# HG changeset patch
# User Rik <octave@nomad.inbox5.com>
# Date 1334010897 25200
# Node ID 759944521fd6689118c82235ec681e0e1f330b87
# Parent  ac8520c03fc93433d82c87250b8bfa70e3da954b
Improve tetramesh docstring and add function to manual.

* geometry.txi: Add tetramesh to manual.

* delaunay.m, delaunay3.m, delaunayn.m: Update seealso cross-references.

* tetramesh.m: Update docstring.  Use Octave coding conventions.

diff --git a/doc/interpreter/geometry.txi b/doc/interpreter/geometry.txi
--- a/doc/interpreter/geometry.txi
+++ b/doc/interpreter/geometry.txi
@@ -96,6 +96,7 @@
 
 Octave has the functions @code{triplot}, @code{trimesh}, and @code{trisurf}
 to plot the Delaunay triangulation of a 2-dimensional set of points.
+@code{tetramesh} will plot the triangulation of a 3-dimensional set of points.
 
 @DOCSTRING(triplot)
 
@@ -103,6 +104,8 @@
 
 @DOCSTRING(trisurf)
 
+@DOCSTRING(tetramesh)
+
 The difference between @code{triplot}, and @code{trimesh} or @code{triplot},
 is that the former only plots the 2-dimensional triangulation itself, whereas
 the second two plot the value of a function @code{f (@var{x}, @var{y})}.  An
diff --git a/scripts/geometry/delaunay.m b/scripts/geometry/delaunay.m
--- a/scripts/geometry/delaunay.m
+++ b/scripts/geometry/delaunay.m
@@ -56,7 +56,7 @@
 ## plot (VX, VY, "b", x, y, "r*");
 ## @end group
 ## @end example
-## @seealso{delaunay3, delaunayn, convhull, voronoi}
+## @seealso{delaunay3, delaunayn, convhull, voronoi, triplot, trimesh, trisurf}
 ## @end deftypefn
 
 ## Author: Kai Habel <kai.habel@gmx.de>
diff --git a/scripts/geometry/delaunay3.m b/scripts/geometry/delaunay3.m
--- a/scripts/geometry/delaunay3.m
+++ b/scripts/geometry/delaunay3.m
@@ -42,7 +42,7 @@
 ## To append user options to the defaults it is necessary to repeat the 
 ## default arguments in @var{options}.  Use a null string to pass no arguments.
 ##
-## @seealso{delaunay, delaunayn, convhull, voronoi}
+## @seealso{delaunay, delaunayn, convhull, voronoi, tetramesh}
 ## @end deftypefn
 
 ## Author: Kai Habel <kai.habel@gmx.de>
diff --git a/scripts/geometry/delaunayn.m b/scripts/geometry/delaunayn.m
--- a/scripts/geometry/delaunayn.m
+++ b/scripts/geometry/delaunayn.m
@@ -47,7 +47,7 @@
 ## To append user options to the defaults it is necessary to repeat the 
 ## default arguments in @var{options}.  Use a null string to pass no arguments.
 ##
-## @seealso{delaunay, delaunay3, convhulln, voronoin}
+## @seealso{delaunay, delaunay3, convhulln, voronoin, trimesh, tetramesh}
 ## @end deftypefn
 
 function T = delaunayn (pts, varargin)
diff --git a/scripts/plot/tetramesh.m b/scripts/plot/tetramesh.m
--- a/scripts/plot/tetramesh.m
+++ b/scripts/plot/tetramesh.m
@@ -19,104 +19,91 @@
 ## -*- texinfo -*-
 ## @deftypefn  {Function File} tetramesh (@var{T}, @var{X})
 ## @deftypefnx {Function File} tetramesh (@var{T}, @var{X}, @var{C})
-## @deftypefnx {Function File} {[@var{h}] =} tetramesh (...)
-## @deftypefnx {Function File} {[@var{h}] =} tetramesh (..., @var{PROP}, @var{VAL})
+## @deftypefnx {Function File} tetramesh (@dots{}, @var{property}, @var{val}, @dots{})
+## @deftypefnx {Function File} {@var{h} =} tetramesh (@dots{})
 ##
-## 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. 
+## Display the tetrahedrons defined in the m-by-4 matrix @var{T}
+## as 3-D patches.  @var{T} is typically the output of a Delaunay triangulation
+## of a 3-D 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 3-D 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.
+## The vector @var{C} specifies the color of each tetrahedron as an index
+## into the current colormap.  The default value is 1:m where m is the number
+## of tetrahedrons; the indices are scaled to map to the full range of the
+## colormap.  If there are more tetrahedrons than colors in the colormap then
+## the values in @var{C} are cyclically 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.
+## Calling @code{tetramesh (@dots{}, "property", "value", @dots{})} passes all
+## property/value pairs directly to the patch function as additional arguments.
 ##
-## The command
+## The optional return value @var{h} is a vector of patch handles where each
+## handle represents one tetrahedron in the order given by @var{T}. 
+## A typical use case for @var{h} is to turn the respective patch "visible"
+## property "on" or "off".
 ##
-##@example
-## @group
-## demo tetramesh
-## @end group
-## @end example
-##
-## @noindent
-## will show some examples how to use it.
-#### @seealso{patch}
+## Type @code{demo tetramesh} to see examples on using @code{tetramesh}.
+## @seealso{delaunay3, delaunayn, trimesh, patch}
 ## @end deftypefn
 
 ## Author: Martin Helm <martin@mhelm.de>
 
-function [h] = tetramesh (varargin)
+function h = tetramesh (varargin)
 
   [reg, prop] = parseparams (varargin);
 
   if (length (reg) < 2 || length (reg) > 3)
-    print_usage ()
+    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")
+  if (! ismatrix (T) || columns (T) != 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")
+  if (! ismatrix (X) || columns (X) != 3)
+    error ("tetramesh: X must be a n-by-3 matrix");
   endif
 
-  size_T = size (T, 1);
+  size_T = rows (T);
   colmap = colormap ();
   
-  # do we need to enable gnuplot workaround?
-  shrink = strcmp (graphics_toolkit (), "gnuplot");
-
   if (length (reg) < 3)
     size_colmap = size (colmap, 1);
     C = mod ((1:size_T)' - 1, size_colmap) + 1;
     if (size_T < size_colmap && size_T > 1) 
-      # expand to the available range of colors
+      ## expand to the available range of colors
       C = floor ((C - 1) * (size_colmap - 1) / (size_T - 1)) + 1;
     endif
   else
     C = reg{3};
     if (! isvector (C) || size_T != length (C))
-      error ("tetramesh: C must be a vector of the same length as T")
+      error ("tetramesh: C must be a vector of the same length as T");
     endif
   endif
 
   h = zeros (1, size_T);
-  if (shrink)
-    # tiny reduction of the tetrahedron size to help gnuplot by
-    # avoiding identical faces with different colors
-    for ii = 1:size_T
-      [th, p] = __shrink__ ([1 2 3 4], X(T(ii, :), :), 1 - 1e-7);
-      h(ii) = patch ("Faces", th, "Vertices", p, "FaceColor", ...
-                     colmap(C(ii), :), prop{:});
+  if (strcmp (graphics_toolkit (), "gnuplot"))
+    ## tiny reduction of the tetrahedron size to help gnuplot by
+    ## avoiding identical faces with different colors
+    for i = 1:size_T
+      [th, p] = __shrink__ ([1 2 3 4], X(T(i, :), :), 1 - 1e-7);
+      hvec(i) = patch ("Faces", th, "Vertices", p, 
+                       "FaceColor", colmap(C(i), :), prop{:});
     endfor
   else
-    for ii = 1:size_T
+    for i = 1:size_T
       th = [1 2 3; 2 3 4; 3 4 1; 4 1 2];
-      h(ii) = patch ("Faces", th, "Vertices", X(T(ii, :), :), "FaceColor", ...
-                     colmap(C(ii), :), prop{:});
+      hvec(i) = patch ("Faces", th, "Vertices", X(T(i, :), :), 
+                       "FaceColor", colmap(C(i), :), prop{:});
     endfor
   endif
 
-  if (nargout == 0) #return nothing
-    clear h;
+  if (nargout > 0)
+    h = hvec;
   endif
+
 endfunction
 
 ## shrink the tetrahedron relative to its center of gravity
@@ -127,7 +114,9 @@
   tri = reshape (1:12, 3, 4)';
 endfunction
 
+
 %!demo
+%! clf;
 %! d = [-1 1];
 %! [x,y,z] = meshgrid (d, d, d);
 %! x = [x(:); 0];
@@ -135,17 +124,15 @@
 %! z = [z(:); 0];
 %! tetra = delaunay3 (x, y, z);
 %! X = [x(:) y(:) z(:)];
-%! clf ()
-%! colormap (jet (64))
+%! colormap (jet (64));
 %! h = tetramesh (tetra, X);
-%! for ii=1:2:length(h);
-%!   set(h(ii), "Visible", "off");
-%! endfor
-%! axis equal
-%! view (30, 20)
-%! title ("Using jet (64), every other tetrahedron invisible")
+%! set (h(1:2:end), "Visible", "off");
+%! axis equal;
+%! view (30, 20);
+%! title ("Using jet (64), every other tetrahedron invisible");
 
 %!demo
+%! clf;
 %! d = [-1 1];
 %! [x,y,z] = meshgrid (d, d, d);
 %! x = [x(:); 0];
@@ -153,9 +140,9 @@
 %! z = [z(:); 0];
 %! tetra = delaunay3 (x, y, z);
 %! X = [x(:) y(:) z(:)];
-%! clf ()
 %! colormap (gray (256));
-%! tetramesh (tetra, X, 21:20:241, "EdgeColor", "w")
-%! axis equal
-%! view (30, 20)
-%! title ("Using gray (256) and white edges")
+%! tetramesh (tetra, X, 21:20:241, "EdgeColor", "w");
+%! axis equal;
+%! view (30, 20);
+%! title ("Using gray (256) and white edges");
+