Navigation

Operators and Keywords

Function List:

C++ API

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

Read images from various file formats.

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

The size and class of the output depends on the format of the image. A color image is returned as an MxNx3 matrix. Gray-level 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 gray and color, and "logical" for black and white. Note that indexed images always return the indexes for a colormap, independent if 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 only read the first page.

Depending on the file format, it is possible to configure the reading of images with param, val 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 and has no effect. For maximum performance while reading multiple images from a single file, use the Index option.

‘"PixelRegion"’

Controls the image region that is read. Takes as value 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, 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