octave_packages/m/plot/subplot.m

   1 ## Copyright (C) 1995-2012 John W. Eaton
   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} {} subplot (@var{rows}, @var{cols}, @var{index})
  21 ## @deftypefnx {Function File} {} subplot (@var{rcn})
  22 ## Set up a plot grid with @var{rows} by @var{cols} subwindows and plot
  23 ## in location given by @var{index}.
  24 ##
  25 ## If only one argument is supplied, then it must be a three digit value
  26 ## specifying the location in digits 1 (rows) and 2 (columns) and the plot
  27 ## index in digit 3.
  28 ##
  29 ## The plot index runs row-wise.  First all the columns in a row are filled
  30 ## and then the next row is filled.
  31 ##
  32 ## For example, a plot with 2 by 3 grid will have plot indices running as
  33 ## follows:
  34 ## @tex
  35 ## \vskip 10pt
  36 ## \hfil\vbox{\offinterlineskip\hrule
  37 ## \halign{\vrule#&&\qquad\hfil#\hfil\qquad\vrule\cr
  38 ## height13pt&1&2&3\cr height12pt&&&\cr\noalign{\hrule}
  39 ## height13pt&4&5&6\cr height12pt&&&\cr\noalign{\hrule}}}
  40 ## \hfil
  41 ## \vskip 10pt
  42 ## @end tex
  43 ## @ifnottex
  44 ##
  45 ## @example
  46 ## @group
  47 ## +-----+-----+-----+
  48 ## |  1  |  2  |  3  |
  49 ## +-----+-----+-----+
  50 ## |  4  |  5  |  6  |
  51 ## +-----+-----+-----+
  52 ## @end group
  53 ## @end example
  54 ##
  55 ## @var{index} may be a vector.  In which case, the new axis will enclose
  56 ## the grid locations specified.  The first demo illustrates an example:
  57 ##
  58 ## @example
  59 ## demo ("subplot", 1)
  60 ## @end example
  61 ##
  62 ## @end ifnottex
  63 ## @seealso{axes, plot}
  64 ## @end deftypefn
  65
  66 ## Author: Vinayak Dutt <Dutt.Vinayak@mayo.EDU>
  67 ## Adapted-By: jwe
  68
  69 function h = subplot (varargin)
  70
  71   align_axes = false;
  72   replace_axes = false;
  73   have_position = false;
  74   initial_args_decoded = false;
  75
  76   if (nargin > 2)
  77     ## R, C, N?
  78     arg1 = varargin{1};
  79     arg2 = varargin{2};
  80     arg3 = varargin{3};
  81     if (isnumeric (arg1) && isscalar (arg1) && isnumeric (arg2)
  82         && isscalar (arg2) && isnumeric (arg3))
  83       rows = arg1;
  84       cols = arg2;
  85       index = arg3;
  86       varargin(1:3)= [];
  87       initial_args_decoded = true;
  88     endif
  89   endif
  90
  91   if (! initial_args_decoded && nargin > 1)
  92     ## check for 'position', pos, ...
  93     if (strcmpi (varargin{1}, "position"))
  94       arg = varargin{2};
  95       if (isnumeric (arg) && numel (arg) == 4)
  96         pos = arg;
  97         varargin(1:2) = [];
  98         have_position = true;
  99         initial_args_decoded = true;
 100       else
 101         error ("expecting position to be a 4-element numeric array");
 102       endif
 103     endif
 104   endif
 105
 106   if (! initial_args_decoded && nargin > 0)
 107     arg = varargin{1};
 108     if (nargin == 1 && ishandle (arg))
 109       ## Axes handle?
 110       axes (arg);
 111       cf = get (0, "currentfigure");
 112       set (cf, "nextplot", "add");
 113       return;
 114     elseif (isscalar (arg) && arg >= 0)
 115       ## RCN?
 116       index = rem (arg, 10);
 117       arg = (arg - index) / 10;
 118       cols = rem (arg, 10);
 119       arg = (arg - cols) / 10;
 120       rows = rem (arg, 10);
 121       varargin(1) = [];
 122       initial_args_decoded = true;
 123     else
 124       error ("subplot: expecting axes handle or RCN argument");
 125     endif
 126   endif
 127
 128   if (! initial_args_decoded)
 129     print_usage ();
 130   endif
 131
 132   if (! have_position)
 133     cols = round (cols);
 134     rows = round (rows);
 135     index = round (index);
 136
 137     if (any (index < 1) || any (index > rows*cols))
 138       error ("subplot: INDEX value must be greater than 1 and less than ROWS*COLS");
 139     endif
 140
 141     if (cols < 1 || rows < 1 || index < 1)
 142       error ("subplot: COLS, ROWS, and INDEX must be be positive");
 143     endif
 144   endif
 145
 146   nargs = numel (varargin);
 147   while (nargs > 0)
 148     arg = varargin{1};
 149     if (strcmpi (arg, "align"))
 150       align_axes = true;
 151     elseif (strcmpi (arg, "replace"))
 152       replace_axes = true;
 153     else
 154       break;
 155     endif
 156     varargin(1) = [];
 157     nargs--;
 158   endwhile
 159
 160   axesunits = get (0, "defaultaxesunits");
 161   cf = gcf ();
 162   figureunits = get (cf, "units");
 163   unwind_protect
 164     units = "normalized";
 165     set (0, "defaultaxesunits", units);
 166     set (cf, "units", "pixels");
 167
 168     ## FIXME: At the moment we force gnuplot to use the aligned mode
 169     ##        which will set "activepositionproperty" to "position".
 170     ##        Τhis can yield to text overlap between labels and titles
 171     ##        see bug #31610
 172     if (strcmp (get (cf, "__graphics_toolkit__"), "gnuplot"))
 173       align_axes = true;
 174     endif
 175
 176     if (! have_position)
 177       if (align_axes)
 178         pos = subplot_position (rows, cols, index, "position");
 179       elseif (strcmp (get (cf, "__graphics_toolkit__"), "gnuplot"))
 180         pos = subplot_position (rows, cols, index, "outerpositiontight");
 181       else
 182         pos = subplot_position (rows, cols, index, "outerposition");
 183       endif
 184     endif
 185
 186     set (cf, "nextplot", "add");
 187
 188     found = false;
 189     kids = get (cf, "children");
 190     for child = reshape (kids, 1, numel (kids))
 191       ## Check whether this child is still valid; this might not be the
 192       ## case anymore due to the deletion of previous children (due to
 193       ## "deletefcn" callback or for legends/colorbars that are deleted
 194       ## with their corresponding axes).
 195       if (! ishandle (child))
 196         continue;
 197       endif
 198       if (strcmp (get (child, "type"), "axes"))
 199         ## Skip legend and colorbar objects.
 200         if (strcmp (get (child, "tag"), "legend")
 201             || strcmp (get (child, "tag"), "colorbar"))
 202           continue;
 203         endif
 204         if (align_axes)
 205           objpos = get (child, "position");
 206         else
 207           objpos = get (child, "outerposition");
 208         endif
 209         if (all (objpos == pos) && ! replace_axes)
 210           ## If the new axes are in exactly the same position as an
 211           ## existing axes object, use the existing axes.
 212           found = true;
 213           tmp = child;
 214         else
 215           ## If the new axes overlap an old axes object, delete the old
 216           ## axes.
 217           x0 = pos(1);
 218           x1 = x0 + pos(3);
 219           y0 = pos(2);
 220           y1 = y0 + pos(4);
 221           objx0 = objpos(1);
 222           objx1 = objx0 + objpos(3);
 223           objy0 = objpos(2);
 224           objy1 = objy0 + objpos(4);
 225           if (! (x0 >= objx1 || x1 <= objx0 || y0 >= objy1 || y1 <= objy0))
 226             delete (child);
 227           endif
 228         endif
 229       endif
 230     endfor
 231
 232     if (found)
 233       set (cf, "currentaxes", tmp);
 234     elseif (align_axes)
 235       tmp = axes ("box", "off", "position", pos, varargin{:});
 236     elseif (strcmp (get (cf, "__graphics_toolkit__"), "gnuplot"))
 237       tmp = axes ("box", "off", "outerposition", pos, varargin{:});
 238     else
 239       tmp = axes ("looseinset", [0 0 0 0], "box", "off", "outerposition", pos,
 240                   "autopos_tag", "subplot", varargin{:});
 241     endif
 242
 243   unwind_protect_cleanup
 244     set (0, "defaultaxesunits", axesunits);
 245     set (cf, "units", figureunits);
 246   end_unwind_protect
 247
 248   if (nargout > 0)
 249     h = tmp;
 250   endif
 251
 252 endfunction
 253
 254 function pos = subplot_position (rows, cols, index, position_property)
 255
 256   if (rows == 1 && cols == 1)
 257     ## Trivial result for subplot (1,1,1)
 258     if (strcmpi (position_property, "position"))
 259       pos = get (0, "defaultaxesposition");
 260     else
 261       pos = get (0, "defaultaxesouterposition");
 262     endif
 263     return
 264   endif
 265
 266   if (strcmp (position_property, "outerposition")
 267       || strcmp (position_property, "outerpositiontight"))
 268     margins.left   = 0.05;
 269     margins.bottom = 0.05;
 270     margins.right  = 0.05;
 271     margins.top    = 0.05;
 272     if (strcmp (position_property, "outerpositiontight"))
 273       margins.column = 0.;
 274       margins.row = 0.;
 275     else
 276       margins.column = 0.04 / cols;
 277       margins.row = 0.04 / rows;
 278     endif
 279     width = 1 - margins.left - margins.right - (cols-1)*margins.column;
 280     width = width / cols;
 281     height = 1 - margins.top - margins.bottom - (rows-1)*margins.row;
 282     height = height / rows;
 283   else
 284     defaultaxesposition = get (0, "defaultaxesposition");
 285
 286     ## The outer margins surrounding all subplot "positions" are independent
 287     ## of the number of rows and/or columns
 288     margins.left   = defaultaxesposition(1);
 289     margins.bottom = defaultaxesposition(2);
 290     margins.right  = 1.0 - margins.left - defaultaxesposition(3);
 291     margins.top    = 1.0 - margins.bottom - defaultaxesposition(4);
 292
 293     ## Fit from Matlab experiments
 294     pc = 1 ./ [0.1860, (margins.left + margins.right - 1)];
 295     margins.column = 1 ./ polyval (pc , cols);
 296     pr = 1 ./ [0.2282, (margins.top + margins.bottom - 1)];
 297     margins.row    = 1 ./ polyval (pr , rows);
 298
 299     ## Calculate the width/height of the subplot axes "position".
 300     ## This is also consistent with Matlab
 301     width = 1 - margins.left - margins.right - (cols-1)*margins.column;
 302     width = width / cols;
 303     height = 1 - margins.top - margins.bottom - (rows-1)*margins.row;
 304     height = height / rows;
 305   endif
 306
 307   ## Index offsets from the lower left subplot
 308   yi = fix ((index(:)-1)/cols);
 309   xi = index(:) - yi*cols - 1;
 310   yi = (rows - 1) - yi;
 311
 312   ## Lower left corner of the subplot, i.e. position(1:2)
 313   x0 = xi .* (width + margins.column) + margins.left;
 314   y0 = yi .* (height + margins.row) + margins.bottom;
 315
 316   if (numel(x0) > 1)
 317     ## subplot (row, col, m:n)
 318     x1 = max (x0(:)) + width;
 319     y1 = max (y0(:)) + height;
 320     x0 = min (x0(:));
 321     y0 = min (y0(:));
 322     pos = [x0, y0, x1-x0, y1-y0];
 323   else
 324     ## subplot (row, col, num)
 325     pos = [x0, y0, width, height];
 326   endif
 327
 328 endfunction
 329
 330 %!demo
 331 %! clf
 332 %! r = 3;
 333 %! c = 3;
 334 %! fmt = {'horizontalalignment', 'center', 'verticalalignment', 'middle'};
 335 %! for n = 1:(r*c)
 336 %!   subplot (r, c, n)
 337 %!   xlabel (sprintf ("xlabel #%d", n))
 338 %!   ylabel (sprintf ("ylabel #%d", n))
 339 %!   title (sprintf ("title #%d", n))
 340 %!   text (0.5, 0.5, sprintf('subplot(%d,%d,%d)', r, c, n), fmt{:})
 341 %!   axis ([0 1 0 1])
 342 %! endfor
 343 %! subplot (r, c, 1:3)
 344 %! xlabel (sprintf ("xlabel #%d:%d", 1, 3))
 345 %! ylabel (sprintf ("ylabel #%d:%d", 1, 3))
 346 %! title (sprintf ("title #%d:%d", 1, 3))
 347 %! text (0.5, 0.5, sprintf('subplot(%d,%d,%d:%d)', r, c, 1, 3), fmt{:})
 348 %! axis ([0 1 0 1])
 349
 350 %!demo
 351 %! clf
 352 %! x = 0:1;
 353 %! for n = 1:4
 354 %!   subplot (2, 2, n, "align")
 355 %!   plot (x, x)
 356 %!   xlabel (sprintf ("xlabel (2,2,%d)", n))
 357 %!   ylabel (sprintf ("ylabel (2,2,%d)", n))
 358 %!   title (sprintf ("title (2,2,%d)", n))
 359 %! endfor
 360 %! subplot (1, 2, 1, "align")
 361 %! plot (x, x)
 362 %! xlabel ("xlabel (1,2,1)")
 363 %! ylabel ("ylabel (1,2,1)")
 364 %! title ("title (1,2,1)")
 365