imwrite (MATLAB Functions)

Write image to graphics file

Syntax

imwrite(A,filename,fmt)
imwrite(X,map,filename,fmt)
imwrite(...,filename)
imwrite(...,Param1,Val1,Param2,Val2...)

Description

imwrite(A,filename,fmt) writes the image A to the file specified by filename in the format specified by fmt.

A can be an M-by-N (greyscale image) or M-by-N-by-3 (color image) array. A cannot be an empty array. If the format specified is TIFF, imwrite can also accept an M-by-N-by-4 arrray containing color data that uses the CMYK color space. For information about the class of the input array and the output image, see Class Support.

filename is a string that specifies the name of the output file.

fmt can be any of the text strings listed in the table in Supported Formats. This list of supported formats is determined by the MATLAB image file format registry. See imformats for more information about this registry.

imwrite(X,map,filename,fmt) writes the indexed image in X and its associated colormap map to filename in the format specified by fmt. If X is of class uint8 or uint16, imwrite writes the actual values in the array to the file. If X is of class double, the imwrite function offsets the values in the array before writing, using uint8(X-1). The map parameter must be a valid MATLAB colormap. Note that most image file formats do not support colormaps with more than 256 entries.

imwrite(...,filename) writes the image to filename, inferring the format to use from the filename's extension. The extension must be one of the values for fmt, listed in Supported Formats.

imwrite(...,Param1,Val1,Param2,Val2...) specifies parameters that control various characteristics of the output file for HDF, JPEG, PBM, PGM, PNG, PPM, and TIFF files. For example, if you are writing a JPEG file, you can specify the quality of the output image. For the lists of parameters available for each format, see Format-Specific Parameters.

Supported Formats

This table summarizes the types of images that imwrite can write. The MATLAB file format registry determines which file formats are supported. See imformats for more information about this registry. Note that, for certain formats, imwrite may take additional parameters, described in Format-Specific Parameters.

Format
Full Name
Variants

'bmp'
Windows Bitmap (BMP
1-bit, 8-bit, and 24-bit uncompressed images

'gif'
Graphics Interchange Format (GIF)
8-bit images

'hdf'
Hierarchical Data Format (HDF)
8-bit raster image datasets, with or without associated colormap, 24-bit raster image data sets; uncompressed or with RLE or JPEG compression

'jpg' or 'jpeg'
Joint Photographic Experts Group (JPEG)
8-bit, 12-bit, and 16-bit Baseline JPEG images
Note: Indexed images are converted to RGB before writing out JPEG files, because the JPEG format does not support indexed images.

'pbm'
Portable Bitmap (PBM)
Any 1-bit PBM image, ASCII (plain) or raw (binary) encoding

'pcx'
Windows Paintbrush (PCX)
8-bit images

'pgm'
Portable Graymap (PGM)
Any standard PGM image; ASCII (plain) encoded with arbitrary color depth; raw (binary) encoded with up to 16 bits per gray value

'png'
Portable Network Graphics (PNG)
1-bit, 2-bit, 4-bit, 8-bit, and 16-bit grayscale images; 8-bit and 16-bit grayscale images with alpha channels; 1-bit, 2-bit, 4-bit, and 8-bit indexed images; 24-bit and 48-bit truecolor images; 24-bit and 48-bit truecolor images with alpha channels

'pnm'
Portable Anymap (PNM)
Any of the PPM/PGM/PBM formats, chosen automatically

'ppm'
Portable Pixmap (PPM)
Any standard PPM image. ASCII (plain) encoded with arbitrary color depth; raw (binary) encoded with up to 16 bits per color component

'ras'
Sun Raster (RAS)
Any RAS image, including 1-bit bitmap, 8-bit indexed, 24-bit truecolor and 32-bit truecolor with alpha

'tif' or 'tiff'
Tagged Image File Format (TIFF)
Baseline TIFF images, including 1-bit, 8-bit, 16-bit, and 24-bit uncompressed images; 1-bit, 8-bit, 16-bit, and 24-bit images with packbits compression; 1-bit images with CCITT 1D, Group 3, and Group 4 compression; CIELAB, ICCLAB, and CMYK images

'xwd'
X Windows Dump (XWD)
8-bit ZPixmaps

Format	Full Name	Variants
`'bmp'`	Windows Bitmap (BMP	1-bit, 8-bit, and 24-bit uncompressed images
`'gif'`	Graphics Interchange Format (GIF)	8-bit images
`'hdf'`	`Hierarchical Data Format (HDF)`	8-bit raster image datasets, with or without associated colormap, 24-bit raster image data sets; uncompressed or with RLE or JPEG compression
`'jpg' or 'jpeg'`	Joint Photographic Experts Group (JPEG)	8-bit, 12-bit, and 16-bit Baseline JPEG images Note: Indexed images are converted to RGB before writing out JPEG files, because the JPEG format does not support indexed images.
`'pbm'`	Portable Bitmap (PBM)	Any 1-bit PBM image, ASCII (plain) or raw (binary) encoding
`'pcx'`	Windows Paintbrush (PCX)	8-bit images
`'pgm'`	Portable Graymap (PGM)	Any standard PGM image; ASCII (plain) encoded with arbitrary color depth; raw (binary) encoded with up to 16 bits per gray value
`'png'`	Portable Network Graphics (PNG)	1-bit, 2-bit, 4-bit, 8-bit, and 16-bit grayscale images; 8-bit and 16-bit grayscale images with alpha channels; 1-bit, 2-bit, 4-bit, and 8-bit indexed images; 24-bit and 48-bit truecolor images; 24-bit and 48-bit truecolor images with alpha channels
`'pnm'`	`Portable Anymap (PNM)`	Any of the PPM/PGM/PBM formats, chosen automatically
`'ppm'`	Portable Pixmap (PPM)	Any standard PPM image. ASCII (plain) encoded with arbitrary color depth; raw (binary) encoded with up to 16 bits per color component
`'ras'`	Sun Raster (RAS)	Any RAS image, including 1-bit bitmap, 8-bit indexed, 24-bit truecolor and 32-bit truecolor with alpha
`'tif' or 'tiff'`	Tagged Image File Format (TIFF)	Baseline TIFF images, including 1-bit, 8-bit, 16-bit, and 24-bit uncompressed images; 1-bit, 8-bit, 16-bit, and 24-bit images with packbits compression; 1-bit images with CCITT 1D, Group 3, and Group 4 compression; CIELAB, ICCLAB, and CMYK images
`'xwd'`	X Windows Dump (XWD)	8-bit ZPixmaps

Format-Specific Parameters

The following tables list parameters that can be used with specific file formats.

GIF-Specific Parameters

This table describes the available parameters for GIF files.

Parameter
Values
Default

'BackgroundColor'

A scalar integer. This value specifies which index in the colormap should be treated as the transparent color for the image and is used for certain disposal methods in animated GIFs. If X is uint8 or logical, then indexing starts at 0. If X is double, then indexing starts at 1.

'Comment'

A string or cell array of strings containing a comment to be added to the image. For a cell array of strings, a carriage return is added after each row.

'DelayTime'

A scalar value between 0 and 655 inclusive, that specifies the delay in seconds before displaying the next image.

'DisposalMethod'

One of the following strings, which sets the disposal method of an animated GIF: 'leaveInPlace', 'restoreBG', 'restorePrevious', or 'doNotSpecify'.

'LoopCount'

A finite integer between 0 and 65535 or the value Inf (the default) which specifies the number of times to repeat the animation. By default, the animation loops continuously. For a value of 0, the animation will be played once. For a value of 1, the animation will be played twice, etc.
Inf

'TransparentColor'

A scalar integer. This value specifies which index in the colormap should be treated as the transparent color for the image. If X is uint8 or logical, then indexing starts at 0. If X is double, then indexing starts at 1.

'WriteMode'

One of these strings: 'overwrite' (the default) or 'append'. In append mode, a single frame is added to the existing file.
'overwrite'

Parameter	Values	Default
`'BackgroundColor'`	A scalar integer. This value specifies which index in the colormap should be treated as the transparent color for the image and is used for certain disposal methods in animated GIFs. If `X` is `uint8` or `logical`, then indexing starts at `0`. If `X` is `double`, then indexing starts at `1`.
`'Comment'`	A string or cell array of strings containing a comment to be added to the image. For a cell array of strings, a carriage return is added after each row.
`'DelayTime'`	A scalar value between 0 and 655 inclusive, that specifies the delay in seconds before displaying the next image.
`'DisposalMethod'`	One of the following strings, which sets the disposal method of an animated GIF: `'leaveInPlace'`, `'restoreBG'`, `'restorePrevious'`, or `'doNotSpecify'`.
`'LoopCount'`	A finite integer between 0 and 65535 or the value `Inf` (the default) which specifies the number of times to repeat the animation. By default, the animation loops continuously. For a value of 0, the animation will be played once. For a value of 1, the animation will be played twice, etc.	`Inf`
`'TransparentColor'`	A scalar integer. This value specifies which index in the colormap should be treated as the transparent color for the image. If X is `uint8` or `logical`, then indexing starts at `0`. If X is double, then indexing starts at `1`.
`'WriteMode'`	One of these strings: `'overwrite'` (the default) or `'append'`. In append mode, a single frame is added to the existing file.	`'overwrite'`

HDF-Specific Parameters

This table describes the available parameters for HDF files.

Parameter
Values
Default

'Compression'
One of these strings:
'none' 'jpeg'(valid only for grayscale and RGB images)
'rle' (valid only for grayscale and indexed images)
'rle'

'Quality'
A number between 0 and 100; this parameter applies only if 'Compression' is 'jpeg'.
Higher numbers mean higher quality (less image degradation due to compression), but the resulting file size is larger.
75

'WriteMode'
One of these strings:
'overwrite' 'append'
'overwrite'

Parameter	Values	Default
`'Compression'`	One of these strings: `'none' 'jpeg'`(valid only for grayscale and RGB images) `'rle'` (valid only for grayscale and indexed images)	`'rle'`
`'Quality'`	A number between 0 and 100; this parameter applies only if `'Compression'` is `'jpeg'`. Higher numbers mean higher quality (less image degradation due to compression), but the resulting file size is larger.	`75`
`'WriteMode'`	One of these strings: `'overwrite' 'append'`	`'overwrite'`

JPEG-Specific Parameters

This table describes the available parameters for JPEG files.

Parameter
Values
Default

'Bitdepth'
A scalar value indicating desired bitdepth;
for grayscale images this can be 8, 12, or 16;
for color images this can be 8 or 12.
8 (grayscale) and 8 bit per plane for color images

'Comment'
A column vector cell array of strings or a character matrix. Each row of input is written out as a comment in the JPEG file.
Empty

'Mode'
Specifies the type of compression used; value can be either of these strings: 'lossy' or 'lossless'
'lossy'

'Quality'
A number between 0 and 100; higher numbers mean higher quality (less image degradation due to compression), but the resulting file size is larger.
75

Parameter	Values	Default
`'Bitdepth'`	A scalar value indicating desired bitdepth; for grayscale images this can be 8, 12, or 16; for color images this can be 8 or 12.	8 (grayscale) and 8 bit per plane for color images
`'Comment'`	A column vector cell array of strings or a character matrix. Each row of input is written out as a comment in the JPEG file.	Empty
`'Mode'`	Specifies the type of compression used; value can be either of these strings: `'lossy'` or `'lossless'`	`'lossy'`
`'Quality'`	A number between 0 and 100; higher numbers mean higher quality (less image degradation due to compression), but the resulting file size is larger.	`75`

PBM-, PGM-, and PPM-Specific Parameters

This table describes the available parameters for PBM, PGM, and PPM files.

Parameter
Values
Default

'Encoding'
One of these strings:
'ASCII' for plain encoding
'rawbits' for binary encoding
'rawbits'

'MaxValue'
A scalar indicating the maximum gray or color value. Available only for PGM and PPM files.
For PBM files, this value is always 1.
Default is 65535 if image array is 'uint16'; 255 otherwise.

Parameter	Values	Default
`'Encoding'`	One of these strings: `'ASCII'` for plain encoding `'rawbits'` for binary encoding	`'rawbits'`
`'MaxValue'`	A scalar indicating the maximum gray or color value. Available only for PGM and PPM files. For PBM files, this value is always `1`.	Default is `65535` if image array is `'uint16'`; `255` otherwise.

PNG-Specific Parameters

The following table describes the available parameters for PNG files. In addition to these PNG parameters, you can use any parameter name that satisfies the PNG specification for keywords; that is, uses only printable characters, contains 80 or fewer characters, and no contains no leading or trailing spaces. The value corresponding to these user-specified parameters must be a string that contains no control characters other than linefeed.

Parameter
Values
Default

'Author'
A string
Empty

'Description'
A string
Empty

'Copyright'
A string
Empty

'CreationTime'
A string
Empty

'Software'
A string
Empty

'Disclaimer'
A string
Empty

'Warning'
A string
Empty

'Source'
A string
Empty

'Comment'
A string
Empty

'InterlaceType'
Either 'none' or 'adam7'
'none'

'BitDepth'
A scalar value indicating desired bit depth. For grayscale images this can be 1, 2, 4, 8, or 16.
For grayscale images with an alpha channel this can be 8 or 16. For indexed images this can be 1, 2, 4, or 8. For truecolor images with or without an alpha channel this can be 8 or 16.
8 bits per pixel if image is double or uint8;
16 bits per pixel if image is uint16;
1 bit per pixel if image is logical

'Transparency'
This value is used to indicate transparency information only when no alpha channel is used. Set to the value that indicates which pixels should be considered transparent. (If the image uses a colormap, this value represents an index number to the colormap.)
For indexed images: a Q-element vector in the range [0,1], where Q is no larger than the colormap length and each value indicates the transparency associated with the corresponding colormap entry. In most cases, Q = 1.
For grayscale images: a scalar in the range [0,1]. The value indicates the grayscale color to be considered transparent.
For truecolor images: a three-element vector in the range [0,1]. The value indicates the true-color color to be considered transparent.

Note: You cannot specify 'Transparency' and 'Alpha' at the same time.
Empty

'Background'
The value specifies background color to be used when compositing transparent pixels. For indexed images: an integer in the range [1,P], where P is the colormap length. For grayscale images: a scalar in the range [0,1]. For truecolor images: a three-element vector in the range [0,1].
Empty

'Gamma'
A nonnegative scalar indicating the file gamma
Empty

'Chromaticities'
An eight-element vector [wx wy rx ry gx gy bx by] that specifies the reference white point and the primary chromaticities
Empty

'XResolution'
A scalar indicating the number of pixels/unit in the horizontal direction
Empty

'YResolution'
A scalar indicating the number of pixels/unit in the vertical direction
Empty

'ResolutionUnit'
Either 'unknown' or 'meter'
Empty

'Alpha'
A matrix specifying the transparency of each pixel individually. The row and column dimensions must be the same as the data array; they can be uint8, uint16, or double, in which case the values should be in the range [0,1].
Empty

'SignificantBits'
A scalar or vector indicating how many bits in the data array should be regarded as significant; values must be in the range [1,BitDepth].
For indexed images: a three-element vector. For grayscale images: a scalar. For grayscale images with an alpha channel: a two-element vector. For truecolor images: a three-element vector. For truecolor images with an alpha channel: a four-element vector.
Empty

Parameter	Values	Default
`'Author'`	A string	Empty
`'Description'`	A string	Empty
`'Copyright'`	A string	Empty
`'CreationTime'`	A string	Empty
`'Software'`	A string	Empty
`'Disclaimer'`	A string	Empty
`'Warning'`	A string	Empty
`'Source'`	A string	Empty
`'Comment'`	A string	Empty
`'InterlaceType'`	Either `'none'` or `'adam7'`	`'none'`
`'BitDepth'`	A scalar value indicating desired bit depth. For grayscale images this can be 1, 2, 4, 8, or 16. For grayscale images with an alpha channel this can be 8 or 16. For indexed images this can be 1, 2, 4, or 8. For truecolor images with or without an alpha channel this can be 8 or 16.	8 bits per pixel if image is double or `uint8`; 16 bits per pixel if image is `uint16`; 1 bit per pixel if image is `logical`
`'Transparency'`	This value is used to indicate transparency information only when no alpha channel is used. Set to the value that indicates which pixels should be considered transparent. (If the image uses a colormap, this value represents an index number to the colormap.) For indexed images: a `Q-`element vector in the range [0,1], where `Q` is no larger than the colormap length and each value indicates the transparency associated with the corresponding colormap entry. In most cases, `Q = 1`. For grayscale images: a scalar in the range [0,1]. The value indicates the grayscale color to be considered transparent. For truecolor images: a three-element vector in the range [0,1]. The value indicates the true-color color to be considered transparent. Note: You cannot specify `'Transparency'` and `'Alpha'` at the same time.	Empty
`'Background'`	The value specifies background color to be used when compositing transparent pixels. For indexed images: an integer in the range [1,`P`], where `P` is the colormap length. For grayscale images: a scalar in the range [0,1]`.` For truecolor images: a three-element vector in the range [0,1]`.`	Empty
`'Gamma'`	A nonnegative scalar indicating the file gamma	Empty
`'Chromaticities'`	An eight-element vector `[wx wy rx ry gx gy bx by]` that specifies the reference white point and the primary chromaticities	Empty
`'XResolution'`	A scalar indicating the number of pixels/unit in the horizontal direction	Empty
`'YResolution'`	A scalar indicating the number of pixels/unit in the vertical direction	Empty
`'ResolutionUnit'`	Either `'unknown'` or `'meter'`	Empty
`'Alpha'`	A matrix specifying the transparency of each pixel individually. The row and column dimensions must be the same as the data array; they can be `uint8`, `uint16`, or `double`, in which case the values should be in the range [0,1]`.`	Empty
`'SignificantBits'`	A scalar or vector indicating how many bits in the data array should be regarded as significant; values must be in the range [1,`BitDepth`]. For indexed images: a three-element vector. For grayscale images: a scalar. For grayscale images with an alpha channel: a two-element vector. For truecolor images: a three-element vector. For truecolor images with an alpha channel: a four-element vector.	Empty

RAS-Specific Parameters

This table describes the available parameters for RAS files.

Parameter
Values
Default

'Alpha'
A matrix specifying the transparency of each pixel individually; the row and column dimensions must be the same as the data array; can be uint8, uint16, or double. Can only be used with truecolor images.
Empty matrix ([])

'Type'
One of these strings:
'standard' (uncompressed, b-g-r color order with truecolor images)
'rgb' (like 'standard', but uses r-g-b color order for truecolor images)
'rle' (run-length encoding of 1-bit and 8-bit images)
'standard'

Parameter	Values	Default
`'Alpha'`	A matrix specifying the transparency of each pixel individually; the row and column dimensions must be the same as the data array; can be `uint8`, `uint16`, or `double`. Can only be used with truecolor images.	Empty matrix (`[]`)
`'Type'`	One of these strings: `'standard'` (uncompressed, b-g-r color order with truecolor images) `'rgb'` (like `'standard'`, but uses r-g-b color order for truecolor images) `'rle'` (run-length encoding of 1-bit and 8-bit images)	`'standard'`

TIFF-Specific Parameters

This table describes the available parameters for TIFF files.

Parameter
Values
Default

'ColorSpace'
Specifies one of the following color spaces used to represent the color data.
'rgb' 'cielab' 'icclab'
See L*a*b* Color Data for more information about this parameter.
'rgb'

'Compression'
One of these strings: 'none', 'packbits', 'ccitt', 'fax3', or 'fax4'
The 'ccitt', 'fax3', and 'fax4' compression schemes are valid for binary images only.

'ccitt' for binary images; 'packbits' for nonbinary images

'Description'
Any string; fills in the ImageDescription field returned by imfinfo
Empty

'Resolution'
A two-element vector containing the XResolution and YResolution, or a scalar indicating both resolutions
72

'WriteMode'
One of these strings:
'overwrite' 'append'
'overwrite'

Parameter	Values	Default
`'ColorSpace'`	Specifies one of the following color spaces used to represent the color data. `'rgb' 'cielab' 'icclab'` See Lab* Color Data for more information about this parameter.	`'rgb'`
`'Compression'`	One of these strings: `'none'`, `'packbits'`, `'ccitt'`, `'fax3'`, or `'fax4'` The `'ccitt'`, `'fax3'`, and `'fax4'` compression schemes are valid for binary images only.	`'ccitt'` for binary images; `'packbits'` for nonbinary images
`'Description'`	Any string; fills in the `ImageDescription` field returned by `imfinfo`	Empty
`'Resolution'`	A two-element vector containing the XResolution and YResolution, or a scalar indicating both resolutions	`72`
`'WriteMode'`	One of these strings: `'overwrite' 'append'`	`'overwrite'`

Class Support

The input array A can be of class logical, uint8, uint16, or double. Indexed images (X) can be of class uint8, uint16, or double; the associated colormap, map, must be of class double.

The class of the image written to the file depends on the format specified. For most formats, if the input array is of class uint8, imwrite outputs the data as 8-bit values. If the input array is of class uint16 and the format supports 16-bit data (JPEG, PNG, and TIFF), imwrite outputs the data as 16-bit values. If the format does not support 16-bit values, imwrite issues an error. Several formats, such as JPEG and PNG, support a parameter that lets you specify the bitdepth of the output data.

If the input array is of class double, and the image is a grayscale or RGB color image, imwrite assumes the dynamic range is [0,1] and automatically scales the data by 255 before writing it to the file as 8-bit values.

If the input array is of class double, and the image is an indexed image, imwrite converts the indices to zero-based indices by subtracting 1 from each element, and then writes the data as uint8.

If the input array is of class logical, imwrite assumes the data is a binary image and writes it to the file with a bit depth of 1, if the format allows it. BMP, PNG, or TIFF formats accept binary images as input arrays.

L*a*b* Color Data

For TIFF files only, imwrite can write a color image that uses the L*a*b* color space. The 1976 CIE L*a*b* specification defines numeric values that represent luminance (L*) and chrominance (a* and b*) information.

To store L*a*b* color data in a TIFF file, the values must be encoded to fit into either 8-bit or 16-bit storage. imwrite can store L*a*b* color data in a TIFF file using these encodings:

8-bit and 16-bit encodings defined by the TIFF specification, called the CIELAB encodings
8-bit and 16-bit encodings defined by the International Color Consortium , called ICCLAB encodings

The output class and encoding used by imwrite to store color data depends on the class of the input array and the value you specify for the TIFF-specific ColorSpace parameter. The following table explains these options. (The 8-bit and 16-bit CIELAB encodings cannot be input arrays because they use a mixture of signed and unsigned values and cannot be represented as a single MATLAB array.)

Input Class and Encoding
ColorSpace Parameter Value
Output Class and Encoding

8-bit ICCLAB ¹
'icclab'
8-bit ICCLAB

'cielab'
8-bit CIELAB

16-bit ICCLAB ²
'icclab'
16-bit ICCLAB

'cielab'
16-bit CIELAB

double precision 1976 CIE L*a*b* values ³
'icclab'
8-bit ICCLAB

'cielab'
8-bit CIELAB

Input Class and Encoding	ColorSpace Parameter Value	Output Class and Encoding
8-bit ICCLAB ¹	`'icclab'`	8-bit ICCLAB
	`'cielab'`	8-bit CIELAB
16-bit ICCLAB ²	`'icclab'`	16-bit ICCLAB
	`'cielab'`	16-bit CIELAB
double precision 1976 CIE Lab* values ³	`'icclab'`	8-bit ICCLAB
	`'cielab'`	8-bit CIELAB

¹ 8-bit ICCLAB represents values as integers in the range [0 255]. L* values are multiplied by 255/100; 128 is added to both the a* and b* values.

² 16-bit ICCLAB multiplies L* values by 65280/100 and represents the values as integers in the range [0, 65280]. 32768 is added to both the a* and b* values, which are represented as integers in the range [0,65535].

³ L* is in the dynamic range [0, 100]. a* and b* can take any value. Setting a* and b* to 0 produces a neutral color (gray).

Example

This example appends an indexed image X and its colormap map to an existing uncompressed multipage HDF file.

imwrite(X,map,'your_hdf_file.hdf','Compression','none',...
'WriteMode','append')

See Also

fwrite, getframe, imfinfo, imformats, imread

Bit-Mapped Images for related functions

imread ind2rgb