1########################################################################
2##
3## Copyright (C) 2010-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  {} {@var{plot_box_aspect_ratio} =} pbaspect ( )
28## @deftypefnx {} {} pbaspect (@var{plot_box_aspect_ratio})
29## @deftypefnx {} {} pbaspect (@var{mode})
30## @deftypefnx {} {@var{plot_box_aspect_ratio_mode} =} pbaspect ("mode")
31## @deftypefnx {} {} pbaspect (@var{hax}, @dots{})
32##
33## Query or set the plot box aspect ratio of the current axes.
34##
35## The aspect ratio is a normalized 3-element vector representing the rendered
36## lengths of the x, y, and z axes.
37##
38## @code{pbaspect(@var{mode})}
39##
40## Set the plot box aspect ratio mode of the current axes.  @var{mode} is
41## either @qcode{"auto"} or @qcode{"manual"}.
42##
43## @code{pbaspect ("mode")}
44##
45## Return the plot box aspect ratio mode of the current axes.
46##
47## @code{pbaspect (@var{hax}, @dots{})}
48##
49## Operate on the axes in handle @var{hax} instead of the current axes.
50##
51## @seealso{axis, daspect, xlim, ylim, zlim}
52## @end deftypefn
53
54function pbratio = pbaspect (varargin)
55
56  ## Grab axes handle if present
57  if (nargin > 0)
58    if (isscalar (varargin{1}) && isaxes (varargin{1}))
59      hax = varargin{1};
60      varargin = varargin(2:end);
61    else
62      hax = gca ();
63    endif
64  else
65    hax = gca ();
66  endif
67
68  nargin = numel (varargin);
69  if (nargin > 1)
70    print_usage ();
71  endif
72
73  if (nargin == 0)
74    pbratio = get (hax, "plotboxaspectratio");
75  else
76    arg = varargin{1};
77    if (isnumeric (arg))
78      if (numel (arg) == 2)
79        set (hax, "plotboxaspectratio", [arg, 1]);
80      elseif (numel (arg) == 3)
81        set (hax, "plotboxaspectratio", arg);
82      else
83        error ("pbaspect: PLOT_BOX_ASPECT_RATIO must be a 2 or 3 element vector");
84      endif
85    elseif (ischar (arg))
86      arg = tolower (arg);
87      switch (arg)
88        case "auto"
89          set (hax, "plotboxaspectratiomode", "auto");
90        case "manual"
91          set (hax, "plotboxaspectratiomode", "manual");
92        case "mode"
93          pbratio = get (hax, "plotboxaspectratiomode");
94        otherwise
95          error ("pbaspect: Invalid MODE <%s>", arg);
96      endswitch
97    else
98      print_usage ();
99    endif
100  endif
101
102endfunction
103
104
105%!demo
106%! clf;
107%! x = 0:0.01:4;
108%! plot (x,cos(x), x,sin(x));
109%! pbaspect ([1 1 1]);
110%! title ("plot box is square");
111
112%!demo
113%! clf;
114%! x = 0:0.01:4;;
115%! plot (x,cos(x), x,sin(x));
116%! pbaspect ([2 1 1]);
117%! title ("plot box aspect ratio is 2x1");
118
119%!demo
120%! clf;
121%! x = 0:0.01:4;
122%! plot (x,cos(x), x,sin(x));
123%! daspect ([1 1 1]);
124%! pbaspect ([2 1 1]);
125%! title ("plot box is 2x1, and axes [0 4 -1 1]");
126