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 in A to filename in the format specified by fmt. A can be either a grayscale image (M-by-N) or a truecolor image (M-by-N-by-3). filename is a string that specifies the name of the output file. Empty image data is not allowed. The possible values for fmt are determined by the MATLAB file format registry. See imformats for more information about this registry. To view a summary of these formats, see Supported Formats.

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 legal values for fmt.

imwrite(...,Param1,Val1,Param2,Val2...) specifies parameters that control various characteristics of the output file. For example, if you are writing a JPEG file, you can set the quality of the JPEG compression. Parameter settings can currently be made for HDF, JPEG, PBM, PGM, PNG, PPM, and TIFF files. 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
1-bit, 8-bit, and 24-bit uncompressed images

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

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

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

'pcx'
Windows Paintbrush
8-bit images

'pgm'
Portable Graymap
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
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 with or without alpha channels

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

'ppm'
Portable Pixmap
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
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
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

'xwd'
X Windows Dump
8-bit ZPixmaps

Format	Full Name	Variants
`'bmp'`	Windows Bitmap	1-bit, 8-bit, and 24-bit uncompressed images
`'hdf'`	`Hierarchical Data Format`	8-bit raster image datasets, with or without associated colormap, 24-bit raster image datasets; uncompressed or with RLE or JPEG compression
`'jpg' or 'jpeg'`	Joint Photographic Experts Group	Baseline JPEG images (8- or 24-bit) Note: Indexed images are converted to RGB before writing out JPEG files, because the JPEG format does not support indexed images.
`'pbm'`	Portable Bitmap	Any 1-bit PBM image, ASCII (plain) or raw (binary) encoding
`'pcx'`	Windows Paintbrush	8-bit images
`'pgm'`	Portable Graymap	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	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 with or without alpha channels
`'pnm'`	`Portable Anymap`	Any of the PPM/PGM/PBM formats, chosen automatically
`'ppm'`	Portable Pixmap	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	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	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
`'xwd'`	X Windows Dump	8-bit ZPixmaps

Format-Specific Parameters

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

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', or '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'`, or `'append'.`	`'overwrite'`

JPEG-Specific Parameters

This table describes the available parameters for JPEG files.

Parameter
Values
Default

'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

'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

Parameter	Values	Default
`'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`
`'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

RAS-Specific Parameters

This table describes the available parameters for RAS files.

Parameter
Values
Default

'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'

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

Parameter	Values	Default
`'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'`
`'Alpha'`	A matrix specifying the transparency of each pixel individually; the row and column dimensions must be the same as the data array; may be `uint8`, `uint16`, or `double`. May only be used with truecolor images.	Empty matrix (`[]`)

TIFF-Specific Parameters

This table describes the available parameters for TIFF files.

Parameter
Values
Default

'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' or 'append'.
'overwrite'

Parameter	Values	Default
`'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'` or `'append'`.	`'overwrite'`

PNG-Specific Parameters

This table describes the available parameters for PNG files.

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 truecolor 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 truecolor 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

In addition to these PNG parameters, you can use any parameter name that satisfies the PNG specification for keywords, including only printable characters, 80 characters or fewer, and 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.

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 or '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 or `'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

Class Support

Most of the supported image file formats store uint8 data. PNG and TIFF formats additionally support uint16 data. For grayscale and RGB images, if the data array is double, the assumed dynamic range is [0,1]. The data array is automatically scaled by 255 before being written as uint8. If the data array is uint8 or uint16, it is written without scaling as uint8 or uint16, respectively.

Note When the imwrite function writes logical data to a BMP, PNG or TIFF file, it assumes the data is a binary image and writes it to the file with a bit-depth of 1.

For indexed images, if the index array is double, then the indices are first converted to zero-based indices by subtracting 1 from each element, and then they are written as uint8. If the index array is uint8 or uint16, then it is written without modification as uint8 or uint16, respectively. When writing PNG files, you can override this behavior with the 'BitDepth' parameter; see PNG-Specific Syntax for details.

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, imfinfo, imformats, imread

Bit-Mapped Images for related functions

imread ind2rgb