# HG changeset patch
# User Colin Macdonald <cbm@m.fsf.org>
# Date 1468356953 25200
#      Tue Jul 12 13:55:53 2016 -0700
# Node ID a572f8fb34e42200c4b675e4042a6cdab721bce0
# Parent  96771721b2d52eb2bd2b48edf28b8686d523d1eb
Add camzoom function.

This doesn't precisely match Matlab's behaviour: added some xtest
against someone's Matlab output.  This is probably good enough for
interactive use so adding it now.

* doc/interpreter/plot.txi: Add docstrings to manual.
* scripts/help/__unimplemented__.m: Trim list.
* scripts/plot/appearance/camzoom.m: New function.
* scripts/plot/appearance/camroll.m: Update seealso.
* scripts/plot/appearance/module.mk: Update.

diff -r 96771721b2d5 -r a572f8fb34e4 doc/interpreter/plot.txi
--- a/doc/interpreter/plot.txi	Mon Jul 11 19:14:07 2016 -0700
+++ b/doc/interpreter/plot.txi	Tue Jul 12 13:55:53 2016 -0700
@@ -410,6 +410,8 @@
 
 @DOCSTRING(camva)
 
+@DOCSTRING(camzoom)
+
 @DOCSTRING(slice)
 
 @DOCSTRING(ribbon)
diff -r 96771721b2d5 -r a572f8fb34e4 scripts/help/__unimplemented__.m
--- a/scripts/help/__unimplemented__.m	Mon Jul 11 19:14:07 2016 -0700
+++ b/scripts/help/__unimplemented__.m	Tue Jul 12 13:55:53 2016 -0700
@@ -578,7 +578,6 @@
   "camorbit",
   "campan",
   "camproj",
-  "camzoom",
   "categorical",
   "categories",
   "cdf2rdf",
diff -r 96771721b2d5 -r a572f8fb34e4 scripts/plot/appearance/camroll.m
--- a/scripts/plot/appearance/camroll.m	Mon Jul 11 19:14:07 2016 -0700
+++ b/scripts/plot/appearance/camroll.m	Tue Jul 12 13:55:53 2016 -0700
@@ -53,7 +53,7 @@
 ## By default, these commands effect the current axis; alternatively
 ## an axis can be specified by the optional argument @var{ax}.
 ##
-## @seealso{camup}
+## @seealso{camzoom, camup}
 ## @end deftypefn
 
 
diff -r 96771721b2d5 -r a572f8fb34e4 scripts/plot/appearance/camzoom.m
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/scripts/plot/appearance/camzoom.m	Tue Jul 12 13:55:53 2016 -0700
@@ -0,0 +1,142 @@
+## Copyright (C) 2016 Colin B. Macdonald
+##
+## This file is part of Octave.
+##
+## Octave is free software; you can redistribute it and/or modify it
+## under the terms of the GNU General Public License as published by
+## the Free Software Foundation; either version 3 of the License, or (at
+## your option) any later version.
+##
+## This software is distributed in the hope that it will be useful,
+## but WITHOUT ANY WARRANTY; without even the implied warranty
+## of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+## General Public License for more details.
+##
+## You should have received a copy of the GNU General Public
+## License along with this software; see the file COPYING.
+## If not, see <http://www.gnu.org/licenses/>.
+
+## -*- texinfo -*-
+## @documentencoding UTF-8
+## @deftypefn  {} {} camzoom (@var{f})
+## @deftypefnx {} {} camzoom (@var{ax}, @var{f})
+## Zoom the camera in or out.
+##
+## A value of @var{f} larger than 1 ``zooms in'' and we see more
+## of the middle part of the scene:
+## @example
+## @group
+## hf = figure();
+## sphere (36)
+## camzoom (1.2)
+## @end group
+## @end example
+##
+## A value smaller than 1 ``zooms out'' so the camera can see more
+## of the scene:
+## @example
+## @group
+## camzoom (0.5)
+## @end group
+## @end example
+##
+## Technically speaking, zooming effects the ``viewing angle'' and
+## this gives a way to reset to the default zoom:
+## @example
+## @group
+## camva ("auto")
+## close (hf)
+## @end group
+## @end example
+##
+## By default, these commands effect the current axis; alternatively
+## an axis can be specified by the optional argument @var{ax}.
+##
+## @seealso{camroll, camva}
+## @end deftypefn
+
+
+function p = camzoom (varargin)
+
+  [hax, varargin, nargin] = __plt_get_axis_arg__ ("camva", varargin{:});
+
+  if (nargin != 1)
+    print_usage ();
+  endif
+
+  f = varargin{1};
+
+  if (! (isnumeric (f) && isscalar (f) ))
+    print_usage ();
+  endif
+
+  if (isempty (hax))
+    hax = gca ();
+  else
+    hax = hax(1);
+  endif
+
+  a = camva (hax);
+  # XXX: I don't think this quite matches Matlab, what is the standard
+  # meaning of zoom factor?  Maybe they do that.
+  camva (hax, a/f);
+
+endfunction
+
+
+%!demo
+%! peaks ()
+%! camzoom (2)
+
+
+%!error <Invalid> camzoom (1, 2, 3)
+%!error <Invalid> camzoom (1, [2, 3])
+%!error <Invalid> camzoom ("string")
+
+%!shared hf
+%! hf = figure ("visible", "off");
+
+%!test
+%! sphere ()
+%! x = camva ();
+%! camzoom (5)
+%! assert (abs (x - camva ()) > x/3)
+%! camzoom (1/5)
+%! y = camva ();
+%! assert (x, y, eps)
+
+%!xtest
+%! ## matlab's camzoom() is not a simply scaling of camva
+%! clf; sphere()
+%! x = camva ();
+%! camzoom (2)
+%! y = camva ();
+%! ## Matlab 2014a
+%! xm = 10.339584907202;
+%! ym = 5.18033628450948;
+%! assert (x/y, xm/ym, 1e-10)
+
+%!xtest
+%! clf; peaks ()
+%! campos ([20, 30, 50])
+%! camtarget ([0 0 1])
+%! x = camva ();
+%! camzoom (5)
+%! y = camva ();
+%! ## Matlab 2014a
+%! xm = 13.0746680295069;
+%! ym = 2.62588066987212;
+%! assert (x/y, xm/ym, 1e-10)
+
+%!test
+%! ## test ax input by creating another axis
+%! clf
+%! subplot (1, 2, 1); sphere (); hax = gca ();
+%! subplot (1, 2, 2); sphere (); camzoom (hax, 2)
+%! subplot (1, 2, 1); x = camva ();
+%! subplot (1, 2, 2); y = camva ();
+%! assert (x, 5, 2)
+%! assert (y, 10, 2)
+
+%!test
+%! close (hf)
diff -r 96771721b2d5 -r a572f8fb34e4 scripts/plot/appearance/module.mk
--- a/scripts/plot/appearance/module.mk	Mon Jul 11 19:14:07 2016 -0700
+++ b/scripts/plot/appearance/module.mk	Tue Jul 12 13:55:53 2016 -0700
@@ -17,6 +17,7 @@
   scripts/plot/appearance/camtarget.m \
   scripts/plot/appearance/camup.m \
   scripts/plot/appearance/camva.m \
+  scripts/plot/appearance/camzoom.m \
   scripts/plot/appearance/caxis.m \
   scripts/plot/appearance/clabel.m \
   scripts/plot/appearance/daspect.m \
