主題
	用於影像檔案讀取與寫入的旗標（Flags）

	iOS 黏合程式碼

	MacOS (OSX) 黏合程式碼

詳細描述

類別
struct	cv::Animation
	表示具有多個影格的動畫。`Animation` 結構旨在儲存與管理動畫序列的數據，例如來自動畫格式（如 GIF、AVIF、APNG、WebP）的數據。它提供對迴圈、背景顏色設定、影格計時及影格儲存的支援。更多...

class	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 >())
	將影像連同元數據儲存至指定的檔案。

函式文件

◆ haveImageReader()

bool cv::haveImageReader ( const String & filename )

Python
	cv.haveImageReader(	filename	) ->	retval

#include <opencv2/imgcodecs.hpp>

檢查指定的影像檔案是否可由 OpenCV 解碼。

haveImageReader 函式會檢查 OpenCV 是否有能力讀取指定的檔案。在嘗試載入影像前，這對於驗證是否支援特定影像格式相當有用。

參數

filename 要檢查的檔案名稱。

回傳值: 若指定的檔案有可用的影像讀取器且檔案可開啟，則回傳 true，否則回傳 false。

備註: 此函式會檢查影像編解碼器（codecs）的可用性，這些編解碼器可以是內建於 OpenCV 或動態載入的。它不會載入影像編解碼器實作並解碼資料，而是使用簽章（signature）檢查。如果檔案無法開啟或格式不支援，函式將回傳 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。

備註: 此函式會檢查影像編解碼器的可用性。它不會檢查檔案實際是否存在，而是檢查寫入該類型檔案的能力。

參見: 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。
計數	欲載入的幀數。此為選擇性參數，預設為 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	儲存檢索到之詮釋資料的向量之向量（vector of vectors）或矩陣向量。
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 bitmaps - *.bmp, *.dib (永遠支援)
GIF files - *.gif (永遠支援)
JPEG files - *.jpeg, *.jpg, *.jpe (請見注意章節)
JPEG 2000 files - *.jp2 (請見注意章節)
Portable Network Graphics - *.png (請見注意章節)
WebP - *.webp (請見注意章節)
AVIF - *.avif (請見注意章節)
Portable image format - *.pbm, *.pgm, *.ppm, *.pxm, *.pnm (永遠支援)
PFM files - *.pfm (請見注意章節)
Sun rasters - *.sr, *.ras (永遠支援)
TIFF files - *.tiff, *.tif (請見注意章節)
OpenEXR Image files - *.exr (請見注意章節)
Radiance HDR - *.hdr, *.pic (永遠支援)
GDAL 支援的點陣與向量地理空間資料 (請見注意章節)

備註

函式會根據影像的內容而非副檔名來判斷影像類型。
若是彩色影像，解碼後的影像通道將以 B G R 順序儲存。
當使用 IMREAD_GRAYSCALE 時，若可用，將使用編解碼器內部的灰階轉換。結果可能與 cvtColor() 的輸出有所不同。
在 Microsoft Windows* 與 Mac OS* 上，預設使用 OpenCV 隨附的編解碼器（libjpeg, libpng, libtiff 以及 libjasper）。因此，OpenCV 永遠可以讀取 JPEGs, PNGs 與 TIFFs。在 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 驅動程式來解碼影像，並支援 Raster 與 Vector 格式。
如果影像檔案中嵌入了 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。
計數	欲載入的幀數。此為選擇性參數，預設為 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	計數,
		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	欲載入影像的起始索引
計數	欲載入影像的計數
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 (constcv::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。

回傳值若影像成功寫入指定檔案，則回傳 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>
用於綁定的多影像過載
這是此函式的呼叫圖
<p><b>此瀏覽器無法顯示 SVG：請改用 Firefox, Chrome, Safari 或 Opera。</b></p>
◆ 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。

此頁面於 Wed Dec 31 2025 07:26:22 由   1.12.0 為 OpenCV 生成

filename	檔案名稱。
img	(Mat 或 Mat 向量) 欲儲存的影像。
params	以配對方式 (paramId_1, paramValue_1, paramId_2, paramValue_2, ...) 編碼的格式特定參數，請參見 cv::ImwriteFlags。

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

filename	欲儲存動畫的檔案名稱。副檔名決定了格式。
animation	包含欲儲存之幀與詮釋資料的 Animation 結構之常數參考。
params	以配對方式 (paramId_1, paramValue_1, paramId_2, paramValue_2, ...) 編碼的格式特定參數。這些參數用於指定編碼過程的額外選項。詳細參數請參考 `cv::ImwriteFlags`。

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

filename	檔案名稱。與 imwrite 一樣，影像格式由副檔名決定。
img	(Mat 或 Mat 向量) 欲儲存的影像。
metadataTypes	儲存於 metadata 中欲寫入的詮釋資料區塊型別向量，請參見 ImageMetadataType。
metadata	包含欲寫入檔案之詮釋資料區塊的向量之向量或矩陣向量。
params	以配對方式 (paramId_1, paramValue_1, paramId_2, paramValue_2, ...) 編碼的格式特定參數，請參見 cv::ImwriteFlags。

主題

詳細描述

類別

函式

函式文件

◆ haveImageReader()

◆ haveImageWriter()

◆ imcount()

◆ imdecode() [1/2]

◆ imdecode() [2/2]

◆ imdecodeanimation()

◆ imdecodemulti()

◆ imdecodeWithMetadata()

◆ imencode()

◆ imencodeanimation()

◆ imencodemulti()

◆ imencodeWithMetadata()

◆ imread() [1/2]

◆ imread() [2/2]

◆ imreadanimation()

◆ imreadmulti() [1/2]

◆ imreadmulti() [2/2]

◆ imreadWithMetadata()

◆ imwrite()

◆ imwriteanimation()

◆ imwritemulti()

◆ imwriteWithMetadata()