| MATLAB Function Reference |
  |
imwrite
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). If A is of class uint8 or uint16, 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 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, 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, PNG, JPEG, and TIFF files. For example, if you are writing a JPEG file, you can set the "quality" of the JPEG compression. For the lists of parameters available for each format, see the tables below.
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 Photographic Experts 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' (the default), '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'.
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' (the default), or 'append'.
|
'overwrite'
|
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
|
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'
|
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]. 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.
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.
Format Support
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; uncompressed or with RLE or JPEG compression.
|
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 1D, Group 3, and Group 4 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.
Note
If a logical double or uint8 is written to a PNG or TIFF file, it is assumed to be a binary image and will be written 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 out as uint8. If the index array is uint8 or uint16 (PNG and TIFF only), then it is written out without modification as uint8 or uint16, respectively. When writing PNG files, you can override this behavior with the 'BitDepth' parameter; see the PNG table in this imwrite reference for details.
Remarks
imwrite is a function in MATLAB.
Example
This example appends an indexed image X and its colormap map to an existing uncompressed multipage HDF file named flowers.hdf.
imwrite(X,map,'flowers.hdf','Compression','none',...
'WriteMode','append')
See Also
fwrite, imfinfo, imread
| | imread | | ind2rgb | |