Navigation

Operators and Keywords

Function List:

C++ API

: [img, map, alpha] = imread (filename)
: […] = imread (url)
: […] = imread (…, ext)
: […] = imread (…, idx)
: […] = imread (…, param1, value1, …)

Read images from various file formats.

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

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

The bit depth of the image determines the class of the output: "uint8", "uint16", or "single" for grayscale and color, and "logical" for black-and-white. Note that indexed images always return the indexes for a colormap, independent of whether map is a requested output. To obtain the actual RGB image, use ind2rgb. When more than one indexed image is being read, map is obtained from the first. In some rare cases this may be incorrect and 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. 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 parameter, value pairs. The following options are supported:

"Frames" or "Index"

This is an alternative method to specify idx. When specifying it in this way, its value can also be the string "all".

"Info"

This option exists for MATLAB compatibility, but has no effect. For maximum performance when reading multiple images from a single file, use the "Index" option.

"PixelRegion"

Controls the image region that is read. The value must be a cell array with two arrays of 3 elements {[rows], [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: 

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

See also: imwrite, imfinfo, imformats.

Package: octave