1########################################################################
2##
3## Copyright (C) 1993-2021 The Octave Project Developers
4##
5## See the file COPYRIGHT.md in the top-level directory of this
6## distribution or <https://octave.org/copyright/>.
7##
8## This file is part of Octave.
9##
10## Octave is free software: you can redistribute it and/or modify it
11## under the terms of the GNU General Public License as published by
12## the Free Software Foundation, either version 3 of the License, or
13## (at your option) any later version.
14##
15## Octave is distributed in the hope that it will be useful, but
16## WITHOUT ANY WARRANTY; without even the implied warranty of
17## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
18## GNU General Public License for more details.
19##
20## You should have received a copy of the GNU General Public License
21## along with Octave; see the file COPYING.  If not, see
22## <https://www.gnu.org/licenses/>.
23##
24########################################################################
25
26## -*- texinfo -*-
27## @deftypefn  {} {} mesh (@var{x}, @var{y}, @var{z})
28## @deftypefnx {} {} mesh (@var{z})
29## @deftypefnx {} {} mesh (@dots{}, @var{c})
30## @deftypefnx {} {} mesh (@dots{}, @var{prop}, @var{val}, @dots{})
31## @deftypefnx {} {} mesh (@var{hax}, @dots{})
32## @deftypefnx {} {@var{h} =} mesh (@dots{})
33## Plot a 3-D wireframe mesh.
34##
35## The wireframe mesh is plotted using rectangles.  The vertices of the
36## rectangles [@var{x}, @var{y}] are typically the output of @code{meshgrid}.
37## over a 2-D rectangular region in the x-y plane.  @var{z} determines the
38## height above the plane of each vertex.  If only a single @var{z} matrix is
39## given, then it is plotted over the meshgrid
40## @code{@var{x} = 1:columns (@var{z}), @var{y} = 1:rows (@var{z})}.
41## Thus, columns of @var{z} correspond to different @var{x} values and rows
42## of @var{z} correspond to different @var{y} values.
43##
44## The color of the mesh is computed by linearly scaling the @var{z} values
45## to fit the range of the current colormap.  Use @code{caxis} and/or
46## change the colormap to control the appearance.
47##
48## Optionally, the color of the mesh can be specified independently of @var{z}
49## by supplying a color matrix, @var{c}.
50##
51## Any property/value pairs are passed directly to the underlying surface
52## object.  The full list of properties is documented at
53## @ref{Surface Properties}.
54##
55## If the first argument @var{hax} is an axes handle, then plot into this axes,
56## rather than the current axes returned by @code{gca}.
57##
58## The optional return value @var{h} is a graphics handle to the created
59## surface object.
60##
61## @seealso{ezmesh, meshc, meshz, trimesh, contour, surf, surface, meshgrid, hidden, shading, colormap, caxis}
62## @end deftypefn
63
64function h = mesh (varargin)
65
66  if (! all (cellfun ("isreal", varargin)))
67    error ("mesh: X, Y, Z, C arguments must be real");
68  endif
69
70  [hax, varargin, nargin] = __plt_get_axis_arg__ ("mesh", varargin{:});
71
72  oldfig = [];
73  if (! isempty (hax))
74    oldfig = get (0, "currentfigure");
75  endif
76  unwind_protect
77    hax = newplot (hax);
78
79    mesh_props = {"facecolor", "w", "edgecolor", "flat", ...
80                  "facelighting", "none", "edgelighting", "flat"};
81    chararg = find (cellfun ("isclass", varargin, "char"), 1);
82    if (isempty (chararg))
83      htmp = surface (varargin{:}, mesh_props{:});
84    else
85      htmp = surface (varargin{1:chararg-1}, mesh_props{:},
86                      varargin{chararg:end});
87    endif
88
89    if (! ishold ())
90      set (hax, "view", [-37.5, 30],
91                "xgrid", "on", "ygrid", "on", "zgrid", "on");
92    endif
93  unwind_protect_cleanup
94    if (! isempty (oldfig))
95      set (0, "currentfigure", oldfig);
96    endif
97  end_unwind_protect
98
99  if (nargout > 0)
100    h = htmp;
101  endif
102
103endfunction
104
105
106%!demo
107%! clf;
108%! x = logspace (0,1,11);
109%! z = x'*x;
110%! mesh (x, x, z);
111%! xlabel "X-axis";
112%! ylabel "Y-axis";
113%! zlabel "Z-axis";
114%! title ("mesh() with color proportional to height");
115
116%!demo
117%! clf;
118%! x = logspace (0,1,11);
119%! z = x'*x;
120%! mesh (x, x, z, z.^2);
121%! xlabel "X-axis";
122%! ylabel "Y-axis";
123%! zlabel "linear scale";
124%! title ("mesh() with color proportional to Z^2");
125
126%!demo
127%! clf;
128%! x = logspace (0,1,11);
129%! z = x'*x;
130%! mesh (x, x, z, z.^2);
131%! set (gca, "zscale", "log");
132%! xlabel "X-axis";
133%! ylabel "Y-axis";
134%! zlabel "log scale";
135%! title ({"mesh() with color proportional to Z^2", "Z-axis is log scale"});
136%! try
137%!   if (strcmp (get (gcf, "__graphics_toolkit__"), "gnuplot"))
138%!     title ({"Gnuplot: mesh color is wrong", "This is a Gnuplot bug"});
139%!   endif
140%! catch
141%! end_try_catch
142
143%!demo
144%! clf;
145%! x = logspace (0,1,11);
146%! z = x'*x;
147%! mesh (x, x, z, "facecolor", "none", "edgecolor", "c");
148%! xlabel "X-axis";
149%! ylabel "Y-axis";
150%! zlabel "Z-axis";
151%! title ({"mesh() default properties overridden", ...
152%!         "transparent mesh with cyan color"});
153