图像文件读取和写入

主题
	用于图像文件读取和写入的标志
	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::imdecodemulti (InputArray buf, int flags, CV_OUT std::vector< Mat > &mats, const cv::Range &range=Range::all())
	从内存缓冲区读取多页图像。
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::imencodemulti (const String &ext, InputArrayOfArrays imgs, 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 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 >())
	绑定库的多图像重载

函数文档

haveImageReader()

CV_EXPORTS_W bool cv::haveImageReader

(

const String &

filename

)

Python
	cv.haveImageReader(	filename	) ->	返回值

#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	) ->	返回值

#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]	) ->	返回值

#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	) ->	返回值

#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	) ->	返回值

#include <opencv2/imgcodecs.hpp>

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

参数

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

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	页面的连续选择。

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。

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。

imread() [1/2]

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

Python
	cv.imread(	filename[, flags]	) ->	返回值
	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]	) ->	返回值
	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

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]	) ->	返回值

#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 位（或 16 位、32 位浮点数）4 通道图像 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 位（或 16 位）4 通道图像 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) 图像。
  • 可以以 TIFF 格式保存多个图像（Mat 向量）（参见下面的代码示例）。
  • 32 位浮点数 3 通道 (CV_32FC3) TIFF 图像将使用 LogLuv 高动态范围编码保存（每个像素 4 字节）。

如果不支持图像格式，则图像将转换为 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]	) ->	返回值

#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]	) ->	返回值

#include <opencv2/imgcodecs.hpp>

绑定库的多图像重载

此函数的调用图如下所示