function [X, map, alpha] = imread(varargin)
%IMREAD Read image from graphics file.
% A = IMREAD(FILENAME,FMT) reads a grayscale or color image from the file
% specified by the string FILENAME. If the file is not in the current
% directory, or in a directory on the MATLAB path, specify the full
% pathname.
%
% The text string FMT specifies the format of the file by its standard
% file extension. For example, specify 'gif' for Graphics Interchange
% Format files. To see a list of supported formats, with their file
% extensions, use the IMFORMATS function. If IMREAD cannot find a file
% named FILENAME, it looks for a file named FILENAME.FMT.
%
% The return value A is an array containing the image data. If the file
% contains a grayscale image, A is an M-by-N array. If the file contains
% a truecolor image, A is an M-by-N-by-3 array. For TIFF files containing
% color images that use the CMYK color space, A is an M-by-N-by-4 array.
% See TIFF in the Format-Specific Information section for more
% information.
%
% The class of A depends on the bits-per-sample of the image data,
% rounded to the next byte boundary. For example, IMREAD returns 24-bit
% color data as an array of uint8 data because the sample size for each
% color component is 8 bits. See the Remarks section for a discussion of
% bitdepths, and see the Format-Specific Information section for more
% detail about supported bitdepths and sample sizes for a particular
% format.
%
% [X,MAP] = IMREAD(FILENAME,FMT) reads the indexed image in FILENAME into
% X and its associated colormap into MAP. Colormap values in the image
% file are automatically rescaled into the range [0,1].
%
% [...] = IMREAD(FILENAME) attempts to infer the format of the file
% from its content.
%
% [...] = IMREAD(URL,...) reads the image from an Internet URL. The
% URL must include the protocol type (e.g., "http://").
%
% Remarks
%
% Bitdepth is the number of bits used to represent each image pixel.
% Bitdepth is calculated by multiplying the bits-per-sample with the
% samples-per-pixel. Thus, a format that uses 8-bits for each color
% component (or sample) and three samples per pixel has a bitdepth of 24.
% Sometimes the sample size associated with a bitdepth can be ambiguous:
% does a 48-bit bitdepth represent six 8-bit samples or three 16-bit
% samples? The following format-specific sections provide sample size
% information to avoid this ambiguity.
%
% Format-Specific Information (Listed Alphabetically by Format)
%
% BMP -- Windows Bitmap
%
% Supported Compression Output
% Bitdepths None RLE Class Notes
% ---------------------------------------------------------
% 1-bit x - logical
% 4-bit x x uint8
% 8-bit x x uint8
% 16-bit x - uint8 1 sample/pixel
% 24-bit x - uint8 3 samples/pixel
% 32-bit x - uint8 3 samples/pixel (1 byte padding)
%
% CUR -- Cursor File
%
% Supported Compression Output
% Bitdepths None Compressed Class
% --------------------------------------------------
% 1-bit x - logical
% 4-bit x - uint8
% 8-bit x - uint8
%
% Special syntaxes:
%
% [...] = IMREAD(...,IDX) reads in one image from a multi-image icon or
% cursor file. IDX is an integer value that specifies the order that the
% image appears in the file. For example, if IDX is 3, IMREAD reads the
% third image in the file. If you omit this argument, IMREAD reads the
% first image in the file.
%
% [A,MAP,ALPHA] = IMREAD(...) returns the AND mask for the resource,
% which can be used to determine transparency information. For cursor
% files, this mask may contain the only useful data.
%
% GIF -- Graphics Interchange Format
%
% Supported Compression Output
% Bitdepths None Compressed Class
% ---------------------------------------------
% 1-bit x - logical
% 2-to-8 bit x - uint8
%
% Special syntaxes:
%
% [...] = IMREAD(...,IDX) reads in one or more frames from a multiframe
% (i.e., animated) GIF file. IDX must be an integer scalar or vector of
% integer values. For example, if IDX is 3, IMREAD reads the third image
% in the file. If IDX is 1:5, only the first five frames are returned.
%
% [...] = IMREAD(...,'Frames',IDX) is the same as the syntax above except
% that IDX can be 'all'. In this case, all of the frames are read and
% returned in the order that they appear in the file.
%
% Note: Because of the way GIF files are structured, all of the frames
% must be read when a particular frame is requested. Consequently, it is
% much faster to specify a vector of frames or 'all' for IDX than to call
% IMREAD in a loop when reading multiple frames from the same GIF file.
%
% HDF -- Hierarchical Data Format
%
% Supported Raster image Raster image Output
% Bitdepths with colormap without colormap Class Notes
% ------------------------------------------------------------
% 8-bit x x uint8
% 24-bit - x uint8 3 samples/pixel
%
% Special Syntaxes:
%
% [...] = IMREAD(...,REF) reads in one image from a multi-image HDF file.
% REF is an integer value that specifies the reference number used to
% identify the image. For example, if REF is 12, IMREAD reads the image
% whose reference number is 12. (Note that in an HDF file the reference
% numbers do not necessarily correspond with the order of the images in
% the file. You can use IMFINFO to match up image order with reference
% number.) If you omit this argument, IMREAD reads the first image in
% the file.
%
% ICO -- Icon File
%
% See CUR.
%
% JPEG -- Joint Photographic Experts Group
%
% Note: IMREAD can read any baseline JPEG image as well as JPEG images
% with some commonly used extensions.
%
% Supported Compression Output
% Bitdepths Lossy Lossless Class Notes
% --------------------------------------------------------
% 8-bit x x uint8 Grayscale or RGB
% 12-bit x x uint16 Grayscale
% 16-bit - x uint16 Grayscale
% 36-bit x x uint16 RGB(Three 12-bit samples/pixel)
%
% PBM -- Portable Bitmap
%
% Supported Raw ASCII (Plain) Output
% Bitdepths Binary Encoded Class
% ----------------------------------------
% 1-bit x x logical
%
% PCX -- Windows Paintbrush
%
% Supported Output
% Bitdepths Class Notes
% ----------------------------------------------
% 1-bit logical Grayscale only
% 8-bit uint8 Grayscale or indexed
% 24-bit uint8 RGB (8-bit samples)
%
% PGM -- Portable Graymap
%
% Supported Raw ASCII (Plain) Output
% Bitdepths Binary Encoded Class
% ------------------------------------------------
% up to 16-bit x - uint8
% Arbitrary - x
%
% PNG -- Portable Network Graphics
%
% Supported Output
% Bitdepths Class Notes
% -------------------------------------------
% 1-bit logical Grayscale only
% 2-bit uint8 Grayscale only
% 4-bit uint8 Grayscale only
% 8-bit uint8 Grayscale or Indexed
% 16-bit