图像文件读写

主题
	用于图像文件读写的标志
	iOS 胶水代码
	MacOS(OSX) 胶水代码

详细说明

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

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

函数文档 (Function Documentation)

haveImageReader()

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()

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()

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]

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::ImreadModes 值的标志。

imdecode() [2/2]

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

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

#include <opencv2/imgcodecs.hpp>

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

参数

buf	输入数组或字节向量。
flags (标志)	可以取 cv::ImreadModes 值的标志，默认值为 cv::IMREAD_ANYCOLOR。
dst	解码矩阵的可选输出占位符。当函数重复调用同一大小的图像时，它可以节省图像重新分配。如果解码器失败，函数返回空的 cv::Mat 对象，但不释放用户提供的 dst 缓冲区。

imdecodeanimation()

bool cv::imdecodeanimation	(	InputArray	buf,
		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()

bool cv::imdecodemulti	(	InputArray	buf,
		int	flags (标志),
		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::ImreadModes 值的标志。
mats	如果多于一页，则为保存每页的 Mat 对象的向量。
range	页面的连续选择。

imdecodeWithMetadata()

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

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

#include <opencv2/imgcodecs.hpp>

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

此函数从指定的内存缓冲区解码图像。如果缓冲区太短或包含无效数据，函数将返回一个空矩阵 ( Mat::data==NULL )。

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

注意

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

参数

buf	包含编码图像数据的输入数组或字节向量。
metadataTypes	输出向量，其中包含 metadata 中返回的元数据块类型，参见 cv::ImageMetadataType
metadata	向量的向量或矩阵的向量，用于存储检索到的元数据
flags (标志)	可以取 cv::ImreadModes 值的标志，默认值为 cv::IMREAD_ANYCOLOR。

返回

解码后的图像作为 cv::Mat 对象。如果解码失败，函数将返回一个空矩阵。

imencode()

bool cv::imencode	(	const String &	ext,
		InputArray	img,
		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()

bool cv::imencodeanimation	(	const String &	ext,
		const Animation &	animation,
		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	指向 unsigned char 向量的引用，其中将存储编码数据。
params	可选的格式特定参数，编码为对（paramId_1, paramValue_1, paramId_2, paramValue_2, ...）。这些参数用于指定编码过程的其他选项。有关可能参数的详细信息，请参阅 cv::ImwriteFlags。

返回

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

imencodemulti()

bool cv::imencodemulti	(	const String &	ext,
		InputArrayOfArrays	imgs,
		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()

bool cv::imencodeWithMetadata	(	const String &	ext,
		InputArray	img,
		const std::vector< int > &	metadataTypes,
		InputArrayOfArrays	metadata,
		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	向量，其中包含 metadata 中存储的元数据块类型，用于写入，参见 ImageMetadataType。
metadata	向量的向量或矩阵的向量，其中包含要存储到文件中的元数据块。
buf	调整大小以适应压缩图像的输出缓冲区。
params	格式特定参数。参见 cv::imwrite 和 cv::ImwriteFlags。

imread() [1/2]

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 值的标志，默认值为 cv::IMREAD_COLOR_BGR。

imread() [2/2]

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 值的标志，默认值为 cv::IMREAD_COLOR_BGR。

注意

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

imreadanimation()

bool cv::imreadanimation	(	const String &	filename,
		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]

bool cv::imreadmulti	(	const String &	filename,
		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]

bool cv::imreadmulti	(	const String &	filename,
		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()

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

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

#include <opencv2/imgcodecs.hpp>

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

此函数与 cv::imread() 行为类似，从指定文件加载图像。除了图像像素数据，它还尝试提取文件中嵌入的任何可用元数据（例如 EXIF、XMP 等），具体取决于文件格式支持。

注意

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

参数

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

返回

加载的图像作为 cv::Mat 对象。如果图像无法读取，函数将返回一个空矩阵。

imwrite()

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”通道顺序）图像，但以下情况除外

• 使用 BMP 编码器，可以保存 8 位无符号 (CV_8U) 图像。
  • 可以使用此函数保存带 alpha 通道的 BMP 图像。为此，请创建一个 8 位 4 通道 (CV_8UC4) BGRA 图像，确保 alpha 通道是最后一个分量。完全透明的像素的 alpha 值应为 0，而完全不透明的像素的 alpha 值应为 255。OpenCV v4.13.0 或更高版本默认使用 BI_BITFIELDS 压缩。参见 IMWRITE_BMP_COMPRESSION。
• 使用 OpenEXR 编码器，只能保存 32 位浮点 (CV_32F) 图像。可以保存超过 4 个通道。（然后 imread 可以加载它。）
  • 不支持 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 通道是最后一个分量。完全透明的像素的 alpha 值应为 0，而完全不透明的像素的 alpha 值应为 255/65535/1.0。
• 使用 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 通道是最后一个分量。完全透明的像素的 alpha 值应为 0，而完全不透明的像素的 alpha 值应为 255/65535（参见下面的代码示例）。
• 使用 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 通道是最后一个分量。完全透明的像素的 alpha 值应为 0，而完全不透明的像素的 alpha 值应为 255。
  • 由于 GIF 限制为索引颜色格式，因此不支持 8 位单通道图像 (CV_8UC1)。
• 使用 AVIF 编码器，可以保存 8 位无符号 (CV_8U) 和 16 位无符号 (CV_16U) 图像。
  • CV_16U 图像只能保存为 10 位或 12 位（不是 16 位）。参见 IMWRITE_AVIF_DEPTH。
  • 可以使用此函数保存带 alpha 通道的 AVIF 图像。为此，请创建一个 8 位 4 通道 (CV_8UC4) / 16 位 4 通道 (CV_16UC4) BGRA 图像，确保 alpha 通道是最后一个分量。完全透明的像素的 alpha 值应为 0，而完全不透明的像素的 alpha 值应为 255 (8 位) / 1023 (10 位) / 4095 (12 位)（参见下面的代码示例）。

如果不支持图像格式，图像将转换为 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, "Exception converting image to PNG format: %s\n", ex.what());
    }
 
    if (result)
printf("Saved PNG file with alpha data.\n");
    else
printf("ERROR: Can't save PNG file.\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("Multiple files saved in test.tiff\n");
 
    return result ? 0 : 1;
}

参数

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

返回

如果图像成功写入指定文件，则为 true；否则为 false。

imwriteanimation()

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 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()

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	向量，其中包含 metadata 中存储的元数据块类型，用于写入，参见 ImageMetadataType。
metadata	向量的向量或矩阵的向量，其中包含要存储到文件中的元数据块。
params	格式特定参数，编码为对（paramId_1, paramValue_1, paramId_2, paramValue_2, ...）。参见 cv::ImwriteFlags