imwrite — Write image data to PNG, JPEG, GIF, BMP, or TIFF files.
Writes grayscale, truecolor, RGBA, logical, and indexed image arrays to common image formats. Numeric floating-point image data is interpreted in the normalized range [0, 1]; uint8 data is written directly; uint16 data is preserved for PNG/TIFF and projected to 8-bit for GIF/JPEG/BMP.
Syntax
imwrite(A, filename)
imwrite(A, filename, fmt)
imwrite(A, filename, name, value, ...)
imwrite(X, map, filename, ...)Inputs
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
A | NumericArray | Yes | — | Grayscale, truecolor, or RGBA image data. |
filename | StringScalar | Yes | — | Output image path. |
A | NumericArray | Yes | — | Image data. |
name | StringScalar | Variadic | — | Name-value option. |
value | Any | Variadic | — | Name-value option value. |
X | NumericArray | Yes | — | Indexed image data. |
map | NumericArray | Yes | — | Nx3 colormap. |
Errors
| Identifier | When | Message |
|---|---|---|
RunMat:imwrite:InvalidArgument | Arguments do not match a supported imwrite form. | imwrite: invalid argument |
RunMat:imwrite:InvalidFilename | Filename is missing or empty. | imwrite: invalid filename |
RunMat:imwrite:InvalidFormat | Image format cannot be inferred or is unsupported. | imwrite: invalid image format |
RunMat:imwrite:InvalidImage | Image data has unsupported type, shape, or values. | imwrite: invalid image data |
RunMat:imwrite:InvalidColormap | Indexed-image colormap is not an Nx3 numeric array. | imwrite: invalid colormap |
RunMat:imwrite:InvalidOption | Name-value option is malformed or unsupported for the requested format. | imwrite: invalid option |
RunMat:imwrite:EncodeError | Image data cannot be encoded. | imwrite: encode error |
RunMat:imwrite:Io | Image file cannot be read for append or written. | imwrite: file I/O error |
How imwrite works
- Accepts MxN grayscale, MxNx3 RGB, MxNx4 RGBA, logical, and indexed image arrays.
- For indexed image writes, pass
Xwith an Nx3 colormap.uint8anduint16indices are zero-based; floating-point indices are one-based. - The destination path can be a string scalar or char vector. When
fmtis omitted, the file extension determines the output format. - Common explicit format hints include
"png","jpg","jpeg","gif","bmp","tif", and"tiff". - Advanced writer options that are not currently supported produce explicit unsupported-option errors.
Options
"Alpha"supplies an MxN alpha plane for PNG, GIF, and TIFF output."Quality"controls JPEG quality from 0 to 100. The default is 75."DelayTime"controls GIF frame delay in seconds."LoopCount"controls GIF repeat count.Infrequests infinite looping."WriteMode"accepts"overwrite"or"append". Append is supported for GIF animations.
Examples
Write an RGB PNG
rgb = uint8(zeros(32, 32, 3));
rgb(:,:,1) = 255;
imwrite(rgb, "red.png")Write a JPEG with explicit quality
imwrite(rgb, "photo.jpg", "Quality", 90)Append frames to an animated GIF
imwrite(frame1, "anim.gif", "LoopCount", Inf, "DelayTime", 0.2);
imwrite(frame2, "anim.gif", "WriteMode", "append", "DelayTime", 0.2)Write indexed image data
imwrite(X, map, "indexed.gif")Using imwrite with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how imwrite changes the result.
Run a small imwrite example, explain the result, then change one input and compare the output.
FAQ
Which image formats can imwrite create?⌄
RunMat covers common MATLAB imwrite forms for PNG, JPEG, GIF, BMP, and TIFF output, including direct-color, indexed, alpha PNG/GIF/TIFF, JPEG quality, and animated GIF append workflows.
What errors can image writes raise?⌄
Invalid arguments, filenames, formats, image data, colormaps, options, encoder failures, and filesystem failures raise descriptive RunMat:imwrite:* errors.
Related Image functions
About RunMat
RunMat is an open-source runtime that executes MATLAB-syntax code blazing on any GPU. It is licensed under the Apache 2.0 license.
- RunMat automatically optimizes your math for GPU execution on Apple, Nvidia, and AMD hardware. No code changes needed. Simulations that took hours now take minutes.
- Start running code in seconds. RunMat runs in the browser, on the desktop, or from the CLI. No license server, no IT ticket.