@c DO NOT EDIT!  Generated automatically by munge-texi.

@c Copyright (C) 1996, 1997, 2007 John W. Eaton
@c
@c This file is part of Octave.
@c
@c Octave is free software; you can redistribute it and/or modify it
@c under the terms of the GNU General Public License as published by the
@c Free Software Foundation; either version 3 of the License, or (at
@c your option) any later version.
@c 
@c Octave is distributed in the hope that it will be useful, but WITHOUT
@c ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
@c FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
@c for more details.
@c 
@c You should have received a copy of the GNU General Public License
@c along with Octave; see the file COPYING.  If not, see
@c <http://www.gnu.org/licenses/>.

@node Image Processing
@chapter Image Processing

Since an image basically is a matrix Octave is a very powerful
environment for processing and analysing images. To illustrate
how easy it is to do image processing in Octave, the following
example will load an image, smooth it by a 5-by-5 averaging filter,
and compute the gradient of the smoothed image.

@example
I = loadimage ("default.img");
S = conv2 (I, ones (5, 5) / 25, "same");
[Dx, Dy] = gradient (S);
@end example

@noindent
In this example @code{S} contains the smoothed image, and @code{Dx}
and @code{Dy} contains the partial spatial derivatives of the image.

@menu
* Loading and Saving Images::   
* Displaying Images::           
* Representing Images::         
* Plotting on top of Images::   
* Color Conversion::            
@end menu

@node Loading and Saving Images
@section Loading and Saving Images

The first step in most image processing tasks is to load an image
into Octave. Currently Octave only support saving images in the
Portable Pixmap Format (PPM), PostScript, and Octave's own format, and
loading images in Octave's format. Most image processing code will
follow the structure of this code

@example
I = loadimage ("my_input_image.img");
J = process_my_image (I);
saveimage ("my_output_image.img", J);
@end example

@anchor{doc-loadimage}
@deftypefn {Function File} {[@var{x}, @var{map}] =} loadimage (@var{file})
Load an image file and it's associated color map from the specified
@var{file}.  The image must be stored in Octave's image format.
@seealso{saveimage, load, save}
@end deftypefn


@anchor{doc-saveimage}
@deftypefn {Function File} {} saveimage (@var{file}, @var{x}, @var{fmt}, @var{map})
Save the matrix @var{x} to @var{file} in image format @var{fmt}.  Valid
values for @var{fmt} are

@table @code
@item "img"
Octave's image format.  The current colormap is also saved in the file.

@item "ppm"
Portable pixmap format.

@item "ps"
PostScript format.  Note that images saved in PostScript format can not
be read back into Octave with loadimage.
@end table

If the fourth argument is supplied, the specified colormap will also be
saved along with the image.

Note: if the colormap contains only two entries and these entries are
black and white, the bitmap ppm and PostScript formats are used.  If the
image is a gray scale image (the entries within each row of the colormap
are equal) the gray scale ppm and PostScript image formats are used,
otherwise the full color formats are used.
@seealso{loadimage, save, load, colormap}
@end deftypefn


@anchor{doc-IMAGE_PATH}
@deftypefn {Built-in Function} {@var{val} =} IMAGE_PATH ()
@deftypefnx {Built-in Function} {@var{old_val} =} IMAGE_PATH (@var{new_val})
Query or set the internal variable that specifies a colon separated
list of directories in which to search for image files.
@end deftypefn


@node Displaying Images
@section Displaying Images

A natural part of image processing is visualization of an image.
The most basic function for this is the @code{imshow} function that
shows the image given in the first input argument. This function uses
an external program to show the image. If gnuplot 4.2 or later is 
available it will be used to display the image, otherwise the
@code{display}, @code{xv}, or @code{xloadimage} program is used. The
actual program can be selected with the @code{image_viewer} function.

@anchor{doc-imshow}
@deftypefn {Function File} {} imshow (@var{im})
@deftypefnx {Function File} {} imshow (@var{im}, @var{limits})
@deftypefnx {Function File} {} imshow (@var{im}, @var{map})
@deftypefnx {Function File} {} imshow (@var{rgb}, @dots{})
@deftypefnx {Function File} {} imshow (@var{filename})
@deftypefnx {Function File} {} imshow (@dots{}, @var{string_param1}, @var{value1}, @dots{})
Display the image @var{im}, where @var{im} can be a 2-dimensional
(gray-scale image) or a 3-dimensional (RGB image) matrix.

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

If @var{map} is a valid color map, the image will be shown as an indexed
image using the supplied color map.

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

If given, the parameter @var{string_param1} has value
@var{value1}. @var{string_param1} can be any of the following:
@table @samp
@item "displayrange"
@var{value1} is the display range as described above.
@end table
@seealso{image, imagesc, colormap, gray2ind, rgb2ind}
@end deftypefn


@anchor{doc-image}
@deftypefn {Function File} {} image (@var{img})
@deftypefnx {Function File} {} image (@var{x}, @var{y}, @var{img})
Display a matrix as a color image.  The elements of @var{x} are indices
into the current colormap, and the colormap will be scaled so that the
extremes of @var{x} are mapped to the extremes of teh colormap.

It first tries to use @code{gnuplot}, then @code{display} from 
@code{ImageMagick}, then @code{xv}, and then @code{xloadimage}.
The actual program used can be changed using the @code{image_viewer}
function.

The axis values corresponding to the matrix elements are specified in
@var{x} and @var{y}. If you're not using gnuplot 4.2 or later, these
variables are ignored.
@seealso{imshow, imagesc, colormap, image_viewer}
@end deftypefn


@anchor{doc-imagesc}
@deftypefn {Function File} {} imagesc (@var{a})
@deftypefnx {Function File} {} imagesc (@var{x}, @var{y}, @var{a})
@deftypefnx {Function File} {} imagesc (@dots{}, @var{limits})
@deftypefnx {Function File} {} imagesc (@var{h}, @dots{})
@deftypefnx {Function File} { @var{h} = } imagesc (@dots{})
Display a scaled version of the matrix @var{a} as a color image.  The
colormap is scaled so that the entries of the matrix occupy the entire
colormap.  If @var{limits} = [@var{lo}, @var{hi}] are given, then that
range is set to the 'clim' of the current axes.

The axis values corresponding to the matrix elements are specified in
@var{x} and @var{y}, either as pairs giving the minimum and maximum
values for the respective axes, or as values for each row and column
of the matrix @var{a}.

@seealso{image, imshow, clim, caxis}
@end deftypefn


@anchor{doc-image_viewer}
@deftypefn {Function File} {[@var{fcn}, @var{default_zoom}] =} image_viewer (@var{fcn}, @var{default_zoom})
Change the program or function used for viewing images and return the
previous values.

When the @code{image} or @code{imshow} function is called it will
launch an external program to display the image.  The default behaviour
is to use gnuplot if the installed version supports image viewing,
and otherwise try the programs @code{display}, @code{xv}, and
@code{xloadimage}.  Using this function it is possible to change that
behaviour.

When called with one input argument images will be displayed by saving
the image to a file and the system command @var{command} will called
to view the image.  The @var{command} must be a string containing
@code{%s} and possibly @code{%f}. The @code{%s} will be replaced by
the filename of the image, and the @code{%f} will (if present) be
replaced by the zoom factor given to the @code{image} function.
For example,
@example
image_viewer ("eog %s");
@end example
changes the image viewer to the @code{eog} program.

With two input arguments, images will be displayed by calling
the function @var{function_handle}.  For example,
@example
image_viewer (data, @@my_image_viewer);
@end example
sets the image viewer function to @code{my_image_viewer}.  The image
viewer function is called with
@example
my_image_viewer (@var{x}, @var{y}, @var{im}, @var{zoom}, @var{data})
@end example
where @var{x} and @var{y} are the axis of the image, @var{im} is the image
variable, and @var{data} is extra user-supplied data to be passed to
the viewer function.

With three input arguments it is possible to change the zooming.
Some programs (like @code{xloadimage}) require the zoom factor to be
between 0 and 100, and not 0 and 1 like Octave assumes. This is
solved by setting the third argument to 100.

@seealso{image, imshow}
@end deftypefn


@node Representing Images
@section Representing Images

In general Octave supports four different kinds of images, gray-scale
images, RGB images, binary images, and indexed images. A gray-scale
image is represented with an M-by-N matrix in which each
element corresponds to the intensity of a pixel. An RGB image is
represented with an M-by-N-by3 array where each
3-vector corresponds to the red, green, and blue intensities of each
pixel.

The actual meaning of the value of a pixel in a gray-scale or RGB
image depends on the class of the matrix. If the matrix is of class
@code{double} pixel intensities are between 0 and 1, if it is of class
@code{uint8} intensities are between 0 and 255, and if it is of class
@code{uint16} intensities are between 0 and 65535.

A binary image is a M-by-N matrix of class @code{logical}.
A pixel in a binary image is black if it is @code{false} and white
if it is @code{true}.

An indexed image consists of an M-by-N matrix of integers
and a C-by-3 color map. Each integer corresponds to an
index in the color map, and each row in the color map corresponds to
a RGB color. The color map must be of class @code{double} with values
between 0 and 1.

@anchor{doc-gray2ind}
@deftypefn {Function File} {[@var{img}, @var{map}] =} gray2ind (@var{})
Convert a gray scale intensity image to an Octave indexed image.
@end deftypefn


@anchor{doc-ind2gray}
@deftypefn {Function File} {} ind2gray (@var{x}, @var{map})
Convert an Octave indexed image to a gray scale intensity image.
If @var{map} is omitted, the current colormap is used to determine the
intensities.
@seealso{gray2ind, rgb2ntsc, image, colormap}
@end deftypefn


@anchor{doc-rgb2ind}
@deftypefn  {Function File} {[@var{x}, @var{map}] =} rgb2ind (@var{rgb})
@deftypefnx {Function File} {[@var{x}, @var{map}] =} rgb2ind (@var{r}, @var{g}, @var{b})
Convert and RGB image to an Octave indexed image.
@seealso{ind2rgb, rgb2ntsc}
@end deftypefn


@anchor{doc-ind2rgb}
@deftypefn {Function File} {@var{rgb} =} ind2rgb (@var{x}, @var{map})
@deftypefnx {Function File} {[@var{r}, @var{g}, @var{b}] =} ind2rgb (@var{x}, @var{map})
Convert an indexed image to red, green, and blue color components.
If the colormap doesn't contain enough colors, pad it with the
last color in the map.
If @var{map} is omitted, the current colormap is used for the conversion.
@seealso{rgb2ind, image, imshow, ind2gray, gray2ind}
@end deftypefn


@anchor{doc-colormap}
@deftypefn {Function File} {} colormap (@var{map})
@deftypefnx {Function File} {} colormap ("default")
Set the current colormap.

@code{colormap (@var{map})} sets the current colormap to @var{map}.  The
color map should be an @var{n} row by 3 column matrix.  The columns
contain red, green, and blue intensities respectively.  All entries
should be between 0 and 1 inclusive.  The new colormap is returned.

@code{colormap ("default")} restores the default colormap (the
@code{jet} map with 64 entries).  The default colormap is returned.

With no arguments, @code{colormap} returns the current color map.
@seealso{jet}
@end deftypefn


@anchor{doc-autumn}
@deftypefn {Function File} {} autumn (@var{n})
Create color colormap. This colormap is red through orange to yellow.
The argument @var{n} should be a scalar.  If it
is omitted, the length of the current colormap or 64 is assumed.
@seealso{colormap}
@end deftypefn


@anchor{doc-bone}
@deftypefn {Function File} {} bone (@var{n})
Create color colormap. This colormap is a gray colormap with a light 
blue tone. The argument @var{n} should be a scalar.  If it
is omitted, the length of the current colormap or 64 is assumed.
@seealso{colormap}
@end deftypefn


@anchor{doc-cool}
@deftypefn {Function File} {} cool (@var{n})
Create color colormap. The colormap is cyan to magenta. The argument 
@var{n} should be a scalar.  If it is omitted, the length of the current
colormap or 64 is assumed.
@seealso{colormap}
@end deftypefn


@anchor{doc-copper}
@deftypefn {Function File} {} copper (@var{n})
Create color colormap. This colormap is black to a light copper tone.
The argument @var{n} should be a scalar.  If it
is omitted, the length of the current colormap or 64 is assumed.
@seealso{colormap}
@end deftypefn


@anchor{doc-gray}
@deftypefn {Function File} {} gray (@var{n})
Return a gray colormap with @var{n} entries corresponding to values from
0 to @var{n}-1.  The argument @var{n} should be a scalar.  If it is
omitted, the length of the current colormap or 64 is assumed.
@end deftypefn


@anchor{doc-hot}
@deftypefn {Function File} {} hot (@var{n})
Create color colormap. This colormap is black through dark red, red, 
orange, yellow to white. The argument @var{n} should be a scalar.  If it
is omitted, the length of the current colormap or 64 is assumed.
@seealso{colormap}
@end deftypefn


@anchor{doc-hsv}
@deftypefn {Function File} {} hsv (@var{n})
Create color colormap. This colormap is red through yellow, green, cyan,
blue, magenta to red. The argument @var{n} should be a scalar.  If it
is omitted, the length of the current colormap or 64 is assumed.
@seealso{colormap}
@end deftypefn


@anchor{doc-jet}
@deftypefn {Function File} {} jet (@var{n})
Create color colormap. This colormap is dark blue through blue, cyan, 
green, yellow, red to dark red. The argument @var{n} should be a scalar. 
If it is omitted, the length of the current colormap or 64 is assumed.
@seealso{colormap}
@end deftypefn


@anchor{doc-ocean}
@deftypefn {Function File} {} ocean (@var{n})
Create color colormap.  The argument @var{n} should be a scalar.  If it
is omitted, the length of the current colormap or 64 is assumed.
@end deftypefn


@anchor{doc-pink}
@deftypefn {Function File} {} pink (@var{n})
Create color colormap. This colormap gives a sephia tone on black and
white images. The argument @var{n} should be a scalar.  If it
is omitted, the length of the current colormap or 64 is assumed.
@seealso{colormap}
@end deftypefn


@anchor{doc-prism}
@deftypefn {Function File} {} prism (@var{n})
Create color colormap. This colormap cycles trough red, orange, yellow,
green, blue and violet. The argument @var{n} should be a scalar.  If it
is omitted, the length of the current colormap or 64 is assumed.
@seealso{colormap}
@end deftypefn


@anchor{doc-rainbow}
@deftypefn {Function File} {} rainbow (@var{n})
Create color colormap. This colormap is red through orange, yellow, green, 
blue to violet. The argument @var{n} should be a scalar.  If it
is omitted, the length of the current colormap or 64 is assumed.
@seealso{colormap}
@end deftypefn


@anchor{doc-spring}
@deftypefn {Function File} {} spring (@var{n})
Create color colormap. This colormap is magenta to yellow.
The argument @var{n} should be a scalar.  If it
is omitted, the length of the current colormap or 64 is assumed.
@seealso{colormap}
@end deftypefn


@anchor{doc-summer}
@deftypefn {Function File} {} summer (@var{n})
Create color colormap. This colormap is green to yellow.
The argument @var{n} should be a scalar.  If it
is omitted, the length of the current colormap or 64 is assumed.
@seealso{colormap}
@end deftypefn


@anchor{doc-white}
@deftypefn {Function File} {} white (@var{n})
Create color colormap.  This colormap is completely white.
The argument @var{n} should be a scalar.  If it
is omitted, the length of the current colormap or 64 is assumed.
@seealso{colormap}
@end deftypefn


@anchor{doc-winter}
@deftypefn {Function File} {} winter (@var{n})
Create color colormap. This colormap is blue to green.
The argument @var{n} should be a scalar.  If it
is omitted, the length of the current colormap or 64 is assumed.
@seealso{colormap}
@end deftypefn


An additional colormap is @code{gmap40}. This code map contains only
colors with integer values of the red, green and blue components. This
workaround a limitation on gnuplot 4.0, that does not allow the color of
line or patch objects to be set, and so @code{gmap40} is useful for
gnuplot 4.0 users, and in particular in conjunction with the @var{bar},
@var{barh} or @var{contour} functions.

@anchor{doc-gmap40}
@deftypefn {Function File} {} gmap40 (@var{n})
Create a color colormap. The colormap is red, green, blue, yellow,
magneta and cyan. These are the colors that are allowed with patch
objects using gnuplot 4.0, and so this colormap function is specially
designed for users of gnuplot 4.0.  The argument @var{n} should be 
a scalar.  If it is omitted, a length of 6 is assumed. Larger values
of @var{n} result in a repetition of the above colors
@seealso{colormap}
@end deftypefn


@node Plotting on top of Images
@section Plotting on top of Images

If gnuplot is being used to display images it is possible to plot on
top of images. Since an image is a matrix it is indexed by row and
column values. The plotting system is, however, based on the 
traditional @math{(x, y)} system. To minimize the difference between
the two systems Octave places the origin of the coordinate system in
the point corresponding to the pixel at @math{(1, 1)}. So, to plot
points given by row and column values on top of an image, one should
simply call @code{plot} with the column values as the first argument
and the row values as the second. As an example the following code
generates an image with random intensities between 0 and 1, and shows
the image with red circles over pixels with an intensity above 
@math{0.99}.

@example
I = rand (100, 100);
[row, col] = find (I > 0.99);
hold ("on");
imshow (I);
plot (col, row, "ro");
hold ("off");
@end example

@node Color Conversion
@section Color Conversion

Octave supports conversion from the RGB color system to NTSC and HSV
and vice versa. 

@anchor{doc-rgb2hsv}
@deftypefn {Function File} {@var{hsv_map} =} rgb2hsv (@var{rgb_map})
Transform a colormap from the rgb space to the hsv space.

A color n the RGB space consists of the red, green and blue intensities.

In the HSV space each color is represented by their hue, saturation
and value (brightness).  Value gives the amount of light in the color.
Hue describes the dominant wavelength. 
Saturation is the amount of Hue mixed into the color.
@seealso{hsv2rgb}
@end deftypefn


@anchor{doc-hsv2rgb}
@deftypefn {Function File} {@var{rgb_map} =} hsv2rgb (@var{hsv_map})
Transform a colormap from the hsv space to the rgb space. 
@seealso{rgb2hsv}
@end deftypefn


@anchor{doc-rgb2ntsc}
@deftypefn {Function File} {} rgb2ntsc (@var{rgb})
Image format conversion.
@end deftypefn


@anchor{doc-ntsc2rgb}
@deftypefn {Function File} {} ntsc2rgb (@var{yiq})
Image format conversion.
@end deftypefn



