MATLAB Function Reference
  Go to function:
    Search    Help Desk 
imwrite    Examples   See Also

Write an image to a graphics file

Synopsis

Description

imwrite(A,filename,fmt) writes the image in A to filename. filename is a string that specifies the name of the output file, and fmt is a string that specifies the format of the file. If A is a grayscale intensity image or a truecolor (RGB) image of class uint8, imwrite writes the actual values in the array to the file. If A is of class double, imwrite rescales the values in the array before writing, using uint8(round(255*A)). This operation converts the floating-point numbers in the range [0, 1] to 8-bit integers in the range [0, 255].

imwrite(X,map,filename,fmt) writes the indexed image in X and its associated colormap map to filename. 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, imwrite offsets the values in the array before writing using uint8(X-1). (See note below for an exception.) map must be a valid MATLAB colormap of class double; imwrite rescales the values in map using uint8(round(255*map)). Note that most image file formats do not support colormaps with more than 256 entries.

Note:
If the image is double, and you specify PNG as the output format and a bit depth of 16 bpp, the values in the array will be offset using uint16(X-1).

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. Parameter settings can currently be made for HDF, JPEG, and TIFF files. For example, if you are writing a JPEG file, you can set the "quality" of the JPEG compression. For the full list of parameters available per format, see the tables of parameters.

filename is a string that specifies the name of the output file, and fmt is a string that specifies the format of the file.

This table lists the possible values for fmt:

Format
 File type
'bmp'
 Windows Bitmap (BMP)
'hdf'
 Hierarchical Data Format (HDF)
'jpg' or 'jpeg'
 Joint Photographers Expert Group (JPEG)
'pcx'
 Windows Paintbrush (PCX)
'png'
 Portable Network Graphics (PNG)
'tif' or 'tiff'
 Tagged Image File Format (TIFF)
'xwd'
 X Windows Dump (XWD)

This table describes the available parameters for HDF files:

Parameter
 Values
 Default
'Compression'
 One of these strings: 'none', 'rle', 'jpeg'. 'rle' is valid only for grayscale and indexed images. 'jpeg' is valid only for grayscale and RGB images.
 'rle'
'Quality'
 A number between 0 and 100; this parameter applies only if 'Compression' is 'jpeg'.
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
'WriteMode'
 One of these strings: 'overwrite', 'append'
 'overwrite'

This table describes the available parameters for JPEG files:

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

This table describes the available parameters for TIFF files:

Parameter
 Values
 Default
'Compression'
 One of these strings: 'none', 'packbits', 'ccitt'; 'ccitt' is valid for binary images only. 'packbits' is the default for nonbinary images; 'ccitt' is the default for binary images.
 'ccitt' for binary images; 'packbits' for all other images
'Description'
 Any string; fills in the ImageDescription field returned by imfinfo.
 empty
'Resolution'
 A scalar value that is used to set the resolution of the output file in both the x and y directions.
 72

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 will represent 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]. For truecolor images: a 3-element vector in the range [0,1].

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 3-element vector in the range [0,1].

 Empty
'Gamma'
A nonnegative scalar indicating the file gamma
 Empty
'Chromaticities'
An 8-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 3-element vector. For grayscale images: a scalar. For grayscale images with an alpha channel: a 2-element vector. For truecolor images: a 3-element vector. For truecolor images with an alpha channel: a 4-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.

This table summarizes the types of images that imwrite can write:

Format
 Variants
BMP
 8-bit uncompressed images with associated colormap; 24-bit uncompressed images
HDF
 8-bit raster image datasets, with or without associated colormap; 24-bit raster image datasets
JPEG
 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.
PCX
 8-bit images
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 with or without alpha channels
TIFF
 Baseline TIFF images, including 1-bit, 8-bit, and 24-bit uncompressed images; 1-bit, 8-bit, and 24-bit images with packbits compression; 1-bit images with CCITT compression
XWD
 8-bit ZPixmaps

Class Support

Most of the supported image file formats store uint8 data. PNG and TIFF 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 out as uint8. If the data array is uint8 or uint16 (PNG and TIFF only), then it is written out without scaling as uint8 or uint16, respectively.

Example

See Also

fwrite, imfinfo, imread


[ Previous | Help Desk | Next ]