图像文件读取和写入

模块
	用于图像文件读取和写入的标志
	iOS 胶水
	MacOS(OSX) 胶水

详细描述

类
类	cv::ImageCollection
	按需读取多页图像。 更多...

函数
CV_EXPORTS_W bool	cv::haveImageReader (const String &filename)
	如果 OpenCV 可以解码指定的图像，则返回 true。
CV_EXPORTS_W bool	cv::haveImageWriter (const String &filename)
	如果 OpenCV 可以使用指定的文件名对图像进行编码，则返回 true。
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 Mat	cv::imread (const String &filename, int flags=IMREAD_COLOR)
	从文件加载图像。
CV_EXPORTS_W void	cv::imread (const String &filename, OutputArray dst, int flags=IMREAD_COLOR)
	从文件加载图像。
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 >())
	将图像保存到指定的文件。
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	) ->	retval

#include <opencv2/imgcodecs.hpp>

如果 OpenCV 可以解码指定的图像，则返回 true。

参数

filename

图像的文件名

haveImageWriter()

CV_EXPORTS_W bool cv::haveImageWriter

(

const String &

filename

)

Python
	cv.haveImageWriter(	filename	) ->	retval

#include <opencv2/imgcodecs.hpp>

如果 OpenCV 可以使用指定的文件名对图像进行编码，则返回 true。

参数

filename

图像的文件名

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 函数将返回多页图像中的页数，对于单页图像返回 1

参数

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

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 缓冲区。

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。

imread() [1/2]

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

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

#include <opencv2/imgcodecs.hpp>

从文件加载图像。

imread 函数从指定文件加载图像并返回图像。如果图像无法读取（由于文件丢失、权限不足、格式不支持或格式无效），则函数将返回一个空矩阵（Mat::data==NULL）。

目前，支持以下文件格式

• Windows 位图 - *.bmp, *.dib（始终支持）
• 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* 操作系统和 MacOSX* 上，默认情况下使用与 OpenCV 图像一起提供的编解码器（libjpeg、libpng、libtiff 和 libjasper）。因此，OpenCV 始终可以读取 JPEG、PNG 和 TIFF。在 MacOSX 上，还有一个选项可以使用本机 MacOSX 图像读取器。但要注意，目前这些本机图像加载器由于嵌入到 MacOSX 中的颜色管理而提供具有不同像素值的图像。
• 在 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 设置限制。

参数

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

imread() [2/2]

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

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

#include <opencv2/imgcodecs.hpp>

从文件加载图像。

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

参数

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

注意

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

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]	) ->	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）图像。
• 使用 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）、16 位无符号（CV_16U）、32 位浮点（CV_32F）和 64 位浮点（CV_64F）图像。
  • 可以将多个图像（Mat 的向量）以 TIFF 格式保存（参见下面的代码示例）。
  • 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, "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

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>

用于绑定的多图像重载

以下是此函数的调用图