octave_packages/m/image/imshow.m

   1 ## Copyright (C) 1994-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} {} imshow (@var{im})
  21 ## @deftypefnx {Function File} {} imshow (@var{im}, @var{limits})
  22 ## @deftypefnx {Function File} {} imshow (@var{im}, @var{map})
  23 ## @deftypefnx {Function File} {} imshow (@var{rgb}, @dots{})
  24 ## @deftypefnx {Function File} {} imshow (@var{filename})
  25 ## @deftypefnx {Function File} {} imshow (@dots{}, @var{string_param1}, @var{value1}, @dots{})
  26 ## @deftypefnx {Function File} {@var{h} =} imshow (@dots{})
  27 ## Display the image @var{im}, where @var{im} can be a 2-dimensional
  28 ## (gray-scale image) or a 3-dimensional (RGB image) matrix.
  29 ##
  30 ## If @var{limits} is a 2-element vector @code{[@var{low}, @var{high}]},
  31 ## the image is shown using a display range between @var{low} and
  32 ## @var{high}.  If an empty matrix is passed for @var{limits}, the
  33 ## display range is computed as the range between the minimal and the
  34 ## maximal value in the image.
  35 ##
  36 ## If @var{map} is a valid color map, the image will be shown as an indexed
  37 ## image using the supplied color map.
  38 ##
  39 ## If a file name is given instead of an image, the file will be read and
  40 ## shown.
  41 ##
  42 ## If given, the parameter @var{string_param1} has value
  43 ## @var{value1}.  @var{string_param1} can be any of the following:
  44 ## @table @asis
  45 ## @item "displayrange"
  46 ## @var{value1} is the display range as described above.
  47 ## @end table
  48 ##
  49 ## The optional return value @var{h} is a graphics handle to the image.
  50 ## @seealso{image, imagesc, colormap, gray2ind, rgb2ind}
  51 ## @end deftypefn
  52
  53 ## Author: Stefan van der Walt  <stefan@sun.ac.za>
  54 ## Author: Soren Hauberg <hauberg at gmail dot com>
  55 ## Adapted-By: jwe
  56
  57 function h = imshow (im, varargin)
  58
  59   if (nargin == 0)
  60     print_usage ();
  61   endif
  62
  63   display_range = NA;
  64   true_color = false;
  65   indexed = false;
  66
  67   ## Get the image.
  68   if (ischar (im))
  69     [im, map] = imread (im);
  70     indexed = true;
  71     colormap (map);
  72   endif
  73
  74   nd = ndims (im);
  75
  76   if (! ((isnumeric (im) || islogical (im)) && (nd == 2 || nd == 3)))
  77     error ("imshow: IM must be an image or the filename of an image");
  78   endif
  79
  80   if (nd == 2)
  81     if (! indexed)
  82       colormap (gray ());
  83     endif
  84   elseif (size (im, 3) == 3)
  85     if (ismember (class (im), {"uint8", "uint16", "double", "single"}))
  86       true_color = true;
  87     else
  88       error ("imshow: color image must be uint8, uint16, double, or single");
  89     endif
  90   else
  91     error ("imshow: expecting MxN or MxNx3 matrix for image");
  92   endif
  93
  94   narg = 1;
  95   while (narg <= numel (varargin))
  96     arg = varargin{narg++};
  97     if (isnumeric (arg))
  98       if (numel (arg) == 2 || isempty (arg))
  99         display_range = arg;
 100       elseif (columns (arg) == 3)
 101         indexed = true;
 102         colormap (arg);
 103       elseif (! isempty (arg))
 104         error ("imshow: argument number %d is invalid", narg+1);
 105       endif
 106     elseif (ischar (arg))
 107       switch (arg)
 108         case "displayrange";
 109           display_range = varargin{narg++};
 110         case {"truesize", "initialmagnification"}
 111           warning ("image: zoom argument ignored -- use GUI features");
 112         otherwise
 113           warning ("imshow: unrecognized property %s", arg);
 114           narg++;
 115       endswitch
 116     else
 117       error ("imshow: argument number %d is invalid", narg+1);
 118     endif
 119   endwhile
 120
 121   ## Check for complex images.
 122   if (iscomplex (im))
 123     warning ("imshow: only showing real part of complex image");
 124     im = real (im);
 125   endif
 126
 127   ## Set default display range if display_range not set yet.
 128   if (isempty (display_range))
 129     display_range = [min(im(:)), max(im(:))];
 130   elseif (isna (display_range))
 131     t = class (im);
 132     switch (t)
 133       case {"double", "single", "logical"}
 134         display_range = [0, 1];
 135       case {"int8", "int16", "int32", "uint8", "uint16", "uint32"}
 136         display_range = [intmin(t), intmax(t)];
 137       otherwise
 138         error ("imshow: invalid data type for image");
 139     endswitch
 140   endif
 141
 142   nans = isnan (im(:));
 143   if (any (nans))
 144     warning ("Octave:imshow-NaN",
 145              "imshow: pixels with NaN or NA values are set to minimum pixel value");
 146     im(nans) = display_range(1);
 147   endif
 148
 149   ## This is for compatibility.
 150   if (! (indexed || (true_color && isinteger (im))) || islogical (im))
 151     im = double (im);
 152   endif
 153
 154   ## Clamp the image to the range boundaries
 155   if (! (true_color || indexed || islogical (im)))
 156     low = display_range(1);
 157     high = display_range(2);
 158     im(im < low) = low;
 159     im(im > high) = high;
 160   endif
 161
 162   if (true_color || indexed)
 163     tmp = image ([], [], im);
 164   else
 165     tmp = image (im);
 166     set (tmp, "cdatamapping", "scaled");
 167     ## The backend is responsible for scaling to clim if necessary.
 168     set (gca (), "clim", display_range);
 169   endif
 170   set (gca (), "visible", "off", "ydir", "reverse");
 171   axis ("image");
 172
 173   if (nargout > 0)
 174     h = tmp;
 175   endif
 176
 177 endfunction
 178
 179 %!error imshow ()                           # no arguments
 180 %!error imshow ({"cell"})                   # No image or filename given
 181 %!error imshow (ones(4,4,4))                # Too many dimensions in image
 182
 183 %!demo
 184 %!  imshow ("default.img");
 185
 186 %!demo
 187 %!  imshow ("default.img");
 188 %!  colormap ("autumn");
 189
 190 %!demo
 191 %!  [I, M] = imread ("default.img");
 192 %!  imshow (I, M);
 193
 194 %!demo
 195 %!  [I, M] = imread ("default.img");
 196 %!  [R, G, B] = ind2rgb (I, M);
 197 %!  imshow (cat(3, R, G*0.5, B*0.8));
 198
 199 %!demo
 200 %!  imshow (rand (100, 100));
 201
 202 %!demo
 203 %!  imshow (rand (100, 100, 3));
 204
 205 %!demo
 206 %!  imshow (100*rand (100, 100, 3));
 207
 208 %!demo
 209 %!  imshow (rand (100, 100));
 210 %!  colormap (jet);