octave_packages/m/plot/clabel.m

   1 ## Copyright (C) 2008-2012 David Bateman
   2 ##
   3 ## This file is part of Octave.
   4 ##
   5 ## Octave is free software; you can redistribute it and/or modify it
   6 ## under the terms of the GNU General Public License as published by
   7 ## the Free Software Foundation; either version 3 of the License, or (at
   8 ## your option) any later version.
   9 ##
  10 ## Octave is distributed in the hope that it will be useful, but
  11 ## WITHOUT ANY WARRANTY; without even the implied warranty of
  12 ## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13 ## General Public License for more details.
  14 ##
  15 ## You should have received a copy of the GNU General Public License
  16 ## along with Octave; see the file COPYING.  If not, see
  17 ## <http://www.gnu.org/licenses/>.
  18
  19 ## -*- texinfo -*-
  20 ## @deftypefn  {Function File} {} clabel (@var{c}, @var{h})
  21 ## @deftypefnx {Function File} {} clabel (@var{c}, @var{h}, @var{v})
  22 ## @deftypefnx {Function File} {} clabel (@var{c}, @var{h}, "manual")
  23 ## @deftypefnx {Function File} {} clabel (@var{c})
  24 ## @deftypefnx {Function File} {} clabel (@var{c}, @var{h})
  25 ## @deftypefnx {Function File} {} clabel (@dots{}, @var{prop}, @var{val}, @dots{})
  26 ## @deftypefnx {Function File} {@var{h} =} clabel (@dots{})
  27 ## Add labels to the contours of a contour plot.  The contour plot is specified
  28 ## by the contour matrix @var{c} and optionally the contourgroup object @var{h}
  29 ## that are returned by @code{contour}, @code{contourf} and @code{contour3}.
  30 ## The contour labels are rotated and placed in the contour itself.
  31 ##
  32 ## By default, all contours are labeled.  However, the contours to label can be
  33 ## specified by the vector @var{v}.  If the "manual" argument is given then
  34 ## the contours to label can be selected with the mouse.
  35 ##
  36 ## Additional property/value pairs that are valid properties of text objects
  37 ## can be given and are passed to the underlying text objects.  Additionally,
  38 ## the property "LabelSpacing" is available allowing the spacing between labels
  39 ## on a contour (in points) to be specified.  The default is 144 points, or 2
  40 ## inches.
  41 ##
  42 ## The optional return value @var{h} is a vector of graphics handles to
  43 ## the text objects representing each label.
  44 ## The "userdata" property of the text objects contains the numerical value of
  45 ## the contour label.
  46 ##
  47 ## An example of the use of @code{clabel} is
  48 ##
  49 ## @example
  50 ## @group
  51 ## [c, h] = contour (peaks (), -4 : 6);
  52 ## clabel (c, h, -4:2:6, "fontsize", 12);
  53 ## @end group
  54 ## @end example
  55 ##
  56 ## @seealso{contour, contourf, contour3, meshc, surfc, text}
  57 ## @end deftypefn
  58
  59 function retval = clabel (c, varargin)
  60   label_spacing = 2 * 72;
  61   have_hg = false;
  62   have_labelspacing = false;
  63
  64   if (nargin < 1)
  65     print_usage ();
  66   elseif (nargin == 1)
  67     hparent = gca ();
  68   else
  69     arg = varargin{1};
  70     if (isscalar (arg) && ishandle(arg)
  71         && strcmp (get (arg, "type"), "hggroup"))
  72       obj = get (arg);
  73       if (! isfield (obj, "contourmatrix"))
  74         error ("clabel: expecting the handle to be a contour group");
  75       endif
  76       hg = arg;
  77       have_hg = true;
  78       varargin(1) = [];
  79     else
  80       hparent = gca ();
  81     endif
  82   endif
  83
  84   if (length(varargin) > 0 && isnumeric (varargin{1}))
  85     v = varargin{1}(:);
  86     varargin(1) = [];
  87   else
  88     v = [];
  89   endif
  90
  91   for i = 1 : length (varargin) - 1
  92     arg = varargin{i};
  93     if (strcmpi (arg, "labelspacing"))
  94       label_spacing = varargin{i+1};
  95       have_labelspacing = true;
  96       varargin(i:i+1) = [];
  97       break;
  98     endif
  99   endfor
 100
 101   for i = 1 : length (varargin)
 102     arg = varargin{i};
 103     if (strcmpi (arg, "manual"))
 104       error ("clabel: manual contouring mode not supported");
 105     endif
 106   endfor
 107
 108   if (have_hg)
 109     if (! isempty (v))
 110       if (have_labelspacing)
 111         set (hg, "textlistmode", "manual", "textlist", v,
 112              "labelspacing", label_spacing, "showtext", "on");
 113       else
 114         set (hg, "textlistmode", "manual", "textlist", v, "showtext", "on");
 115       endif
 116     else
 117       if (have_labelspacing)
 118         set (hg,"showtext", "on", "labelspacing", label_spacing);
 119       else
 120         set (hg,"showtext", "on");
 121       endif
 122     endif
 123     retval = findobj (hg, "type", "text");
 124     if (! isempty (varargin))
 125       set (retval, varargin {:});
 126     endif
 127   else
 128     retval =  __clabel__ (c, v, hparent, label_spacing, [], varargin{:});
 129   endif
 130 endfunction
 131
 132
 133 %!demo
 134 %! clf
 135 %! [c, h] = contour (peaks(), -4:6);
 136 %! clabel (c, h, -4:2:6, "fontsize", 12);
 137
 138 %!demo
 139 %! clf
 140 %! [c, h] = contourf (peaks(), -7:6);
 141 %! clabel (c, h, -6:2:6, "fontsize", 12);
 142