octave_packages/m/plot/colorbar.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} {} colorbar (@var{s})
  21 ## @deftypefnx {Function File} {} colorbar ("peer", @var{h}, @dots{})
  22 ## Add a colorbar to the current axes.  Valid values for @var{s} are
  23 ##
  24 ## @table @asis
  25 ## @item "EastOutside"
  26 ## Place the colorbar outside the plot to the right.  This is the default.
  27 ##
  28 ## @item "East"
  29 ## Place the colorbar inside the plot to the right.
  30 ##
  31 ## @item "WestOutside"
  32 ## Place the colorbar outside the plot to the left.
  33 ##
  34 ## @item "West"
  35 ## Place the colorbar inside the plot to the left.
  36 ##
  37 ## @item "NorthOutside"
  38 ## Place the colorbar above the plot.
  39 ##
  40 ## @item "North"
  41 ## Place the colorbar at the top of the plot.
  42 ##
  43 ## @item "SouthOutside"
  44 ## Place the colorbar under the plot.
  45 ##
  46 ## @item "South"
  47 ## Place the colorbar at the bottom of the plot.
  48 ##
  49 ## @item "Off", "None"
  50 ## Remove any existing colorbar from the plot.
  51 ## @end table
  52 ##
  53 ## If the argument "peer" is given, then the following argument is treated
  54 ## as the axes handle on which to add the colorbar.
  55 ## @end deftypefn
  56
  57 function h = colorbar (varargin)
  58   ax = [];
  59   loc = "eastoutside";
  60   args = {};
  61   deleting = false;
  62
  63   i = 1;
  64   while (i <= nargin)
  65     arg = varargin {i++};
  66     if (ischar(arg))
  67       if (strcmpi (arg, "peer"))
  68         if (i > nargin)
  69           error ("colorbar: missing axes handle after \"peer\"");
  70         else
  71           ax = varargin{i++};
  72           if (!isscalar (ax) || ! ishandle (ax)
  73               || ! strcmp (get (ax, "type"), "axes"))
  74             error ("colorbar: expecting an axes handle following \"peer\"");
  75           endif
  76         endif
  77       elseif (strcmpi (arg, "north") || strcmpi (arg, "south")
  78               || strcmpi (arg, "east") || strcmpi (arg, "west")
  79               || strcmpi (arg, "northoutside") || strcmpi (arg, "southoutside")
  80               || strcmpi (arg, "eastoutside") || strcmpi (arg, "westoutside"))
  81         loc = tolower (arg);
  82       elseif (strcmpi (arg, "location") && i <= nargin)
  83         loc = tolower (varargin{i++});
  84       elseif (strcmpi (arg, "off") || strcmpi (arg, "none"))
  85         deleting = true;
  86       else
  87         args{end+1} = arg;
  88       endif
  89     else
  90       args{end+1} = arg;
  91     endif
  92   endwhile
  93
  94   if (isempty (ax))
  95     ax = gca ();
  96   endif
  97
  98   showhiddenhandles = get (0, "showhiddenhandles");
  99   unwind_protect
 100     set (0, "showhiddenhandles", "on");
 101     cax = findobj (get (ax, "parent"), "tag", "colorbar", "type", "axes", "axes", ax);
 102     if (! isempty (cax))
 103       delete (cax);
 104     endif
 105   unwind_protect_cleanup
 106     set (0, "showhiddenhandles", showhiddenhandles);
 107   end_unwind_protect
 108
 109   if (! deleting)
 110     ## FIXME - Matlab does not require the "position" property to be active.
 111     ##         Is there a way to determine the plotbox position for the
 112     ##         gnuplot graphics toolkit with the outerposition is active?
 113     set (ax, "activepositionproperty", "position");
 114     obj = get (ax);
 115     obj.__my_handle__ = ax;
 116     position = obj.position;
 117     clen = rows (get (get (ax, "parent"), "colormap"));
 118     cext = get (ax, "clim");
 119     cdiff = (cext(2) - cext(1)) / clen / 2;
 120     cmin = cext(1) + cdiff;
 121     cmax = cext(2) - cdiff;
 122
 123     [pos, cpos, vertical, mirror] =  ...
 124         __position_colorbox__ (loc, obj, ancestor (ax, "figure"));
 125     set (ax, "position", pos);
 126
 127     cax = __go_axes__ (get (ax, "parent"), "tag", "colorbar",
 128                        "handlevisibility", "on",
 129                        "activepositionproperty", "position",
 130                        "position", cpos);
 131     addproperty ("location", cax, "radio",
 132                  "eastoutside|east|westoutside|west|northoutside|north|southoutside|south",
 133                  loc);
 134     addproperty ("axes", cax, "handle", ax);
 135
 136     if (vertical)
 137       hi = image (cax, [0,1], [cmin, cmax], [1 : clen]');
 138       if (mirror)
 139         set (cax, "xtick", [], "xdir", "normal", "ydir", "normal",
 140              "ylim", cext, "ylimmode", "manual",
 141              "yaxislocation", "right", args{:});
 142       else
 143         set (cax, "xtick", [], "xdir", "normal", "ydir", "normal",
 144              "ylim", cext, "ylimmode", "manual",
 145              "yaxislocation", "left", args{:});
 146       endif
 147     else
 148       hi = image (cax, [cmin, cmax], [0,1], [1 : clen]);
 149       if (mirror)
 150         set (cax, "ytick", [], "xdir", "normal", "ydir", "normal",
 151              "xlim", cext, "xlimmode", "manual",
 152              "xaxislocation", "top", args{:});
 153       else
 154         set (cax, "ytick", [], "xdir", "normal", "ydir", "normal",
 155              "xlim", cext, "xlimmode", "manual",
 156              "xaxislocation", "bottom", args{:});
 157       endif
 158     endif
 159
 160     ctext = text (0, 0, "", "tag", "colorbar","visible", "off",
 161                   "handlevisibility", "off", "xliminclude", "off",
 162                   "yliminclude", "off", "zliminclude", "off",
 163                   "deletefcn", {@deletecolorbar, cax, obj});
 164
 165     set (cax, "deletefcn", {@resetaxis, obj});
 166
 167     addlistener (ax, "clim", {@update_colorbar_clim, hi, vertical});
 168     addlistener (ax, "plotboxaspectratio", {@update_colorbar_axis, cax, obj});
 169     addlistener (ax, "plotboxaspectratiomode", {@update_colorbar_axis, cax, obj});
 170     addlistener (ax, "dataaspectratio", {@update_colorbar_axis, cax, obj});
 171     addlistener (ax, "dataaspectratiomode", {@update_colorbar_axis, cax, obj});
 172     addlistener (ax, "position", {@update_colorbar_axis, cax, obj});
 173
 174   endif
 175
 176   if (nargout > 0)
 177     h = cax;
 178   endif
 179 endfunction
 180
 181 function deletecolorbar (h, d, hc, orig_props)
 182   ## Don't delete the colorbar and reset the axis size if the
 183   ## parent figure is being deleted.
 184   if (ishandle (hc) && strcmp (get (hc, "type"), "axes")
 185       && (isempty (gcbf()) || strcmp (get (gcbf(), "beingdeleted"),"off")))
 186     if (strcmp (get (hc, "beingdeleted"), "off"))
 187       delete (hc);
 188     endif
 189     if (!isempty (ancestor (h, "axes"))
 190         && strcmp (get (ancestor (h, "axes"), "beingdeleted"), "off"))
 191       set (ancestor (h, "axes"), "position", orig_props.position, ...
 192                             "outerposition", orig_props.outerposition, ...
 193                     "activepositionproperty", orig_props.activepositionproperty);
 194     endif
 195   endif
 196 endfunction
 197
 198 function resetaxis (h, d, orig_props)
 199   if (ishandle (h) && strcmp (get (h, "type"), "axes")
 200       && (isempty (gcbf()) || strcmp (get (gcbf(), "beingdeleted"),"off"))
 201       && ishandle (get (h, "axes")))
 202      set (get (h, "axes"), "position", orig_props.position, ...
 203                            "outerposition", orig_props.outerposition, ...
 204                    "activepositionproperty", orig_props.activepositionproperty);
 205   endif
 206 endfunction
 207
 208 function update_colorbar_clim (h, d, hi, vert)
 209   if (ishandle (h) && strcmp (get (h, "type"), "image")
 210       && (isempty (gcbf()) || strcmp (get (gcbf(), "beingdeleted"),"off")))
 211     clen = rows (get (get (h, "parent"), "colormap"));
 212     cext = get (h, "clim");
 213     cdiff = (cext(2) - cext(1)) / clen / 2;
 214     cmin = cext(1) + cdiff;
 215     cmax = cext(2) - cdiff;
 216
 217     if (vert)
 218       set (hi, "ydata", [cmin, cmax]);
 219       set (get (hi, "parent"), "ylim", cext);
 220     else
 221       set (hi, "xdata", [cmin, cmax]);
 222       set (get (hi, "parent"), "xlim", cext);
 223     endif
 224   endif
 225 endfunction
 226
 227 function update_colorbar_axis (h, d, cax, orig_props)
 228
 229   if (ishandle (cax) && strcmp (get (cax, "type"), "axes")
 230       && (isempty (gcbf()) || strcmp (get (gcbf(), "beingdeleted"),"off")))
 231     loc = get (cax, "location");
 232     obj = get (h);
 233     obj.__my_handle__ = h;
 234     obj.position = orig_props.position;
 235     obj.outerposition = orig_props.outerposition;
 236     [pos, cpos, vertical, mirror] =  ...
 237         __position_colorbox__ (loc, obj, ancestor (h, "figure"));
 238
 239     if (vertical)
 240       if (mirror)
 241         set (cax, "xtick", [], "xdir", "normal", "ydir", "normal",
 242              "yaxislocation", "right", "position", cpos);
 243       else
 244         set (cax, "xtick", [], "xdir", "normal", "ydir", "normal",
 245              "yaxislocation", "left", "position", cpos);
 246       endif
 247     else
 248       if (mirror)
 249         set (cax, "ytick", [], "xdir", "normal", "ydir", "normal",
 250              "xaxislocation", "top", "position", cpos);
 251       else
 252         set (cax, "ytick", [], "xdir", "normal", "ydir", "normal",
 253              "xaxislocation", "bottom", "position", cpos);
 254       endif
 255     endif
 256
 257   endif
 258 endfunction
 259
 260 function [pos, cpos, vertical, mirr] = __position_colorbox__ (cbox, obj, cf)
 261
 262   ## This will always represent the position prior to adding the colorbar.
 263   pos = obj.position;
 264   sz = pos(3:4);
 265
 266   if (strcmpi (obj.plotboxaspectratiomode, "manual")
 267       || strcmpi (obj.dataaspectratiomode, "manual"))
 268     if (isempty (strfind (cbox, "outside")))
 269       scale = 1.0;
 270     else
 271       scale = 0.8;
 272     endif
 273     if (isempty (strfind (cbox, "east")) && isempty (strfind (cbox, "west")))
 274       scale = [1, scale];
 275     else
 276       scale = [scale, 1];
 277     endif
 278     if (strcmp (get (cf, "__graphics_toolkit__"), "gnuplot")
 279         && strcmp (obj.activepositionproperty, "outerposition"))
 280       obj.outerposition = obj.outerposition .* [1, 1, scale];
 281       off = 0.5 * (obj.outerposition (3:4) - __actual_axis_position__ (obj)(3:4));
 282     else
 283       obj.position = obj.position .* [1, 1, scale];
 284       off = 0.5 * (obj.position (3:4) - __actual_axis_position__ (obj)(3:4));
 285     endif
 286   else
 287     off = 0.0;
 288   endif
 289
 290   switch (cbox)
 291     case "northoutside"
 292       origin = pos(1:2) + [0., 0.9] .* sz + [1, -1] .* off;
 293       sz = sz .* [1.0, 0.06];
 294       pos(4) = 0.8 * pos(4);
 295       mirr = true;
 296       vertical = false;
 297     case "north"
 298       origin = pos(1:2) + [0.05, 0.9] .* sz + [1, -1] .* off;
 299       sz = sz .* [1.0, 0.06] * 0.9;
 300       mirr = false;
 301       vertical = false;
 302     case "southoutside"
 303       origin = pos(1:2) + off;
 304       sz = sz .* [1.0, 0.06];
 305       pos(2) = pos(2) + pos(4) * 0.2;
 306       pos(4) = 0.8 * pos(4);
 307       mirr = false;
 308       vertical = false;
 309     case "south"
 310       origin = pos(1:2) + [0.05, 0.05] .* sz + off;
 311       sz = sz .* [1.0, 0.06] * 0.9;
 312       mirr = true;
 313       vertical = false;
 314     case "eastoutside"
 315       origin = pos(1:2) + [0.9, 0] .* sz + [-1, 1] .* off;
 316       sz = sz .* [0.06, 1.0];
 317       pos(3) = 0.8 * pos(3);
 318       mirr = true;
 319       vertical = true;
 320     case "east"
 321       origin = pos(1:2) + [0.9, 0.05] .* sz + [-1, 1] .* off;
 322       sz = sz .* [0.06, 1.0] * 0.9;
 323       mirr = false;
 324       vertical = true;
 325     case "westoutside"
 326       origin = pos(1:2) + off;
 327       sz = sz .* [0.06, 1.0];
 328       pos(1) = pos(1) + pos(3) * 0.2;
 329       pos(3) = 0.8 * pos(3);
 330       mirr = false;
 331       vertical = true;
 332     case "west"
 333       origin = pos(1:2) + [0.05, 0.05] .* sz + off;
 334       sz = sz .* [0.06, 1.0] .* 0.9;
 335       mirr = true;
 336       vertical = true;
 337   endswitch
 338
 339   cpos = [origin, sz];
 340
 341   if (strcmpi (obj.plotboxaspectratiomode, "manual")
 342       || strcmpi (obj.dataaspectratiomode, "manual"))
 343     obj.position = pos;
 344     actual_pos = __actual_axis_position__ (obj);
 345     if (strfind (cbox, "outside"))
 346       scale = 1.0;
 347     else
 348       scale = 0.9;
 349     endif
 350     if (sz(1) > sz(2))
 351       ## Ensure north or south colorbars are the proper length
 352       dx = (1-scale)*actual_pos(3);
 353       cpos(1) = actual_pos(1) + dx/2;
 354       cpos(3) = actual_pos(3) - dx;
 355     else
 356       ## Ensure east or west colorbars are the proper height
 357       dy = (1-scale)*actual_pos(4);
 358       cpos(2) = actual_pos(2) + dy/2;
 359       cpos(4) = actual_pos(4) - dy;
 360     endif
 361   endif
 362
 363 endfunction
 364
 365 %!demo
 366 %! clf
 367 %! n = 64; x = kron (1:n,ones(n,1)); x = abs(x - x.');
 368 %! imagesc(x)
 369 %! colorbar();
 370
 371 %!demo
 372 %! clf
 373 %! n = 64; x = kron (1:n,ones(n,1)); x = abs(x - x.');
 374 %! imagesc(x)
 375 %! colorbar("westoutside");
 376
 377 %!demo
 378 %! clf
 379 %! n = 64; x = kron (1:n,ones(n,1)); x = abs(x - x.');
 380 %! imagesc(x)
 381 %! colorbar("peer", gca (), "northoutside");
 382
 383 %!demo
 384 %! clf
 385 %! n = 64; x = kron (1:n,ones(n,1)); x = abs(x - x.');
 386 %! imagesc(x)
 387 %! colorbar("southoutside");
 388
 389 %!demo
 390 %! clf
 391 %! contour(peaks())
 392 %! colorbar("west");
 393
 394 %!demo
 395 %! clf
 396 %! subplot(2,2,1)
 397 %! contour(peaks())
 398 %! colorbar("east");
 399 %! subplot(2,2,2)
 400 %! contour(peaks())
 401 %! colorbar("west");
 402 %! subplot(2,2,3)
 403 %! contour(peaks())
 404 %! colorbar("north");
 405 %! subplot(2,2,4)
 406 %! contour(peaks())
 407 %! colorbar("south");
 408
 409 %!demo
 410 %! clf
 411 %! n = 64; x = kron (1:n,ones(n,1)); x = abs(x - x.');
 412 %! subplot(2,2,1)
 413 %! imagesc(x)
 414 %! colorbar();
 415 %! subplot(2,2,2)
 416 %! imagesc(x)
 417 %! colorbar("westoutside");
 418 %! subplot(2,2,3)
 419 %! imagesc(x)
 420 %! colorbar("northoutside");
 421 %! subplot(2,2,4)
 422 %! imagesc(x)
 423 %! colorbar("southoutside");
 424
 425 %!demo
 426 %! clf
 427 %! n = 64; x = kron (1:n,ones(n,1)); x = abs(x - x.');
 428 %! subplot(1,2,1)
 429 %! imagesc(x)
 430 %! axis square;
 431 %! colorbar();
 432 %! subplot(1,2,2)
 433 %! imagesc(x)
 434 %! axis square;
 435 %! colorbar("westoutside");
 436
 437 %!demo
 438 %! clf
 439 %! n = 64; x = kron (1:n,ones(n,1)); x = abs(x - x.');
 440 %! subplot(1,2,1)
 441 %! imagesc(x)
 442 %! axis square;
 443 %! colorbar("northoutside");
 444 %! subplot(1,2,2)
 445 %! imagesc(x)
 446 %! axis square;
 447 %! colorbar("southoutside");
 448
 449 %!demo
 450 %! clf
 451 %! n = 64; x = kron (1:n,ones(n,1)); x = abs(x - x.');
 452 %! subplot(2,1,1)
 453 %! imagesc(x)
 454 %! axis square;
 455 %! colorbar();
 456 %! subplot(2,1,2)
 457 %! imagesc(x)
 458 %! axis square;
 459 %! colorbar("westoutside");
 460
 461 %!demo
 462 %! clf
 463 %! n = 64; x = kron (1:n,ones(n,1)); x = abs(x - x.');
 464 %! subplot(2,1,1)
 465 %! imagesc(x)
 466 %! axis square;
 467 %! colorbar("northoutside");
 468 %! subplot(2,1,2)
 469 %! imagesc(x)
 470 %! axis square;
 471 %! colorbar("southoutside");
 472
 473 %!demo
 474 %! clf
 475 %! n = 64; x = kron (1:n,ones(n,1)); x = abs(x - x.');
 476 %! subplot(1,2,1)
 477 %! imagesc(x)
 478 %! colorbar();
 479 %! subplot(1,2,2)
 480 %! imagesc(x)
 481 %! colorbar("westoutside");
 482
 483 %!demo
 484 %! clf
 485 %! n = 64; x = kron (1:n,ones(n,1)); x = abs(x - x.');
 486 %! subplot(1,2,1)
 487 %! imagesc(x)
 488 %! colorbar("northoutside");
 489 %! subplot(1,2,2)
 490 %! imagesc(x)
 491 %! colorbar("southoutside");
 492
 493 %!demo
 494 %! clf
 495 %! n = 64; x = kron (1:n,ones(n,1)); x = abs(x - x.');
 496 %! subplot(2,1,1)
 497 %! imagesc(x)
 498 %! colorbar();
 499 %! subplot(2,1,2)
 500 %! imagesc(x)
 501 %! colorbar("westoutside");
 502
 503 %!demo
 504 %! clf
 505 %! n = 64; x = kron (1:n,ones(n,1)); x = abs(x - x.');
 506 %! subplot(2,1,1)
 507 %! imagesc(x)
 508 %! colorbar("northoutside");
 509 %! subplot(2,1,2)
 510 %! imagesc(x)
 511 %! colorbar("southoutside");
 512
 513 %!demo
 514 %! clf
 515 %! n = 64; x = kron (1:n,ones(n,1)); x = abs(x - x.');
 516 %! subplot(1,2,1)
 517 %! contour(x)
 518 %! axis square;
 519 %! colorbar("east");
 520 %! xlim ([1, 64])
 521 %! ylim ([1, 64])
 522 %! subplot(1,2,2)
 523 %! contour(x)
 524 %! colorbar("west");
 525 %! xlim ([1, 64])
 526 %! ylim ([1, 64])
 527
 528 %!demo
 529 %! clf
 530 %! n = 64; x = kron (1:n,ones(n,1)); x = abs(x - x.');
 531 %! contour (x)
 532 %! xlim ([1, 64])
 533 %! ylim ([1, 64])
 534 %! colorbar ();
 535 %! colorbar off
 536
 537 %!demo
 538 %! clf
 539 %! n = 64; x = kron (1:n,ones(n,1)); x = abs(x - x.');
 540 %! contour (x)
 541 %! xlim ([1, 64])
 542 %! ylim ([1, 64])
 543 %! colorbar ();
 544 %! colorbar ();
 545
 546 %!demo
 547 %! clf
 548 %! imagesc (1./hilb(99));
 549 %! h = colorbar;
 550 %! set (h, 'yscale', 'log');
 551
 552 %!demo
 553 %! clf
 554 %! imagesc (log10 (1 ./ hilb (99)));
 555 %! h = colorbar;
 556 %! ytick = get(h, "ytick");
 557 %! set (h, "yticklabel", sprintf ('10^{%g}|', ytick));
 558
 559 %!demo
 560 %! clf
 561 %! n=5;x=linspace(0,5,n);y=linspace(0,1,n);
 562 %! imagesc(1./hilb(n)); axis equal; colorbar
 563
 564 %!demo
 565 %! clf
 566 %! n=5;x=linspace(0,5,n);y=linspace(0,1,n);
 567 %! imagesc(x,y,1./hilb(n)); axis equal; colorbar
 568
 569 %!demo
 570 %! clf
 571 %! n=5;x=linspace(0,5,n);y=linspace(0,1,n);
 572 %! imagesc(y,x,1./hilb(n)); axis equal; colorbar
 573 ## This requires that the axes position be properly determined for "axes equal"
 574
 575 %!demo
 576 %! clf
 577 %! axes
 578 %! colorbar
 579 %! hold on
 580 %! contour(peaks)
 581 %! hold off
 582
 583 %!demo
 584 %! clf
 585 %! plot([0, 2])
 586 %! colorbar ("east")
 587 %! axis square
 588
 589 %!demo
 590 %! clf
 591 %! plot([0, 2])
 592 %! colorbar ("eastoutside")
 593 %! axis square
 594
 595 %!demo
 596 %! clf
 597 %! pcolor (peaks (20))
 598 %! shading ("interp")
 599 %! axis ("tight", "square")
 600 %! colorbar ()
 601 #%! axes('color','none','box','on','activepositionproperty','position')
 602
 603 %!demo
 604 %! clf
 605 %! plot([0, 2])
 606 %! colorbar ("east")
 607 %! axis equal
 608
 609 %!demo
 610 %! clf
 611 %! plot([0, 2])
 612 %! colorbar ("eastoutside")
 613 %! axis equal