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）
- ファイルストレージ（File Storage）
- データの書き込み（Writing Data）
- データの読み込み（Reading Data）
- 実行時型情報と汎用関数（RTTI and Generic Functions）
その他の関数（Miscellaneous Functions）
エラーハンドリングとシステム関数（Error Handling and System Functions）
- エラーハンドリング（Error Handling）
- システム関数（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はファイルを閉じて，一時的な構造体をすべて解放する．この関数は，すべての入出力操作が終了した後に実行されなければならない．

型	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*

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