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）
データの書き込み（Writing Data）
StartWriteStruct
新しい構造体の書き込みを開始する
void cvStartWriteStruct( CvFileStorage* fs, const char* name,
int struct_flags, const char* type_name=NULL,
CvAttrList attributes=cvAttrList());
- fs
- ファイルストレージ．
- name
- 書き込む構造体の名前．読み込む場合は，この名前で構造体にアクセスできる．
- struct_flags
- 次の値の組合せ．
CV_NODE_SEQ - 書き込む構造体はシーケンス（CvFileStorageを参照）， つまり要素は名前を持たない．
CV_NODE_MAP - 書き込む構造体はマップ（CvFileStorageを参照）， つまり全ての要素が名前を持つ．
これら二つのうち一つだけを指定しなければならない．
CV_NODE_FLOW - YAMLストリームに対してのみ意味を持つオプションフラグ． 構造体は，よりコンパクトなflow（blockではなく）として保存される． このフラグは全要素がスカラーである構造体か配列に対して用いることが推奨される． - type_name
- オプションパラメータ - オブジェクトの型の名前． XMLの場合，構造体開始タグのtype_id属性として書かれる． YAMLの場合，構造体名に続くコロンの後に書かれる（CvFileStorageの説明の中にある例を参照）． 主にユーザオブジェクトと共に使われる．ストレージが読まれたとき，エンコードされた型名がオブジェクトの型を決定する （CvTypeInfoとcvFindTypeを参照）．
- attributes
- このパラメータは現在は使われていない．
関数cvStartWriteStructは，シーケンスかマップが複合した構造体（コレクション）の書き込みを開始する． スカラーか構造体で構成された全ての構造体のフィールドが書き込まれた後で，cvEndWriteStructを実行しなければならない． この関数は，いくつかのオブジェクトをグループ化する場合や， ユーザオブジェクト（CvTypeInfoを参照）の書き込み関数を実装する場合にも使われることがある．
EndWriteStruct
構造体の書き込みを終了する
void cvEndWriteStruct( CvFileStorage* fs );
- fs
- ファイルストレージ．
関数cvEndWriteStructは，構造体の書き込みを終了する．
WriteInt
整数型の値を書き込む
void cvWriteInt( CvFileStorage* fs, const char* name, int value );
- fs
- ファイルストレージ．
- name
- 書き込まれる値の名前．親の構造体がシーケンスの場合は，NULLにしなければならない．
- value
- 書き込まれる値．
関数cvWriteIntは，1つの整数値（名前あり，または無し）をファイルに書き込む．
WriteReal
浮動小数点型の値を書き込む
void cvWriteReal( CvFileStorage* fs, const char* name, double value );
- fs
- ファイルストレージ．
- name
- 書き込まれる値の名前．親の構造体がシーケンスの場合は，NULLにしなければならない．
- value
- 書き込まれる値．
関数cvWriteRealは，単精度浮動小数点型の値（名前あり，または無し）をファイルに書き込む． 特別な値はエンコードされる：Not A NumberはNaN に，±Infinityは +.Inf (-.Inf) になる．
以下の例では新たな型の登録を行なわず，終了条件のような独自の構造体を保存する低レベルの書き込み関数の使い方を示す．
void write_termcriteria( CvFileStorage* fs, const char* struct_name,
CvTermCriteria* termcrit )
{
cvStartWriteStruct( fs, struct_name, CV_NODE_MAP, NULL, cvAttrList(0,0));
cvWriteComment( fs, "termination criteria", 1 ); // 単なるコメント
if( termcrit->type & CV_TERMCRIT_ITER )
cvWriteInt( fs, "max_iterations", termcrit->max_iter );
if( termcrit->type & CV_TERMCRIT_EPS )
cvWriteReal( fs, "accuracy", termcrit->epsilon );
cvEndWriteStruct( fs );
}
WriteString
文字列を書き込む
void cvWriteString( CvFileStorage* fs, const char* name,
const char* str, int quote=0 );
- fs
- ファイルストレージ．
- name
- 書き込まれる文字列の名前．親の構造体がシーケンスの場合は，NULLにしなければならない．
- str
- 書き込まれる文字列．
- quote
- 0以外の場合，書き込まれる文字列は必要かどうかに関わらず引用符で挟まれる． 0の場合，必要な場合にのみ引用符が使われる（例えば，文字列が数字で始まっていたり，スペースを含む場合）．
関数cvWriteStringは，文字列をファイルストレージに書き込む．
WriteComment
コメントを書き込む
void cvWriteComment( CvFileStorage* fs, const char* comment, int eol_comment );
- fs
- ファイルストレージ．
- comment
- 一行または複数行の，書き込まれるコメント．
- eol_comment
- 0以外の場合，この関数は現在の行の最後にコメントを入れようと試みる． フラグが0で，コメントが複数，または現在の行の最後に納まらない場合は，コメントは新しい行から始められる．
関数cvWriteCommentは，ファイルストレージにコメントを書き込む． このコメントはデバッグや説明を記述するために使われるもので，読み込み時には読み飛ばされる．
StartNextStream
次のストリームを開始する
void cvStartNextStream( CvFileStorage* fs );
- fs
- ファイルストレージ．
関数cvStartNextStreamは，ファイルストレージ内の次のストリームを開始する． YAMLとXMLはどちらも複数の「ストリーム」をサポートしている． これはファイルの連結や書き込みプロセスの再開に役立つ．
Write
ユーザオブジェクトを書き込む
void cvWrite( CvFileStorage* fs, const char* name,
const void* ptr, CvAttrList attributes=cvAttrList() );
- fs
- ファイルストレージ．
- name
- 書き込まれるオブジェクトの名前．親の構造体がシーケンスの場合は，NULLにしなければならない．
- ptr
- オブジェクトへのポインタ．
- attributes
- オブジェクトの属性．これは特定の型に対して固有である（以下を参照）．
関数cvWriteは，オブジェクトをファイルストレージに書き込む． まずcvTypeOfを用いて適切な型情報を見つける．そして，型情報のwriteメソッドが呼び出される．
属性は書き込み手続きをカスタマイズするために使われる．標準の型では以下の属性をサポートしている （全ての*dt属性は，cvWriteRawDataと同じフォーマットを持つ）．
- CvSeq
-
- header_dt - CvSeq，または CvChain（シーケンスがフリーマンチェインの場合），または CvContour （シーケンスが輪郭か点列の場合）に続く，シーケンスヘッダのユーザフィールドの説明．
- dt - シーケンス要素の説明．
- recursive - 属性が存在し，「0」でも「false」でも無い場合，シーケンス（輪郭）のすべての木は保存される．
- CvGraph
-
- グラフ頂点のユーザフィールドの説明．
- header_dt - CvGraphに続く，グラフヘッダのユーザフィールドの説明．
- vertex_dt - グラフ頂点のユーザフィールドの説明．
- edge_dt - グラフエッジのユーザフィールドの説明（エッジの重みは常に書かれるため，明示的に指定する必要が無いことに注意）．
以下はCvFileStorageの解説にあるYAMLを生成するコードである．
#include "cxcore.h"
int main( int argc, char** argv )
{
CvMat* mat = cvCreateMat( 3, 3, CV_32F );
CvFileStorage* fs = cvOpenFileStorage( "example.yml", 0, CV_STORAGE_WRITE );
cvSetIdentity( mat );
cvWrite( fs, "A", mat, cvAttrList(0,0) );
cvReleaseFileStorage( &fs );
cvReleaseMat( &mat );
return 0;
}
WriteRawData
複数の数値を書き込む
void cvWriteRawData( CvFileStorage* fs, const void* src,
int len, const char* dt );
- fs
- ファイルストレージ．
- src
- 書き込む配列へのポインタ．
- len
- 書き込む配列の要素数．
- dt
- 次に示すフォーマットを持つ配列の個々の要素の仕様．
([count]{'u'|'c'|'w'|'s'|'i'|'f'|'d'})...，で，これらの記号は基本的なC言語の型と同じである．
- 'u' - 8ビット符号なし数
- 'c' - 8ビット符号あり数
- 'w' - 16ビット符号なし数
- 's' - 16ビット符号あり数
- 'i' - 32ビット符号あり数
- 'f' - 単精度浮動小数点型数
- 'd' - 倍精度浮動小数点型数
- 'r' - ポインタ．下位32ビットは，符号あり整数として書き込まれる． この型は，書き込まれる要素同士がリンク構造を持つような構造体を格納するのに利用できる．
関数cvWriteRawDataは，一つ一つの要素が複数の数値の集まりである配列を書き込む． この関数は cvWriteIntと cvWriteRealの繰り返しで置き換えられるが，単一の実行のほうが効率的である． 名前を持つ要素が一つも無いため，マップよりはシーケンスに書き込むべきであることに注意する．
WriteFileNode
ファイルノードを他のファイルストレージに書き込む
void cvWriteFileNode( CvFileStorage* fs, const char* new_node_name,
const CvFileNode* node, int embed );
- fs
- 書き込み先のファイルストレージ．
- new_file_node
- 書き込み先ファイルストレージ内のファイルノードの新しい名前． 元の名前を維持するためには，cvGetFileNodeName(node)を用いる．
- node
- 書き込まれるノード．
- embed
- 書き込まれるノードがコレクションで，このパラメータが0でない場合，階層の余分なレベルは生成されない． その代わりに，nodeの全ての要素は現在書き込まれている構造体に書き込まれる． 当然，マップ要素はマップにのみ書き込まれ，シーケンス要素はシーケンスにのみ書き込まれる．
関数cvWriteFileNodeは，ファイルストレージにファイルノードのコピーを書き込む． この関数の用途として，いくつかのファイルストレージを一つにまとめる，XMLとYAMLのフォーマットを交換する，などが挙げられる．