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

@c Copyright (C) 1996-2012 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

@c imread scripts/image/imread.m
@anchor{doc-imread}
@deftypefn {Function File} {[@var{img}, @var{map}, @var{alpha}] =} imread (@var{filename})
Read images from various file formats.

The size and numeric class of the output depends on the
format of the image.  A color image is returned as an
@nospell{MxNx3} matrix.  Gray-level and black-and-white images are
of size @nospell{MxN}.
The color depth of the image determines the numeric
class of the output: "uint8" or "uint16" for gray
and color, and "logical" for black and white.

@seealso{@ref{doc-imwrite,,imwrite}, @ref{doc-imfinfo,,imfinfo}}
@end deftypefn


@c imwrite scripts/image/imwrite.m
@anchor{doc-imwrite}
@deftypefn  {Function File} {} imwrite (@var{img}, @var{filename})
@deftypefnx {Function File} {} imwrite (@var{img}, @var{filename}, @var{fmt})
@deftypefnx {Function File} {} imwrite (@var{img}, @var{filename}, @var{fmt}, @var{p1}, @var{v1}, @dots{})
@deftypefnx {Function File} {} imwrite (@var{img}, @var{map}, @var{filename}, @dots{})
Write images in various file formats.

If @var{fmt} is not supplied, the file extension of @var{filename} is used
to determine the format.

The parameter-value pairs (@var{p1}, @var{v1}, @dots{}) are optional.
Currently the following options are supported for @t{JPEG} images:

@table @samp
@item Quality
Set the quality of the compression.  The value should be an
integer between 0 and 100, with larger values indicating higher visual
quality and lower compression.
@end table

@strong{Supported Formats}
@multitable @columnfractions .33 .66
@headitem Extension @tab Format
@item bmp @tab Windows Bitmap
@item gif @tab Graphics Interchange Format
@item jpg and jpeg @tab Joint Photographic Experts Group
@item pbm @tab Portable Bitmap
@item pcx @tab
@item pgm @tab Portable Graymap
@item png @tab Portable Network Graphics
@item pnm @tab Portable Anymap
@item ppm @tab Portable Pixmap
@item ras @tab Sun Raster
@item tif and tiff @tab Tagged Image File Format
@item xwd @tab X11 Dump
@end multitable

@strong{Unsupported Formats}
@multitable @columnfractions .33 .66
@headitem Extension @tab Format
@item hdf @tab Hierarchical Data Format V4
@item @nospell{jp2} and jpx @tab Joint Photographic Experts Group 2000
@end multitable

@seealso{@ref{doc-imread,,imread}, @ref{doc-imfinfo,,imfinfo}}
@end deftypefn


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

When called from inside a function with the "local" option, the variable is
changed locally for the function and any subroutines it calls.  The original
variable value is restored when exiting the function.
@end deftypefn


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.

@c imfinfo scripts/image/imfinfo.m
@anchor{doc-imfinfo}
@deftypefn  {Function File} {@var{info} =} imfinfo (@var{filename})
@deftypefnx {Function File} {@var{info} =} imfinfo (@var{url})
Read image information from a file.

@code{imfinfo} returns a structure containing information about the image
stored in the file @var{filename}.  The output structure contains the
following fields.

@table @samp
@item Filename
The full name of the image file.

@item FileSize
Number of bytes of the image on disk

@item FileModDate
Date of last modification to the file.

@item Height
Image height in pixels.

@item Width
Image Width in pixels.

@item BitDepth
Number of bits per channel per pixel.

@item Format
Image format (e.g., @code{"jpeg"}).

@item LongFormat
Long form image format description.

@item XResolution
X resolution of the image.

@item YResolution
Y resolution of the image.

@item TotalColors
Number of unique colors in the image.

@item TileName
Tile name.

@item AnimationDelay
Time in 1/100ths of a second (0 to 65535) which must expire before displaying
the next image in an animated sequence.

@item AnimationIterations
Number of iterations to loop an animation (e.g., Netscape loop extension)
for.

@item ByteOrder
Endian option for formats that support it.  Is either @code{"little-endian"},
@code{"big-endian"}, or @code{"undefined"}.

@item Gamma
Gamma level of the image.  The same color image displayed on two different
workstations may look different due to differences in the display monitor.

@item Matte
@code{true} if the image has transparency.

@item ModulusDepth
Image modulus depth (minimum number of bits required to support
red/green/blue
components without loss of accuracy).

@item Quality
JPEG/MIFF/PNG compression level.

@item QuantizeColors
Preferred number of colors in the image.

@item ResolutionUnits
Units of image resolution.  Is either @code{"pixels per inch"},
@code{"pixels per centimeter"}, or @code{"undefined"}.

@item ColorType
Image type.  Is either @code{"grayscale"}, @code{"indexed"},
@code{"truecolor"},
or @code{"undefined"}.

@item View
FlashPix viewing parameters.
@end table

@seealso{@ref{doc-imread,,imread}, @ref{doc-imwrite,,imwrite}}
@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.

@c imshow scripts/image/imshow.m
@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{})
@deftypefnx {Function File} {@var{h} =} imshow (@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 @asis
@item "displayrange"
@var{value1} is the display range as described above.
@end table

The optional return value @var{h} is a graphics handle to the image.
@seealso{@ref{doc-image,,image}, @ref{doc-imagesc,,imagesc}, @ref{doc-colormap,,colormap}, @ref{doc-gray2ind,,gray2ind}, @ref{doc-rgb2ind,,rgb2ind}}
@end deftypefn


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

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.

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
@code{ydir} property to @code{"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, @code{flipud (ydata,1)}.

The optional return value @var{h} is a graphics handle to the image.
@seealso{@ref{doc-imshow,,imshow}, @ref{doc-imagesc,,imagesc}, @ref{doc-colormap,,colormap}}
@end deftypefn


@c imagesc scripts/image/imagesc.m
@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}.

The optional return value @var{h} is a graphics handle to the image.
@seealso{@ref{doc-image,,image}, @ref{doc-imshow,,imshow}, @ref{doc-caxis,,caxis}}
@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-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.

@c gray2ind scripts/image/gray2ind.m
@anchor{doc-gray2ind}
@deftypefn {Function File} {[@var{img}, @var{map}] =} gray2ind (@var{I}, @var{n})
Convert a gray scale intensity image to an Octave indexed image.
The indexed image will consist of @var{n} different intensity values.  If not
given @var{n} will default to 64.
@end deftypefn


@c ind2gray scripts/image/ind2gray.m
@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{@ref{doc-gray2ind,,gray2ind}, @ref{doc-rgb2ntsc,,rgb2ntsc}, @ref{doc-image,,image}, @ref{doc-colormap,,colormap}}
@end deftypefn


@c rgb2ind scripts/image/rgb2ind.m
@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 an RGB image to an Octave indexed image.
@seealso{@ref{doc-ind2rgb,,ind2rgb}, @ref{doc-rgb2ntsc,,rgb2ntsc}}
@end deftypefn


@c ind2rgb scripts/image/ind2rgb.m
@anchor{doc-ind2rgb}
@deftypefn  {Function File} {@var{rgb} =} ind2rgb (@var{x}, @var{map})
@deftypefnx {Function File} {[@var{R}, @var{R}, @var{R}] =} 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{@ref{doc-rgb2ind,,rgb2ind}, @ref{doc-image,,image}, @ref{doc-imshow,,imshow}, @ref{doc-ind2gray,,ind2gray}, @ref{doc-gray2ind,,gray2ind}}
@end deftypefn


@c colormap scripts/image/colormap.m
@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{@ref{doc-jet,,jet}}
@end deftypefn


@c autumn scripts/image/autumn.m
@anchor{doc-autumn}
@deftypefn  {Function File} {@var{map} =} autumn ()
@deftypefnx {Function File} {@var{map} =} autumn (@var{n})
Create color colormap.  This colormap ranges from red through orange
to yellow.
The argument @var{n} must be a scalar.
If unspecified, the length of the current colormap, or 64, is used.
@seealso{@ref{doc-colormap,,colormap}}
@end deftypefn


@c bone scripts/image/bone.m
@anchor{doc-bone}
@deftypefn  {Function File} {@var{map} =} bone ()
@deftypefnx {Function File} {@var{map} =} bone (@var{n})
Create color colormap.  This colormap varies from black to white with
gray-blue shades.
The argument @var{n} must be a scalar.
If unspecified, the length of the current colormap, or 64, is used.
@seealso{@ref{doc-colormap,,colormap}}
@end deftypefn


@c cool scripts/image/cool.m
@anchor{doc-cool}
@deftypefn  {Function File} {@var{map} =} cool ()
@deftypefnx {Function File} {@var{map} =} cool (@var{n})
Create color colormap.  The colormap varies from cyan to magenta.
The argument @var{n} must be a scalar.
If unspecified, the length of the current colormap, or 64, is used.
@seealso{@ref{doc-colormap,,colormap}}
@end deftypefn


@c copper scripts/image/copper.m
@anchor{doc-copper}
@deftypefn  {Function File} {@var{map} =} copper ()
@deftypefnx {Function File} {@var{map} =} copper (@var{n})
Create color colormap.  This colormap varies from black to
a light copper tone.
The argument @var{n} must be a scalar.
If unspecified, the length of the current colormap, or 64, is used.
@seealso{@ref{doc-colormap,,colormap}}
@end deftypefn


@c flag scripts/image/flag.m
@anchor{doc-flag}
@deftypefn  {Function File} {@var{map} =} flag ()
@deftypefnx {Function File} {@var{map} =} flag (@var{n})
Create color colormap.  This colormap cycles through red, white, blue
and black with each index change.
The argument @var{n} must be a scalar.
If unspecified, the length of the current colormap, or 64, is used.
@seealso{@ref{doc-colormap,,colormap}}
@end deftypefn


@c gray scripts/image/gray.m
@anchor{doc-gray}
@deftypefn  {Function File} {@var{map} =} gray ()
@deftypefnx {Function File} {@var{map} =} gray (@var{n})
Create gray colormap.  This colormap varies from black to white with
shades of gray.
The argument @var{n} must be a scalar.
If unspecified, the length of the current colormap, or 64, is used.
@end deftypefn


@c hot scripts/image/hot.m
@anchor{doc-hot}
@deftypefn  {Function File} {@var{map} =} hot ()
@deftypefnx {Function File} {@var{map} =} hot (@var{n})
Create color colormap.  This colormap ranges from black through dark red,
red, orange, yellow, to white.
The argument @var{n} must be a scalar.
If unspecified, the length of the current colormap, or 64, is used.
@seealso{@ref{doc-colormap,,colormap}}
@end deftypefn


@c hsv scripts/image/hsv.m
@anchor{doc-hsv}
@deftypefn {Function File} {} hsv (@var{n})
Create color colormap.  This colormap begins with red, changes through
yellow, green, cyan, blue, and magenta, before returning to red.
It is useful for displaying periodic functions.  It is obtained by linearly
varying the hue through all possible values while keeping constant maximum
saturation and value and is equivalent to
@code{hsv2rgb ([linspace(0,1,N)', ones(N,2)])}.

The argument @var{n} must be a scalar.
If unspecified, the length of the current colormap, or 64, is used.
@seealso{@ref{doc-colormap,,colormap}}
@end deftypefn


@c jet scripts/image/jet.m
@anchor{doc-jet}
@deftypefn  {Function File} {@var{map} =} jet ()
@deftypefnx {Function File} {@var{map} =} jet (@var{n})
Create color colormap.  This colormap ranges from dark blue through blue,
cyan, green, yellow, red, to dark red.
The argument @var{n} must be a scalar.
If unspecified, the length of the current colormap, or 64, is used.
@seealso{@ref{doc-colormap,,colormap}}
@end deftypefn


@c ocean scripts/image/ocean.m
@anchor{doc-ocean}
@deftypefn  {Function File} {@var{map} =} ocean ()
@deftypefnx {Function File} {@var{map} =} ocean (@var{n})
Create color colormap.  This colormap varies from black to white with shades
of blue.
The argument @var{n} must be a scalar.
If unspecified, the length of the current colormap, or 64, is used.
@end deftypefn


@c pink scripts/image/pink.m
@anchor{doc-pink}
@deftypefn  {Function File} {@var{map} =} pink ()
@deftypefnx {Function File} {@var{map} =} pink (@var{n})
Create color colormap.  This colormap varies from black to white with
shades of gray-pink.  It gives a sepia tone when used on grayscale images.
The argument @var{n} must be a scalar.
If unspecified, the length of the current colormap, or 64, is used.
@seealso{@ref{doc-colormap,,colormap}}
@end deftypefn


@c prism scripts/image/prism.m
@anchor{doc-prism}
@deftypefn  {Function File} {@var{map} =} prism ()
@deftypefnx {Function File} {@var{map} =} prism (@var{n})
Create color colormap.  This colormap cycles through red, orange, yellow,
green, blue and violet with each index change.
The argument @var{n} must be a scalar.
If unspecified, the length of the current colormap, or 64, is used.
@seealso{@ref{doc-colormap,,colormap}}
@end deftypefn


@c rainbow scripts/image/rainbow.m
@anchor{doc-rainbow}
@deftypefn  {Function File} {@var{map} =} rainbow ()
@deftypefnx {Function File} {@var{map} =} rainbow (@var{n})
Create color colormap.  This colormap ranges from red through orange,
yellow, green, blue, to violet.
The argument @var{n} must be a scalar.
If unspecified, the length of the current colormap, or 64, is used.
@seealso{@ref{doc-colormap,,colormap}}
@end deftypefn


@c spring scripts/image/spring.m
@anchor{doc-spring}
@deftypefn  {Function File} {@var{map} =} spring ()
@deftypefnx {Function File} {@var{map} =} spring (@var{n})
Create color colormap.  This colormap varies from magenta to yellow.
The argument @var{n} must be a scalar.
If unspecified, the length of the current colormap, or 64, is used.
@seealso{@ref{doc-colormap,,colormap}}
@end deftypefn


@c summer scripts/image/summer.m
@anchor{doc-summer}
@deftypefn  {Function File} {@var{map} =} summer ()
@deftypefnx {Function File} {@var{map} =} summer (@var{n})
Create color colormap.  This colormap varies from green to yellow.
The argument @var{n} must be a scalar.
If unspecified, the length of the current colormap, or 64, is used.
@seealso{@ref{doc-colormap,,colormap}}
@end deftypefn


@c white scripts/image/white.m
@anchor{doc-white}
@deftypefn  {Function File} {@var{map} =} white ()
@deftypefnx {Function File} {@var{map} =} 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{@ref{doc-colormap,,colormap}}
@end deftypefn


@c winter scripts/image/winter.m
@anchor{doc-winter}
@deftypefn  {Function File} {@var{map} =} winter ()
@deftypefnx {Function File} {@var{map} =} winter (@var{n})
Create color colormap.  This colormap varies from blue to green.
The argument @var{n} must be a scalar.
If unspecified, the length of the current colormap, or 64, is used.
@seealso{@ref{doc-colormap,,colormap}}
@end deftypefn


@c contrast scripts/image/contrast.m
@anchor{doc-contrast}
@deftypefn {Function File} {} contrast (@var{x}, @var{n})
Return a gray colormap that maximizes the contrast in an image.  The
returned colormap will have @var{n} rows.  If @var{n} is not defined
then the size of the current colormap is used instead.
@seealso{@ref{doc-colormap,,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
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.

@c gmap40 scripts/image/gmap40.m
@anchor{doc-gmap40}
@deftypefn  {Function File} {@var{map} =} gmap40 ()
@deftypefnx {Function File} {@var{map} =} gmap40 (@var{n})
Create color colormap.  The colormap consists of red, green, blue, yellow,
magenta and cyan.  This colormap is specifically designed for users of
gnuplot 4.0 where these 6 colors are the allowable ones for patch objects.
The argument @var{n} must be a scalar.
If unspecified, a length of 6 is assumed.  Larger values
of @var{n} result in a repetition of the above colors.
@seealso{@ref{doc-colormap,,colormap}}
@end deftypefn


The following three functions modify the existing colormap rather than
replace it.   

@c brighten scripts/image/brighten.m
@anchor{doc-brighten}
@deftypefn  {Function File} {@var{map_out} =} brighten (@var{map}, @var{beta})
@deftypefnx {Function File} {@var{map_out} =} brighten (@var{h}, @var{beta})
@deftypefnx {Function File} {@var{map_out} =} brighten (@var{beta})
Darken or brighten the given colormap.  If the @var{map} argument
is omitted, the function is applied to the current colormap.  The first
argument can also be a valid graphics handle @var{h}, in which case
@code{brighten} is applied to the colormap associated with this handle.

Should the resulting colormap @var{map_out} not be assigned, it will be
written to the current colormap.

The argument @var{beta} should be a scalar between -1 and 1,
where a negative value darkens and a positive value brightens
the colormap.
@seealso{@ref{doc-colormap,,colormap}}
@end deftypefn


@c spinmap scripts/plot/spinmap.m
@anchor{doc-spinmap}
@deftypefn {Function File} {} spinmap (@var{t}, @var{inc})
Cycle the colormap for @var{t} seconds with an increment
of @var{inc}.  Both parameters are optional.  The default cycle time
is 5 seconds and the default increment is 2.

A higher value of @var{inc} causes a faster cycle through the
colormap.
@seealso{@ref{doc-gca,,gca}, @ref{doc-colorbar,,colorbar}}
@end deftypefn


@c whitebg scripts/plot/whitebg.m
@anchor{doc-whitebg}
@deftypefn  {Function File} {} whitebg ()
@deftypefnx {Function File} {} whitebg (@var{color})
@deftypefnx {Function File} {} whitebg ("none")
@deftypefnx {Function File} {} whitebg (@var{fig})
@deftypefnx {Function File} {} whitebg (@var{fig}, @var{color})
@deftypefnx {Function File} {} whitebg (@var{fig}, "none")
Invert the colors in the current color scheme.  The root properties are
also inverted such that all subsequent plot use the new color scheme.

If defined, @var{fig} is the handle to the figure to be inverted.  In
this case only the specified figure has its color properties changed.

If the optional argument @var{color} is present then the background color
is set to @var{color} rather than inverted.  @var{color} may be a string
representing one of the eight known colors or an RGB triplet.  The special
string argument "none" restores the plot to the default colors.
@seealso{@ref{doc-reset,,reset}}
@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
@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. 

@c rgb2hsv scripts/image/rgb2hsv.m
@anchor{doc-rgb2hsv}
@deftypefn {Function File} {@var{hsv_map} =} rgb2hsv (@var{rgb})
Transform a colormap or image from the RGB space to the HSV space.

A color in 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{@ref{doc-hsv2rgb,,hsv2rgb}}
@end deftypefn


@c hsv2rgb scripts/image/hsv2rgb.m
@anchor{doc-hsv2rgb}
@deftypefn {Function File} {@var{rgb_map} =} hsv2rgb (@var{hsv_map})
Transform a colormap or image from the HSV space to the RGB space.
@seealso{@ref{doc-rgb2hsv,,rgb2hsv}}
@end deftypefn


@c rgb2ntsc scripts/image/rgb2ntsc.m
@anchor{doc-rgb2ntsc}
@deftypefn {Function File} {} rgb2ntsc (@var{rgb})
Transform a colormap or image from RGB to NTSC.
@seealso{@ref{doc-ntsc2rgb,,ntsc2rgb}}
@end deftypefn


@c ntsc2rgb scripts/image/ntsc2rgb.m
@anchor{doc-ntsc2rgb}
@deftypefn {Function File} {} ntsc2rgb (@var{yiq})
Transform a colormap or image from NTSC to RGB.
@seealso{@ref{doc-rgb2ntsc,,rgb2ntsc}}
@end deftypefn



