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

@c Copyright (C) 1996-2025 The Octave Project Developers
@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
@c the Free Software Foundation, either version 3 of the License, or
@c (at your option) any later version.
@c
@c Octave is distributed in the hope that it will be useful, but
@c WITHOUT ANY WARRANTY; without even the implied warranty of
@c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
@c GNU General Public License 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 <https://www.gnu.org/licenses/>.

@node Image Processing
@chapter Image Processing

Since an image is basically 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 which is done with the @code{imread} function.
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 (J, "my_output_image.img");
@end group
@end example

@c imread scripts/image/imread.m
@anchor{XREFimread}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {[@var{img}, @var{map}, @var{alpha}] =} imread (@var{filename})
@deftypefnx {} {[@dots{}] =} imread (@var{url})
@deftypefnx {} {[@dots{}] =} imread (@dots{}, @var{ext})
@deftypefnx {} {[@dots{}] =} imread (@dots{}, @var{idx})
@deftypefnx {} {[@dots{}] =} imread (@dots{}, @var{param1}, @var{value1}, @dots{})
Read images from various file formats.

Read an image as a matrix from the file @var{filename} or from the online
resource @var{url}.  If neither is given, but @var{ext} was specified, look
for a file with the extension @var{ext}.

The size and class of the output depends on the format of the image.  A
color image is returned as an @nospell{MxNx3} matrix.  Grayscale and
black-and-white images are of size @nospell{MxN}@.  Multipage images will
have an additional 4th dimension.

The bit depth of the image determines the class of the output:
@qcode{"uint8"}, @qcode{"uint16"}, or @qcode{"single"} for grayscale and
color, and @qcode{"logical"} for black-and-white.  Note that indexed images
always return the indexes for a colormap, independent of whether @var{map}
is a requested output.  To obtain the actual RGB image, use @code{ind2rgb}.
When more than one indexed image is being read, @var{map} is obtained from
the first.  In some rare cases this may be incorrect and @code{imfinfo} can
be used to obtain the colormap of each image.

See the Octave manual for more information in representing images.
(@pxref{Representing Images})

Some file formats, such as TIFF and GIF, are able to store multiple images
in a single file.  @var{idx} can be a scalar or vector specifying the
index of the images to read.  By default, Octave will read only the first
page.

Depending on the file format, it is possible to configure the reading of
images with @var{parameter}, @var{value} pairs.  The following options are
supported:

@table @asis
@item @qcode{"Frames"} or @qcode{"Index"}
This is an alternative method to specify @var{idx}.  When specifying it
in this way, its value can also be the string @qcode{"all"}.

@item @qcode{"Info"}
This option exists for @sc{matlab} compatibility, but has no effect.  For
maximum performance when reading multiple images from a single file, use
the @qcode{"Index"} option.

@item @qcode{"PixelRegion"}
Controls the image region that is read.  The value must be a cell array with
two arrays of 3 elements @code{@{[@var{rows}], [@var{cols}]@}}.  The
elements in the array are the start, increment, and end pixel to be read.
If the increment value is omitted it defaults to 1.  For example, the
following are all equivalent:

@format
@group
@code{imread (filename, "PixelRegion", @{[200 600], [300 700]@})}
@code{imread (filename, "PixelRegion", @{[200 1 600], [300 1 700]@})}
@code{imread (filename)(200:600, 300:700)}
@end group
@end format

@end table

@xseealso{@ref{XREFimwrite,,imwrite}, @ref{XREFimfinfo,,imfinfo}, @ref{XREFimformats,,imformats}}
@end deftypefn


@c imwrite scripts/image/imwrite.m
@anchor{XREFimwrite}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} imwrite (@var{img}, @var{filename})
@deftypefnx {} {} imwrite (@var{img}, @var{filename}, @var{ext})
@deftypefnx {} {} imwrite (@var{img}, @var{map}, @var{filename})
@deftypefnx {} {} imwrite (@dots{}, @var{param1}, @var{val1}, @dots{})
Write images in various file formats.

The image @var{img} can be a binary, grayscale, RGB, or multi-dimensional
image.  The size and class of @var{img} should be the same as what should
be expected when reading it with @code{imread}: the 3rd and 4th dimensions
reserved for color space, and multiple pages respectively.  If it's an
indexed image, the colormap @var{map} must also be specified.

If @var{ext} is not supplied, the file extension of @var{filename} is used
to determine the format.  The actual supported formats are dependent on
options made during the build of Octave.  Use @code{imformats} to check
the support of the different image formats.

Depending on the file format, it is possible to configure the writing of
images with @var{param}, @var{val} pairs.  The following options are
supported:

@table @samp
@item Alpha
Alpha (transparency) channel for the image.  This must be a matrix with
same class, and number of rows and columns of @var{img}.  In case of a
multipage image, the size of the 4th dimension must also match and the third
dimension must be a singleton.  By default, image will be completely opaque.

@item Compression
Compression to use one the image.  Can be one of the following: "none"
(default), "bzip", "fax3", "fax4", "jpeg", "lzw", "rle", or "deflate".
Note that not all compression types are available for all image formats
in which it defaults to your @nospell{Magick} library.

@item DelayTime
For formats that accept animations (such as GIF), controls for how long a
frame is displayed until it moves to the next one.  The value must be scalar
(which will applied to all frames in @var{img}), or a vector of length
equal to the number of frames in @var{im}.  The value is in seconds, must
be between 0 and 655.35, and defaults to 0.5.

@item DisposalMethod
For formats that accept animations (such as GIF), controls what happens to
a frame before drawing the next one.  Its value can be one of the
following strings: "doNotSpecify" (default); "leaveInPlace"; "restoreBG";
and "restorePrevious", or a cell array of those string with length equal
to the number of frames in @var{img}.

@item LoopCount
For formats that accept animations (such as GIF), controls how many times
the sequence is repeated.  A value of Inf means an infinite loop (default),
a value of 0 or 1 that the sequence is played only once (loops zero times),
while a value of 2 or above loops that number of times (looping twice means
it plays the complete sequence 3 times).  This option is ignored when there
is only a single image at the end of writing the file.

@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.  Defaults to 75.

@item WriteMode
Some file formats, such as TIFF and GIF, are able to store multiple images
in a single file.  This option specifies if @var{img} should be appended
to the file (if it exists) or if a new file should be created for it
(possibly overwriting an existing file).  The value should be the string
@qcode{"Overwrite"} (default), or @qcode{"Append"}.

Despite this option, the most efficient method of writing a multipage
image is to pass a 4 dimensional @var{img} to @code{imwrite}, the same
matrix that could be expected when using @code{imread} with the option
@qcode{"Index"} set to @qcode{"all"}.

@end table

@xseealso{@ref{XREFimread,,imread}, @ref{XREFimfinfo,,imfinfo}, @ref{XREFimformats,,imformats}}
@end deftypefn


@c IMAGE_PATH libinterp/corefcn/environment.cc
@anchor{XREFIMAGE_PATH}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{val} =} IMAGE_PATH ()
@deftypefnx {} {@var{old_val} =} IMAGE_PATH (@var{new_val})
@deftypefnx {} {@var{old_val} =} 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 @qcode{"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.

@xseealso{@ref{XREFEXEC_PATH,,EXEC_PATH}, @ref{XREFOCTAVE_HOME,,OCTAVE_HOME}, @ref{XREFOCTAVE_EXEC_HOME,,OCTAVE_EXEC_HOME}}
@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{XREFimfinfo}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{info} =} imfinfo (@var{filename})
@deftypefnx {} {@var{info} =} imfinfo (@var{url})
@deftypefnx {} {@var{info} =} imfinfo (@dots{}, @var{ext})
Read image information from a file.

@code{imfinfo} returns a structure containing information about the image
stored in the file @var{filename}.  If there is no file @var{filename},
and @var{ext} was specified, it will look for a file named @var{filename}
and extension @var{ext}, i.e., a file named @var{filename}.@var{ext}.

The output structure @var{info} contains the following fields:

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

@item FileModDate
Date of last modification to the file.

@item FileSize
Number of bytes of the image on disk

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

@item Height
Image height in pixels.

@item Width
Image Width in pixels.

@item BitDepth
Number of bits per channel per pixel.

@item ColorType
Image type.  Value is @qcode{"grayscale"}, @qcode{"indexed"},
@qcode{"truecolor"}, @qcode{"CMYK"}, or @qcode{"undefined"}.

@item XResolution
X resolution of the image.

@item YResolution
Y resolution of the image.

@item ResolutionUnit
Units of image resolution.  Value is @qcode{"Inch"},
@qcode{"Centimeter"}, or @qcode{"undefined"}.

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

@item LoopCount
Number of iterations to loop an animation.

@item ByteOrder
Endian option for formats that support it.  Value is
@qcode{"little-endian"}, @qcode{"big-endian"}, or @qcode{"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 Quality
JPEG/MIFF/PNG compression level.  Value is an integer in the range [0 100].

@item DisposalMethod
Only valid for GIF images, control how successive frames are rendered (how
the preceding frame is disposed of) when creating a GIF animation.  Values
can be @qcode{"doNotSpecify"}, @qcode{"leaveInPlace"}, @qcode{"restoreBG"},
or @qcode{"restorePrevious"}.  For non-GIF files, value is an empty string.

@item Chromaticities
Value is a 1x8 Matrix with the x,y chromaticity values for white, red,
green, and blue points, in that order.

@item Comment
Image comment.

@item Compression
Compression type.  Value can be @qcode{"none"}, @qcode{"bzip"},
@qcode{"fax3"}, @qcode{"fax4"}, @qcode{"jpeg"}, @qcode{"lzw"},
@qcode{"rle"}, @qcode{"deflate"}, @qcode{"lzma"}, @qcode{"jpeg2000"},
@qcode{"jbig2"}, @qcode{"jbig2"}, or @qcode{"undefined"}.

@item Colormap
Colormap for each image.

@item Orientation
The orientation of the image with respect to the rows and columns.  Value
is an integer between 1 and 8 as defined in the TIFF 6 specifications, and
for @sc{matlab} compatibility.

@item Software
Name and version of the software or firmware of the camera or image input
device used to generate the image.

@item Make
The manufacturer of the recording equipment.  This is the manufacture of the
@nospell{DSC}, scanner, video digitizer or other equipment that generated
the image.

@item Model
The model name or model number of the recording equipment as mentioned on
the field @qcode{"Make"}.

@item DateTime
The date and time of image creation as defined by the Exif standard, i.e.,
it is the date and time the file was changed.

@item ImageDescription
The title of the image as defined by the Exif standard.

@item Artist
Name of the camera owner, photographer or image creator.

@item Copyright
Copyright notice of the person or organization claiming rights to the image.

@item DigitalCamera
A struct with information retrieved from the Exif tag.

@item GPSInfo
A struct with geotagging information retrieved from the Exif tag.
@end table

@xseealso{@ref{XREFimread,,imread}, @ref{XREFimwrite,,imwrite}, @ref{XREFimshow,,imshow}, @ref{XREFimformats,,imformats}}
@end deftypefn


By default, Octave's image IO functions (@code{imread}, @code{imwrite},
and @code{imfinfo}) use the @code{GraphicsMagick} library for their
operations.  This means a vast number of image formats is supported
but considering the large amount of image formats in science and
its commonly closed nature, it is impossible to have a library
capable of reading them all.  Because of this, the function
@code{imformats} keeps a configurable list of available formats,
their extensions, and what functions should the image IO functions
use.  This allows one to expand Octave's image IO capabilities by
creating functions aimed at acting on specific file formats.

While it would be possible to call the extra functions directly,
properly configuring Octave with @code{imformats} allows one to keep a
consistent code that is abstracted from file formats.

It is important to note that a file format is not actually defined by its
file extension and that @code{GraphicsMagick} is capable to read and write
more file formats than the ones listed by @code{imformats}.  What this
means is that even with an incorrect or missing extension the image may
still be read correctly, and that even unlisted formats are not necessarily
unsupported.

@c imformats scripts/image/imformats.m
@anchor{XREFimformats}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} imformats ()
@deftypefnx {} {@var{formats} =} imformats (@var{ext})
@deftypefnx {} {@var{formats} =} imformats (@var{format})
@deftypefnx {} {@var{formats} =} imformats ("add", @var{format})
@deftypefnx {} {@var{formats} =} imformats ("remove", @var{ext})
@deftypefnx {} {@var{formats} =} imformats ("update", @var{ext}, @var{format})
@deftypefnx {} {@var{formats} =} imformats ("factory")
Manage supported image formats.

@var{formats} is a structure with information about each supported file
format, or from a specific format @var{ext}, the value displayed on the
field @var{ext}.  It contains the following fields:

@table @asis
@item ext
The name of the file format.  This may match the file extension but Octave
will automatically detect the file format.

@item description
A long description of the file format.

@item @nospell{isa}
A function handle to confirm if a file is of the specified format.

@item write
A function handle to write if a file is of the specified format.

@item read
A function handle to open files the specified format.

@item info
A function handle to obtain image information of the specified format.

@item alpha
Logical value if format supports alpha channel (transparency or matte).

@item multipage
Logical value if format supports multipage (multiple images per file).
@end table

It is possible to change the way Octave manages file formats with the
options @qcode{"add"}, @qcode{"remove"}, and @qcode{"update"}, and supplying
a structure @var{format} with the required fields.  The option
@qcode{"factory"} resets the configuration to the default.

This can be used by Octave packages to extend the image reading capabilities
Octave, through use of the PKG_ADD and PKG_DEL commands.

@xseealso{@ref{XREFimfinfo,,imfinfo}, @ref{XREFimread,,imread}, @ref{XREFimwrite,,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{XREFimshow}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} imshow (@var{im})
@deftypefnx {} {} imshow (@var{im}, @var{limits})
@deftypefnx {} {} imshow (@var{im}, @var{map})
@deftypefnx {} {} imshow (@var{rgb}, @dots{})
@deftypefnx {} {} imshow (@var{filename})
@deftypefnx {} {} imshow (@dots{}, @var{string_param1}, @var{value1}, @dots{})
@deftypefnx {} {@var{h} =} imshow (@dots{})
Display the image @var{im}, where @var{im} can be a 2-dimensional
(grayscale 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 filename 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 @qcode{"displayrange"}
@var{value1} is the display range as described above.

@item @qcode{"colormap"}
@var{value1} is the colormap to use when displaying an indexed image.

@item @qcode{"xdata"}
If @var{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 @var{value1}
 must be a vector and only the first and last elements will be used
for xfirst and xlast respectively.

@item @qcode{"ydata"}
If @var{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 @var{value1} must be a vector
and only the first and last elements will be used for yfirst and ylast
respectively.

@end table

The optional return value @var{h} is a graphics handle to the image.
@xseealso{@ref{XREFimage,,image}, @ref{XREFimagesc,,imagesc}, @ref{XREFcolormap,,colormap}, @ref{XREFgray2ind,,gray2ind}, @ref{XREFrgb2ind,,rgb2ind}}
@end deftypefn


@c image scripts/image/image.m
@anchor{XREFimage}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} image (@var{img})
@deftypefnx {} {} image (@var{x}, @var{y}, @var{img})
@deftypefnx {} {} image (@dots{}, "@var{prop}", @var{val}, @dots{})
@deftypefnx {} {} image ("@var{prop1}", @var{val1}, @dots{})
@deftypefnx {} {@var{h} =} image (@dots{})
Display a matrix as an indexed color image.

The elements of @var{img} are indices into the current colormap.

@var{x} and @var{y} are optional 2-element vectors, @w{@code{[min, max]}},
which specify the coordinates of the centers of the corner pixels.
If a range is specified as @w{@code{[max, min]}}@ then the image will be
reversed along that axis.  For convenience, @var{x} and @var{y} may be
specified as N-element vectors matching the length of the data in @var{img}.
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.

The optional return value @var{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
@code{ydir} property to @qcode{"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)}.

Calling Forms: The @code{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 @code{newplot} to prepare the graphic figure
and axes.  When the only inputs to @code{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.

Graphic Properties: The full list of properties is documented at
@ref{Image Properties}.
@xseealso{@ref{XREFimshow,,imshow}, @ref{XREFimagesc,,imagesc}, @ref{XREFcolormap,,colormap}}
@end deftypefn


@c imagesc scripts/image/imagesc.m
@anchor{XREFimagesc}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} imagesc (@var{img})
@deftypefnx {} {} imagesc (@var{x}, @var{y}, @var{img})
@deftypefnx {} {} imagesc (@dots{}, @var{climits})
@deftypefnx {} {} imagesc (@dots{}, "@var{prop}", @var{val}, @dots{})
@deftypefnx {} {} imagesc ("@var{prop1}", @var{val1}, @dots{})
@deftypefnx {} {} imagesc (@var{hax}, @dots{})
@deftypefnx {} {@var{h} =} imagesc (@dots{})
Display a scaled version of the matrix @var{img} as a color image.

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

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

The optional return value @var{h} is a graphics handle to the image.

Calling Forms: The @code{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 @code{newplot} to prepare the graphic figure
and axes.  When the only inputs to @code{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 @ref{Image Properties}.

@xseealso{@ref{XREFimage,,image}, @ref{XREFimshow,,imshow}, @ref{XREFclim,,clim}}
@end deftypefn


@node Representing Images
@section Representing Images

In general Octave supports four different kinds of images, grayscale
images, RGB images, binary images, and indexed images.  A grayscale
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 grayscale 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.

The following convenience functions are available for conversion between image
formats.

@c im2double scripts/image/im2double.m
@anchor{XREFim2double}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{dimg} =} im2double (@var{img})
@deftypefnx {} {@var{dimg} =} im2double (@var{img}, "indexed")
Convert image to double precision.

The conversion of @var{img} to double precision, is dependent on the type of
input image.  The following input classes are supported:

@table @samp
@item uint8, uint16, and int16
The range of values from the class is scaled to the interval [0 1].

@item logical
True and false values are assigned a value of 1 and 0 respectively.

@item single
Values are cast to double.

@item double
Returns the same image.

@end table

If @var{img} is an indexed image, then the second argument should be the
string @qcode{"indexed"}.  If so, then @var{img} must either be of floating
point class, or unsigned integer class and it will simply be cast to double.
If it is an integer class, an offset of +1 is applied.

@xseealso{@ref{XREFdouble,,double}}
@end deftypefn


@c gray2ind scripts/image/gray2ind.m
@anchor{XREFgray2ind}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{img} =} gray2ind (@var{I})
@deftypefnx {} {@var{img} =} gray2ind (@var{I}, @var{n})
@deftypefnx {} {@var{img} =} gray2ind (@var{BW})
@deftypefnx {} {@var{img} =} gray2ind (@var{BW}, @var{n})
@deftypefnx {} {[@var{img}, @var{map}] =} gray2ind (@dots{})
Convert a grayscale or binary intensity image to an indexed image.

The indexed image will consist of @var{n} different intensity values.
If not given @var{n} defaults to 64 for grayscale images or 2 for binary
black and white images.

The output @var{img} is of class uint8 if @var{n} is less than or equal to
256; Otherwise the return class is uint16.
@xseealso{@ref{XREFind2gray,,ind2gray}, @ref{XREFrgb2ind,,rgb2ind}}
@end deftypefn


@c ind2gray scripts/image/ind2gray.m
@anchor{XREFind2gray}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{I} =} ind2gray (@var{x}, @var{map})
Convert a color indexed image to a grayscale intensity image.

The image @var{x} must be an indexed image which will be converted using the
colormap @var{map}.  If @var{map} does not contain enough colors for the
image, pixels in @var{x} outside the range are mapped to the last color in
the map before conversion to grayscale.

The output @var{I} is of the same class as the input @var{x} and may be
one of @code{uint8}, @code{uint16}, @code{single}, or @code{double}.

Implementation Note: There are several ways of converting colors to
grayscale intensities.  This functions uses the luminance value obtained
from @code{rgb2gray} which is @code{I = 0.299*R + 0.587*G + 0.114*B}.
Other possibilities include the value component from @code{rgb2hsv} or
using a single color channel from @code{ind2rgb}.
@xseealso{@ref{XREFgray2ind,,gray2ind}, @ref{XREFind2rgb,,ind2rgb}}
@end deftypefn


@c rgb2ind scripts/image/rgb2ind.m
@anchor{XREFrgb2ind}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {[@var{x}, @var{map}] =} rgb2ind (@var{rgb})
@deftypefnx {} {[@var{x}, @var{map}] =} rgb2ind (@var{R}, @var{G}, @var{B})
Convert an image in red-green-blue (RGB) color space to an indexed image.

The input image @var{rgb} can be specified as a single matrix of size
@nospell{MxNx3}, or as three separate variables, @var{R}, @var{G}, and
@var{B}, its three color channels, red, green, and blue.

It outputs an indexed image @var{x} and a colormap @var{map} to interpret
an image exactly the same as the input.  No dithering or other form of color
quantization is performed.  The output class of the indexed image @var{x}
can be uint8, uint16 or double, whichever is required to specify the
number of unique colors in the image (which will be equal to the number
of rows in @var{map}) in order.

Multi-dimensional indexed images (of size @nospell{MxNx3xK}) are also
supported, both via a single input (@var{rgb}) or its three color channels
as separate variables.

@xseealso{@ref{XREFind2rgb,,ind2rgb}, @ref{XREFrgb2hsv,,rgb2hsv}, @ref{XREFrgb2gray,,rgb2gray}}
@end deftypefn


@c ind2rgb scripts/image/ind2rgb.m
@anchor{XREFind2rgb}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{rgb} =} ind2rgb (@var{x}, @var{map})
@deftypefnx {} {[@var{R}, @var{G}, @var{B}] =} ind2rgb (@var{x}, @var{map})
Convert an indexed image to red, green, and blue color components.

The image @var{x} must be an indexed image which will be converted using the
colormap @var{map}.  If @var{map} does not contain enough colors for the
image, pixels in @var{x} outside the range are mapped to the last color in
the map.

The output may be a single RGB image (@nospell{MxNx3} matrix where M and N
are the original image @var{x} dimensions, one for each of the red, green
and blue channels).  Alternatively, the individual red, green, and blue
color matrices of size @nospell{MxN} may be returned.

Multi-dimensional indexed images (of size @nospell{MxNx1xK}) are also
supported.

@xseealso{@ref{XREFrgb2ind,,rgb2ind}, @ref{XREFind2gray,,ind2gray}, @ref{XREFhsv2rgb,,hsv2rgb}}
@end deftypefn


Octave also provides tools to produce and work with movie frame structures.
Those structures encapsulate the image data (@qcode{"cdata"} field) together
with the corresponding colormap (@qcode{"colormap"} field).

@c getframe scripts/image/getframe.m
@anchor{XREFgetframe}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{frame} =} getframe ()
@deftypefnx {} {@var{frame} =} getframe (@var{hax})
@deftypefnx {} {@var{frame} =} getframe (@var{hfig})
@deftypefnx {} {@var{frame} =} getframe (@dots{}, @var{rect})

Capture a figure or axes as a movie frame structure.

Without an argument, capture the current axes excluding ticklabels, title,
and x/y/zlabels.  The returned structure @var{frame} has a field
@code{cdata}, which contains the actual image data in the form of an
@nospell{NxMx3} (RGB) uint8 matrix in physical screen pixels, and a field
@code{colormap} which is provided for @sc{matlab} compatibility but is
always empty.

If the first argument @var{hax} is an axes handle, then capture this axes,
rather than the current axes returned by @code{gca}.

If the first argument @var{hfig} is a figure handle then the entire
corresponding figure canvas is captured.

Finally, if a second argument @var{rect} is provided it must be a
four-element vector ([left bottom width height]) defining the region inside
the figure to be captured.  Regardless of the figure @qcode{"units"}
property, @var{rect} must be defined in @strong{pixels}.

@xseealso{@ref{XREFim2frame,,im2frame}, @ref{XREFframe2im,,frame2im}, @ref{XREFmovie,,movie}}
@end deftypefn


@c movie scripts/image/movie.m
@anchor{XREFmovie}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} movie (@var{mov})
@deftypefnx {} {} movie (@var{mov}, @var{n})
@deftypefnx {} {} movie (@var{mov}, @var{n}, @var{fps})
@deftypefnx {} {} movie (@var{h}, @dots{})
Play a movie defined by an array of frame structures.

The movie @var{mov} must be a struct array of frames with fields
@qcode{"cdata"} and @qcode{"colormap"}, as returned by the @code{getframe}
function.  By default all images are displayed once, at 12 fps, in the
current axes.

The optional argument @var{n} is a scalar or vector of integers that
controls the number of times the movie is displayed and which particular
frames are shown:

@table @asis
@item First element:

@table @asis
@item @var{n}(1) > 0
Play the movie @var{n}(1) times.

@item @var{n}(1) < 0
Play the movie @code{abs (@var{n}(1)} times alternatively in forward and
backward order.
@end table

@item Other elements (if any):
Indices of the frames in @var{mov} that will be displayed.
@end table

If the first argument is a handle to a figure or axes @var{h}, the movie is
played in that figure or axes instead of the current axes.

@xseealso{@ref{XREFgetframe,,getframe}, @ref{XREFim2frame,,im2frame}, @ref{XREFframe2im,,frame2im}}
@end deftypefn


@c frame2im scripts/image/frame2im.m
@anchor{XREFframe2im}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {[@var{x}, @var{map}] =} frame2im (@var{frame})
Convert movie frame to indexed image.

A movie frame is simply a struct with the fields @qcode{"cdata"} and
@qcode{"colormap"}.

Support for N-dimensional images or movies is given when @var{frame} is a
struct array.  In such cases, @var{x} will be a @nospell{MxNx1xK or MxNx3xK}
for indexed and RGB movies respectively, with each frame concatenated
along the 4th dimension.

@xseealso{@ref{XREFim2frame,,im2frame}, @ref{XREFgetframe,,getframe}}
@end deftypefn


@c im2frame scripts/image/im2frame.m
@anchor{XREFim2frame}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{frame} =} im2frame (@var{rgb})
@deftypefnx {} {@var{frame} =} im2frame (@var{x}, @var{map})
Convert image to movie frame.

A movie frame is simply a struct with the fields @qcode{"cdata"} and
@qcode{"colormap"}.

Support for N-dimensional images is given when each image projection,
matrix sizes of @nospell{MxN and MxNx3} for RGB images, is concatenated
along the fourth dimension.  In such cases, the returned value is a struct
array.

@xseealso{@ref{XREFframe2im,,frame2im}}
@end deftypefn


The @code{colormap} function is used to change the colormap of the current
axes or figure.

@c colormap scripts/image/colormap.m
@anchor{XREFcolormap}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{cmap} =} colormap ()
@deftypefnx {} {@var{cmap} =} colormap (@var{map})
@deftypefnx {} {@var{cmap} =} colormap (@qcode{"default"})
@deftypefnx {} {@var{cmap} =} colormap (@var{map_name})
@deftypefnx {} {@var{cmap} =} colormap (@var{hax}, @dots{})
@deftypefnx {} {@var{cmap} =} colormap (@var{hfig}, @dots{})
@deftypefnx {} {} colormap @var{map_name}
Query or set the current colormap.

With no input arguments, @code{colormap} returns the current color map.  If
there is no current figure, a new figure will be opened and the default
color map will be returned.

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

@code{colormap (@qcode{"default"})} restores the default colormap (the
@code{viridis} map with 256 entries).  The default colormap is returned.

The map may also be specified by a string, @var{map_name}, which
is the name of a function that returns a colormap.

If the first argument @var{hax} is an axes handle, then the colormap for
the specified axes is queried or set.  If the first argument @var{hfig} is a
figure handle, then the colormap for the specified figure is queried or set.

For convenience, it is also possible to use this function with the
command form, @code{colormap @var{map_name}}.

The list of built-in colormaps is:

@c FIXME: It would be nice to display the actual colormap as an image
@c        in the PDF version of the documentation.
@multitable @columnfractions 0.15 .85
@headitem Map @tab Description
@item viridis @tab default
@item turbo @tab colormap traversing blue, cyan, green, yellow, red; modern replacement for jet.
@item jet @tab colormap traversing blue, cyan, green, yellow, red.
@item cubehelix @tab colormap traversing black, blue, green, red, white with increasing intensity.
@item hsv @tab cyclic colormap traversing Hue, Saturation, Value space.
@item rainbow @tab colormap traversing red, yellow, blue, green, violet.
@item ------------- @tab ---------------------------------------------------------------------------------------------
@item hot @tab colormap traversing black, red, orange, yellow, white.
@item cool @tab colormap traversing cyan, purple, magenta.
@item spring @tab colormap traversing magenta to yellow.
@item summer @tab colormap traversing green to yellow.
@item autumn @tab colormap traversing red, orange, yellow.
@item winter @tab colormap traversing blue to green.
@item ------------- @tab ---------------------------------------------------------------------------------------------
@item gray @tab colormap traversing black to white in shades of gray.
@item bone @tab colormap traversing black, gray-blue, white.
@item copper @tab colormap traversing black to light copper.
@item pink @tab colormap traversing black, gray-pink, white.
@item ocean @tab colormap traversing black, dark-blue, white.
@item ------------- @tab ---------------------------------------------------------------------------------------------
@item colorcube @tab equally spaced colors in RGB color space.
@item flag @tab cyclic 4-color map of red, white, blue, black.
@item lines @tab cyclic colormap with colors from axes @qcode{"ColorOrder"} property.
@item prism @tab cyclic 6-color map of red, orange, yellow, green, blue, violet.
@item ------------- @tab ---------------------------------------------------------------------------------------------
@item white @tab all white colormap (no colors).
@end multitable
@xseealso{@ref{XREFviridis,,viridis}, @ref{XREFturbo,,turbo}, @ref{XREFjet,,jet}, @ref{XREFcubehelix,,cubehelix}, @ref{XREFhsv,,hsv}, @ref{XREFrainbow,,rainbow}, @ref{XREFhot,,hot}, @ref{XREFcool,,cool}, @ref{XREFspring,,spring}, @ref{XREFsummer,,summer}, @ref{XREFautumn,,autumn}, @ref{XREFwinter,,winter}, @ref{XREFgray,,gray}, @ref{XREFbone,,bone}, @ref{XREFcopper,,copper}, @ref{XREFpink,,pink}, @ref{XREFocean,,ocean}, @ref{XREFcolorcube,,colorcube}, @ref{XREFflag,,flag}, @ref{XREFlines,,lines}, @ref{XREFprism,,prism}, @ref{XREFwhite,,white}}
@end deftypefn


@c iscolormap scripts/image/iscolormap.m
@anchor{XREFiscolormap}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{tf} =} iscolormap (@var{cmap})
Return true if @var{cmap} is a colormap.

A colormap is a real matrix, of class single or double, with 3 columns.
Each row represents a single color.  The 3 columns contain red, green,
and blue intensities respectively.

All values in a colormap should be in the [0 1] range but this is not
enforced.  Each function must decide what to do for values outside this
range.

@xseealso{@ref{XREFcolormap,,colormap}, @ref{XREFrgbplot,,rgbplot}}
@end deftypefn


The following functions return predefined colormaps, the same that can be
requested by name using the @code{colormap} function.

@c rgbplot scripts/image/rgbplot.m
@anchor{XREFrgbplot}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} rgbplot (@var{cmap})
@deftypefnx {} {} rgbplot (@var{cmap}, @var{style})
@deftypefnx {} {@var{h} =} rgbplot (@dots{})
Plot the components of a colormap.

Two different @var{style}s are available for displaying the @var{cmap}:

@table @asis
@item profile (default)
Plot the RGB line profile of the colormap for each of the channels (red,
green and blue) with the plot lines colored appropriately.  Each line
represents the intensity of an RGB component across the colormap.

@item composite
Draw the colormap across the X-axis so that the actual index colors are
visible rather than the individual color components.

@end table

The optional return value @var{h} is a graphics handle to the created plot.

Run @code{demo rgbplot} to see an example of @code{rgbplot} and each style
option.
@xseealso{@ref{XREFcolormap,,colormap}}
@end deftypefn


@c autumn scripts/image/autumn.m
@anchor{XREFautumn}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{map} =} autumn ()
@deftypefnx {} {@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 @var{n} is not specified the length of the current colormap is used.  If
there is no current colormap the default value of 256 is used.
@xseealso{@ref{XREFcolormap,,colormap}}
@end deftypefn


@c bone scripts/image/bone.m
@anchor{XREFbone}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{map} =} bone ()
@deftypefnx {} {@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 @var{n} is not specified the length of the current colormap is used.  If
there is no current colormap the default value of 256 is used.
@xseealso{@ref{XREFcolormap,,colormap}}
@end deftypefn


@c colorcube scripts/image/colorcube.m
@anchor{XREFcolorcube}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{map} =} colorcube ()
@deftypefnx {} {@var{map} =} colorcube (@var{n})
Create color colormap.  This colormap is composed of as many equally
spaced colors (not grays) in the RGB color space as possible.

If there are not a perfect number @var{n} of regularly spaced colors then
the remaining entries in the colormap are gradients of pure red, green,
blue, and gray.

The argument @var{n} must be a scalar.
If @var{n} is not specified the length of the current colormap is used.  If
there is no current colormap the default value of 256 is used.
@xseealso{@ref{XREFcolormap,,colormap}}
@end deftypefn


@c cool scripts/image/cool.m
@anchor{XREFcool}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{map} =} cool ()
@deftypefnx {} {@var{map} =} cool (@var{n})
Create color colormap.  The colormap varies from cyan to magenta.

The argument @var{n} must be a scalar.
If @var{n} is not specified the length of the current colormap is used.  If
there is no current colormap the default value of 256 is used.
@xseealso{@ref{XREFcolormap,,colormap}}
@end deftypefn


@c copper scripts/image/copper.m
@anchor{XREFcopper}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{map} =} copper ()
@deftypefnx {} {@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 @var{n} is not specified the length of the current colormap is used.  If
there is no current colormap the default value of 256 is used.
@xseealso{@ref{XREFcolormap,,colormap}}
@end deftypefn


@c cubehelix scripts/image/cubehelix.m
@anchor{XREFcubehelix}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{map} =} cubehelix ()
@deftypefnx {} {@var{map} =} cubehelix (@var{n})
@deftypefnx {} {@var{map} =} cubehelix (@var{n}, @var{start}, @var{rots}, @var{hue}, @var{gamma})
Create cubehelix colormap.

This colormap varies from black to white going though blue, green, and red
tones while maintaining a monotonically increasing perception of intensity.
This is achieved by traversing a color cube from black to white through
a helix, hence the name cubehelix, while taking into account the perceived
brightness of each channel according to the NTSC specifications from 1953.

@example
rgbplot (cubehelix (256))
@end example

The argument @var{n} must be a scalar.
If @var{n} is not specified the length of the current colormap is used.  If
there is no current colormap the default value of 256 is used.

Reference: Green, D. A., 2011,
@cite{A @nospell{colour} scheme for the display of astronomical intensity
images}, Bulletin of the Astronomical Society of India, 39, 289.

@xseealso{@ref{XREFcolormap,,colormap}}
@end deftypefn


@c flag scripts/image/flag.m
@anchor{XREFflag}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{map} =} flag ()
@deftypefnx {} {@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 @var{n} is not specified the length of the current colormap is used.  If
there is no current colormap the default value of 256 is used.
@xseealso{@ref{XREFcolormap,,colormap}}
@end deftypefn


@c gray scripts/image/gray.m
@anchor{XREFgray}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{map} =} gray ()
@deftypefnx {} {@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 @var{n} is not specified the length of the current colormap is used.  If
there is no current colormap the default value of 256 is used.
@xseealso{@ref{XREFcolormap,,colormap}}
@end deftypefn


@c hot scripts/image/hot.m
@anchor{XREFhot}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{map} =} hot ()
@deftypefnx {} {@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 @var{n} is not specified the length of the current colormap is used.  If
there is no current colormap the default value of 256 is used.
@xseealso{@ref{XREFcolormap,,colormap}}
@end deftypefn


@c hsv scripts/image/hsv.m
@anchor{XREFhsv}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{map} =} hsv ()
@deftypefnx {} {@var{map} =} 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.  The map is obtained by
linearly varying the hue through all possible values while keeping constant
maximum saturation and value.  The equivalent code is
@code{hsv2rgb ([(0:N-1)'/N, ones(N,2)])}.

The argument @var{n} must be a scalar.
If @var{n} is not specified the length of the current colormap is used.  If
there is no current colormap the default value of 256 is used.
@xseealso{@ref{XREFcolormap,,colormap}}
@end deftypefn


@c jet scripts/image/jet.m
@anchor{XREFjet}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{map} =} jet ()
@deftypefnx {} {@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 @var{n} is not specified the length of the current colormap is used.  If
there is no current colormap the default value of 256 is used.

Programming Note: The @code{jet} colormap is not perceptually uniform.
Try the @code{viridis} colormap if that is important.  For a drop-in
replacement for @code{jet} with better perceptual characteristics try
the @code{turbo} colormap.
@xseealso{@ref{XREFcolormap,,colormap}, @ref{XREFturbo,,turbo}}
@end deftypefn


@c lines scripts/image/lines.m
@anchor{XREFlines}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{map} =} lines ()
@deftypefnx {} {@var{map} =} lines (@var{n})
Create color colormap.  This colormap is composed of the list of colors
in the current axes @qcode{"ColorOrder"} property.  The default is blue,
orange, yellow, purple, green, light blue, and dark red.

The argument @var{n} must be a scalar.
If @var{n} is not specified the length of the current colormap is used.  If
there is no current colormap the default value of 256 is used.
@xseealso{@ref{XREFcolormap,,colormap}}
@end deftypefn


@c ocean scripts/image/ocean.m
@anchor{XREFocean}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{map} =} ocean ()
@deftypefnx {} {@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 @var{n} is not specified the length of the current colormap is used.  If
there is no current colormap the default value of 256 is used.
@xseealso{@ref{XREFcolormap,,colormap}}
@end deftypefn


@c pink scripts/image/pink.m
@anchor{XREFpink}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{map} =} pink ()
@deftypefnx {} {@var{map} =} pink (@var{n})
Create color colormap.  This colormap varies from black to white with
shades of gray-pink.

This colormap gives a sepia tone when used on grayscale images.

The argument @var{n} must be a scalar.
If @var{n} is not specified the length of the current colormap is used.  If
there is no current colormap the default value of 256 is used.
@xseealso{@ref{XREFcolormap,,colormap}}
@end deftypefn


@c prism scripts/image/prism.m
@anchor{XREFprism}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{map} =} prism ()
@deftypefnx {} {@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 @var{n} is not specified the length of the current colormap is used.  If
there is no current colormap the default value of 256 is used.
@xseealso{@ref{XREFcolormap,,colormap}}
@end deftypefn


@c rainbow scripts/image/rainbow.m
@anchor{XREFrainbow}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{map} =} rainbow ()
@deftypefnx {} {@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 @var{n} is not specified the length of the current colormap is used.  If
there is no current colormap the default value of 256 is used.
@xseealso{@ref{XREFcolormap,,colormap}}
@end deftypefn


@c spring scripts/image/spring.m
@anchor{XREFspring}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{map} =} spring ()
@deftypefnx {} {@var{map} =} spring (@var{n})
Create color colormap.  This colormap varies from magenta to yellow.

The argument @var{n} must be a scalar.
If @var{n} is not specified the length of the current colormap is used.  If
there is no current colormap the default value of 256 is used.
@xseealso{@ref{XREFcolormap,,colormap}}
@end deftypefn


@c summer scripts/image/summer.m
@anchor{XREFsummer}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{map} =} summer ()
@deftypefnx {} {@var{map} =} summer (@var{n})
Create color colormap.  This colormap varies from green to yellow.

The argument @var{n} must be a scalar.
If @var{n} is not specified the length of the current colormap is used.  If
there is no current colormap the default value of 256 is used.
@xseealso{@ref{XREFcolormap,,colormap}}
@end deftypefn


@c turbo scripts/image/turbo.m
@anchor{XREFturbo}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{map} =} turbo ()
@deftypefnx {} {@var{map} =} turbo (@var{n})
Create color colormap.  This colormap ranges from dark blue through green
to dark red; similar to the outdated @code{jet} colormap but perceptually
uniform.

The argument @var{n} must be a scalar.
If @var{n} is not specified the length of the current colormap is used.  If
there is no current colormap the default value of 256 is used.
@xseealso{@ref{XREFcolormap,,colormap}}
@end deftypefn


@c viridis scripts/image/viridis.m
@anchor{XREFviridis}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{map} =} viridis ()
@deftypefnx {} {@var{map} =} viridis (@var{n})
Create color colormap.  This colormap ranges from dark purplish-blue through
blue, green, to yellow.

The argument @var{n} must be a scalar.
If @var{n} is not specified the length of the current colormap is used.  If
there is no current colormap the default value of 256 is used.
@xseealso{@ref{XREFcolormap,,colormap}}
@end deftypefn


@c white scripts/image/white.m
@anchor{XREFwhite}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{map} =} white ()
@deftypefnx {} {@var{map} =} white (@var{n})
Create color colormap.  This colormap is completely white.

The argument @var{n} must be a scalar.
If @var{n} is not specified the length of the current colormap is used.  If
there is no current colormap the default value of 256 is used.
@xseealso{@ref{XREFcolormap,,colormap}}
@end deftypefn


@c winter scripts/image/winter.m
@anchor{XREFwinter}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{map} =} winter ()
@deftypefnx {} {@var{map} =} winter (@var{n})
Create color colormap.  This colormap varies from blue to green.

The argument @var{n} must be a scalar.
If @var{n} is not specified the length of the current colormap is used.  If
there is no current colormap the default value of 256 is used.
@xseealso{@ref{XREFcolormap,,colormap}}
@end deftypefn


@c contrast scripts/image/contrast.m
@anchor{XREFcontrast}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{cmap} =} contrast (@var{x})
@deftypefnx {} {@var{cmap} =} 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.
@xseealso{@ref{XREFcolormap,,colormap}, @ref{XREFbrighten,,brighten}}
@end deftypefn


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

@c brighten scripts/image/brighten.m
@anchor{XREFbrighten}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{map_out} =} brighten (@var{beta})
@deftypefnx {} {@var{map_out} =} brighten (@var{map}, @var{beta})
@deftypefnx {} {@var{map_out} =} brighten (@var{h}, @var{beta})
@deftypefnx {} {} brighten (@dots{})
Brighten or darken a colormap.

The argument @var{beta} must be a scalar between -1 and 1, where a negative
value darkens and a positive value brightens the 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.

If no output is specified then the result is written to the current
colormap.
@xseealso{@ref{XREFcolormap,,colormap}, @ref{XREFcontrast,,contrast}}
@end deftypefn


@c spinmap scripts/image/spinmap.m
@anchor{XREFspinmap}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} spinmap ()
@deftypefnx {} {} spinmap (@var{t})
@deftypefnx {} {} spinmap (@var{t}, @var{inc})
@deftypefnx {} {} spinmap ("inf")
Cycle the colormap for @var{t} seconds with a color increment of @var{inc}.

Both parameters are optional.  The default cycle time is 5 seconds and the
default increment is 2.  If the option @qcode{"inf"} is given then cycle
continuously until @kbd{Control-C} is pressed.

When rotating, the original color 1 becomes color 2, color 2 becomes
color 3, etc.  A positive or negative increment is allowed and a higher
value of @var{inc} will cause faster cycling through the colormap.
@xseealso{@ref{XREFcolormap,,colormap}}
@end deftypefn


@c whitebg scripts/plot/appearance/whitebg.m
@anchor{XREFwhitebg}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} whitebg ()
@deftypefnx {} {} whitebg (@var{color})
@deftypefnx {} {} whitebg ("none")
@deftypefnx {} {} whitebg (@var{hfig})
@deftypefnx {} {} whitebg (@var{hfig}, @var{color})
@deftypefnx {} {} whitebg (@var{hfig}, "none")
Invert the colors in the current color scheme.

The root properties are also inverted such that all subsequent plots will
use the new color scheme.

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 @qcode{"none"} restores the plot to the factory default
colors.

If the first argument @var{hfig} is a figure handle or list of figure
handles, then operate on these figures rather than the current figure
returned by @code{gcf}.  The root properties will not be changed unless 0
is in the list of figures.

Programming Note: @code{whitebg} operates by changing the color properties
of the children of the specified figures.  Only objects with a single color
are affected.  For example, a patch with a single @qcode{"FaceColor"} will
be changed, but a patch with shading (@qcode{"interp"}) will not be
modified.  For inversion, the new color is simply the inversion in RGB
space: @code{@var{cnew} = [1-@var{R} 1-@var{G} 1-@var{B}]}.  When a color
is specified, the axes and figure are set to the new color, and the color
of child objects are then adjusted to have some contrast (visibility)
against the new background.
@xseealso{@ref{XREFreset,,reset}, @ref{XREFget,,get}, @ref{XREFset,,set}}
@end deftypefn


The following functions can be used to manipulate colormaps.

@c cmunique scripts/image/cmunique.m
@anchor{XREFcmunique}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {[@var{Y}, @var{newmap}] =} cmunique (@var{X}, @var{map})
@deftypefnx {} {[@var{Y}, @var{newmap}] =} cmunique (@var{RGB})
@deftypefnx {} {[@var{Y}, @var{newmap}] =} cmunique (@var{I})
Convert an input image @var{X} to an output indexed image @var{Y} which uses
the smallest colormap possible @var{newmap}.

When the input is an indexed image (@var{X} with colormap @var{map}) the
output is a colormap @var{newmap} from which any repeated rows have been
eliminated.  The output image, @var{Y}, is the original input image with
the indices adjusted to match the new, possibly smaller, colormap.

When the input is an RGB image (an @nospell{MxNx3} array), the output
colormap will contain one entry for every unique color in the original
image.  In the worst case the new map could have as many rows as the
number of pixels in the original image.

When the input is a grayscale image @var{I}, the output colormap will
contain one entry for every unique intensity value in the original image.
In the worst case the new map could have as many rows as the number of
pixels in the original image.

Implementation Details:

@var{newmap} is always an Mx3 matrix, even if the input image is
an intensity grayscale image @var{I} (all three RGB planes are
assigned the same value).

The output image is of class uint8 if the size of the new colormap is
less than or equal to 256.  Otherwise, the output image is of class double.

@xseealso{@ref{XREFrgb2ind,,rgb2ind}, @ref{XREFgray2ind,,gray2ind}}
@end deftypefn


@c cmpermute scripts/image/cmpermute.m
@anchor{XREFcmpermute}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {[@var{Y}, @var{newmap}] =} cmpermute (@var{X}, @var{map})
@deftypefnx {} {[@var{Y}, @var{newmap}] =} cmpermute (@var{X}, @var{map}, @var{index})
Reorder colors in a colormap.

When called with only two arguments, @code{cmpermute} randomly rearranges
the colormap @var{map} and returns a new colormap @var{newmap}.  It also
returns the indexed image @var{Y} which is the equivalent of the original
input image @var{X} when displayed using @var{newmap}.

When called with an optional third argument the order of colors in the new
colormap is defined by @var{index}.

@strong{Caution:} @var{index} should not have repeated elements or the
function will fail.

@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 the HSV color system
and vice versa.  It is also possible to convert from a color RGB image to a
grayscale image.

@c rgb2hsv scripts/image/rgb2hsv.m
@anchor{XREFrgb2hsv}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{hsv_map} =} rgb2hsv (@var{rgb_map})
@deftypefnx {} {@var{hsv_img} =} rgb2hsv (@var{rgb_img})
Transform a colormap or image from RGB to HSV color space.

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

A color in HSV space is represented by hue, saturation and value
(brightness) levels in a cylindrical coordinate system.  Hue is the
azimuth and describes the dominant color.  Saturation is the radial
distance and gives the amount of hue mixed into the color.  Value is
the height and is the amount of light in the color.

Output class and size will be the same as input.

@xseealso{@ref{XREFhsv2rgb,,hsv2rgb}, @ref{XREFrgb2ind,,rgb2ind}, @ref{XREFrgb2gray,,rgb2gray}}
@end deftypefn


@c hsv2rgb scripts/image/hsv2rgb.m
@anchor{XREFhsv2rgb}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{rgb_map} =} hsv2rgb (@var{hsv_map})
@deftypefnx {} {@var{rgb_img} =} hsv2rgb (@var{hsv_img})
Transform a colormap or image from HSV to RGB color space.

A color in HSV space is represented by hue, saturation and value
(brightness) levels in a cylindrical coordinate system.  Hue is the
azimuth and describes the dominant color.  Saturation is the radial
distance and gives the amount of hue mixed into the color.  Value is
the height and is the amount of light in the color.

The input can be both a colormap or RGB image.  In the case of floating
point input, values are expected to be on the [0 1] range.  In the case
of hue (azimuth), since the value corresponds to an angle,
@code{mod (h, 1)} is used.

@example
@group
>> hsv2rgb ([0.5 1 1])
@result{} ans = 0 1 1

>> hsv2rgb ([2.5 1 1])
@result{} ans = 0 1 1

>> hsv2rgb ([3.5 1 1])
@result{} ans = 0 1 1
@end group
@end example

Output class and size will be the same as input.

@xseealso{@ref{XREFrgb2hsv,,rgb2hsv}, @ref{XREFind2rgb,,ind2rgb}}
@end deftypefn


@c rgb2gray scripts/image/rgb2gray.m
@anchor{XREFrgb2gray}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{I} =} rgb2gray (@var{rgb_img})
@deftypefnx {} {@var{gray_map} =} rgb2gray (@var{rgb_map})
Transform an image or colormap from red-green-blue (RGB) color space to
a grayscale intensity image.

The input may be of class uint8, int8, uint16, int16, single, or double.
The output is of the same class as the input.

Implementation Note:
The grayscale intensity is calculated as

@example
@group
@var{I} = 0.298936*@var{R} + 0.587043*@var{G} + 0.114021*@var{B}
@end group
@end example

@noindent
which corresponds to the luminance channel when RGB is translated to
@nospell{YIQ} as documented in @url{https://en.wikipedia.org/wiki/YIQ}.
@xseealso{@ref{XREFrgb2hsv,,rgb2hsv}, @ref{XREFrgb2ind,,rgb2ind}}
@end deftypefn