CXCORE リファレンスマニュアル

最終変更者: 怡土順一, 最終変更リビジョン: 448, 最終変更日時: 2008-12-24 00:28:23 +0900 (水, 24 12月 2008)

基本構造体（Basic Structures）
配列操作（Operations on Arrays）
動的構造体（Dynamic Structures）
描画関数（Drawing Functions）
データ永続性と実行時型情報（Data Persistence and RTTI）
その他の関数（Miscellaneous Functions）
エラーハンドリングとシステム関数（Error Handling and System Functions）
- エラーハンドリング（Error Handling）
- システム関数（System Functions）

配列操作（Operations on Arrays）

初期化（Initialization）

CreateImage

ヘッダの作成とデータ領域の確保

IplImage* cvCreateImage( CvSize size, int depth, int channels );

size: 画像の幅と高さ．
depth: 画像要素のビットデプス．以下の内のいずれか．
IPL_DEPTH_8U - 符号無し 8 ビット整数
IPL_DEPTH_8S - 符号有り 8 ビット整数
IPL_DEPTH_16U - 符号無し 16 ビット整数
IPL_DEPTH_16S - 符号有り 16 ビット整数
IPL_DEPTH_32S - 符号有り 32 ビット整数
IPL_DEPTH_32F - 単精度浮動小数点数
IPL_DEPTH_64F - 倍精度浮動小数点数
channels: 要素（ピクセル）毎のチャンネル数．1, 2, 3, 4 のいずれか．このチャンネルはインタリーブされる．例えば，通常のカラー画像のデータレイアウトは，
b0 g0 r0 b1 g1 r1 ...
となっている．一般的な IPL 画像フォーマットはノンインタリーブ画像を格納することができ，これを処理することができる OpenCV の関数も存在するが，この関数はインタリーブ画像しか作成できない．

関数 cvCreateImage はヘッダを作成し，データ領域を確保する．これは，以下の形式を短縮したものである．

    header = cvCreateImageHeader(size,depth,channels);
    cvCreateData(header);

CreateImageHeader

メモリ確保と初期化を行い，IplImage 構造体を返す

IplImage* cvCreateImageHeader( CvSize size, int depth, int channels );

size: 画像の幅と高さ．
depth: 画像のカラーデプス（CreateImage を参照）．
channels: チャンネル数（CreateImage を参照）．

関数 cvCreateImageHeader は，メモリ確保と初期化を行い， IplImage 構造体を返す．これは，

  iplCreateImageHeader( channels, 0, depth,
                        channels == 1 ? "GRAY" : "RGB",
                        channels == 1 ? "GRAY" : channels == 3 ? "BGR" :
                        channels == 4 ? "BGRA" : "",
                        IPL_DATA_ORDER_PIXEL, IPL_ORIGIN_TL, 4,
                        size.width, size.height,
                        0,0,0,0);

と似ているが，この関数はデフォルトでは IPL の関数を用いない（マクロ CV_TURN_ON_IPL_COMPATIBILITY も参照すること）．

ReleaseImageHeader

ヘッダを解放する

void cvReleaseImageHeader( IplImage** image );

image: 確保したヘッダへのポインタのポインタ．

関数 cvReleaseImageHeader は，ヘッダを解放する．これは，

    if( image )
    {
        iplDeallocate( *image, IPL_IMAGE_HEADER | IPL_IMAGE_ROI );
        *image = 0;
    }

と似ているが，この関数はデフォルトでは IPL の関数を用いない（マクロ CV_TURN_ON_IPL_COMPATIBILITY も参照すること）．

ReleaseImage

ヘッダと画像データを解放する

void cvReleaseImage( IplImage** image );

image: 確保した画像ヘッダへのポインタのポインタ．

関数 cvReleaseImage は，ヘッダと画像データを解放する．これは，以下の形式を短縮したものである．

    if( *image )
    {
        cvReleaseData( *image );
        cvReleaseImageHeader( image );
    }

InitImageHeader

ユーザによって確保された画像ヘッダを初期化する

IplImage* cvInitImageHeader( IplImage* image, CvSize size, int depth,
                             int channels, int origin=0, int align=4 );

image: 初期化される画像ヘッダ．
size: 画像の幅と高さ．
depth: 画像のカラーデプス（CreateImage を参照）．
channels: チャンネル数（CreateImage を参照）．
origin: IPL_ORIGIN_TL または IPL_ORIGIN_BL．
align: 画像の行のアライメント，通常は4，あるいは 8 バイト．

関数 cvInitImageHeader は，ユーザから渡されたポインタが指す画像のヘッダ構造体を初期化し，そのポインタを返す．

CloneImage

画像の完全なコピーを作成する

IplImage* cvCloneImage( const IplImage* image );

image: オリジナル画像．

関数 cvCloneImage は，ヘッダ，ROI，データを含む画像の完全なコピーを作成する．

SetImageCOI

与えられた値を channel of interest（COI）としてセットする

void cvSetImageCOI( IplImage* image, int coi );

image: 画像ヘッダ．
coi: COI（Channel of interest）．

関数 cvSetImageCOI は，与えられた値を COI（channel of interest）としてセットする．値 0 は全てのチャンネルが選択されている事を意味し，値 1 は最初のチャンネルが選択されている事を意味する．もしCOI が NULL かつ，パラメータが coi != 0 の場合には，COI が確保される． OpenCV の関数の多くは COI をサポートしていないことに注意すること．別々の画像/行列チャンネルを処理するには，（cvCopy や cvSplit によって）別々の画像/行列へチャンネルをコピーし，それを処理してから，必要ならばその結果を（cvCopy や cvCvtPlaneToPix によって）もう一度コピーし直して返す．

GetImageCOI

COI のインデックスを戻す

int cvGetImageCOI( const IplImage* image );

image: 画像ヘッダ．

関数 cvGetImageCOI は，画像の COI（channel of interest）を返す（全チャンネルが選択される場合には，0 が返される）．

SetImageROI

与えられた矩形を画像の ROI としてセットする

void cvSetImageROI( IplImage* image, CvRect rect );

image: 画像ヘッダ．
rect: ROI を表す矩形．

関数 cvSetImageROI は，与えられた矩形を画像の ROI としてセットする．もし，ROI が NULL で，パラメータ rect の値が画像全体ではない場合には，ROI が確保される． COI とは異なり，OpenCV の関数の多くが ROI をサポートしている．そして，ROI はある意味，別の画像として扱われる（例えば，全てのピクセル座標は ROI の左上あるいは左下（画像の原点に依存）からカウントされる）．

ResetImageROI

画像の ROI を解放する

void cvResetImageROI( IplImage* image );

image: 画像ヘッダ．

関数 cvResetImageROI は，画像の ROI を解放する．解放後は全画像が選択されている状態と同じになる．以下のようにしても，同じように全選択ができるが，この方法では image->roi は解放されない．

cvSetImageROI( image, cvRect( 0, 0, image->width, image->height ));
cvSetImageCOI( image, 0 );

GetImageROI

画像の ROI 座標を返す

CvRect cvGetImageROI( const IplImage* image );

image: 画像ヘッダ．

関数 cvGetImageROI は，画像の ROI 座標を返す． ROI が存在しない場合には，矩形 cvRect(0,0,image->width,image->height) が返される．

CreateMat

新たな行列を作成する

CvMat* cvCreateMat( int rows, int cols, int type );

rows: 行列の行数．
cols: 行列の列数．
type: 行列要素の種類．通常，次のような指定形式になる． CV_<bit_depth>(S|U|F)C<number_of_channels>．例えば，
CV_8UC1 は，符号無し 8 ビット 1 チャンネル行列， CV_32SC2 は，符号有り 32 ビット 2 チャンネル行列を意味する．

関数 cvCreateMat は，新たな行列とその内部データのためのヘッダを確保し，作成された行列へのポインタを返す．これは以下の省略形である．

    CvMat* mat = cvCreateMatHeader( rows, cols, type );
    cvCreateData( mat );

行列は行単位で保存され，すべての行は4バイトでアライメントされる．

CreateMatHeader

新たな行列のヘッダを作成する

CvMat* cvCreateMatHeader( int rows, int cols, int type );

rows: 行列の行数．
cols: 行列の列数．
type: 行列要素の種類（cvCreateMatを参照）．

関数 cvCreateMatHeaderは，新たな行列のヘッダを作成し，そのポインタを返す．さらに，cvCreateData を用いるか，cvSetData により，ユーザが確保したデータ領域を明示的にセットすることで，行列データが確保される．

ReleaseMat

行列を解放する

void cvReleaseMat( CvMat** mat );

mat: 行列へのポインタのポインタ．

関数 cvReleaseMat は，行列データの参照カウンタをデクリメントして，行列ヘッダを解放する．

    if( *mat )
        cvDecRefData( *mat );
    cvFree( (void**)mat );

InitMatHeader

行列ヘッダを初期化する

CvMat* cvInitMatHeader( CvMat* mat, int rows, int cols, int type,
                        void* data=NULL, int step=CV_AUTOSTEP );

mat: 初期化する行列のヘッダへのポインタ．
rows: 行列の行数．
cols: 行列の列数．
type: 行列要素の種類．
data: 行列のヘッダで指定されるデータへのポインタ（オプション）．
step: 割り当てられたデータの行長をバイト単位で表す．デフォルトでは，stepには可能な限り小さい値が用いられる．つまり，行列の連続する行間にギャップが存在しない．

関数 cvInitMatHeader は，既に確保された構造体 CvMat を初期化する．これは，OpenCV の行列関数で生データを処理するために用いることもできる．

例えば，以下のコードは二つの行列の積を計算し，通常の行列として格納する．

二つの行列の積の計算

   double a[] = { 1, 2, 3, 4,
                  5, 6, 7, 8,
                  9, 10, 11, 12 };

   double b[] = { 1, 5, 9,
                  2, 6, 10,
                  3, 7, 11,
                  4, 8, 12 };

   double c[9];
   CvMat Ma, Mb, Mc ;

   cvInitMatHeader( &Ma, 3, 4, CV_64FC1, a );
   cvInitMatHeader( &Mb, 4, 3, CV_64FC1, b );
   cvInitMatHeader( &Mc, 3, 3, CV_64FC1, c );

   cvMatMulAdd( &Ma, &Mb, 0, &Mc );
   // この行列 c には，行列 a(3×4) と 行列 b(4×3) の積が入っている

Mat

行列ヘッダを初期化する（軽量版）

CvMat cvMat( int rows, int cols, int type, void* data=NULL );

rows: 行列の行数．
cols: 行列の列数．
type: 行列要素の種類（CreateMat を参照）．
data: 行列のヘッダで指定されるデータへのポインタ（オプション）．

関数 cvMat は， cvInitMatHeader の高速なインライン置換である．つまり，これは以下と等価である．

     CvMat mat;
     cvInitMatHeader( &mat, rows, cols, type, data, CV_AUTOSTEP );

CloneMat

行列のコピーを作成する

CvMat* cvCloneMat( const CvMat* mat );

mat: 入力行列．

関数 cvCloneMat は，入力行列のコピーを作成し，そのポインタを返す．

CreateMatND

多次元の密な配列を作成する

CvMatND* cvCreateMatND( int dims, const int* sizes, int type );

dims: 配列の次元数．CV_MAX_DIM（デフォルトでは32．ビルド時に変更される可能性もある）を超えてはいけない．
sizes: 次元サイズの配列．
type: 配列要素の種類．CvMat のものと同じ．

関数 cvCreateMatND は，多次元の密な配列のヘッダとその内部データを確保し，作成された配列のポインタを返す．これは以下の省略形である．

    CvMatND* mat = cvCreateMatNDHeader( dims, sizes, type );
    cvCreateData( mat );

配列データは行単位で保存される．全ての行は4バイトでアライメントされる．

CreateMatNDHeader

新たな行列のヘッダを作成する

CvMatND* cvCreateMatNDHeader( int dims, const int* sizes, int type );

dims: 配列の次元数．
sizes: 次元サイズの配列．
type: 配列要素の種類．CvMat のものと同じ．

関数 cvCreateMatND は，多次元の密な配列のヘッダを確保する．さらに，cvCreateData を用いるか， cvSetData により，ユーザが確保したデータ領域を明示的にセットすることで，配列データが確保される．

ReleaseMatND

多次元配列を解放する

void cvReleaseMatND( CvMatND** mat );

mat: 配列へのポインタのポインタ．

関数 cvReleaseMatND は，配列データの参照カウンタをデクリメントして，配列ヘッダを解放する．

    if( *mat )
        cvDecRefData( *mat );
    cvFree( (void**)mat );

InitMatNDHeader

多次元配列のヘッダを初期化する

CvMatND* cvInitMatNDHeader( CvMatND* mat, int dims, const int* sizes, int type, void* data=NULL );

mat: 初期化する配列のヘッダへのポインタ．
dims: 配列の次元数．
sizes: 次元サイズの配列．
type: 配列要素の種類．CvMat のものと同じ．
data: 行列のヘッダで指定されるデータへのポインタ（オプション）．

関数 cvInitMatNDHeader は，ユーザによって確保された構造体 CvMatND を初期化する．

CloneMatND

多次元配列の完全なコピーを作成する

CvMatND* cvCloneMatND( const CvMatND* mat );

mat: 入力配列．

関数 cvCloneMatND は，入力配列のコピーを作成し，そのポインタを返す．

DecRefData

配列データの参照カウンタをデクリメントする

void cvDecRefData( CvArr* arr );

arr: 配列ヘッダ．

関数 cvDecRefData は，参照カウンタのポインタが NULL ではない場合に CvMat あるいは CvMatND のデータの参照カウンタをデクリメントし，さらにカウンタが 0 になった場合にはデータを解放する．現在の実装では，データが関数 cvCreateData によって確保された場合にのみ，参照カウンタは NULL ではなくなる．その他の場合として，以下のものがある．
cvSetData によって，外部データがヘッダに割り当てられた．
行列ヘッダが，より大きな行列あるいは画像の一部になっている．
行列ヘッダが，画像あるいは n 次元行列ヘッダから変換された．

このような場合，参照カウンタは NULL にセットされ，デクリメントされない．データが解放されるか否かに関わらず，データポインタと参照カウンタポインタはこの関数によってクリアされる．

IncRefData

配列データの参照カウンタをインクリメントする

int cvIncRefData( CvArr* arr );

arr: 配列ヘッダ．

関数 cvIncRefData は，参照カウンタポインタが NULL ではない場合に， CvMat あるいは CvMatND のデータの参照カウンタをインクリメントし，新たなカウンタ値を返す．そうでない場合は 0 を返す．

CreateData

配列データを確保する

void cvCreateData( CvArr* arr );

arr: 配列ヘッダ．

関数 cvCreateData は，画像，行列あるいは多次元配列のデータを確保する．行列の場合は OpenCV の確保関数が用いられる．IplImage の場合も OpenCV の関数が用いられる．ただし，CV_TURN_ON_IPL_COMPATIBILITY が呼ばれた場合は例外的に，データを確保するために IPL 関数が用いられる．

ReleaseData

配列データを解放する

void cvReleaseData( CvArr* arr );

arr: 配列ヘッダ．

関数 cvReleaseData は，配列データを解放する． CvMat あるいは CvMatND の場合，これは単に cvDecRefData() を呼ぶだけである．つまり，この関数は外部データを解放することができない． cvCreateData の注意事項も参照すること．

SetData

ユーザデータを配列ヘッダに割り当てる

void cvSetData( CvArr* arr, void* data, int step );

arr: 配列ヘッダ．
data: ユーザデータ．
step: バイト単位で表された行の長さ．

関数 cvSetData は，ユーザデータを配列のヘッダに割り当てる．ヘッダは，関数 cvCreate*Header，関数 cvInit*Header あるいは関数 cvMat（行列の場合）を用いて，あらかじめ初期化されるべきである．

GetRawData

配列の低レベル情報を取り出す

void cvGetRawData( const CvArr* arr, uchar** data,
                   int* step=NULL, CvSize* roi_size=NULL );

arr: 配列ヘッダ．
data: 出力である全画像の原点へのポインタ，あるいは ROI が設定されている場合は ROI の原点へのポインタ．
step: 出力であるバイト単位で表された行の長さ．
roi_size: 出力であるROI サイズ．

関数 cvGetRawData は，配列データに関する低レベル情報を変数に出力する．すべての出力パラメータは任意であり，いくつかのポインタは NULL にセットされる場合がある．配列が ROI をもつ IplImage である場合，ROI のパラメータが返される．

以下に，この関数を用いて配列の要素にアクセスする例を示す．

GetRawData を用いて，シングルチャンネル浮動小数点型数配列の要素の絶対値を計算する．

    float* data;
    int step;

    CvSize size;
    int x, y;

    cvGetRawData( array, (uchar**)&data, &step, &size );
    step /= sizeof(data[0]);

    for( y = 0; y < size.height; y++, data += step )
        for( x = 0; x < size.width; x++ )
            data[x] = (float)fabs(data[x]);

GetMat

任意の配列に対する行列ヘッダを返す

CvMat* cvGetMat( const CvArr* arr, CvMat* header, int* coi=NULL, int allowND=0 );

arr: 入力配列．
header: テンポラリバッファとして用いられる構造体 CvMat へのポインタ．
coi: COIを記憶するための，オプションの出力パラメータ．
allowND: これが 0 でない場合，この関数は多次元の密な配列（CvMatND*）を扱うことが可能で， 2次元行列（CvMatND が2次元の場合）あるいは 1次元行列（CvMatNDが 1次元，あるいは 2次元より大きい場合）を返す．配列は連続でなければならない．

関数 cvGetMat は，入力配列に対する行列ヘッダを返す．入力配列になり得るものは，行列 - CvMat，画像 - IplImage あるいは，多次元の密な配列 - CvMatND*（最後の例は，allowND != 0 の場合のみ）である．行列の場合，この関数は単に入力ポインタを返す． IplImage* あるいは CvMatND* の場合は，現在の画像の ROI のパラメータで構造体 header を初期化し，このテンポラリ構造体へのポインタを返す． COI は CvMat ではサポートされないので，これは別に返される．

この関数は，同じコードで 2種類の配列 - IplImage および CvMat - を扱う簡単な方法を提供する．関数 cvGetImage によって，CvMat から IplImage への逆変換が可能である．

入力配列は，確保あるいは添付された内部データを持たなければならず，そうでない場合は，この関数は失敗する．

入力配列が，平面（二次元）データレイアウトおよび COI を持つ IplImage の場合，この関数は選択された平面へのポインタおよび COI = 0 を返す． OpenCV の関数を用いて，平面データレイアウトを持つマルチチャンネル画像を平面毎に処理する事が可能である．

GetImage

任意の配列に対する画像ヘッダを返す

IplImage* cvGetImage( const CvArr* arr, IplImage* image_header );

arr: 入力配列．
image_header: テンポラリバッファとして用いられる構造体 IplImage へのポインタ．

関数 cvGetImage は，入力配列，行列 - CvMat*，画像 - IplImage*，に対する画像ヘッダを返す．画像の場合は，この関数は単に入力ポインタを返す．CvMat* の場合は，入力行列のパラメータで構造体 image_header を初期化する． ROI がセットされている場合，IplImage から CvMat へ変換した後に，その CvMat から IplImage に戻すと，異なったヘッダになる可能性がある．従って，画像の長さをその幅とアライメントから計算するような IPL 関数は，この関数の結果として得られる画像に対しては失敗する可能性がある．

CreateSparseMat

疎な配列を作成する

CvSparseMat* cvCreateSparseMat( int dims, const int* sizes, int type );

dims: 配列の次元数．密な行列とは逆に，次元数は実質的には無制限である（2¹⁶ まで）．
sizes: 次元サイズの配列．
type: 配列要素の種類．CvMat のものと同じ．

関数 cvCreateSparseMat は，多次元の疎な配列を確保する．初期状態では配列は要素を持たない．つまり，cvGet*D あるいは cvGetReal*D は，全インデックスに対して 0 を返す．

ReleaseSparseMat

疎な配列を解放する

void cvReleaseSparseMat( CvSparseMat** mat );

mat: 配列へのポインタのポインタ．

関数 cvReleaseSparseMat は，疎な配列を解放し，終了時に配列ポインタをクリアする．

CloneSparseMat

疎な配列の完全なコピーを作成する

CvSparseMat* cvCloneSparseMat( const CvSparseMat* mat );

mat: 入力配列．

関数 cvCloneSparseMat は，入力配列のコピーを作成し，そのポインタを返す．

CXCORE リファレンス マニュアル

CXCORE リファレンスマニュアル