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

@c Copyright (C) 1996-2015 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 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}
@deftypefn  {Function File} {[@var{img}, @var{map}, @var{alpha}] =} imread (@var{filename})
@deftypefnx {Function File} {[@dots{}] =} imread (@var{url})
@deftypefnx {Function File} {[@dots{}] =} imread (@dots{}, @var{ext})
@deftypefnx {Function File} {[@dots{}] =} imread (@dots{}, @var{idx})
@deftypefnx {Function File} {[@dots{}] =} imread (@dots{}, @var{param1}, @var{val1}, @dots{})
Read images from various file formats.

Read an image as a matrix from the file @var{filename}.  If there is no file
@var{filename}, and @var{ext} was specified, it will look for a file with
the extension @var{ext}.  Finally, it will attempt to download and read an
image from @var{url}.

The size and 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}.  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 gray and color,
and @qcode{"logical"} for black and white.  Note that indexed images always
return the indexes for a colormap, independent if @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.

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 only read the first
page.

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

@table @samp
@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 and has no effect.  For
maximum performance while reading multiple images from a single file, use
the Index option.

@item @qcode{"PixelRegion"}
Controls the image region that is read.  Takes as value 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, defaults to 1.  For example, the following are
all equivalent:

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

@end table

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


@c imwrite scripts/image/imwrite.m
@anchor{XREFimwrite}
@deftypefn  {Function File} {} imwrite (@var{img}, @var{filename})
@deftypefnx {Function File} {} imwrite (@var{img}, @var{filename}, @var{ext})
@deftypefnx {Function File} {} imwrite (@var{img}, @var{map}, @var{filename})
@deftypefnx {Function File} {} 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 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

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


@c IMAGE_PATH libinterp/corefcn/defaults.cc
@anchor{XREFIMAGE_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 @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.

@seealso{@ref{XREFEXEC_PATH,,EXEC_PATH}, @ref{XREFOCTAVE_HOME,,OCTAVE_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}
@deftypefn  {Function File} {@var{info} =} imfinfo (@var{filename})
@deftypefnx {Function File} {@var{info} =} imfinfo (@var{url})
@deftypefnx {Function File} {@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 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

@seealso{@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}
@deftypefn  {Function File} {} imformats ()
@deftypefnx {Function File} {@var{formats} =} imformats (@var{ext})
@deftypefnx {Function File} {@var{formats} =} imformats (@var{format})
@deftypefnx {Function File} {@var{formats} =} imformats ("add", @var{format})
@deftypefnx {Function File} {@var{formats} =} imformats ("remove", @var{ext})
@deftypefnx {Function File} {@var{formats} =} imformats ("update", @var{ext}, @var{format})
@deftypefnx {Function File} {@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 @code{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.

@seealso{@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}
@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
(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 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 @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 two element vector, it must contain horizontal axis
limits in the form [xmin xmax]; Otherwise @var{value1} must be a vector and
only the first and last elements will be used for xmin and xmax respectively.

@item @qcode{"ydata"}
If @var{value1} is a two element vector, it must contain vertical axis
limits in the form [ymin ymax]; Otherwise @var{value1} must be a vector and
only the first and last elements will be used for ymin and ymax respectively.

@end table

The optional return value @var{h} is a graphics handle to the image.
@seealso{@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}
@deftypefn  {Function File} {} image (@var{img})
@deftypefnx {Function File} {} image (@var{x}, @var{y}, @var{img})
@deftypefnx {Function File} {} image (@dots{}, "@var{prop}", @var{val}, @dots{})
@deftypefnx {Function File} {} image ("@var{prop1}", @var{val1}, @dots{})
@deftypefnx {Function File} {@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 range for the axis labels.  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.
@strong{Warning:} @var{x} and @var{y} are ignored when using gnuplot 4.0
or earlier.

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.
@seealso{@ref{XREFimshow,,imshow}, @ref{XREFimagesc,,imagesc}, @ref{XREFcolormap,,colormap}}
@end deftypefn


@c imagesc scripts/image/imagesc.m
@anchor{XREFimagesc}
@deftypefn  {Function File} {} imagesc (@var{img})
@deftypefnx {Function File} {} imagesc (@var{x}, @var{y}, @var{img})
@deftypefnx {Function File} {} imagesc (@dots{}, @var{climits})
@deftypefnx {Function File} {} imagesc (@dots{}, "@var{prop}", @var{val}, @dots{})
@deftypefnx {Function File} {} imagesc ("@var{prop1}", @var{val1}, @dots{})
@deftypefnx {Function File} {} imagesc (@var{hax}, @dots{})
@deftypefnx {Function File} {@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.

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{img}.

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.

@seealso{@ref{XREFimage,,image}, @ref{XREFimshow,,imshow}, @ref{XREFcaxis,,caxis}}
@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.

@c iscolormap scripts/image/iscolormap.m
@anchor{XREFiscolormap}
@deftypefn {Function File} {} iscolormap (@var{cmap})
Return true if @var{cmap} is a colormap.

A colormap is a real matrix with @var{n} rows and 3 columns.  Each row
represents a single color.  The columns contain red, green, and blue
intensities respectively.  All entries must be between 0 and 1 inclusive.
@seealso{@ref{XREFcolormap,,colormap}, @ref{XREFrgbplot,,rgbplot}}
@end deftypefn


@c gray2ind scripts/image/gray2ind.m
@anchor{XREFgray2ind}
@deftypefn  {Function File} {@var{img} =} gray2ind (@var{I})
@deftypefnx {Function File} {@var{img} =} gray2ind (@var{I}, @var{n})
@deftypefnx {Function File} {@var{img} =} gray2ind (@var{BW})
@deftypefnx {Function File} {@var{img} =} gray2ind (@var{BW}, @var{n})
@deftypefnx {Function File} {[@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.
@seealso{@ref{XREFind2gray,,ind2gray}, @ref{XREFrgb2ind,,rgb2ind}}
@end deftypefn


@c ind2gray scripts/image/ind2gray.m
@anchor{XREFind2gray}
@deftypefn {Function File} {@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{cmap}.  If @var{cmap} 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{rgb2ntsc} 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}.
@seealso{@ref{XREFgray2ind,,gray2ind}, @ref{XREFind2rgb,,ind2rgb}}
@end deftypefn


@c rgb2ind scripts/image/rgb2ind.m
@anchor{XREFrgb2ind}
@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 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.

@seealso{@ref{XREFind2rgb,,ind2rgb}, @ref{XREFrgb2hsv,,rgb2hsv}, @ref{XREFrgb2ntsc,,rgb2ntsc}}
@end deftypefn


@c ind2rgb scripts/image/ind2rgb.m
@anchor{XREFind2rgb}
@deftypefn  {Function File} {@var{rgb} =} ind2rgb (@var{x}, @var{map})
@deftypefnx {Function File} {[@var{R}, @var{G}, @var{B}] =} ind2rgb (@var{x}, @var{map})
Convert an indexed image to red, green, and blue color components.

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.

@seealso{@ref{XREFrgb2ind,,rgb2ind}, @ref{XREFind2gray,,ind2gray}, @ref{XREFhsv2rgb,,hsv2rgb}, @ref{XREFntsc2rgb,,ntsc2rgb}}
@end deftypefn


@c colormap scripts/image/colormap.m
@anchor{XREFcolormap}
@deftypefn  {Function File} {@var{cmap} =} colormap ()
@deftypefnx {Function File} {@var{cmap} =} colormap (@var{map})
@deftypefnx {Function File} {@var{cmap} =} colormap ("default")
@deftypefnx {Function File} {@var{cmap} =} colormap ("@var{map_name}")
@deftypefnx {Function File} {@var{cmap} =} colormap (@var{hax}, @dots{})
@deftypefnx {Command} {} colormap @var{map_name}
@deftypefnx {Function File} {@var{cmaps} =} colormap ("list")
@deftypefnx {Function File} {} colormap ("register", "@var{name}")
@deftypefnx {Function File} {} colormap ("unregister", "@var{name}")
Query or set the current colormap.

With no input arguments, @code{colormap} returns the current color map.

@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 ("default")} restores the default colormap (the
@code{jet} map with 64 entries).  The default colormap is returned.

The map may also be specified by a string, @qcode{"@var{map_name}"}, where
@var{map_name} 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 parent figure of @var{hax} is queried or set.

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

@code{colormap ("list")} returns a cell array with all of the available
colormaps.  The options @qcode{"register"} and @qcode{"unregister"}
add or remove the colormap @var{name} from this list.

@seealso{@ref{XREFjet,,jet}}
@end deftypefn


@c rgbplot scripts/image/rgbplot.m
@anchor{XREFrgbplot}
@deftypefn  {Function File} {} rgbplot (@var{cmap})
@deftypefnx {Function File} {} rgbplot (@var{cmap}, @var{style})
@deftypefnx {Function File} {@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 each RGB components 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.
@seealso{@ref{XREFcolormap,,colormap}}
@end deftypefn


@c autumn scripts/image/autumn.m
@anchor{XREFautumn}
@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{XREFcolormap,,colormap}}
@end deftypefn


@c bone scripts/image/bone.m
@anchor{XREFbone}
@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{XREFcolormap,,colormap}}
@end deftypefn


@c colorcube scripts/image/colorcube.m
@anchor{XREFcolorcube}
@deftypefn  {Function File} {@var{map} =} colorcube ()
@deftypefnx {Function File} {@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 unspecified, the length of the current colormap, or 64, is used.
@seealso{@ref{XREFcolormap,,colormap}}
@end deftypefn


@c cool scripts/image/cool.m
@anchor{XREFcool}
@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{XREFcolormap,,colormap}}
@end deftypefn


@c copper scripts/image/copper.m
@anchor{XREFcopper}
@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{XREFcolormap,,colormap}}
@end deftypefn


@c cubehelix scripts/image/cubehelix.m
@anchor{XREFcubehelix}
@deftypefn  {Function File} {@var{map} =} cubehelix ()
@deftypefnx {Function File} {@var{map} =} cubehelix (@var{n})
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 transversing 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 unspecified, the length of the current colormap, or 64, 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.

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


@c flag scripts/image/flag.m
@anchor{XREFflag}
@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{XREFcolormap,,colormap}}
@end deftypefn


@c gray scripts/image/gray.m
@anchor{XREFgray}
@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.
@seealso{@ref{XREFcolormap,,colormap}}
@end deftypefn


@c hot scripts/image/hot.m
@anchor{XREFhot}
@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{XREFcolormap,,colormap}}
@end deftypefn


@c hsv scripts/image/hsv.m
@anchor{XREFhsv}
@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.  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 unspecified, the length of the current colormap, or 64, is used.
@seealso{@ref{XREFcolormap,,colormap}}
@end deftypefn


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


@c lines scripts/image/lines.m
@anchor{XREFlines}
@deftypefn  {Function File} {@var{map} =} lines ()
@deftypefnx {Function File} {@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,
green, red, cyan, pink, yellow, and gray.

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


@c ocean scripts/image/ocean.m
@anchor{XREFocean}
@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.
@seealso{@ref{XREFcolormap,,colormap}}
@end deftypefn


@c pink scripts/image/pink.m
@anchor{XREFpink}
@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.

This colormap 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{XREFcolormap,,colormap}}
@end deftypefn


@c prism scripts/image/prism.m
@anchor{XREFprism}
@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{XREFcolormap,,colormap}}
@end deftypefn


@c rainbow scripts/image/rainbow.m
@anchor{XREFrainbow}
@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{XREFcolormap,,colormap}}
@end deftypefn


@c spring scripts/image/spring.m
@anchor{XREFspring}
@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{XREFcolormap,,colormap}}
@end deftypefn


@c summer scripts/image/summer.m
@anchor{XREFsummer}
@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{XREFcolormap,,colormap}}
@end deftypefn


@c white scripts/image/white.m
@anchor{XREFwhite}
@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} must be a scalar.
If unspecified, the length of the current colormap, or 64, is used.
@seealso{@ref{XREFcolormap,,colormap}}
@end deftypefn


@c winter scripts/image/winter.m
@anchor{XREFwinter}
@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{XREFcolormap,,colormap}}
@end deftypefn


@c contrast scripts/image/contrast.m
@anchor{XREFcontrast}
@deftypefn  {Function File} {@var{cmap} =} contrast (@var{x})
@deftypefnx {Function File} {@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.
@seealso{@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}
@deftypefn  {Function File} {@var{map_out} =} brighten (@var{beta})
@deftypefnx {Function File} {@var{map_out} =} brighten (@var{map}, @var{beta})
@deftypefnx {Function File} {@var{map_out} =} brighten (@var{h}, @var{beta})
@deftypefnx {Function File} {} 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.
@seealso{@ref{XREFcolormap,,colormap}, @ref{XREFcontrast,,contrast}}
@end deftypefn


@c spinmap scripts/image/spinmap.m
@anchor{XREFspinmap}
@deftypefn  {Function File} {} spinmap ()
@deftypefnx {Function File} {} spinmap (@var{t})
@deftypefnx {Function File} {} spinmap (@var{t}, @var{inc})
@deftypefnx {Function File} {} 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.
@seealso{@ref{XREFcolormap,,colormap}}
@end deftypefn


@c whitebg scripts/plot/appearance/whitebg.m
@anchor{XREFwhitebg}
@deftypefn  {Function File} {} whitebg ()
@deftypefnx {Function File} {} whitebg (@var{color})
@deftypefnx {Function File} {} whitebg ("none")
@deftypefnx {Function File} {} whitebg (@var{hfig}, @dots{})
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 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 default colors.

If the first argument @var{hfig} is a figure handle, then operate on
this figure rather than the current figure returned by @code{gcf}.  The
root properties will not be changed.
@seealso{@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}
@deftypefn  {Function File} {[@var{Y}, @var{newmap}] =} cmunique (@var{X}, @var{map})
@deftypefnx {Function File} {[@var{Y}, @var{newmap}] =} cmunique (@var{RGB})
@deftypefnx {Function File} {[@var{Y}, @var{newmap}] =} cmunique (@var{I})
Convert an input image @var{X} to an ouput 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.

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


@c cmpermute scripts/image/cmpermute.m
@anchor{XREFcmpermute}
@deftypefn  {Function File} {[@var{Y}, @var{newmap}] =} cmpermute (@var{X}, @var{map})
@deftypefnx {Function File} {[@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:} @code{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 NTSC and HSV
and vice versa.

@c rgb2hsv scripts/image/rgb2hsv.m
@anchor{XREFrgb2hsv}
@deftypefn  {Function File} {@var{hsv_map} =} rgb2hsv (@var{rgb})
@deftypefnx {Function File} {@var{hsv_map} =} rgb2hsv (@var{rgb})
Transform a colormap or image from red-green-blue (RGB) space to
hue-saturation-value (HSV) 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.  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{XREFhsv2rgb,,hsv2rgb}, @ref{XREFrgb2ind,,rgb2ind}, @ref{XREFrgb2ntsc,,rgb2ntsc}}
@end deftypefn


@c hsv2rgb scripts/image/hsv2rgb.m
@anchor{XREFhsv2rgb}
@deftypefn  {Function File} {@var{rgb_map} =} hsv2rgb (@var{hsv_map})
@deftypefnx {Function File} {@var{rgb_img} =} hsv2rgb (@var{hsv_img})
Transform a colormap or image from hue-saturation-value (HSV) space to
red-green-blue (RGB) space.

A color in HSV space is represented by hue, saturation and value
(brightness) levels.  Value gives the amount of light in the color.  Hue
describes the dominant wavelength.  Saturation is the amount of hue mixed
into the color.

A color in the RGB space consists of red, green, and blue intensities.
@seealso{@ref{XREFrgb2hsv,,rgb2hsv}, @ref{XREFind2rgb,,ind2rgb}, @ref{XREFntsc2rgb,,ntsc2rgb}}
@end deftypefn


@c rgb2ntsc scripts/image/rgb2ntsc.m
@anchor{XREFrgb2ntsc}
@deftypefn  {Function File} {@var{yiq_map} =} rgb2ntsc (@var{rgb_map})
@deftypefnx {Function File} {@var{yiq_img} =} rgb2ntsc (@var{rgb_img})
Transform a colormap or image from red-green-blue (RGB) color space to
luminance-chrominance (NTSC) space.  The input may be of class uint8,
uint16, single, or double.  The output is of class double.

Implementation Note:
The reference matrix for the transformation is

@example
@group
/Y\     0.299  0.587  0.114  /R\
|I|  =  0.596 -0.274 -0.322  |G|
\Q/     0.211 -0.523  0.312  \B/
@end group
@end example

@noindent
as documented in @url{http://en.wikipedia.org/wiki/YIQ} and truncated to 3
significant figures.  Note: The FCC version of NTSC uses only 2 significant
digits and is slightly different.
@seealso{@ref{XREFntsc2rgb,,ntsc2rgb}, @ref{XREFrgb2hsv,,rgb2hsv}, @ref{XREFrgb2ind,,rgb2ind}}
@end deftypefn


@c ntsc2rgb scripts/image/ntsc2rgb.m
@anchor{XREFntsc2rgb}
@deftypefn  {Function File} {@var{rgb_map} =} ntsc2rgb (@var{yiq_map})
@deftypefnx {Function File} {@var{rgb_img} =} ntsc2rgb (@var{yiq_img})
Transform a colormap or image from luminance-chrominance (NTSC) space to
red-green-blue (RGB) color space.

Implementation Note:
The conversion matrix is chosen to be the inverse of the matrix used for
rgb2ntsc such that

@example
x == ntsc2rgb (rgb2ntsc (x))
@end example

@sc{matlab} uses a slightly different matrix where rounding means the
equality above does not hold.
@seealso{@ref{XREFrgb2ntsc,,rgb2ntsc}, @ref{XREFhsv2rgb,,hsv2rgb}, @ref{XREFind2rgb,,ind2rgb}}
@end deftypefn