1########################################################################
2##
3## Copyright (C) 2013-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  {} {} waterfall (@var{x}, @var{y}, @var{z})
28## @deftypefnx {} {} waterfall (@var{z})
29## @deftypefnx {} {} waterfall (@dots{}, @var{c})
30## @deftypefnx {} {} waterfall (@dots{}, @var{prop}, @var{val}, @dots{})
31## @deftypefnx {} {} waterfall (@var{hax}, @dots{})
32## @deftypefnx {} {@var{h} =} waterfall (@dots{})
33## Plot a 3-D waterfall plot.
34##
35## A waterfall plot is similar to a @code{meshz} plot except only
36## mesh lines for the rows of @var{z} (x-values) are shown.
37##
38## The wireframe mesh is plotted using rectangles.  The vertices of the
39## rectangles [@var{x}, @var{y}] are typically the output of @code{meshgrid}.
40## over a 2-D rectangular region in the x-y plane.  @var{z} determines the
41## height above the plane of each vertex.  If only a single @var{z} matrix is
42## given, then it is plotted over the meshgrid
43## @code{@var{x} = 1:columns (@var{z}), @var{y} = 1:rows (@var{z})}.
44## Thus, columns of @var{z} correspond to different @var{x} values and rows
45## of @var{z} correspond to different @var{y} values.
46##
47## The color of the mesh is computed by linearly scaling the @var{z} values
48## to fit the range of the current colormap.  Use @code{caxis} and/or
49## change the colormap to control the appearance.
50##
51## Optionally the color of the mesh can be specified independently of @var{z}
52## by supplying a color matrix, @var{c}.
53##
54## Any property/value pairs are passed directly to the underlying surface
55## object.  The full list of properties is documented at
56## @ref{Surface Properties}.
57##
58## If the first argument @var{hax} is an axes handle, then plot into this axes,
59## rather than the current axes returned by @code{gca}.
60##
61## The optional return value @var{h} is a graphics handle to the created
62## surface object.
63##
64## @seealso{meshz, mesh, meshc, contour, surf, surface, ribbon, meshgrid, hidden, shading, colormap, caxis}
65## @end deftypefn
66
67function h = waterfall (varargin)
68
69  htmp = meshz (varargin{:});
70
71  set (htmp, "meshstyle", "row");
72
73  if (nargout > 0)
74    h = htmp;
75  endif
76
77endfunction
78
79
80%!demo
81%! clf;
82%! colormap ("default");
83%! Z = peaks ();
84%! waterfall (Z);
85%! title ("waterfall() plot of peaks() function");
86
87%!demo
88%! clf;
89%! colormap ("default");
90%! Z = peaks ();
91%! subplot (1,2,1)
92%!  meshz (Z);
93%!  daspect ([2.5, 2.5, 1]);
94%!  title ("meshz() plot");
95%! subplot (1,2,2)
96%!  waterfall (Z);
97%!  daspect ([2.5, 2.5, 1]);
98%!  title ("waterfall() plot");
99