### 32.2 Displaying Images ¶

A natural part of image processing is visualization of an image. The most basic function for this is the `imshow` function that shows the image given in the first input argument.

imshow `(im)` ¶
imshow `(im, limits)` ¶
imshow `(im, map)` ¶
imshow `(rgb, …)` ¶
imshow `(filename)` ¶
imshow `(…, string_param1, value1, …)` ¶
`h =` imshow `(…)` ¶

  Display the image im, where im can be a 2-dimensional (grayscale image) or a 3-dimensional (RGB image) matrix.

  If limits is a 2-element vector `[low, high]`, the image is shown using a display range between low and high. If an empty matrix is passed for limits, the display range is computed as the range between the minimal and the maximal value in the image.

  If map is a valid colormap, the image will be shown as an indexed image using the supplied colormap.

  If a filename is given instead of an image, the file will be read and shown.

  If given, the parameter string_param1 has value value1. string_param1 can be any of the following:

  `"displayrange"`

    value1 is the display range as described above.

  `"colormap"`

    value1 is the colormap to use when displaying an indexed image.

  `"xdata"`

    If value1 is a 2-element vector, it must contain horizontal image limits in the form [xfirst, xlast], where xfirst and xlast are the abscissa of the centers of the corner pixels. Otherwise value1 must be a vector and only the first and last elements will be used for xfirst and xlast respectively.

  `"ydata"`

    If value1 is a 2-element vector, it must contain vertical image limits in the form [yfirst, ylast], where yfirst and ylast are the ordinates of the center of the corner pixels. Otherwise value1 must be a vector and only the first and last elements will be used for yfirst and ylast respectively.

  The optional return value h is a graphics handle to the image.

  See also: image, imagesc, colormap, gray2ind, rgb2ind.

image `(img)` ¶
image `(x, y, img)` ¶
image `("CData", img)` ¶
image `("XData", x, "YData", y, "CData", img)` ¶
image `(…, prop, val)` ¶
image `(hax, …)` ¶
`h =` image `(…)` ¶

  Display a matrix as an image.

  img may be a 2-D matrix where each element is an index into the current colormap. For floating point data, the value 1 chooses the first color in the colormap. For integer data, the value 0 chooses the first color in the colormap.

  Or img may be a 3-D matrix where the third dimension is an RGB triplet specifying the color. If the image data is floating point then the data must be in the range [0, 1]. If the image data is of integer type (uint8 or uint16) then the data must be in the range [0, INTMAX].

  x and y are optional 1-element (`[min]`) or 2-element vectors (`[min, max]`) which specify the coordinate(s) of the center of a corner pixel. If unspecified, the default minimum value is 1 and the maximum is the length of img along the specific dimension. If a range is specified as `[max, min]` then the image will be reversed along that axis. For convenience, x and y may be specified as vectors, however, only the first and last elements will be used to determine the axis limits.

  Multiple property/value pairs may be specified for the image object, but they must appear in pairs.

  If the first argument hax is an axes handle, then plot into this axes, rather than the current axes returned by `gca`.

  The optional return value h is a graphics handle to the image.

  Implementation Note: The origin (0, 0) for images is located in the upper left. For ordinary plots, the origin is located in the lower left. Octave handles this inversion by plotting the data normally, and then reversing the direction of the y-axis by setting the `ydir` property to `"reverse"`. This has implications whenever an image and an ordinary plot need to be overlaid. The recommended solution is to display the image and then plot the reversed ydata using, for example, `flipud (ydata)`.

  Calling Forms: The `image` function can be called in two forms: High-Level and Low-Level. When invoked with normal options, the High-Level form is used which first calls `newplot` to prepare the graphic figure and axes. When the only inputs to `image` are property/value pairs the Low-Level form is used which creates a new instance of an image object and inserts it in the current axes (as if `hold on` was in effect).

  Graphic Properties: The full list of properties is documented at Image Properties.

  See also: imshow, imagesc, colormap.

imagesc `(img)` ¶
imagesc `(x, y, img)` ¶
imagesc `(…, climits)` ¶
imagesc `(…, "prop", val, …)` ¶
imagesc `("prop1", val1, …)` ¶
imagesc `(hax, …)` ¶
`h =` imagesc `(…)` ¶

  Display a scaled version of the matrix img as a color image.

  The colormap is scaled so that the entries of the matrix occupy the entire colormap. If `climits = [lo, hi]` is given, then that range is set to the `"clim"` of the current axes.

  x and y are optional 2-element vectors, `[min, max]`, which specify the coordinates of the centers of the corner pixels. If a range is specified as `[max, min]` then the image will be reversed along that axis. For convenience, x and y may be specified as N-element vectors matching the length of the data in img. However, only the first and last elements will be used to determine the image limits.

  The optional return value h is a graphics handle to the image.

  Calling Forms: The `imagesc` function can be called in two forms: High-Level and Low-Level. When invoked with normal options, the High-Level form is used which first calls `newplot` to prepare the graphic figure and axes. When the only inputs to `image` are property/value pairs the Low-Level form is used which creates a new instance of an image object and inserts it in the current axes. The full list of properties is documented at Image Properties.

  See also: image, imshow, clim.