imwrite

将图像写入图形文件

全页折叠

语法

imwrite(A,filename)

imwrite(A,map,filename)

imwrite(___,fmt)

imwrite(___,Name,Value)

说明

示例

imwrite(A,filename) 将图像数据 A 写入 filename 指定的文件，并从扩展名推断出文件格式。imwrite 在当前文件夹中创建新文件。输出图像的位深取决于 A 的数据类型和文件格式。对于大多数格式来说：

如果 A 的数据类型为 uint8，则 imwrite 输出 8 位值。
如果 A 的数据类型为 uint16 且输出文件格式支持 16 位数据（JPEG、PNG 和 TIFF），则 imwrite 将输出 16 位的值。如果输出文件格式不支持 16 位数据，则 imwrite 返回错误。
如果 A 是灰度图像或者属于数据类型 double 或 single 的 RGB 彩色图像，则 imwrite 假设动态范围是 [0, 1]，并在将其作为 8 位值写入文件之前自动按 255 缩放数据。如果 A 中的数据是 single，则在将其写入 GIF 或 TIFF 文件之前将 A 转换为 double。
如果 A 的数据类型为 logical，则 imwrite 会假定数据为二值图像并将数据写入位深为 1 的文件（如果格式允许）。BMP、PNG 或 TIFF 格式以输入数组形式接受二值图像。

如果 A 包含索引图像数据，则应另外指定 map 输入参数。

示例

imwrite(A,map,filename) 将 A 中的索引图像及其关联的颜色图 map 写入由 filename 指定的文件。

如果 A 是属于数据类型 double 或 single 的索引图像，则 imwrite 通过从每个元素中减去 1 来将索引转换为从 0 开始的索引，然后以 uint8 形式写入数据。如果 A 中的数据是 single，则在将其写入 GIF 或 TIFF 文件之前将 A 转换为 double。

imwrite(___,fmt) 以 fmt 指定的格式写入图像，无论 filename 中的文件扩展名如何。您可在上述语法的任何输入参数之后指定 fmt。

示例

imwrite(___,Name,Value) 使用一个或多个名称-值参数，以指定 GIF、HDF、JPEG、PBM、PGM、PNG、PPM 和 TIFF 文件输出的其他参数。例如，您可以向 PNG 格式的图像添加注释。

示例

全部折叠

将灰度图像写入 PNG

打开实时脚本

将一个 50×50 的灰度值数组写入当前文件夹中的 PNG 文件。

A = rand(50);
imwrite(A,"myGray.png")

将索引图像数据写入 PNG

打开实时脚本

将索引图像数组和其关联的颜色图写入 PNG 文件。

从文件 earth.mat 中加载示例图像数据。

load earth.mat

图像数组 X 和其关联颜色图 map 均加载至工作区。

将数据写入新的 PNG 文件。

imwrite(X,map,"myearth.png")

imwrite 在当前文件夹中创建文件 myearth.png。

使用 imshow 查看新 PNG 文件。

imshow("myearth.png")

Figure contains an axes object. The axes object contains an object of type image.

用 MATLAB 颜色图写入索引图像

打开实时脚本

用 MATLAB® 内置的颜色图 copper 将图像数据写入新的 PNG 文件。

从文件 earth.mat 中加载示例图像数据。

load earth.mat

图像数组 X 和其关联颜色图 map 均加载至工作区。map 是一个 64 RGB 向量矩阵。

用 64 RGB 向量创建一个铜色调颜色图。然后，使用这个新的颜色图将图像数据写入 PNG 文件。

newmap = copper(64);
imwrite(X,newmap,"copperearth.png");

imwrite 在当前文件夹中创建文件 copperearth.png。

使用 imshow 查看新 PNG 文件。

imshow("copperearth.png")

Figure contains an axes object. The axes object contains an object of type image.

将真彩色图像写入 JPEG

打开实时脚本

创建真彩色图像数据并将其写入 JPEG 文件。

创建一个随机 RGB 值的 49×49×3 数组。

A = rand(49,49,3);

将图像数据写入一个 JPEG 文件。当您使用 .jpg 文件扩展名时，imwrite 会自动选择此格式。使用 Comment 名称-值参数添加文件注释。

imwrite(A,"newImage.jpg","Comment","My JPEG file")

查看有关新文件的信息。

info = imfinfo("newImage.jpg");
info.ColorType

ans = 
'truecolor'

[info.Height,info.Width,info.NumberOfSamples,info.BitDepth]

ans = 1×4

    49    49     3    24

info.Comment

ans = 1x1 cell array
    {'My JPEG file'}

将多个图像写入 TIFF 文件

打开实时脚本

将多个图像写入一个多页 TIFF 文件。

创建两个随机图像数据集 im1 和 im2。

im1 = rand(50,40,3);
im2 = rand(50,50,3);

将第一个图像写入新的 TIFF 文件。然后将第二个图像添加至同一文件。

imwrite(im1,"myMultipageFile.tiff")
imwrite(im2,"myMultipageFile.tiff","WriteMode","append")

写入 GIF 动画

打开实时脚本

绘制一系列图、将它们捕获为图像，然后写入 GIF 动画文件。

绘制 $y = x^{n}$ ，其中 $n = 3$ 。

x = 0:0.01:1;
n = 3;
y = x.^n;
plot(x,y,"LineWidth",3)
title("y = x^n,  n = " + num2str(n))

Figure contains an axes object. The axes object with title y = blank x toThePowerOf n baseline , blank blank n blank = blank 3 contains an object of type line.

捕获 $n$ 值递增时的一系列绘图。

n = 1:0.5:5;
nImages = length(n);

fig = figure;
for idx = 1:nImages
    y = x.^n(idx);
    plot(x,y,"LineWidth",3)
    title("y = x^n,  n = " + num2str(n(idx)))
    drawnow
    frame = getframe(fig);
    im{idx} = frame2im(frame);
end
close;

将多个系列的图像显示在一个图窗中。

figure;
for idx = 1:nImages
    subplot(3,3,idx)
    imshow(im{idx});
end

将九个图像保存到一个 GIF 文件中。因为 GIF 文件不支持三维数据，所以应调用 rgb2ind，使用颜色图 map 将图像中的 RGB 数据转换为索引图像 A。要将多个图像追加到第一个图像，请在名称-值参数 "append" 设置为 WriteMode 的情况下调用 imwrite。

filename = "testAnimated.gif"; % Specify the output file name
for idx = 1:nImages
    [A,map] = rgb2ind(im{idx},256);
    if idx == 1
        imwrite(A,map,filename,"gif","LoopCount",Inf,"DelayTime",1);
    else
        imwrite(A,map,filename,"gif","WriteMode","append","DelayTime",1);
    end
end

imwrite 将 GIF 文件写入您的当前文件夹。将 LoopCount 设置为 Inf 会导致动画连续循环。将 DelayTime 设置为 1 会指定动画中每个图像的显示之间有 1 秒的延迟。

输入参数

全部折叠

`A` — 图像数据
矩阵

图像数据，指定为满（非稀疏）矩阵。

对灰度图像而言，A 可以是 m×n。
对索引图像而言，A 可以是 m×n。指定 map 输入参数中的相关颜色图。
对真彩色图像而言，A 必须是 m×n×3 的矩阵。imwrite 不支持将 RGB 图像写入 GIF 文件。

对于 TIFF 文件而言，A 可以是 m×n×4 数组，其中包含使用 CMYK 颜色空间的颜色数据。

对于多帧 GIF 文件而言，A 可以是包含灰度图像或索引图像的 m×n×1×p 数组，其中 p 是写入帧的数量。这种情况不支持 RGB 图像。

数据类型： double | single | uint8 | uint16 | logical

`filename` — 输出文件名
字符串标量 | 字符向量

输出文件的名称，指定为字符串标量或字符向量。

根据您写入的位置，filename 可以采用以下形式之一。

位置

形式

当前文件夹

要写入当前文件夹，请在 filename 中指定文件名。

filename 必须包含文件扩展名。有关 imwrite 可写入的图像类型列表，请参阅 fmt 输入参数的说明。

示例："myImage.jpg"

其他文件夹

要写入不同于当前文件夹的文件夹，请在 filename 中指定完整或相对路径名称。

示例："C:\myFolder\myImage.ext"

示例："\imgDir\myImage.ext"

远程位置

要写入远程位置，filename 必须包含指定为统一资源定位器 (URL) 形式的文件的完整路径：

scheme_name://path_to_file/my_file.ext

根据远程位置，scheme_name 可以是下表中的值之一。

远程位置	`scheme_name`
Amazon S3™	`s3`
Windows Azure^® Blob 存储	`wasb`, `wasbs`
HDFS™	`hdfs`

有关详细信息，请参阅处理远程数据。

示例："s3://bucketname/path_to_file/my_image.jpg"

数据类型： char | string

`map` — 索引图像的颜色图
m×3 数组

A 中与索引图像数据相关联的颜色图，指定为 m×3 数组。map 必须是有效的 MATLAB^® 颜色图。请参阅 colormap 以了解 MATLAB 内置颜色图列表。大多数图像文件格式都不支持条目数超过 256 个的颜色图。

示例： [0,0,0; 0.5,0.5,0.5; 1,1,1]

示例： jet(60)

数据类型： double

`fmt` — 输出文件格式
`"bmp"` | `"gif"` | `"hdf"` | `"jpg"` | `"jp2"` | ...

输出文件的格式，指定为下表中的格式之一。

此表还概述了 imwrite 可写入的图像类型。MATLAB 文件格式注册表会确定支持哪些文件格式。有关此注册表的详细信息，请参阅 imformats。

对某些格式而言，imwrite 可以接受其他名称-值参数。要查看这些参数，可点击下面的链接格式名称。

`fmt` 的值	输出文件格式	描述
`"bmp"`	Windows^® 位图 (BMP)	1 位、8 位和 24 位未压缩图像
`"gif"`	GIF - 图形交换格式	8 位图像
`"hdf"`	HDF4 - 分层数据格式	带或不带关联颜色图的 8 位光栅图像数据集、24 位光栅图像数据集
`"jpg"` 或 `"jpeg"`	JPEG - 联合图像专家组	8 位、12 位和 16 位基准 JPEG 图像注意 `imwrite` 会先将索引图像转换为 RGB 图像，然后再将数据写入 JPEG 文件，因为 JPEG 格式不支持索引图像。
`"jp2"` 或 `"jpx"`	JPEG 2000 - 联合图像专家组 2000	1 位、8 位和 16 位 JPEG 2000 图像
`"pbm"`	可移植位图 (PBM)	任何 1 位 PBM 图像、ASCII（普通）或原始（二进制）编码
`"pcx"`	Windows 画笔 (PCX)	8 位图像
`"pgm"`	可移植灰度图 (PGM)	任何标准 PGM 图像；使用任意颜色深度编码的 ASCII（普通）图像；每个灰度值最多使用 16 位编码的原始（二进制）图像
`"png"`	PNG - 可移植网络图形	1 位、2 位、4 位、8 位和 16 位灰度图像；带有 alpha 通道的 8 位和 16 位灰度图像；1 位、2 位、4 位和 8 位索引图像；24 位和 48 位真彩色图像；带有 alpha 通道的 24 位和 48 位真彩色图像注意 `imwrite` 函数不支持写入颜色图条目不足的索引 PNG 文件。
`"pnm"`	可移植任意图 (PNM)	自动选择的 PPM/PGM/PBM 任意格式
`"ppm"`	可移植像素图 (PPM)	任何标准 PPM 图像：使用任意颜色深度编码的 ASCII（普通）图像，或每个颜色分量最多使用 16 位编码的原始（二进制）图像
`"ras"`	Sun^® 光栅 (RAS)	任何 RAS 图像，包括 1 位位图、8 位索引图像、带有 alpha 的 24 位真彩色图像和 32 位真彩色图像
`"tif"` 或 `"tiff"`	标记图像文件格式 (TIFF)	基线 TIFF 图像，包括： 1 位、8 位、16 位、24 位和 48 位未压缩的图像以及采用 Packbit 、LZW 或 Deflate 压缩的图像采用 CCITT 1D、Group 3 和 Group 4 压缩的 1 位图像 CIELAB、ICCLAB 和 CMYK 图像
`"xwd"`	X 窗口转储 (XWD)	8 位 ZPixmaps

名称-值参数

将可选的参数对组指定为 Name1=Value1,...,NameN=ValueN，其中 Name 是参数名称，Value 是对应的值。名称-值参数必须出现在其他参数之后，但参数对组的顺序无关紧要。

示例： imwrite(A,"myFile.png",BitDepth=8) 使用可表现每个像素的 8 位图像将数据写入 A 中。

在 R2021a 之前，使用逗号分隔每个名称和值，并用引号将 Name 引起来。

示例： imwrite(A,"myFile.png","BitDepth",8) 使用可表现每个像素的 8 位图像将数据写入 A 中。

GIF - 图形交换格式

全部折叠

`BackgroundColor` — 要用作背景色的颜色
非负整数标量

用作索引图像背景色的颜色，指定为对应于颜色图索引的非负整数标量。

背景色用于一些 GIF 动画的处置方法。

如果图像数据 A 是 uint8 或 logical，则颜色图索引从 0 开始。
如果图像数据 A 是 double，则颜色图索引从 1 开始。

默认背景色对应于颜色图中的第一个颜色。

示例： "BackgroundColor",15

`Comment` — 添加到图像的注释
字符串标量 | 字符向量 | 字符串数组 | 字符向量元胞数组

添加到图像的注释，指定为字符串标量、字符向量、1×n 字符串数组或 1×n 字符向量元胞数组。对于字符串数组或字符向量元胞数组，imwrite 会在每个条目后添加一个回车符。

示例： "Comment",["Sample #314","January 5, 2013"]

数据类型： string | char | cell

`DelayTime` — 显示下一个图像之前的时滞
0.5 （默认） | 范围 [0, 655] 内的标量值

显示下一个图像之前的时滞（秒），指定为范围 [0, 655] 内的标量值。

提示

要获得高动画速率，请将 DelayTime 设置为 0.02。将 DelayTime 设置为较低的值会减慢在许多图像查看器和 Web 浏览器中的实际动画速率。

示例： "DelayTime",60

`DisposalMethod` — GIF 动画的处置方法
`"doNotSpecify"` （默认） | `"leaveInPlace"` | `"restoreBG"` | `"restorePrevious"`

GIF 动画的处置方法，指定为下表中的方法之一。

`DisposalMethod` 的值	结果
`"doNotSpecify"`（默认值）	用另一个帧来替代一个完全尺寸的不透明的帧。
`"leaveInPlace"`	没有被下一帧覆盖的任何像素都将继续显示。
`"restoreBG"`	背景色或背景图块通过透明的像素显示。
`"restorePrevious"`	恢复到以前未处理的帧状态。

示例： "DisposalMethod","restoreBG"

`Location` — 屏幕相对图像的偏移
`[0,0]` （默认） | 二元素向量

屏幕相对图像的偏移（从每个图像的左上角测量），指定为一个二元素向量。第一个向量元素指定自顶部的偏移，第二个元素指定自左侧的偏移，均以像素为单位。

示例： "Location",[10,15]

数据类型： double

`LoopCount` — 重复动画的次数
`Inf` （默认） | 范围 [0, 65,535] 内的整数

重复动画的次数，指定为范围 [0, 65,535] 内的整数或值 Inf。如果指定值 0，动画将播放一次；如果指定值 1，动画将播放两次，依此类推。LoopCount 值为 Inf 会使动画连续循环。

要在 Microsoft^® PowerPoint^® 中启用动画，请为 LoopCount 指定 [1, 65,535] 范围内的值。某些 Microsoft 应用程序会将值 0 的含义解释为根本不进行循环。

示例： "LoopCount",3

`ScreenSize` — 帧的高度和宽度
输入图像的高度和宽度（默认） | 二元素向量

帧的高度和宽度，指定为一个二元素向量。您可以将 ScreenSize 参数与 Location 结合使用，以将帧写入小于整个帧的图像。DisposalMethod 确定用于帧外部的像素的填充值。

示例： "ScreenSize",[1000 1060]

数据类型： double

`TransparentColor` — 用作透明色的颜色
非负整数标量

用作图像透明色的颜色，指定为对应于颜色图索引的非负整数标量。

如果图像数据 A 是 uint8 或 logical，则索引从 0 开始。
如果图像数据 A 是 double，则索引从 1 开始。

示例： "TransparentColor",20

`WriteMode` — 写入模式
`"overwrite"` （默认） | `"append"`

写入模式，指定为 "overwrite" 或 "append"。在 "overwrite" 模式下，imwrite 覆盖现有文件 filename。在 "append" 模式下，imwrite 会向现有文件添加单个帧。

示例： "WriteMode","append"

HDF4 - 分层数据格式

全部折叠

`Compression` — 压缩方案
`"none"` （默认） | `"jpeg"` | `"rle"`

压缩方案，指定为下表中的选项之一。

`Compression` 的值	结果
`"none"`（默认值）	无压缩
`"jpeg"`	JPEG 压缩。仅对灰度图像和 RGB 图像有效。
`"rle"`	行程长度编码。仅对灰度图像和索引图像有效。

示例： "Compression","jpeg"

`Quality` — JPEG 压缩文件的质量
75 （默认） | 范围 [0, 100] 内的标量

JPEG 压缩文件的质量，指定为范围 [0, 100] 内的标量，其中 0 表示较低质量和较高的压缩率，100 表示较高质量和较低的压缩率。此参数仅适用于 Compression 是 "jpeg" 的情况。

示例： "Quality",25

`WriteMode` — 写入模式
`"overwrite"` （默认） | `"append"`

写入模式，指定为 "overwrite" 或 "append"。在 "overwrite" 模式下，imwrite 覆盖现有文件 filename。在 "append" 模式下，imwrite 会向现有文件添加单个帧。

示例： "WriteMode","append"

JPEG - 联合图像专家组

全部折叠

`BitDepth` — 每像素位数
`8` （默认） | `12` | `16`

像素位数，指定为标量。

对于灰度图像，BitDepth 值可以是 8、12 或 16。默认值为 8。对于 16 位图像，Mode 名称-值参数必须为 "lossless"。
对彩色图像，BitDepth 的值是每平面的位数，可以是 8 或 12 位。每平面的默认值为 8 位。

示例： "BitDepth",12

`Comment` — 添加到图像的注释
字符串标量 | 字符向量 | 字符串数组 | 字符向量元胞数组

添加到图像的注释，指定为字符串标量、字符向量、n×1 字符串数组或由字符向量组成的 n×1 元胞数组。对于字符串数组或字符向量元胞数组，imwrite 将每行输入作为注释写入 JPEG 文件中。

示例： "Comment",["First comment";"second comment";"third comment"]

数据类型： string | char | cell

`Mode` — 压缩类型
`"lossy"` （默认） | `"lossless"`

压缩类型，指定为 "lossy" 或 "lossless"。

示例： "Mode","lossless"

`Quality` — 输出文件质量
75 （默认） | 范围 [0, 100] 内的标量

输出文件的质量，指定为范围 [0, 100] 内的标量，其中 0 表示较低质量和较高的压缩率，100 表示较高质量和较低的压缩率。100 的 Quality 值不会写入无损压缩的 JPEG 图像。如需无损压缩的图像，请将 Mode 名称-值参数设置为 "lossless"。

示例： "Quality",100

JPEG 2000 - 联合图像专家组 2000

全部折叠

`Comment` — 添加到图像的注释
字符串标量 | 字符向量 | 字符串数组 | 字符向量元胞数组

添加到图像的注释，指定为字符串标量、字符向量、字符串数组或字符向量元胞数组。对于字符串数组或字符向量元胞数组，imwrite 以列优先顺序将每个条目作为注释写入 JPEG 2000 文件中。

示例： "Comment",["First comment";"second comment";"third comment"]

示例： "Comment",{'First comment','second comment','third comment'}

数据类型： string | char | cell

`CompressionRatio` — 目标压缩比
1 （默认） | 正标量

目标压缩比，指定为大于或等于 1 的正标量。压缩比是输入图像大小与输出压缩大小之比。例如，值为 2 表示输出图像大小将是输入图像大小的一半或更小。值越高，表示文件大小越小，图像质量越低。压缩比不考虑标头大小。

指定 CompressionRatio 仅在 Mode 是 "lossy" 时有效。

示例： "CompressionRatio",3

`Mode` — 压缩类型
`"lossy"` （默认） | `"lossless"`

压缩类型，指定为 "lossy" 或 "lossless"。

示例： "Mode","lossless"

`ProgressionOrder` — 代码流中数据包的顺序
`"LRCP"` （默认） | `"RLCP"` | `"RPCL"` | `"PCRL"` | `"CPRL"`

代码流中数据包的顺序，指定为以下选项之一：

"LRCP"
"RLCP"
"RPCL"
"PCRL"
"CPRL"

字符分别代表如下数据包：L = 层，R = 分辨率，C = 分量，P = 位置。

示例： "ProgressionOrder","RLCP"

`QualityLayers` — 质量层数
1 （默认） | 范围 [1, 20] 内的整数

质量层数，指定为范围 [1, 20] 内的整数。

示例： "QualityLayers",8

`ReductionLevels` — 还原级数
4 （默认） | 范围 [1, 8] 内的整数

还原级数或小波分解级数，指定为 [1, 8] 范围内的整数。

示例： "ReductionLevels",6

`TileSize` — 图块高度和宽度
图像尺寸（默认） | 二元素向量

图块高度和宽度，指定为一个二元素向量。可指定的最小尺寸为 [128 128]。

示例： "TileSize",[130 130]

PBM、PGM 和 PPM - 可移植位图、灰度图、像素图

全部折叠

`Encoding` — 编码
`"rawbits"` （默认） | `"ASCII"`

编码，指定为 "rawbits"（二进制编码）或 "ASCII"（普通编码）。

示例： "Encoding","ASCII"

`MaxValue` — 最大灰色或颜色值
正整数标量

最大灰色或颜色值，指定为正整数标量。

仅为 PGM 和 PPM 文件指定此名称-值参数。对于 PBM 文件，该值始终为 1。

如果图像数组为 uint16，则 MaxValue 的默认值为 65535。否则，默认值为 255。

示例： "MaxValue",510

PNG - 可移植网络图形

全部折叠

`Alpha` — 每个像素的透明度
范围 [0, 1] 内的值矩阵

每个像素的透明度，指定为由在范围 [0, 1] 内的值组成的矩阵。Alpha 矩阵的行和列维度都必须与图像数据数组的相同。仅可为灰度（m×n）和真彩色（m×n×3）图像数据指定 Alpha。

注意

您不能同时指定 Alpha 和 Transparency。

数据类型： double | uint8 | uint16

`Author` — 作者信息
字符串标量 | 字符向量

作者信息，指定为字符串标量或字符向量。

示例： "Author","Ann Smith"

数据类型： string | char

`Background` — 合成透明像素时的背景色
范围 [0, 1] 内的标量 | 范围 [1, P] 内的整数 | 范围 [0, 1] 内的三元素向量

合成透明像素时的背景色，指定为依赖于图像数据的值，如下表所示。

图像类型	`Background` 值的格式
灰度图片	范围 [0, 1] 内的标量。
索引图像	范围 [1, P] 内的整数，其中 P 是颜色图长度。例如，`"Background",50` 将背景色设置为颜色图中第 50 个索引指定的颜色。
真彩色图像	范围 [0, 1] 内 RGB 强度的三元素向量。例如，`"Background",[0 1 1]` 将背景色设置为青色。

数据类型： double

`BitDepth` — 每像素位数
`1` | `2` | `4` | `8` | `16`

像素位数，指定为标量。根据输出图像，标量可以是下列值之一。

图像类型	`BitDepth` 的允许值
灰度图片	`1`、`2`、`4`、`8` 或 `16`
带有 alpha 通道的灰度图像	`8` 或 `16`
索引图像	`1`、`2`、`4` 或 `8`
真彩色图像	`8` 或 `16`

如果图像是 double 或 uint8 类型，则默认位深是 8 位/像素。
如果图像是 uint16 类型，则默认值是 16 位/像素。
如果图像是 logical 类型，则默认值是 1 位/像素。

示例： "BitDepth",4

`Chromaticities` — 参考白和原色色度
八元素向量

参考白和原色色度，指定为 [wx wy rx ry gx gy bx by] 形式的八元素向量。元素 wx 和 wy 是白点色度坐标，元素 rx、ry、gx、gy、bx 和 by 分别是红、绿、蓝色度坐标。

如果指定 Chromaticities，则应同时指定 Gamma 名称-值参数。

示例： "Chromaticities",[0.312,0.329,0.002,0.002,0.001,0.001,0.115,0.312]

数据类型： double

`Comment` — 添加到图像的注释
字符串标量 | 字符向量

添加到图像的注释，指定为字符串标量或字符向量。

`Copyright` — 版权声明
字符串标量 | 字符向量

`CreationTime` — 原图创建的时间
日期时间 | 字符串标量 | 字符向量

原图创建的时间，指定为日期时间、表示时间点的字符串标量或字符向量。如果您将 CreationTime 指定为具有时区的 datetime 值，则 imwrite 会将时区存储为该值的一部分。

示例： "CreationTime",datetime("1955-11-12 10:04 PM","TimeZone","America/Los_Angeles")

`Description` — 图像的描述
字符串标量 | 字符向量

图像的描述，指定为字符串标量或字符向量。

`Disclaimer` — 法律免责声明
字符串标量 | 字符向量

法律免责声明，指定为字符串标量或字符向量。

`Gamma` — 文件的 gamma 值
数值标量

文件的 gamma 值，指定为数值标量。

示例： "Gamma",2.2

`ImageModTime` — 图像最后修改的时间
日期时间 | 字符串标量 | 字符向量

图像最后修改的时间，指定为日期时间、表示时间点的字符串标量或字符向量。如果将 ImageModTime 指定不是 UTC 时区的 datetime 值，则 imwrite 会在存储该值之前将其转换为 UTC。如果将 ImageModTime 指定为不带时区的 datetime 值，则 imwrite 会将该值解释为 UTC。

ImageModTime 的默认值是调用 imwrite 的时间。

示例： "ImageModTime",datetime("2018-04-01 9:00 AM","TimeZone","Europe/Rome")

`InterlaceType` — 隔行扫描方案
`"none"` （默认） | `"adam7"`

隔行扫描方案，指定为 "none"（非隔行扫描）或 "adam7"（使用 Adam7 算法）。

示例： "InterlaceType","adam7"

`ResolutionUnit` — 图像分辨率单位
`"unknown"` （默认） | `"meter"`

图像分辨率的单位，指定为 "unknown" 或 "meter"。如果指定 ResolutionUnit，则必须至少包括 XResolution 和 YResolution 名称-值参数之一。当 ResolutionUnit 的值为 "meter" 时，XResolution 和 YResolution 的值解释为像素/米。

示例： "ResolutionUnit","meter","XResolution",1000

`SignificantBits` — 视作有效的位数
`[]` （默认） | 正整数标量 | 正整数向量

数据数组中视作有效的位数，指定为范围 [1, BitDepth] 内的一个标量或向量。根据输出图像类型，该值必须有以下格式。

图像类型	`SignificantBits` 值的格式
不带 alpha 通道的灰度图像	标量
带有 alpha 通道的灰度图像	二元素向量
索引图像	3 元素向量
不带 alpha 通道的真彩色图像	3 元素向量
带有 alpha 通道的真彩色图像	4 元素向量

示例： "SignificantBits",[2,3]

`Software` — 用于创建图像的软件
字符串标量 | 字符向量

用于创建图像的软件，指定为字符串标量或字符向量。

`Source` — 用于创建图像的设备
字符串标量 | 字符向量

用于创建图像的设备，指定为字符串标量或字符向量。

`Transparency` — 视为透明的像素
`[]` （默认） | 范围 [0, 1] 内的标量 | 向量

没有使用 alpha 通道时视为透明的像素，指定为标量或向量。根据输出图像类型，该值必须具有以下格式。

图像类型	`Transparency` 值的格式
灰度图片	范围 [0, 1] 内的标量，表示视为透明的灰度颜色。
索引图像	[0, 1] 范围值的 Q- 元素向量，其中 Q 不超过颜色图长度，并且每个值指示与对应的颜色图条目关联的透明度。在大多数情况下，Q 为 `1`。
真彩色图像	范围 [0, 1] 内 RGB 强度的三元素向量，表示视为透明的真彩色颜色。

注意

您不能同时指定 Transparency 和 Alpha。

示例： "Transparency",[1 1 1]

数据类型： double

`Warning` — 内容性质警告
字符串标量 | 字符向量

内容性质警告，指定为字符串标量或字符向量。

`XResolution` — 水平方向的图像分辨率
数值标量

水平方向的图像分辨率（单位为像素），指定为数值标量。通过指定 ResolutionUnit 名称-值参数来定义单位。

如果还没有指定 YResolution，则 XResolution 值同时适用于水平和垂直方向。

示例： "XResolution",900

`YResolution` — 垂直方向的图像分辨率
数值标量

垂直方向的图像分辨率（单位为像素），指定为数值标量。通过指定 ResolutionUnit 名称-值参数来定义单位。

如果还没有指定 XResolution，则 YResolution 值同时适用于垂直和水平方向。

示例： "YResolution",900

除了列出的适合 PNG 的名称-值参量之外，还可以使用满足 PNG 关键字设定的任何参数名称。也就是说，该名称只能使用可打印字符，包含 80 个或更少的字符，并且不包含前导或尾随空格。与用户指定的这些名称对应的值必须为不包含换行符以外的任何控制字符的字符串标量或字符向量。

RAS - Sun 光栅图形

全部折叠

`Alpha` — 每个像素的透明度
`[]` （默认） | 矩阵

每个像素的透明度，指定为与图像数据数组具有相同的行和列维度的矩阵。

此名称-值参数仅对真彩色（m×n×3）图像数据有效。

数据类型： double | single | uint8 | uint16

`Type` — 图像类型
`"standard"` （默认） | `"rgb"` | `"rle"`

图像类型，指定为下表中的选项之一。

`Type` 的值	描述
`"standard"`（默认值）	真彩色图像未压缩的 B-G-R 色序
`"rgb"`	真彩色图像未压缩的 R-G-B 色序
`"rle"`	1 位和 8 位图像的行程编码

示例： "Type","rgb"

TIFF - 标记图像文件格式

全部折叠

`ColorSpace` — 表示颜色数据的颜色空间
`"rgb"` （默认） | `"cielab"` | `"icclab"`

表示颜色数据的颜色空间，指定为 "rgb"、"cielab" 或 "icclab"。

此名称-值参数仅当图像数据数组 A 为真彩色（m×n×3）时有效。要在 TIFF 文件中使用 CMYK 颜色空间，请不要使用 ColorSpace 名称-值参数。相反，应指定一个 m×n×4 图像数据数组。

imwrite 可以将使用 L*a*b* 颜色空间的彩色图像数据写入 TIFF 文件。1976 CIE L*a*b* 设定定义了表示亮度 (L*) 与色度（a* 和 b*）信息的数值。要将 L*a*b* 颜色数据存储在 TIFF 文件中，这些值必须经过编码以适合 8 位或 16 位数据存储。imwrite 可以使用以下编码将 L*a*b* 颜色数据存储在 TIFF 文件：

CIELAB 编码 - 由 TIFF 规范定义的 8 位和 16 位编码
ICCLAB 编码 - 由国际色彩联盟定义的 8 位和 16 位编码

imwrite 使用的输出类和编码取决于输入图像数据数组的类以及 ColorSpace 的值，如下表所示。（8 位和 16 位 CIELAB 编码不能是输入数组，因为这些编码混合使用有符号值和无符号值，不能使用单一 MATLAB 数组来表示。）

输入类和编码	`ColorSpace` 的值	输出类和编码
8 位 ICCLAB 这些值为 [0, 255] 范围内的整数。L* 值乘以 `2.55`。 `128` 添加到 a* 和 b* 值中。	`"icclab"`	8 位 ICCLAB
	`"cielab"`	8 位 CIELAB
16 位 ICCLAB 这些值为 [0, 65,280] 范围内的整数。L* 值乘以 `652.8`。 `32768` 添加到 a* 和 b* 值中，这些值以 [0, 65,535] 范围中的整数表示。	`"icclab"`	16 位 ICCLAB
	`"cielab"`	16 位 CIELAB
双精度的 1976 CIE Lab* 值 L* 位于 [0, 100] 动态范围中。a* 和 b* 可以接受任何值。将 a* 和 b* 设置为 `0`（零）会生成一种中性颜色（灰色）。	`"icclab"`	8 位 ICCLAB
	`"cielab"`	8 位 CIELAB

示例： "ColorSpace","cielab"

`Compression` — 压缩方案
`"packbits"` | `"none"` | `"lzw"` | `"deflate"` | `"jpeg"` | `"ccitt"` | `"fax3"` | `"fax4"`

压缩方案，指定为以下选项之一：

"packbits"（非二值图像的默认值）
"none"
"lzw"
"deflate"
"jpeg"
"ccitt"（仅限于二值图像，此类图像的默认值）
"fax3"（仅限于二值图像）
"fax4"（仅限于二值图像）

"jpeg" 是一种有损压缩方案；其他压缩模式为无损压缩。此外，如果您指定 "jpeg" 压缩，则还必须指定 RowsPerStrip 名称-值参数并且该值必须为 8 的倍数。

示例： "Compression","none"

`Description` — 图像描述
字符串标量 | 字符向量

图像描述，由字符串标量或字符向量指定。以下描述是 imfinfo 返回到输出图像的 ImageDescription 字段内的文本。

示例： "Description","Sample 2A301"

`Resolution` — X 分辨率和 Y 分辨率
72 （默认） | 标量 | 二元素向量

X 和 Y 分辨率，指定为指示 X 分辨率和 Y 分辨率的标量，或包含 X 分辨率和 Y 分辨率的二元素向量。

示例： "Resolution",80

示例： "Resolution",[320,72]

数据类型： double

`RowsPerStrip` — 包含在每个条带中的行数
正整数标量

每个条带中包含的行数，指定为标量。默认值将使每个条带约为 8K 字节。

如果您指定 "jpeg" 压缩，则还必须指定 RowsPerStrip 参数。在本例中，该值必须为 8 的倍数。

示例： "RowsPerStrip",16

`WriteMode` — 写入模式
`"overwrite"` （默认） | `"append"`

写入模式，指定为 "overwrite" 或 "append"。在 "overwrite" 模式下，imwrite 覆盖现有文件。在 "append" 模式下，imwrite 会向现有文件添加一页。

示例： "WriteMode","append"

扩展功能

基于线程的环境
使用 MATLAB® `backgroundPool` 在后台运行代码或使用 Parallel Computing Toolbox™ `ThreadPool` 加快代码运行速度。

用法说明和限制：

当您使用 backgroundPool 或 Parallel Computing Toolbox™ Threadpool 在后台运行 imwrite 时，imwrite 不支持读取分层数据格式 (HDF)、SVS 或 TIFF 文件。

有关详细信息，请参阅在基于线程的环境中运行 MATLAB 函数。

GPU 数组
通过使用 Parallel Computing Toolbox™ 在图形处理单元 (GPU) 上运行来加快代码执行。

用法说明和限制：

此函数接受 GPU 数组，但不在 GPU 上运行。

有关详细信息，请参阅Run MATLAB Functions on a GPU (Parallel Computing Toolbox)。

版本历史记录

在 R2006a 之前推出

全部展开

R2022b: 对 PNG 元数据使用 `datetime`

您可以使用 datetime 值来指定 CreationTime 和 ImageModTime 名称-值参数。

R2021b: 支持基于线程的环境

您可以使用 MATLAB backgroundPool 在后台运行 imwrite。

R2021b: JPEG 2000 图像中的像素差异

R2021b 中的 JPEG 2000 图像和以前版本的 MATLAB 之间可能存在像素值差异。

R2019b: 不支持写入颜色图条目不足的索引 PNG 文件

当要写入索引 PNG 文件时，必须指定具有足够条目的颜色图来正确解释图像。

另请参阅

imwrite

语法

说明

示例

将灰度图像写入 PNG

将索引图像数据写入 PNG

用 MATLAB 颜色图写入索引图像

将真彩色图像写入 JPEG

将多个图像写入 TIFF 文件

写入 GIF 动画

输入参数

A — 图像数据 矩阵

filename — 输出文件名 字符串标量 | 字符向量

map — 索引图像的颜色图 m×3 数组

fmt — 输出文件格式 "bmp" | "gif" | "hdf" | "jpg" | "jp2" | ...

名称-值参数

BackgroundColor — 要用作背景色的颜色 非负整数标量

Comment — 添加到图像的注释 字符串标量 | 字符向量 | 字符串数组 | 字符向量元胞数组

DelayTime — 显示下一个图像之前的时滞 0.5 （默认） | 范围 [0, 655] 内的标量值

DisposalMethod — GIF 动画的处置方法 "doNotSpecify" （默认） | "leaveInPlace" | "restoreBG" | "restorePrevious"

Location — 屏幕相对图像的偏移 [0,0] （默认） | 二元素向量

LoopCount — 重复动画的次数 Inf （默认） | 范围 [0, 65,535] 内的整数

ScreenSize — 帧的高度和宽度 输入图像的高度和宽度 （默认） | 二元素向量

TransparentColor — 用作透明色的颜色 非负整数标量

WriteMode — 写入模式 "overwrite" （默认） | "append"

Compression — 压缩方案 "none" （默认） | "jpeg" | "rle"

Quality — JPEG 压缩文件的质量 75 （默认） | 范围 [0, 100] 内的标量

WriteMode — 写入模式 "overwrite" （默认） | "append"

BitDepth — 每像素位数 8 （默认） | 12 | 16

Comment — 添加到图像的注释 字符串标量 | 字符向量 | 字符串数组 | 字符向量元胞数组

Mode — 压缩类型 "lossy" （默认） | "lossless"

Quality — 输出文件质量 75 （默认） | 范围 [0, 100] 内的标量

Comment — 添加到图像的注释 字符串标量 | 字符向量 | 字符串数组 | 字符向量元胞数组

CompressionRatio — 目标压缩比 1 （默认） | 正标量

Mode — 压缩类型 "lossy" （默认） | "lossless"

ProgressionOrder — 代码流中数据包的顺序 "LRCP" （默认） | "RLCP" | "RPCL" | "PCRL" | "CPRL"

QualityLayers — 质量层数 1 （默认） | 范围 [1, 20] 内的整数

ReductionLevels — 还原级数 4 （默认） | 范围 [1, 8] 内的整数

TileSize — 图块高度和宽度 图像尺寸 （默认） | 二元素向量

Encoding — 编码 "rawbits" （默认） | "ASCII"

MaxValue — 最大灰色或颜色值 正整数标量

Alpha — 每个像素的透明度 范围 [0, 1] 内的值矩阵

Author — 作者信息 字符串标量 | 字符向量

Background — 合成透明像素时的背景色 范围 [0, 1] 内的标量 | 范围 [1, P] 内的整数 | 范围 [0, 1] 内的三元素向量

BitDepth — 每像素位数 1 | 2 | 4 | 8 | 16

Chromaticities — 参考白和原色色度 八元素向量

Comment — 添加到图像的注释 字符串标量 | 字符向量

Copyright — 版权声明 字符串标量 | 字符向量

CreationTime — 原图创建的时间 日期时间 | 字符串标量 | 字符向量

Description — 图像的描述 字符串标量 | 字符向量

Disclaimer — 法律免责声明 字符串标量 | 字符向量

Gamma — 文件的 gamma 值 数值标量

ImageModTime — 图像最后修改的时间 日期时间 | 字符串标量 | 字符向量

InterlaceType — 隔行扫描方案 "none" （默认） | "adam7"

ResolutionUnit — 图像分辨率单位 "unknown" （默认） | "meter"

SignificantBits — 视作有效的位数 [] （默认） | 正整数标量 | 正整数向量

Software — 用于创建图像的软件 字符串标量 | 字符向量

Source — 用于创建图像的设备 字符串标量 | 字符向量

Transparency — 视为透明的像素 [] （默认） | 范围 [0, 1] 内的标量 | 向量

Warning — 内容性质警告 字符串标量 | 字符向量

XResolution — 水平方向的图像分辨率 数值标量

YResolution — 垂直方向的图像分辨率 数值标量

Alpha — 每个像素的透明度 [] （默认） | 矩阵

Type — 图像类型 "standard" （默认） | "rgb" | "rle"

ColorSpace — 表示颜色数据的颜色空间 "rgb" （默认） | "cielab" | "icclab"

Compression — 压缩方案 "packbits" | "none" | "lzw" | "deflate" | "jpeg" | "ccitt" | "fax3" | "fax4"

Description — 图像描述 字符串标量 | 字符向量

Resolution — X 分辨率和 Y 分辨率 72 （默认） | 标量 | 二元素向量

RowsPerStrip — 包含在每个条带中的行数 正整数标量

WriteMode — 写入模式 "overwrite" （默认） | "append"

扩展功能

基于线程的环境 使用 MATLAB® backgroundPool 在后台运行代码或使用 Parallel Computing Toolbox™ ThreadPool 加快代码运行速度。

GPU 数组 通过使用 Parallel Computing Toolbox™ 在图形处理单元 (GPU) 上运行来加快代码执行。

版本历史记录

R2022b: 对 PNG 元数据使用 datetime

R2021b: 支持基于线程的环境

R2021b: JPEG 2000 图像中的像素差异

R2019b: 不支持写入颜色图条目不足的索引 PNG 文件

另请参阅

WeChat

`A` — 图像数据
矩阵

`filename` — 输出文件名
字符串标量 | 字符向量

`map` — 索引图像的颜色图
m×3 数组

`fmt` — 输出文件格式
`"bmp"` | `"gif"` | `"hdf"` | `"jpg"` | `"jp2"` | ...

`BackgroundColor` — 要用作背景色的颜色
非负整数标量

`Comment` — 添加到图像的注释
字符串标量 | 字符向量 | 字符串数组 | 字符向量元胞数组

`DelayTime` — 显示下一个图像之前的时滞
0.5 （默认） | 范围 [0, 655] 内的标量值

`DisposalMethod` — GIF 动画的处置方法
`"doNotSpecify"` （默认） | `"leaveInPlace"` | `"restoreBG"` | `"restorePrevious"`

`Location` — 屏幕相对图像的偏移
`[0,0]` （默认） | 二元素向量

`LoopCount` — 重复动画的次数
`Inf` （默认） | 范围 [0, 65,535] 内的整数

`ScreenSize` — 帧的高度和宽度
输入图像的高度和宽度（默认） | 二元素向量

`TransparentColor` — 用作透明色的颜色
非负整数标量

`WriteMode` — 写入模式
`"overwrite"` （默认） | `"append"`

`Compression` — 压缩方案
`"none"` （默认） | `"jpeg"` | `"rle"`

`Quality` — JPEG 压缩文件的质量
75 （默认） | 范围 [0, 100] 内的标量

`WriteMode` — 写入模式
`"overwrite"` （默认） | `"append"`

`BitDepth` — 每像素位数
`8` （默认） | `12` | `16`

`Comment` — 添加到图像的注释
字符串标量 | 字符向量 | 字符串数组 | 字符向量元胞数组

`Mode` — 压缩类型
`"lossy"` （默认） | `"lossless"`

`Quality` — 输出文件质量
75 （默认） | 范围 [0, 100] 内的标量

`Comment` — 添加到图像的注释
字符串标量 | 字符向量 | 字符串数组 | 字符向量元胞数组

`CompressionRatio` — 目标压缩比
1 （默认） | 正标量

`Mode` — 压缩类型
`"lossy"` （默认） | `"lossless"`

`ProgressionOrder` — 代码流中数据包的顺序
`"LRCP"` （默认） | `"RLCP"` | `"RPCL"` | `"PCRL"` | `"CPRL"`

`QualityLayers` — 质量层数
1 （默认） | 范围 [1, 20] 内的整数

`ReductionLevels` — 还原级数
4 （默认） | 范围 [1, 8] 内的整数

`TileSize` — 图块高度和宽度
图像尺寸（默认） | 二元素向量

`Encoding` — 编码
`"rawbits"` （默认） | `"ASCII"`

`MaxValue` — 最大灰色或颜色值
正整数标量

`Alpha` — 每个像素的透明度
范围 [0, 1] 内的值矩阵

`Author` — 作者信息
字符串标量 | 字符向量

`Background` — 合成透明像素时的背景色
范围 [0, 1] 内的标量 | 范围 [1, P] 内的整数 | 范围 [0, 1] 内的三元素向量

`BitDepth` — 每像素位数
`1` | `2` | `4` | `8` | `16`

`Chromaticities` — 参考白和原色色度
八元素向量

`Comment` — 添加到图像的注释
字符串标量 | 字符向量

`Copyright` — 版权声明
字符串标量 | 字符向量

`CreationTime` — 原图创建的时间
日期时间 | 字符串标量 | 字符向量

`Description` — 图像的描述
字符串标量 | 字符向量

`Disclaimer` — 法律免责声明
字符串标量 | 字符向量

`Gamma` — 文件的 gamma 值
数值标量

`ImageModTime` — 图像最后修改的时间
日期时间 | 字符串标量 | 字符向量

`InterlaceType` — 隔行扫描方案
`"none"` （默认） | `"adam7"`

`ResolutionUnit` — 图像分辨率单位
`"unknown"` （默认） | `"meter"`

`SignificantBits` — 视作有效的位数
`[]` （默认） | 正整数标量 | 正整数向量

`Software` — 用于创建图像的软件
字符串标量 | 字符向量

`Source` — 用于创建图像的设备
字符串标量 | 字符向量

`Transparency` — 视为透明的像素
`[]` （默认） | 范围 [0, 1] 内的标量 | 向量

`Warning` — 内容性质警告
字符串标量 | 字符向量

`XResolution` — 水平方向的图像分辨率
数值标量

`YResolution` — 垂直方向的图像分辨率
数值标量

`Alpha` — 每个像素的透明度
`[]` （默认） | 矩阵

`Type` — 图像类型
`"standard"` （默认） | `"rgb"` | `"rle"`

`ColorSpace` — 表示颜色数据的颜色空间
`"rgb"` （默认） | `"cielab"` | `"icclab"`

`Compression` — 压缩方案
`"packbits"` | `"none"` | `"lzw"` | `"deflate"` | `"jpeg"` | `"ccitt"` | `"fax3"` | `"fax4"`

`Description` — 图像描述
字符串标量 | 字符向量

`Resolution` — X 分辨率和 Y 分辨率
72 （默认） | 标量 | 二元素向量

`RowsPerStrip` — 包含在每个条带中的行数
正整数标量

`WriteMode` — 写入模式
`"overwrite"` （默认） | `"append"`

基于线程的环境
使用 MATLAB® `backgroundPool` 在后台运行代码或使用 Parallel Computing Toolbox™ `ThreadPool` 加快代码运行速度。

GPU 数组
通过使用 Parallel Computing Toolbox™ 在图形处理单元 (GPU) 上运行来加快代码执行。

R2022b: 对 PNG 元数据使用 `datetime`