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）
ファイルストレージ（File Storage）
CvFileStorage
ファイルストレージ
typedef struct CvFileStorage
{
... // 隠しフィールド
} CvFileStorage;
構造体CvFileStorageは， ディスク内にあるファイルと関連付けられたファイルストレージの「ブラックボックス」的な表現である． 後述する様々な関数はCvFileStorageを引数に持ち，で構成される スカラー値や標準的なCXCoreオブジェクト（行列やシーケンス，グラフなど），ユーザ定義オブジェクトなどからなる階層的なコレクションのセーブとロードをユーザに提供する．
CXCoreは，XML(http://www.w3c.org/XML)や YAML (http://www.yaml.org)形式のデータの読み書きが可能である． 以下はXMLとYAMLによる浮動小数点型の3×3単位行列Aの表現である．CXCoreの関数を用いると次のようになる．
- XML:
<?xml version="1.0"> <opencv_storage> <A type_id="opencv-matrix"> <rows>3</rows> <cols>3</cols> <dt>f</dt> <data>1. 0. 0. 0. 1. 0. 0. 0. 1.</data> </A> </opencv_storage>
- YAML:
%YAML:1.0 A: !!opencv-matrix rows: 3 cols: 3 dt: f data: [ 1., 0., 0., 0., 1., 0., 0., 0., 1.]
この例で見られるように，XMLでは階層構造の表現にネスト(入れ子)されたタグを用い，YAMLでは（Pythonと類似した）インデントを用いる．
同じCXCore関数を用いて両データ形式の読み書きが可能であり，形式は開かれたファイルの拡張子で判別される． 拡張子はXMLの場合.xml，YAMLの場合は.ymlである．
CvFileNode
ファイルストレージノード
/* ファイルノードタイプ */
#define CV_NODE_NONE 0
#define CV_NODE_INT 1
#define CV_NODE_INTEGER CV_NODE_INT
#define CV_NODE_REAL 2
#define CV_NODE_FLOAT CV_NODE_REAL
#define CV_NODE_STR 3
#define CV_NODE_STRING CV_NODE_STR
#define CV_NODE_REF 4 /* 使用されない */
#define CV_NODE_SEQ 5
#define CV_NODE_MAP 6
#define CV_NODE_TYPE_MASK 7
/* オプションのフラグ */
#define CV_NODE_USER 16
#define CV_NODE_EMPTY 32
#define CV_NODE_NAMED 64
#define CV_NODE_TYPE(tag) ((tag) & CV_NODE_TYPE_MASK)
#define CV_NODE_IS_INT(tag) (CV_NODE_TYPE(tag) == CV_NODE_INT)
#define CV_NODE_IS_REAL(tag) (CV_NODE_TYPE(tag) == CV_NODE_REAL)
#define CV_NODE_IS_STRING(tag) (CV_NODE_TYPE(tag) == CV_NODE_STRING)
#define CV_NODE_IS_SEQ(tag) (CV_NODE_TYPE(tag) == CV_NODE_SEQ)
#define CV_NODE_IS_MAP(tag) (CV_NODE_TYPE(tag) == CV_NODE_MAP)
#define CV_NODE_IS_COLLECTION(tag) (CV_NODE_TYPE(tag) >= CV_NODE_SEQ)
#define CV_NODE_IS_FLOW(tag) (((tag) & CV_NODE_FLOW) != 0)
#define CV_NODE_IS_EMPTY(tag) (((tag) & CV_NODE_EMPTY) != 0)
#define CV_NODE_IS_USER(tag) (((tag) & CV_NODE_USER) != 0)
#define CV_NODE_HAS_NAME(tag) (((tag) & CV_NODE_NAMED) != 0)
#define CV_NODE_SEQ_SIMPLE 256
#define CV_NODE_SEQ_IS_SIMPLE(seq) (((seq)->flags & CV_NODE_SEQ_SIMPLE) != 0)
typedef struct CvString
{
int len;
char* ptr;
}
CvString;
/* 読み込んだファイルストレージに含まれる要素の全てのキー（names）は，
ルックアップ処理の高速化のためハッシュに記憶される */
typedef struct CvStringHashNode
{
unsigned hashval;
CvString str;
struct CvStringHashNode* next;
}
CvStringHashNode;
/* ファイルストレージの基本要素 - スカラー，またはコレクション */
typedef struct CvFileNode
{
int tag;
struct CvTypeInfo* info; /* 型情報（ユーザ定義オブジェクト用，そうでない場合は0） */
union
{
double f; /* 浮動小数点型のスカラー値 */
int i; /* 整数型のスカラー値 */
CvString str; /* 文字列 */
CvSeq* seq; /* シーケンス（順序付きファイルノードのコレクション） */
struct CvMap* map; /* マップ（名前付きファイルノードのコレクション） */
} data;
}
CvFileNode;
この構造体は，ファイルストレージからデータを取り出す（例えば，ファイルからのデータ読み込み）ためだけに用いられる．ファイルへのデータ書き込みは，最小限のバッファを使い逐次的に実行される．ファイルストレージには，データは保存されない．
反対に，ファイルからデータが読み込まれた場合，全てのファイルは解析されて，メモリ内では木構造として表現される． 木構造のそれぞれのノードはCvFileNodeで表現される． ファイルノードNの型は，CV_NODE_TYPE(N->tag)として取得できる． 幾つかのファイルノード（葉）は，文字列や，整数，浮動小数点数などのスカラーである． その他のファイルノードは，ファイルノードのコレクション，スカラーのコレクション，あるいはコレクションのコレクション，などである． コレクションにはシーケンスとマップの2つの型がある（ここではYAMLの表記法を使うが，XMLストリームでも同様である）． シーケンス（CvSeq と混同しないように）は名前付けされていないファイルノードの整列されたコレクションで， マップは名前付けされたファイルノードの整列されていないコレクションである． このように，シーケンスの要素には，インデックス（cvGetSeqElem）によりアクセスされ， マップの要素には名前（cvGetFileNodeByName）でアクセスされる． 以下の表はファイルノードの型の違いを示す．
| 型 | CV_NODE_TYPE(node->tag) | 値 |
| 整数 | CV_NODE_INT | node->data.i |
| 浮動小数点 | CV_NODE_REAL | node->data.f |
| 文字列 | CV_NODE_STR | node->data.str.ptr |
| シーケンス | CV_NODE_SEQ | node->data.seq |
| マップ | CV_NODE_MAP | node->data.map* |
- *
- map フィールドに直接アクセスする必要は無い（CvMapは隠された構造体である）． このマップの要素は，「マップ」ファイルノードのポインタを引数に持つ関数 cvGetFileNodeByNameを使って取得できる．
ユーザ（カスタム）オブジェクトはCvMatやCvSeq等の標準的なCxCoreの型か， cvRegisterTypeで登録された型のインスタンスである． これらのオブジェクトは，ファイルストレージが開かれて解析された後，初期状態ではファイル内でマップ（上述のXMLとYAMLのサンプルファイルのように）として表現されている． その後，オブジェクトはリクエスト（関数cvReadやcvReadByNameを使った場合） に応じてデコード（元々の表現に変換）される．
CvAttrList
属性のリスト
typedef struct CvAttrList
{
const char** attr; /* (attribute_name,attribute_value)のペアからなるNULLで終わる配列 */
struct CvAttrList* next; /* 属性リストの次の塊へのポインタ */
}
CvAttrList;
/* 構造体CvAttrListの初期化 */
inline CvAttrList cvAttrList( const char** attr=NULL, CvAttrList* next=NULL );
/* 属性の値を返すか，もしそのような属性が存在しない場合には0（NULL）を返す */
const char* cvAttrValue( const CvAttrList* attr, const char* attr_name );
現在の実装では，属性はユーザオブジェクトを書き込む際の特別なパラメータを渡すために使われる（cvWriteを参照）． タグの中にあるXMLの属性はオブジェクトの型指定（type_id属性）を除いてサポートされない．
OpenFileStorage
データ読み書きのためのファイルをオープンする
CvFileStorage* cvOpenFileStorage( const char* filename, CvMemStorage* memstorage, int flags );
- filename
- ストレージに関連づけられたファイルの名前．
- memstorage
- 一時的なデータや，CvSeqや CvGraphなどの動的構造体の保存に使われるメモリストレージ．NULLの場合，一時的なメモリが確保されて使用される．
- flags
- 以下の内の一つを指定．
CV_STORAGE_READ - データ読み込みのためのファイルオープン
CV_STORAGE_WRITE - データ書き込みのためのファイルオープン
関数cvOpenFileStorageは，データの読み書きのためのファイルを開く． 書き込みの場合は，新しいファイルが作成されるか，ファイルが存在する場合には上書きされる．また，読み書きされるファイルの種類は拡張子で判別される． XMLの場合は.xml，YAMLの場合は.ymlまたは.yamlである． この関数の戻り値は構造体CvFileStorageへのポインタである．
ReleaseFileStorage
ファイルストレージの解放
void cvReleaseFileStorage( CvFileStorage** fs );
- fs
- 解放するファイルへのポインタのポインタ．
関数cvReleaseFileStorageはファイルを閉じて，一時的な構造体をすべて解放する． この関数は，すべての入出力操作が終了した後に実行されなければならない．