影像檔案讀寫

主題
	用於影像檔案讀寫的標誌
	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