@c Copyright (C) 1996, 1997, 2007, 2008, 2009 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 analyzing 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
@group
I = imread ("myimage.jpg");
S = conv2 (I, ones (5, 5) / 25, "same");
[Dx, Dy] = gradient (S);
@end group
@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.  This is done using the @code{imread} function, which uses the
@code{GraphicsMagick} library for reading.  This means a vast number of image
formats is supported.  The @code{imwrite} function is the corresponding function
for writing images to the disk.

In summary, most image processing code will follow the structure of this code

@example
@group
I = imread ("my_input_image.img");
J = process_my_image (I);
imwrite ("my_output_image.img", J);
@end group
@end example

@DOCSTRING(imread)

@DOCSTRING(imwrite)

@DOCSTRING(IMAGE_PATH)

It is possible to get information about an image file on disk, without actually
reading it into Octave.  This is done using the @code{imfinfo} function which
provides read access to many of the parameters stored in the header of the image
file.

@DOCSTRING(imfinfo)

@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.

@DOCSTRING(imshow)

@DOCSTRING(image)

@DOCSTRING(imagesc)

@DOCSTRING(image_viewer)

@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-by-3 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 an 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
an RGB color.  The color map must be of class @code{double} with values
between 0 and 1.

@DOCSTRING(gray2ind)

@DOCSTRING(ind2gray)

@DOCSTRING(rgb2ind)

@DOCSTRING(ind2rgb)

@DOCSTRING(colormap)

@DOCSTRING(brighten)

@DOCSTRING(autumn)

@DOCSTRING(bone)

@DOCSTRING(cool)

@DOCSTRING(copper)

@DOCSTRING(flag)

@DOCSTRING(gray)

@DOCSTRING(hot)

@DOCSTRING(hsv)

@DOCSTRING(jet)

@DOCSTRING(ocean)

@DOCSTRING(pink)

@DOCSTRING(prism)

@DOCSTRING(rainbow)

@DOCSTRING(spring)

@DOCSTRING(summer)

@DOCSTRING(white)

@DOCSTRING(winter)

@DOCSTRING(contrast)

An additional colormap is @code{gmap40}.  This code map contains only
colors with integer values of the red, green and blue components.  This
is a workaround for a limitation of 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.

@DOCSTRING(gmap40)

You may use the @code{spinmap} function to cycle through the colors in
the current colormap, displaying the changes for the current figure.

@DOCSTRING(spinmap)

@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
@group
I = rand (100, 100);
[row, col] = find (I > 0.99);
hold ("on");
imshow (I);
plot (col, row, "ro");
hold ("off");
@end group
@end example

@node Color Conversion
@section Color Conversion

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

@DOCSTRING(rgb2hsv)

@DOCSTRING(hsv2rgb)

@DOCSTRING(rgb2ntsc)

@DOCSTRING(ntsc2rgb)