CXCORE リファレンス マニュアル
- 基本構造体（Basic Structures）
- 配列操作（Operations on Arrays）
- 動的構造体（Dynamic Structures）
- 描画関数（Drawing Functions）
- データ永続性と実行時型情報（Data Persistence and RTTI）
- ファイルストレージ（File Storage）
- データの書き込み（Writing Data）
- データの読み込み（Reading Data）
- 実行時型情報と汎用関数（RTTI and Generic Functions）
- その他の関数（Miscellaneous Functions）
- エラーハンドリングとシステム関数（Error Handling and System Functions）
データ永続性と実行時型情報（Data Persistence and RTTI）
データの読み込み（Reading Data）
データはファイルストレージから二つの段階を経て取り込まれる．まず要求されたデータを含むファイルノードを探索し， その後にそのノードから手動，もしくは特別なreadメソッドを用いて取り込む．
GetRootFileNode
ファイルストレージのトップレベルノードの一つを取り込む
CvFileNode* cvGetRootFileNode( const CvFileStorage* fs, int stream_index=0 );
- fs
- ファイルストレージ．
- stream_index
- 0から始まるストリームのインデックス． cvStartNextStreamを参照． 多くの場合，ファイル中に存在するのは一つのストームであるが，複数にもなり得る．
関数cvGetRootFileNodeは，トップレベルファイルノードの一つを返す． トップレベルノードは名前を持たず，それらはストリームに相当し，ファイルストレージ内に次々と保存されている． インデックスが範囲外の場合，この関数はNULLポインタを返す． この関数にstream_index=0,1,...を順に指定して呼び出し，NULLポインタが返されるまで繰り返すことで， すべてのトップレベルノードを得ることができる．この関数はファイルストレージの再帰的な走査のために使われる．
GetFileNodeByName
マップ内またはファイルストレージ内からノードを探索する
CvFileNode* cvGetFileNodeByName( const CvFileStorage* fs,
const CvFileNode* map,
const char* name );
- fs
- ファイルストレージ．
- map
- 親マップ．NULLの場合，この関数は一番最初のものから開始して，全てのトップレベルノード(ストリーム)内を探索する．
- name
- ファイルノード名．
関数cvGetFileNodeByNameは，nameのファイルノードを探索する． ノードの探索はmap内で行われ，ポインタがNULLであれば，ストレージのトップレベルファイルノードを含めて行なわれる． マップに対してこの関数を，シーケンスに対してcvGetSeqElem （またはシーケンスリーダ）を用いることで，ファイルストレージの走査が可能になる． あるキーに対する複数のクエリを高速に処理する（例えば構造体の配列など）ためには，cvGetHashedKeyと cvGetFileNodeを組み合わせて使うと良い．
GetHashedKey
与えた名前に対するユニークなポインタを返す
CvStringHashNode* cvGetHashedKey( CvFileStorage* fs, const char* name,
int len=-1, int create_missing=0 );
- fs
- ファイルストレージ．
- name
- ノード名．
- len
- 名前の長さ（事前に分かっている場合），または計算する必要がある場合は-1．
- create_missing
- absent keyをハッシュテーブルに追加するかどうかを指定するフラグ．
関数cvGetHashedKeyは，特定のファイルノード名に対する唯一のポインタを返す． このポインタは関数cvGetFileNodeByName より高速な関数cvGetFileNodeに渡すことができる． 後者の関数は文字列の内容を比較するのではなく，ポインタの比較により文字列を比較するためである．
次の例では，点列が二つのエントリを持つマップのシーケンスとして表されている．例えば，
%YAML:1.0
points:
- { x: 10, y: 10 }
- { x: 20, y: 20 }
- { x: 30, y: 30 }
# ...
そこで，ハッシュ化された"x"と"y"のポインタを得ることで，点のデコードを高速化することが可能になる．
（例）ファイルストレージから構造体の配列を読み込む
#include "cxcore.h"
int main( int argc, char** argv )
{
CvFileStorage* fs = cvOpenFileStorage( "points.yml", 0, CV_STORAGE_READ );
CvStringHashNode* x_key = cvGetHashedNode( fs, "x", -1, 1 );
CvStringHashNode* y_key = cvGetHashedNode( fs, "y", -1, 1 );
CvFileNode* points = cvGetFileNodeByName( fs, 0, "points" );
if( CV_NODE_IS_SEQ(points->tag) )
{
CvSeq* seq = points->data.seq;
int i, total = seq->total;
CvSeqReader reader;
cvStartReadSeq( seq, &reader, 0 );
for( i = 0; i < total; i++ )
{
CvFileNode* pt = (CvFileNode*)reader.ptr;
#if 1 /* 高速バージョン */
CvFileNode* xnode = cvGetFileNode( fs, pt, x_key, 0 );
CvFileNode* ynode = cvGetFileNode( fs, pt, y_key, 0 );
assert( xnode && CV_NODE_IS_INT(xnode->tag) &&
ynode && CV_NODE_IS_INT(ynode->tag));
int x = xnode->data.i; // あるいは x = cvReadInt( xnode, 0 );
int y = ynode->data.i; // あるいは y = cvReadInt( ynode, 0 );
#elif 1 /* 低速バージョン．x_keyとy_keyを使わない */
CvFileNode* xnode = cvGetFileNodeByName( fs, pt, "x" );
CvFileNode* ynode = cvGetFileNodeByName( fs, pt, "y" );
assert( xnode && CV_NODE_IS_INT(xnode->tag) &&
ynode && CV_NODE_IS_INT(ynode->tag));
int x = xnode->data.i; // あるいは x = cvReadInt( xnode, 0 );
int y = ynode->data.i; // あるいは y = cvReadInt( ynode, 0 );
#else /* 超低速だが使いやすいバージョン */
int x = cvReadIntByName( fs, pt, "x", 0 /* デフォルト値 */ );
int y = cvReadIntByName( fs, pt, "y", 0 /* デフォルト値 */ );
#endif
CV_NEXT_SEQ_ELEM( seq->elem_size, reader );
printf("%d: (%d, %d)¥n", i, x, y );
}
}
cvReleaseFileStorage( &fs );
return 0;
}
マップヘのアクセス方法に関わらず，単純なシーケンスを使うものに比べて，これはまだかなり低速であることに注意してほしい． 例えば上の例においては，点を一つのシーケンスにおける整数のペアとしてエンコードする方がより効率的である．
GetFileNode
マップまたはファイルストレージ内のノードを見つける
CvFileNode* cvGetFileNode( CvFileStorage* fs, CvFileNode* map,
const CvStringHashNode* key, int create_missing=0 );
- fs
- ファイルストレージ．
- map
- 親マップ．NULLの場合，この関数はトップレベルノードを探す．もしmapとkeyの両方がNULLの場合には， この関数はトップレベルノードを持つマップであるルートファイルノードを返す．
- key
- cvGetHashedKeyで取得されるノード名ヘの唯一のポインタ．
- create_missing
- absent nodeをマップに追加するかどうかを指定するフラグ．
関数cvGetFileNodeは，ファイルノードを見つける． これはcvGetFileNodeByName （cvGetHashedKeyを参照）の高速バージョンである． マップ内に無い場合，この関数は（パースを行う関数が利用して）新しいノードを挿入することが可能である．
GetFileNodeName
ファイルノードの名前を返す
const char* cvGetFileNodeName( const CvFileNode* node );
- node
- ファイルノード．
関数cvGetFileNodeNameファイルノードの名前を返す． ファイルノードが名前を持たないか，nodeがNULL の場合にはNULLを返す．
ReadInt
ファイルノードから整数値を読み込む
int cvReadInt( const CvFileNode* node, int default_value=0 );
- node
- ファイルノード．
- default_value
- nodeがNULLの場合の戻り値．
関数cvReadIntは，ファイルノードで表現された整数値を返す． ファイルノードがNULLの場合，default_valueを返す （つまり，cvGetFileNodeの直後でNULLポインタのチェックを行わず，この関数を使うと便利である）． ファイルノードがCV_NODE_INT型を持つ場合，node->data.iを返す． ファイルノードがCV_NODE_REAL型を持つ場合，node->data.fを整数に変換して返す． それ以外の場合，戻り値は不定である．
ReadIntByName
ファイルノードを探索し，その値を返す
int cvReadIntByName( const CvFileStorage* fs, const CvFileNode* map,
const char* name, int default_value=0 );
- fs
- ファイルストレージ．
- map
- 親マップ．NULLの場合，この関数はトップレベルノードを探索する．
- name
- ノード名．
- default_value
- ファイルノードが見つからない場合の戻り値．
関数cvReadIntByNameは，cvGetFileNodeByName とcvReadIntの単純な合成である．
.ReadReal
ファイルノードから浮動小数点型の値を取り込む
double cvReadReal( const CvFileNode* node, double default_value=0. );
- node
- ファイルノード．
- default_value
- nodeがNULLの場合の戻り値．
関数cvReadRealは，ファイルノードで表現される浮動小数点型の値を返す． ファイルノードがNULLの場合，default_valueを返す （つまり，cvGetFileNodeの直後でNULLポインタのチェックを行なわず，この関数を使うと便利である）． ファイルノードが CV_NODE_REAL型を持つ場合，node->data.fを返す． ファイルノードがCV_NODE_INT型を持つ場合，node->data.fを浮動小数点型に変換して返す． それ以外の場合，戻り値は不定である．
ReadRealByName
ファイルノードを探してその値を返す
double cvReadRealByName( const CvFileStorage* fs, const CvFileNode* map,
const char* name, double default_value=0. );
- fs
- ファイルストレージ．
- map
- 親マップ．NULLの場合，この関数はトップレベルノードを探す．
- name
- ノード名．
- default_value
- ファイルノードが見つからない場合の戻り値．
関数cvReadRealByNameは，cvGetFileNodeByName とcvReadRealの単純な合成である．
ReadString
ファイルノードから文字列を取り出す
const char* cvReadString( const CvFileNode* node, const char* default_value=NULL );
- node
- ファイルノード．
- default_value
- nodeがNULLの場合の戻り値．
関数cvReadStringは，ファイルノードで表現された文字列を返す． ファイルノードがNULLの場合にはdefault_valueを返す （つまり，cvGetFileNodeの直後でNULLポインタのチェックを行なわず，この関数を使うと便利である）． ファイルノードがCV_NODE_STR型を持つ場合にはnode->data.str.ptrを返す． それ以外の場合，戻り値は不定である．
ReadStringByName
ファイルノードを探索して，その値を返す
const char* cvReadStringByName( const CvFileStorage* fs, const CvFileNode* map,
const char* name, const char* default_value=NULL );
- fs
- ファイルストレージ．
- map
- 親マップ．NULLの場合，この関数はトップレベルノードを探索する．
- name
- ノード名．
- default_value
- ファイルノードが見つからない場合の戻り値．
関数cvReadStringByNameは，cvGetFileNodeByNameと cvReadStringの単純な合成である．
Read
オブジェクトをデコードし，そのポインタを返す
void* cvRead( CvFileStorage* fs, CvFileNode* node,
CvAttrList* attributes=NULL );
- fs
- ファイルストレージ．
- node
- ルートオブジェクトノード．
- attributes
- 使用されないパラメータ．
関数cvReadは，ユーザオブジェクトをデコードし （オブジェクトをファイルストレージのサブツリーからネイティブな表現で作成），それを返す． デコードされるオブジェクトは，readメソッドをサポートする登録された型のインスタンスでなけらばならない （CvTypeInfoを参照）． オブジェクトの型はファイル内でエンコードされた型名で決定される． もしオブジェクトが動的構造体の場合，メモリストレージ内にも生成され， cvOpenFileStorageに渡される． ここでNULLポインタが渡された場合，一時的なメモリストレージの中ではcvReleaseFileStorage が呼ばれた時に解放される． もしオブジェクトが動的構造体でない場合，ヒープ内に生成され，特別な関数か標準のcvRelease を使って解放する必要がある．
ReadByName
オブジェクトを探索し，デコードする
void* cvReadByName( CvFileStorage* fs, const CvFileNode* map,
const char* name, CvAttrList* attributes=NULL );
- fs
- ファイルストレージ．
- map
- 親マップ．NULLの場合，この関数はトップレベルノードを探索する．
- name
- ノード名．
- attributes
- 使用されないパラメータ．
関数cvReadByNameは，cvGetFileNodeByName とcvReadの単純な合成である．
ReadRawData
複数の数値を読み込む
void cvReadRawData( const CvFileStorage* fs, const CvFileNode* src,
void* dst, const char* dt );
- fs
- ファイルストレージ．
- src
- 数値を読み込むファイルノード(シーケンス)．
- dst
- 書き込み先の配列へのポインタ．
- dt
- 配列の個々の要素の仕様．仕様はcvWriteRawDataと同じ．
関数cvReadRawDataは，スカラーのシーケンスで表されたファイルノードから要素を読み込む．
StartReadRawData
ファイルノードのシーケンスリーダの初期化
void cvStartReadRawData( const CvFileStorage* fs, const CvFileNode* src,
CvSeqReader* reader );
- fs
- ファイルストレージ．
- src
- 読み込むファイルノード(シーケンス)．
- reader
- シーケンスリーダへのポインタ．
関数cvStartReadRawDataは，ファイルノードからデータを読み込むためのシーケンスリーダを初期化する． 初期化されたリーダはcvReadRawDataSliceに渡すことができる．
ReadRawDataSlice
複数の数値のシーケンスを読み込む
void cvReadRawDataSlice( const CvFileStorage* fs, CvSeqReader* reader,
int count, void* dst, const char* dt );
- fs
- ファイルストレージ．
- reader
- シーケンスリーダ．cvStartReadRawDataで初期化する．
- count
- 読み込む要素数．
- dst
- 出力配列へのポインタ．
- dt
- 各配列要素の仕様．仕様はcvWriteRawDataと同じ．
関数cvReadRawDataSliceは，ファイルから，シーケンスで表現される一つまたは複数の要素をユーザ定義配列へ読み込む． 読み込むシーケンス要素の総数はcountと各配列要素の要素数の積である． 例えばdt='2if'の場合，この関数はcount*3のシーケンス要素を読み込む． リーダがcvSetSeqReaderPosで再配置されると， ファイルノードシーケンスの幾つかの部分は読み飛ばされるか，重複して読み込まれる可能性がある．