画像ファイルの読み込みと書き込み

トピック
	画像ファイルの読み書きに使用するフラグ
	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_COLOR_BGR)
	指定したファイル内に含まれる画像の枚数を返す。
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)
	メモリバッファから画像を読み込み、関連するメタデータを抽出する。
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_COLOR_BGR)
	ファイルからマルチページ画像を読み込む。
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)
	関連するメタデータとともにファイルから画像を読み込む。
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。

覚え書き

この関数は、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_COLOR_BGR )

Python:
	cv.imcount(	filename[, flags]	) ->	retval

#include <opencv2/imgcodecs.hpp>

指定したファイル内の画像数を返す。

imcount 関数は、マルチページ画像（例: TIFF）の場合はページ数を、アニメーション（例: AVIF）の場合はフレーム数を、それ以外の場合は1を返す。画像をデコードできない場合は0を返す。

引数

filename	読み込むファイルの名前。
flags	cv::ImreadModes の値を取りうるフラグ。デフォルトは cv::IMREAD_COLOR_BGR。

覚え書き

デフォルトのフラグ値は、統一のため cv::IMREAD_ANYCOLOR から cv::IMREAD_COLOR_BGR に変更された。

TODOTodo

cv::IMREAD_LOAD_GDAL フラグを使用した場合、OpenCV の GDAL デコーダがまだマルチページ読み込みをサポートしていないため、戻り値は0または1になる。

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 )

Python:
	cv.imdecodeWithMetadata(	buf, flags[, metadata]	) ->	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::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 (覚え書き セクションを参照)
• Portable Network Graphics - *.png (覚え書き セクションを参照)
• WebP - *.webp (覚え書き セクションを参照)
• AVIF - *.avif (覚え書き セクションを参照)
• Portable image format - *.pbm, *.pgm, *.ppm, *.pxm, *.pnm (常にサポートされている)
• PFMファイル - *.pfm (覚え書き セクションを参照)
• Sun rasters - *.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系オープンソースOSでは、OpenCVはOS付属のコーデックを探す。コーデックのサポートを得るには、関連パッケージ (Debian* や Ubuntu* における "libjpeg-dev" などの開発用ファイルを含む) がインストールされていることを確認するか、CMakeでOPENCV_BUILD_3RDPARTY_LIBSフラグを有効にすること。
• CMakeで WITH_GDAL フラグがtrueに設定され、画像の読み込みに IMREAD_LOAD_GDAL が使用されている場合、画像のデコードに GDAL ドライバが使用され、ラスタ および ベクトル 形式がサポートされる。
• 画像ファイルにEXIF情報が埋め込まれている場合、EXIFの向きが考慮され、フラグ IMREAD_IGNORE_ORIENTATION または IMREAD_UNCHANGED が渡されない限り、それに応じて画像が回転される。
• PFM画像の浮動小数点値を保持するには、IMREAD_UNCHANGEDフラグを使用すること。
• デフォルトでは、ピクセル数は 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_COLOR_BGR )

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_COLOR_BGR。

覚え書き

デフォルトのフラグ値は、統一のため cv::IMREAD_ANYCOLOR から cv::IMREAD_COLOR_BGR に変更された。

参照

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 )

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

#include <opencv2/imgcodecs.hpp>

ファイルから関連するメタデータとともに画像を読み込む。

この関数は cv::imread() と同様に動作し、指定されたファイルから画像を読み込む。画像のピクセルデータに加えて、ファイル形式のサポートに応じて、ファイルに埋め込まれた利用可能なメタデータ (EXIF、XMPなど) の抽出も試みる。

覚え書き

カラー画像の場合、デコードされた画像のチャンネルは B G R の順で格納される。

引数

filename	読み込むファイルの名前。
metadataTypes	metadata で返されるメタデータチャンクの型を格納する出力ベクトル。ImageMetadataType を参照。
metadata	取得したメタデータを格納する、ベクトルのベクトルまたは行列のベクトル。
flags	cv::ImreadModes の値を取りうるフラグ。

戻り値

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' チャンネル順) 画像のみであるが、以下の例外がある:

• With BMP encoder, 8-bit unsigned (CV_8U) images can be saved.
  • アルファチャンネルを持つBMP画像はこの関数で保存できる。これを行うには、8ビット4チャンネル (CV_8UC4) のBGRA画像を作成し、アルファチャンネルが最後のコンポーネントになるようにする。完全に透明なピクセルはアルファ値を0に、完全に不透明なピクセルはアルファ値を255にする。OpenCV v4.13.0以降ではデフォルトでBI_BITFIELDS圧縮を使用する。IMWRITE_BMP_COMPRESSIONを参照。
• With OpenEXR encoder, only 32-bit float (CV_32F) images can be saved. More than 4 channels can be saved. (imread can load it then.)
  • 8ビット符号なし (CV_8U) 画像はサポートされていない。
• With Radiance HDR encoder, non 64-bit float (CV_64F) images can be saved.
  • すべての画像が32ビット浮動小数点 (CV_32F) に変換される。
• JPEG 2000エンコーダでは、8ビット符号なし (CV_8U) および16ビット符号なし (CV_16U) 画像を保存できる。
• With JPEG XL encoder, 8-bit unsigned (CV_8U), 16-bit unsigned (CV_16U) and 32-bit float(CV_32F) images can be saved.
  • アルファチャンネルを持つJPEG XL画像はこの関数で保存できる。これを行うには、8ビット4チャンネル (CV_8UC4) / 16ビット4チャンネル (CV_16UC4) / 32ビット浮動小数点4チャンネル (CV_32FC4) のBGRA画像を作成し、アルファチャンネルが最後のコンポーネントになるようにする。完全に透明なピクセルはアルファ値を0に、完全に不透明なピクセルはアルファ値を255/65535/1.0にする。
• PAMエンコーダでは、8ビット符号なし (CV_8U) および16ビット符号なし (CV_16U) 画像を保存できる。
• With PNG encoder, 8-bit unsigned (CV_8U) and 16-bit unsigned (CV_16U) images can be saved.
  • アルファチャンネルを持つPNG画像はこの関数で保存できる。これを行うには、8ビット4チャンネル (CV_8UC4) / 16ビット4チャンネル (CV_16UC4) のBGRA画像を作成し、アルファチャンネルが最後のコンポーネントになるようにする。完全に透明なピクセルはアルファ値を0に、完全に不透明なピクセルはアルファ値を255/65535にする (下記のコードサンプルを参照)。
• PGM/PPMエンコーダでは、8ビット符号なし (CV_8U) および16ビット符号なし (CV_16U) 画像を保存できる。
• With TIFF encoder, 8-bit unsigned (CV_8U), 8-bit signed (CV_8S), 16-bit unsigned (CV_16U), 16-bit signed (CV_16S), 32-bit unsigned (CV_32U), 32-bit signed (CV_32S), 64-bit unsigned (CV_64U), 64-bit signed (CV_64S), 32-bit float (CV_32F) and 64-bit float (CV_64F) images can be saved.
  • 複数の画像（Mat のベクトル）を TIFF 形式で保存できる（下のコードサンプルを参照）。
  • 32ビット浮動小数点3チャンネル（CV_32FC3）の TIFF 画像は、TIFF_COMPRESSION_SGILOG による LogLuv 高ダイナミックレンジエンコーディング（1ピクセルあたり4バイト）、または TIFF_COMPRESSION_SGILOG24（1ピクセルあたり3バイト）を使って保存できる。
  • 他の圧縮方式（LZW など）も32Fビット深度でサポートされているが、浮動小数点表現のビットパターンに対しては効率があまり良くない場合がある。
• With GIF encoder, 8-bit unsigned (CV_8U) images can be saved.
  • アルファチャンネルを持つGIF画像はこの関数で保存できる。これを行うには、8ビット4チャンネル (CV_8UC4) のBGRA画像を作成し、アルファチャンネルが最後のコンポーネントになるようにする。完全に透明なピクセルはアルファ値を0に、完全に不透明なピクセルはアルファ値を255にする。
  • 8ビットシングルチャンネル画像 (CV_8UC1) は、GIFがインデックスカラー形式に制限されているためサポートされていない。
• With AVIF encoder, 8-bit unsigned (CV_8U) and 16-bit unsigned (CV_16U) images can be saved.
  • CV_16U画像は10ビットまたは12ビットでのみ保存できる (16ビットでは不可)。IMWRITE_AVIF_DEPTHを参照。
  • アルファチャンネルを持つAVIF画像はこの関数で保存できる。これを行うには、8ビット4チャンネル (CV_8UC4) / 16ビット4チャンネル (CV_16UC4) のBGRA画像を作成し、アルファチャンネルが最後のコンポーネントになるようにする。完全に透明なピクセルはアルファ値を0に、完全に不透明なピクセルはアルファ値を255 (8ビット) / 1023 (10ビット) / 4095 (12ビット) にする (下記のコードサンプルを参照)。

画像形式がサポートされていない場合、画像は8ビット符号なし (CV_8U) に変換されてその形式で保存される。

形式、ビット深度、またはチャンネル順が異なる場合は、保存する前に Mat::convertTo や cv::cvtColor を使って変換すること。あるいは、汎用の FileStorage 入出力関数を使って画像を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; // Blue
            bgra[1] = saturate_cast<uchar>((float (mat.cols - j)) / ((float)mat.cols) * UCHAR_MAX); // Green
            bgra[2] = saturate_cast<uchar>((float (mat.rows - i)) / ((float)mat.rows) * UCHAR_MAX); // Red
            bgra[3] = saturate_cast<uchar>(0.5 * (bgra[1] + bgra[2])); // Alpha
        }
    }
}
 
int main()
{
 Mat mat(480, 640, CV_8UC4); // Create a matrix with alpha channel
    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 を参照