图像文件读写

主题
	用于图像文件读写的标志
	iOS 粘合层
	MacOS(OSX) 粘合层

详细描述

类
结构体	cv::Animation
	表示具有多帧的动画。Animation 结构体旨在存储和管理动画序列的数据，例如来自动画格式（例如 GIF、AVIF、APNG、WebP）的数据。它提供循环、背景颜色设置、帧时间以及帧存储支持。 更多...
类	cv::ImageCollection
	按需读取多页图像。 更多...

函数
CV_EXPORTS_W bool	cv::haveImageReader (const String &filename)
	检查 OpenCV 是否可以解码指定的图像文件。
CV_EXPORTS_W bool	cv::haveImageWriter (const String &filename)
	检查 OpenCV 是否可以编码指定的图像文件或指定的文件扩展名。
CV_EXPORTS_W size_t	cv::imcount (const String &filename, int flags=IMREAD_ANYCOLOR)
	返回给定文件中的图像数量。
CV_EXPORTS_W Mat	cv::imdecode (InputArray buf, int flags)
	从内存缓冲区读取图像。
CV_EXPORTS Mat	cv::imdecode (InputArray buf, int flags, Mat *dst)
CV_EXPORTS_W bool	cv::imdecodeanimation (InputArray buf, CV_OUT Animation &animation, int start=0, int count=INT16_MAX)
	从动画图像缓冲区加载帧到 Animation 结构中。
CV_EXPORTS_W bool	cv::imdecodemulti (InputArray buf, int flags, CV_OUT std::vector< Mat > &mats, const cv::Range &range=Range::all())
	从内存缓冲区读取多页图像。
CV_EXPORTS_W Mat	cv::imdecodeWithMetadata (InputArray buf, CV_OUT std::vector< int > &metadataTypes, OutputArrayOfArrays metadata, int flags=IMREAD_ANYCOLOR)
	从内存缓冲区读取图像及相关元数据。
CV_EXPORTS_W bool	cv::imencode (const String &ext, InputArray img, CV_OUT std::vector< uchar > &buf, const std::vector< int > &params=std::vector< int >())
	将图像编码到内存缓冲区。
CV_EXPORTS_W bool	cv::imencodeanimation (const String &ext, const Animation &animation, CV_OUT std::vector< uchar > &buf, const std::vector< int > &params=std::vector< int >())
	将 Animation 编码到内存缓冲区。
CV_EXPORTS_W bool	cv::imencodemulti (const String &ext, InputArrayOfArrays imgs, CV_OUT std::vector< uchar > &buf, const std::vector< int > &params=std::vector< int >())
	将图像数组编码到内存缓冲区。
CV_EXPORTS_W bool	cv::imencodeWithMetadata (const String &ext, InputArray img, const std::vector< int > &metadataTypes, InputArrayOfArrays metadata, CV_OUT std::vector< uchar > &buf, const std::vector< int > &params=std::vector< int >())
	将图像编码到内存缓冲区。
CV_EXPORTS_W Mat	cv::imread (const String &filename, int flags=IMREAD_COLOR_BGR)
	从文件加载图像。
CV_EXPORTS_W void	cv::imread (const String &filename, OutputArray dst, int flags=IMREAD_COLOR_BGR)
	从文件加载图像。
CV_EXPORTS_W bool	cv::imreadanimation (const String &filename, CV_OUT Animation &animation, int start=0, int count=INT16_MAX)
	从动画图像文件加载帧到 Animation 结构中。
CV_EXPORTS_W bool	cv::imreadmulti (const String &filename, CV_OUT std::vector< Mat > &mats, int flags=IMREAD_ANYCOLOR)
	从文件加载多页图像。
CV_EXPORTS_W bool	cv::imreadmulti (const String &filename, CV_OUT std::vector< Mat > &mats, int start, int count, int flags=IMREAD_ANYCOLOR)
	从文件加载多页图像的图像。
CV_EXPORTS_W Mat	cv::imreadWithMetadata (const String &filename, CV_OUT std::vector< int > &metadataTypes, OutputArrayOfArrays metadata, int flags=IMREAD_ANYCOLOR)
	从文件读取图像及相关元数据。
CV_EXPORTS_W bool	cv::imwrite (const String &filename, InputArray img, const std::vector< int > &params=std::vector< int >())
	将图像保存到指定文件。
CV_EXPORTS_W bool	cv::imwriteanimation (const String &filename, const Animation &animation, const std::vector< int > &params=std::vector< int >())
	将 Animation 保存到指定文件。
static CV_WRAP bool	cv::imwritemulti (const String &filename, InputArrayOfArrays img, const std::vector< int > &params=std::vector< int >())
	用于绑定的多图像重载
CV_EXPORTS_W bool	cv::imwriteWithMetadata (const String &filename, InputArray img, const std::vector< int > &metadataTypes, InputArrayOfArrays &metadata, const std::vector< int > &params=std::vector< int >())
	将图像和元数据保存到指定文件。

函数文档

haveImageReader()

CV_EXPORTS_W bool cv::haveImageReader

(

const String &

filename

)

Python
	cv.haveImageReader(	filename	) ->	retval

#include <opencv2/imgcodecs.hpp>

检查 OpenCV 是否可以解码指定的图像文件。

函数 `haveImageReader` 检查 OpenCV 是否能够读取指定文件。这在尝试加载图像之前，可用于验证对给定图像格式的支持。

参数

filename

要检查的文件名。

返回

如果指定文件的图像读取器可用且文件可以打开，则为 true，否则为 false。

注意

此函数检查内置于 OpenCV 或动态加载的图像编解码器的可用性。它不加载图像编解码器实现并解码数据，而是使用签名检查。如果文件无法打开或格式不受支持，则函数将返回 false。

另请参见

cv::haveImageWriter, cv::imread, cv::imdecode

haveImageWriter()

CV_EXPORTS_W bool cv::haveImageWriter

(

const String &

filename

)

Python
	cv.haveImageWriter(	filename	) ->	retval

#include <opencv2/imgcodecs.hpp>

检查 OpenCV 是否可以编码指定的图像文件或指定的文件扩展名。

函数 `haveImageWriter` 检查 OpenCV 是否能够写入指定文件扩展名的图像。这在尝试保存图像之前，可用于验证对给定图像格式的支持。

参数

filename

文件名或文件扩展名（例如“.jpg”、“.png”）。建议提供文件扩展名而不是完整文件名。

返回

如果指定扩展名的图像写入器可用，则为 true，否则为 false。

注意

此函数检查内置于 OpenCV 或动态加载的图像编解码器的可用性。它不检查文件的实际存在，而是检查写入给定类型文件的能力。

另请参见

cv::haveImageReader, cv::imwrite, cv::imencode

imcount()

CV_EXPORTS_W size_t cv::imcount	(	const String &	filename,
		int	flags = IMREAD_ANYCOLOR )

Python
	cv.imcount(	filename[, flags]	) ->	retval

#include <opencv2/imgcodecs.hpp>

返回给定文件中的图像数量。

函数 `imcount` 返回多页图像（例如 TIFF）中的页数、动画（例如 AVIF）中的帧数，否则返回 1。如果图像无法解码，则返回 0。

参数

filename	要加载的文件名。
flags	标志，可取 cv::ImreadModes 的值，默认为 cv::IMREAD_ANYCOLOR。

待办

当使用 cv::IMREAD_LOAD_GDAL 标志时，返回值为 0 或 1，因为 OpenCV 的 GDAL 解码器尚不支持多页读取。

imdecode() [1/2]

CV_EXPORTS_W Mat cv::imdecode	(	InputArray	buf,
		int	flags )

Python
	cv.imdecode(	buf, flags	) ->	retval

#include <opencv2/imgcodecs.hpp>

从内存缓冲区读取图像。

函数 `imdecode` 从内存中的指定缓冲区读取图像。如果缓冲区太短或包含无效数据，函数将返回一个空矩阵（ Mat::data==NULL ）。

支持的格式列表和标志说明请参见 cv::imread。

注意

对于彩色图像，解码后的图像通道将以 B G R 顺序存储。

参数

buf	输入数组或字节向量。
flags	与 cv::imread 中的标志相同，请参见 cv::ImreadModes。

imdecode() [2/2]

CV_EXPORTS Mat cv::imdecode	(	InputArray	buf,
		int	flags,
		Mat *	dst )

Python
	cv.imdecode(	buf, flags	) ->	retval

#include <opencv2/imgcodecs.hpp>

这是一个重载成员函数，为方便起见而提供。它与上述函数的区别仅在于它接受的参数。

参数

buf	输入数组或字节向量。
flags	与 cv::imread 中的标志相同，请参见 cv::ImreadModes。
dst	用于解码矩阵的可选输出占位符。当函数重复调用相同大小的图像时，它可以节省图像重新分配。如果解码器失败，函数将返回空的 cv::Mat 对象，但不会释放用户提供的 dst 缓冲区。

imdecodeanimation()

CV_EXPORTS_W bool cv::imdecodeanimation	(	InputArray	buf,
		CV_OUT Animation &	animation,
		int	start = 0,
		int	count = INT16_MAX )

Python
	cv.imdecodeanimation(	buf[, start[, count]]	) ->	retval, animation

#include <opencv2/imgcodecs.hpp>

从动画图像缓冲区加载帧到 Animation 结构中。

函数 `imdecodeanimation` 从动画图像缓冲区（例如 GIF、AVIF、APNG、WEBP）加载帧到提供的 Animation 结构体中。

参数

buf	包含图像缓冲区的 InputArray 的引用。
animation	对将存储加载帧的 Animation 结构体的引用。它应该在调用函数之前初始化。
start	要加载的第一帧的索引。这是可选的，默认为 0。
count	要加载的帧数。这是可选的，默认为 32767。

返回

如果缓冲区成功加载并提取了帧，则返回 true；否则返回 false。

imdecodemulti()

CV_EXPORTS_W bool cv::imdecodemulti	(	InputArray	buf,
		int	flags,
		CV_OUT std::vector< Mat > &	mats,
		const cv::Range &	range = Range::all() )

Python
	cv.imdecodemulti(	buf, flags[, mats[, range]]	) ->	retval, mats

#include <opencv2/imgcodecs.hpp>

从内存缓冲区读取多页图像。

函数 `imdecodemulti` 从内存中的指定缓冲区读取多页图像。如果缓冲区太短或包含无效数据，函数将返回 false。

支持的格式列表和标志说明请参见 cv::imreadmulti。

注意

对于彩色图像，解码后的图像通道将以 B G R 顺序存储。

参数

buf	输入数组或字节向量。
flags	与 cv::imread 中的标志相同，请参见 cv::ImreadModes。
mats	一个 Mat 对象向量，每个对象持有一个页面（如果多于一个）。
range	页面的连续选择。

imdecodeWithMetadata()

CV_EXPORTS_W Mat cv::imdecodeWithMetadata	(	InputArray	buf,
		CV_OUT std::vector< int > &	metadataTypes,
		OutputArrayOfArrays	metadata,
		int	flags = IMREAD_ANYCOLOR )

Python
	cv.imdecodeWithMetadata(	buf[, metadata[, flags]]	) ->	retval, metadataTypes, metadata

#include <opencv2/imgcodecs.hpp>

从内存缓冲区读取图像及相关元数据。

函数 `imdecode` 从内存中的指定缓冲区读取图像。如果缓冲区太短或包含无效数据，函数将返回一个空矩阵（ Mat::data==NULL ）。

支持的格式列表和标志说明请参见 cv::imread。

注意

对于彩色图像，解码后的图像通道将以 B G R 顺序存储。

参数

buf	输入数组或字节向量。
metadataTypes	输出向量，包含元数据中返回的元数据块类型，请参见 ImageMetadataType。
metadata	向量的向量或矩阵的向量，用于存储检索到的元数据。
flags	与 cv::imread 中的标志相同，请参见 cv::ImreadModes。

imencode()

CV_EXPORTS_W bool cv::imencode	(	const String &	ext,
		InputArray	img,
		CV_OUT std::vector< uchar > &	buf,
		const std::vector< int > &	params = std::vector< int >() )

Python
	cv.imencode(	ext, img[, params]	) ->	retval, buf

#include <opencv2/imgcodecs.hpp>

将图像编码到内存缓冲区。

函数 `imencode` 压缩图像并将其存储在调整大小以适应结果的内存缓冲区中。支持的格式列表和标志说明请参见 cv::imwrite。

参数

ext	定义输出格式的文件扩展名。必须包含前导句点。
img	要压缩的图像。
buf	调整大小以适应压缩图像的输出缓冲区。
params	格式特定的参数。请参见 cv::imwrite 和 cv::ImwriteFlags。

imencodeanimation()

CV_EXPORTS_W bool cv::imencodeanimation	(	const String &	ext,
		const Animation &	animation,
		CV_OUT std::vector< uchar > &	buf,
		const std::vector< int > &	params = std::vector< int >() )

Python
	cv.imencodeanimation(	ext, animation[, params]	) ->	retval, buf

#include <opencv2/imgcodecs.hpp>

将 Animation 编码到内存缓冲区。

函数 `imencodeanimation` 将提供的 Animation 数据编码到内存缓冲区中，形成动画格式。支持的格式取决于实现，可能包括 GIF、AVIF、APNG 或 WEBP 等格式。

参数

ext	确定编码数据格式的文件扩展名。
animation	对包含要编码的帧和元数据的 Animation 结构体的常量引用。
buf	指向存储编码数据的无符号字符向量的引用。
params	可选的格式特定参数，编码为对（paramId_1, paramValue_1, paramId_2, paramValue_2, ...）。这些参数用于指定编码过程的额外选项。有关可能的参数的详细信息，请参阅 cv::ImwriteFlags。

返回

如果动画成功编码，则返回 true；否则返回 false。

imencodemulti()

CV_EXPORTS_W bool cv::imencodemulti	(	const String &	ext,
		InputArrayOfArrays	imgs,
		CV_OUT std::vector< uchar > &	buf,
		const std::vector< int > &	params = std::vector< int >() )

Python
	cv.imencodemulti(	ext, imgs[, params]	) ->	retval, buf

#include <opencv2/imgcodecs.hpp>

将图像数组编码到内存缓冲区。

此函数类似于 cv::imencode，用于内存中的多页图像压缩。支持的格式列表和标志说明请参见 cv::imwrite。

参数

ext	定义输出格式的文件扩展名。必须包含前导句点。
imgs	要写入的图像向量。
buf	调整大小以适应压缩数据的输出缓冲区。
params	格式特定的参数。请参见 cv::imwrite 和 cv::ImwriteFlags。

imencodeWithMetadata()

CV_EXPORTS_W bool cv::imencodeWithMetadata	(	const String &	ext,
		InputArray	img,
		const std::vector< int > &	metadataTypes,
		InputArrayOfArrays	metadata,
		CV_OUT std::vector< uchar > &	buf,
		const std::vector< int > &	params = std::vector< int >() )

Python
	cv.imencodeWithMetadata(	ext, img, metadataTypes, metadata[, params]	) ->	retval, buf

#include <opencv2/imgcodecs.hpp>

将图像编码到内存缓冲区。

函数 `imencode` 压缩图像并将其存储在调整大小以适应结果的内存缓冲区中。支持的格式列表和标志说明请参见 cv::imwrite。

参数

ext	定义输出格式的文件扩展名。必须包含前导句点。
img	要压缩的图像。
metadataTypes	元数据中存储的要写入的元数据块类型向量，请参见 ImageMetadataType。
metadata	向量的向量或矩阵的向量，包含要存储到文件中的元数据块。
buf	调整大小以适应压缩图像的输出缓冲区。
params	格式特定的参数。请参见 cv::imwrite 和 cv::ImwriteFlags。

imread() [1/2]

CV_EXPORTS_W Mat cv::imread	(	const String &	filename,
		int	flags = IMREAD_COLOR_BGR )

Python
	cv.imread(	filename[, flags]	) ->	retval
	cv.imread(	filename[, dst[, flags]]	) ->	dst

#include <opencv2/imgcodecs.hpp>

从文件加载图像。

imread 函数从指定文件加载图像并返回 OpenCV 矩阵。如果图像无法读取（因为文件缺失、权限不当或格式不支持/无效），函数将返回一个空矩阵。

目前，支持以下文件格式

• Windows 位图 - *.bmp, *.dib (始终支持)
• GIF 文件 - *.gif (始终支持)
• JPEG 文件 - *.jpeg, *.jpg, *.jpe (参见 注意 部分)
• JPEG 2000 文件 - *.jp2 (参见 注意 部分)
• 便携式网络图形 - *.png (参见 注意 部分)
• WebP - *.webp (参见 注意 部分)
• AVIF - *.avif (参见 注意 部分)
• 便携式图像格式 - *.pbm, *.pgm, *.ppm, *.pxm, *.pnm (始终支持)
• PFM 文件 - *.pfm (参见 注意 部分)
• Sun 光栅图像 - *.sr, *.ras (始终支持)
• TIFF 文件 - *.tiff, *.tif (参见 注意 部分)
• OpenEXR 图像文件 - *.exr (参见 注意 部分)
• Radiance HDR - *.hdr, *.pic (始终支持)
• GDAL 支持的栅格和矢量地理空间数据 (参见 注意 部分)

注意

• 函数通过图像内容而非文件扩展名来确定图像类型。
• 对于彩色图像，解码后的图像通道将以 B G R 顺序存储。
• 使用 IMREAD_GRAYSCALE 时，如果可用，将使用编解码器的内部灰度转换。结果可能与 cvtColor() 的输出不同。
• 在 Microsoft Windows* 和 Mac OS* 上，默认使用 OpenCV 附带的编解码器（libjpeg、libpng、libtiff 和 libjasper）。因此，OpenCV 始终可以读取 JPEG、PNG 和 TIFF。在 Mac OS 上，还有使用原生 Mac OS 图像读取器的选项。但是，请注意，目前这些原生图像加载器由于 Mac OS 中嵌入的颜色管理，会产生具有不同像素值的图像。
• 在 Linux*、BSD 变体和其他类 Unix 开源操作系统上，OpenCV 查找操作系统提供的编解码器。请确保安装了相关软件包（包括开发文件，例如 Debian* 和 Ubuntu* 中的“libjpeg-dev”）以获得编解码器支持，或在 CMake 中打开 OPENCV_BUILD_3RDPARTY_LIBS 标志。
• 如果在 CMake 中将 WITH_GDAL 标志设置为 true，并且使用 IMREAD_LOAD_GDAL 加载图像，则将使用 GDAL 驱动程序解码图像，支持 栅格 和 矢量 格式。
• 如果 EXIF 信息嵌入在图像文件中，则会考虑 EXIF 方向，因此图像将相应旋转，除非传递了 IMREAD_IGNORE_ORIENTATION 或 IMREAD_UNCHANGED 标志。
• 使用 IMREAD_UNCHANGED 标志保留 PFM 图像的浮点值。
• 默认情况下，像素数量必须小于 2^30。可以通过设置环境变量 OPENCV_IO_MAX_IMAGE_PIXELS 来更改此限制。请参见 OpenCV 环境变量参考。

参数

filename	要加载的文件名。
flags	可取 cv::ImreadModes 值的标志。

imread() [2/2]

CV_EXPORTS_W void cv::imread	(	const String &	filename,
		OutputArray	dst,
		int	flags = IMREAD_COLOR_BGR )

Python
	cv.imread(	filename[, flags]	) ->	retval
	cv.imread(	filename[, dst[, flags]]	) ->	dst

#include <opencv2/imgcodecs.hpp>

从文件加载图像。

这是一个重载成员函数，为方便起见而提供。它与上述函数的区别仅在于它接受的参数和返回值。

参数

filename	要加载的文件名。
dst	将加载图像的对象。
flags	可取 cv::ImreadModes 值的标志

注意

通过 img 参数传递的图像可以预先分配。如果形状和类型与加载图像匹配，则内存会被重用。

imreadanimation()

CV_EXPORTS_W bool cv::imreadanimation	(	const String &	filename,
		CV_OUT Animation &	animation,
		int	start = 0,
		int	count = INT16_MAX )

Python
	cv.imreadanimation(	filename[, start[, count]]	) ->	retval, animation

#include <opencv2/imgcodecs.hpp>

从动画图像文件加载帧到 Animation 结构中。

函数 `imreadanimation` 从动画图像文件（例如 GIF、AVIF、APNG、WEBP）加载帧到提供的 Animation 结构体中。

参数

filename	包含文件路径的字符串。
animation	对将存储加载帧的 Animation 结构体的引用。它应该在调用函数之前初始化。
start	要加载的第一帧的索引。这是可选的，默认为 0。
count	要加载的帧数。这是可选的，默认为 32767。

返回

如果文件成功加载并提取了帧，则返回 true；否则返回 false。

imreadmulti() [1/2]

CV_EXPORTS_W bool cv::imreadmulti	(	const String &	filename,
		CV_OUT std::vector< Mat > &	mats,
		int	flags = IMREAD_ANYCOLOR )

Python
	cv.imreadmulti(	filename[, mats[, flags]]	) ->	retval, mats
	cv.imreadmulti(	filename, start, count[, mats[, flags]]	) ->	retval, mats

#include <opencv2/imgcodecs.hpp>

从文件加载多页图像。

函数 `imreadmulti` 从指定文件加载多页图像到 Mat 对象向量中。

参数

filename	要加载的文件名。
mats	一个 Mat 对象向量，每个对象持有一个页面。
flags	标志，可取 cv::ImreadModes 的值，默认为 cv::IMREAD_ANYCOLOR。

另请参见

cv::imread

imreadmulti() [2/2]

CV_EXPORTS_W bool cv::imreadmulti	(	const String &	filename,
		CV_OUT std::vector< Mat > &	mats,
		int	start,
		int	count,
		int	flags = IMREAD_ANYCOLOR )

Python
	cv.imreadmulti(	filename[, mats[, flags]]	) ->	retval, mats
	cv.imreadmulti(	filename, start, count[, mats[, flags]]	) ->	retval, mats

#include <opencv2/imgcodecs.hpp>

从文件加载多页图像的图像。

函数 `imreadmulti` 从指定文件中加载多页图像的指定范围到 Mat 对象向量中。

参数

filename	要加载的文件名。
mats	一个 Mat 对象向量，每个对象持有一个页面。
start	要加载图像的起始索引
count	要加载的图像数量
flags	标志，可取 cv::ImreadModes 的值，默认为 cv::IMREAD_ANYCOLOR。

另请参见

cv::imread

imreadWithMetadata()

CV_EXPORTS_W Mat cv::imreadWithMetadata	(	const String &	filename,
		CV_OUT std::vector< int > &	metadataTypes,
		OutputArrayOfArrays	metadata,
		int	flags = IMREAD_ANYCOLOR )

Python
	cv.imreadWithMetadata(	filename[, metadata[, flags]]	) ->	retval, metadataTypes, metadata

#include <opencv2/imgcodecs.hpp>

从文件读取图像及相关元数据。

函数 `imreadWithMetadata` 从指定文件读取图像。它的功能与 `imread` 相同，但如果相应文件包含元数据，则会额外读取元数据。

参数

filename	要加载的文件名。
metadataTypes	输出向量，包含元数据中返回的元数据块类型，请参见 ImageMetadataType。
metadata	向量的向量或矩阵的向量，用于存储检索到的元数据。
flags	可取 cv::ImreadModes 值的标志

imwrite()

CV_EXPORTS_W bool cv::imwrite	(	const String &	filename,
		InputArray	img,
		const std::vector< int > &	params = std::vector< int >() )

Python
	cv.imwrite(	filename, img[, params]	) ->	retval

#include <opencv2/imgcodecs.hpp>

将图像保存到指定文件。

函数 `imwrite` 将图像保存到指定文件。图像格式根据文件名扩展名选择（有关扩展名列表，请参见 cv::imread）。通常，只有 8 位无符号 (CV_8U) 单通道或 3 通道（通道顺序为 'BGR'）图像可以使用此函数保存，但以下情况除外：

• 使用 OpenEXR 编码器，只能保存 32 位浮点 (CV_32F) 图像。
  • 不支持 8 位无符号 (CV_8U) 图像。
• 使用 Radiance HDR 编码器，可以保存非 64 位浮点 (CV_64F) 图像。
  • 所有图像都将转换为 32 位浮点 (CV_32F)。
• 使用 JPEG 2000 编码器，可以保存 8 位无符号 (CV_8U) 和 16 位无符号 (CV_16U) 图像。
• 使用 JPEG XL 编码器，可以保存 8 位无符号 (CV_8U)、16 位无符号 (CV_16U) 和 32 位浮点 (CV_32F) 图像。
  • 使用此函数可以保存带 alpha 通道的 JPEG XL 图像。为此，请创建一个 8 位 4 通道 (CV_8UC4) / 16 位 4 通道 (CV_16UC4) / 32 位浮点 4 通道 (CV_32FC4) BGRA 图像，确保 alpha 通道是最后一个分量。完全透明的像素应具有 0 的 alpha 值，而完全不透明的像素应具有 255/65535/1.0 的 alpha 值。
• 使用 PAM 编码器，可以保存 8 位无符号 (CV_8U) 和 16 位无符号 (CV_16U) 图像。
• 使用 PNG 编码器，可以保存 8 位无符号 (CV_8U) 和 16 位无符号 (CV_16U) 图像。
  • 使用此函数可以保存带 alpha 通道的 PNG 图像。为此，请创建一个 8 位 4 通道 (CV_8UC4) / 16 位 4 通道 (CV_16UC4) BGRA 图像，确保 alpha 通道是最后一个分量。完全透明的像素应具有 0 的 alpha 值，而完全不透明的像素应具有 255/65535 的 alpha 值（参见下面的代码示例）。
• 使用 PGM/PPM 编码器，可以保存 8 位无符号 (CV_8U) 和 16 位无符号 (CV_16U) 图像。
• 使用 TIFF 编码器，可以保存 8 位无符号 (CV_8U)、8 位有符号 (CV_8S)、16 位无符号 (CV_16U)、16 位有符号 (CV_16S)、32 位有符号 (CV_32S)、32 位浮点 (CV_32F) 和 64 位浮点 (CV_64F) 图像。
  • 多个图像（Mat 向量）可以保存为 TIFF 格式（参见下面的代码示例）。
  • 32 位浮点 3 通道 (CV_32FC3) TIFF 图像将使用 LogLuv 高动态范围编码（每像素 4 字节）保存。
• 使用 GIF 编码器，可以保存 8 位无符号 (CV_8U) 图像。
  • 使用此函数可以保存带 alpha 通道的 GIF 图像。为此，请创建一个 8 位 4 通道 (CV_8UC4) BGRA 图像，确保 alpha 通道是最后一个分量。完全透明的像素应具有 0 的 alpha 值，而完全不透明的像素应具有 255 的 alpha 值。
  • 由于 GIF 限制为索引颜色格式，不支持 8 位单通道图像 (CV_8UC1)。

如果图像格式不受支持，图像将被转换为 8 位无符号 (CV_8U) 并以这种方式保存。

如果格式、深度或通道顺序不同，请在保存前使用 Mat::convertTo 和 cv::cvtColor 进行转换。或者，使用通用的 FileStorage I/O 函数将图像保存为 XML 或 YAML 格式。

下面的示例展示了如何创建 BGRA 图像，如何设置自定义压缩参数并将其保存到 PNG 文件。它还演示了如何在 TIFF 文件中保存多个图像。

#include <opencv2/imgcodecs.hpp>
 
using namespace cv;
using namespace std;
 
static void paintAlphaMat(Mat &mat)
{
    CV_Assert(mat.channels() == 4);
    for (int i = 0; i < mat.rows; ++i)
    {
        for (int j = 0; j < mat.cols; ++j)
        {
            Vec4b& bgra = mat.at<Vec4b>(i, j);
bgra[0] = UCHAR_MAX; // 蓝色
bgra[1] = saturate_cast<uchar>((float (mat.cols - j)) / ((float)mat.cols) * UCHAR_MAX); // 绿色
bgra[2] = saturate_cast<uchar>((float (mat.rows - i)) / ((float)mat.rows) * UCHAR_MAX); // 红色
bgra[3] = saturate_cast<uchar>(0.5 * (bgra[1] + bgra[2])); // Alpha 通道
        }
    }
}
 
int main()
{
    Mat mat(480, 640, CV_8UC4); // 创建一个带有 Alpha 通道的矩阵
paintAlphaMat(mat);
 
vector<int> compression_params;
compression_params.push_back(IMWRITE_PNG_COMPRESSION);
compression_params.push_back(9);
 
    bool result = false;
    try
    {
result = imwrite("alpha.png", mat, compression_params);
    }
    catch (const cv::Exception& ex)
    {
fprintf(stderr, "将图像转换为 PNG 格式时发生异常：%s\n", ex.what());
    }
 
    if (result)
printf("已保存带 Alpha 数据的 PNG 文件。\n");
    else
printf("错误：无法保存 PNG 文件。\n");
 
vector<Mat> imgs;
imgs.push_back(mat);
imgs.push_back(~mat);
imgs.push_back(mat(Rect(0, 0, mat.cols / 2, mat.rows / 2)));
    imwrite("test.tiff", imgs);
printf("多个文件已保存到 test.tiff\n");
 
    return result ? 0 : 1;
}

参数

filename	文件名。
img	（Mat 或 Mat 向量）要保存的图像或图像列表。
params	格式特定的参数，编码为对（paramId_1, paramValue_1, paramId_2, paramValue_2, ...）。请参见 cv::ImwriteFlags

imwriteanimation()

CV_EXPORTS_W bool cv::imwriteanimation	(	const String &	filename,
		const Animation &	animation,
		const std::vector< int > &	params = std::vector< int >() )

Python
	cv.imwriteanimation(	filename, animation[, params]	) ->	retval

#include <opencv2/imgcodecs.hpp>

将 Animation 保存到指定文件。

函数 `imwriteanimation` 将提供的 Animation 数据以动画格式保存到指定文件。支持的格式取决于实现，可能包括 GIF、AVIF、APNG 或 WEBP 等格式。

参数

filename	保存动画的文件名。文件扩展名决定了格式。
animation	对包含要保存的帧和元数据的 Animation 结构体的常量引用。
params	可选的格式特定参数，编码为对（paramId_1, paramValue_1, paramId_2, paramValue_2, ...）。这些参数用于指定编码过程的额外选项。有关可能的参数的详细信息，请参阅 cv::ImwriteFlags。

返回

如果动画成功保存，则返回 true；否则返回 false。

imwritemulti()

static CV_WRAP bool cv::imwritemulti ( const String & filename, InputArrayOfArrays img, const std::vector< int > & params = std::vector<int>() )

inlinestatic

Python
	cv.imwritemulti(	filename, img[, params]	) ->	retval

#include <opencv2/imgcodecs.hpp>

用于绑定的多图像重载

此函数的调用图如下

imwriteWithMetadata()

CV_EXPORTS_W bool cv::imwriteWithMetadata	(	const String &	filename,
		InputArray	img,
		const std::vector< int > &	metadataTypes,
		InputArrayOfArrays &	metadata,
		const std::vector< int > &	params = std::vector< int >() )

Python
	cv.imwriteWithMetadata(	filename, img, metadataTypes, metadata[, params]	) ->	retval

#include <opencv2/imgcodecs.hpp>

将图像和元数据保存到指定文件。

函数 `imwriteWithMetadata` 将图像保存到指定文件。它的功能与 `imwrite` 相同，但如果相应格式支持元数据，则会额外写入元数据。

参数

filename	文件名。与 `imwrite` 一样，图像格式由文件扩展名决定。
img	（Mat 或 Mat 向量）要保存的图像或图像列表。
metadataTypes	元数据中存储的要写入的元数据块类型向量，请参见 ImageMetadataType。
metadata	向量的向量或矩阵的向量，包含要存储到文件中的元数据块。
params	格式特定的参数，编码为对（paramId_1, paramValue_1, paramId_2, paramValue_2, ...）。请参见 cv::ImwriteFlags