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

@c Copyright (C) 1996, 1997 John W. Eaton
@c This is part of the Octave manual.
@c For copying conditions, see the file gpl.texi.

@node Image Processing
@chapter Image Processing

Octave can display images with the X Window System using the
@code{xloadimage} program.  You do not need to be running X in order to
manipulate images, however, so some of these functions may be useful
even if you are not able to view the results.

Loading images only works with Octave's image format (a file with a
matrix containing the image data, and a matrix containing the
colormap).  Contributions of robust, well-written functions to read
other image formats are welcome.  If you can provide them, or would like
to improve Octave's image processing capabilities in other ways, please
contact @email{bug@@octave.org}.

@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 (a gray scale
colormap with 64 entries).  The default colormap is returned.

With no arguments, @code{colormap} returns the current color map.
@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, 64 is assumed.
@end deftypefn


@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-image}
@deftypefn {Function File} {} image (@var{x}, @var{zoom})
@deftypefnx {Function File} {} image (@var{x}, @var{y}, @var{A}, @var{zoom})
Display a matrix as a color image.  The elements of @var{x} are indices
into the current colormap and should have values between 1 and the
length of the colormap.  If @var{zoom} is omitted, the image will be
scaled to fit within 600x350 (to a max of 4).

It first tries to use @code{display} from @code{ImageMagick} then
@code{xv} and then @code{xloadimage}.

The axis values corresponding to the matrix elements are specified in
@var{x} and @var{y}. At present they are ignored.
@end deftypefn

@seealso{imshow, imagesc, and colormap}


@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{zoom})
@deftypefnx {Function File} {} imagesc (@dots{}, @var{limits})
@deftypefnx {Function File} { @var{B} = } imagesc (@dots{})
Display a scaled version of the matrix @var{A} as a color image.  The
matrix is scaled so that its entries are indices into the current
colormap.  The scaled matrix is returned.  If @var{zoom} is omitted, a
comfortable size is chosen.  If @var{limits} = [@var{lo}, @var{hi}] are
given, then that range maps into the full range of the colormap rather 
than the minimum and maximum values of @var{A}.

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}.  At present they are ignored.
@end deftypefn

@seealso{image and imshow}


@anchor{doc-imshow}
@deftypefn {Function File} {} imshow (@var{i})
@deftypefnx {Function File} {} imshow (@var{x}, @var{map})
@deftypefnx {Function File} {} imshow (@var{i}, @var{n})
@deftypefnx {Function File} {} imshow (@var{r}, @var{g}, @var{b})
Display an image.

@code{imshow (@var{x})} displays an image @var{x}.
The numerical class of the image determines its bit-depth: 1 for
@code{logical}, 8 for @code{uint8} and @code{logical}, and 16 for
@code{double} or @code{uint16}.  If @var{x} has dimensions MxNx3, the
three matrices represent the red, green and blue components of the
image.

@code{imshow (@var{x}, @var{map})} displays an indexed image using the
specified colormap.

@code{imshow (@var{i}, @var{n})} displays a gray scale intensity image of
N levels.

@code{imshow (@var{r}, @var{g}, @var{b})} displays an RGB image.

The character string @code{"truesize"} can always be used as an
optional final argument to prevent automatic zooming of the image.
@end deftypefn
@seealso{image, imagesc, colormap, gray2ind, and rgb2ind}


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

@seealso{gray2ind, rgb2ntsc, image, and colormap}


@anchor{doc-ind2rgb}
@deftypefn {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 @var{map} is omitted, the current colormap is used for the conversion.
@end deftypefn

@seealso{rgb2ind, image, imshow, ind2gray, and gray2ind}


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

@seealso{saveimage, load, and save}


@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


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

@seealso{rgb2hsv}


@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 wavelegth. 
Saturation is the amount of Hue mixed into the color. 
@end deftypefn

@seealso{hsv2rgb}


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


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

@seealso{ind2rgb and rgb2ntsc}


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

@seealso{loadimage, save, load, and colormap}


@anchor{doc-IMAGEPATH}
@defvr {Built-in Variable} IMAGEPATH
A colon separated list of directories in which to search for image
files.
@end defvr

