XML / YAML / JSON ファイルによるファイル入出力

目次

• 目的
• ソースコード
• 解説
• 結果

前のチュートリアル: 離散フーリエ変換
次のチュートリアル: OpenCV の parallel_for_ 関数でコードを並列化する方法 (マンデルブロ集合の例)
次のチュートリアル: OpenCV の parallel_for_ 関数でコードを並列化する方法 (畳み込みの例)

原著者	Bernát Gábor
互換性	OpenCV >= 3.0

目的

次の疑問に対する答えが見つかる。

• YAML、XML、JSONファイルを使って、OpenCVでテキストエントリをファイルに書き込んだり読み込んだりするにはどうすればよいか？
• OpenCVのデータ構造に対して同じ操作を行うにはどうすればよいか？
• 独自のデータ構造に対してはどうすればよいか？
• cv::FileStorage、cv::FileNode、cv::FileNodeIterator などのOpenCVデータ構造はどのように使うのか？

ソースコード

C++

ここからダウンロードできるほか、OpenCV ソースコードライブラリの samples/cpp/tutorial_code/core/file_input_output/file_input_output.cpp にもある。

目的の一覧に挙げたすべての処理を実現する方法のサンプルコードを次に示す。

#include <opencv2/core.hpp>
#include <iostream>
#include <string>
 
using namespace cv;
using namespace std;
 
static void help(char** av)
{
    cout << endl
        << av[0] << " shows the usage of the OpenCV serialization functionality."         << endl << endl
        << "usage: "                                                                      << endl
        <<  av[0] << " [output file name] (default outputfile.yml.gz)"                    << endl << endl
        << "The output file may be XML (xml), YAML (yml/yaml), or JSON (json)." << endl
        << "You can even compress it by specifying this in its extension like xml.gz yaml.gz etc... " << endl
        << "With FileStorage you can serialize objects in OpenCV by using the << and >> operators" << endl
        << "For example: - create a class and have it serialized"                         << endl
        << "             - use it to read and write matrices."                            << endl << endl;
}
 
class MyData
{
public:
    MyData() : A(0), X(0), id()
    {}
 explicit MyData(int) : A(97), X(CV_PI), id("mydata1234") // explicit to avoid implicit conversion
    {}
 void write(FileStorage& fs) const //Write serialization for this class
    {
        fs << "{" << "A" << A << "X" << X << "id" << id << "}";
    }
 void read(const FileNode& node)                          //Read serialization for this class
    {
        A = (int)node["A"];
        X = (double)node["X"];
 id = (string)node["id"];
    }
public:   // Data Members
 int A;
 double X;
 string id;
};
 
//These write and read functions must be defined for the serialization in FileStorage to work
static void write(FileStorage& fs, const std::string&, const MyData& x)
{
    x.write(fs);
}
static void read(const FileNode& node, MyData& x, const MyData& default_value = MyData()){
 if(node.empty())
        x = default_value;
 else
        x.read(node);
}
 
// This function will print our custom class to the console
static ostream& operator<<(ostream& out, const MyData& m)
{
    out << "{ id = " << m.id << ", ";
    out << "X = " << m.X << ", ";
    out << "A = " << m.A << "}";
 return out;
}
 
int main(int ac, char** av)
{
 string filename;
 
 if (ac != 2)
    {
        help(av);
        filename = "outputfile.yml.gz";
    }
 else
        filename = av[1];
 
    { //write
 Mat R = Mat_<uchar>::eye(3, 3),
            T = Mat_<double>::zeros(3, 1);
        MyData m(1);
 
 FileStorage fs(filename, FileStorage::WRITE);
 // or:
 // FileStorage fs;
 // fs.open(filename, FileStorage::WRITE);
 
        fs << "iterationNr" << 100;
        fs << "strings" << "[";                              // text - string sequence
        fs << "image1.jpg" << "Awesomeness" << "../data/baboon.jpg";
        fs << "]";                                           // close sequence
 
        fs << "Mapping";                              // text - mapping
        fs << "{" << "One" << 1;
        fs <<        "Two" << 2 << "}";
 
        fs << "R" << R;                                      // cv::Mat
        fs << "T" << T;
 
        fs << "MyData" << m;                                // your own data structures
 
        fs.release();                                       // explicit close
        cout << "Write operation to file:" << filename << " completed successfully." << endl;
    }
 
    {//read
        cout << endl << "Reading: " << endl;
 FileStorage fs;
        fs.open(filename, FileStorage::READ);
 
 int itNr;
 //fs["iterationNr"] >> itNr;
        itNr = (int) fs["iterationNr"];
        cout << itNr;
 if (!fs.isOpened())
        {
            cerr << "Failed to open " << filename << endl;
            help(av);
 return 1;
        }
 
 FileNode n = fs["strings"];                         // Read string sequence - Get node
 if (n.type() != FileNode::SEQ)
        {
            cerr << "strings is not a sequence! FAIL" << endl;
 return 1;
        }
 
 FileNodeIterator it = n.begin(), it_end = n.end(); // Go through the node
 for (; it != it_end; ++it)
            cout << (string)*it << endl;
 
 
        n = fs["Mapping"];                                // Read mappings from a sequence
        cout << "Two  " << (int)(n["Two"]) << "; ";
        cout << "One  " << (int)(n["One"]) << endl << endl;
 
 
        MyData m;
 Mat R, T;
 
        fs["R"] >> R;                                      // Read cv::Mat
        fs["T"] >> T;
        fs["MyData"] >> m;                                 // Read your own structure_
 
        cout << endl
            << "R = " << R << endl;
        cout << "T = " << T << endl << endl;
        cout << "MyData = " << endl << m << endl << endl;
 
 //Show default behavior for non existing nodes
        cout << "Attempt to read NonExisting (should initialize the data structure with its default).";
        fs["NonExisting"] >> m;
        cout << endl << "NonExisting = " << endl << m << endl;
    }
 
    cout << endl
        << "Tip: Open up " << filename << " with a text editor to see the serialized data." << endl;
 
 return 0;
}

Python

ここからダウンロードできるほか、OpenCV ソースコードライブラリの samples/python/tutorial_code/core/file_input_output/file_input_output.py にもある。

目的の一覧に挙げたすべての処理を実現する方法のサンプルコードを次に示す。

from __future__ import print_function
 
import numpy as np
import cv2 as cv
import sys
 
def help(filename):
 print (
 '''
        {0} shows the usage of the OpenCV serialization functionality. \n\n
        usage:\n
            python3 {0} [output file name] (default outputfile.yml.gz)\n\n
        The output file may be XML (xml), YAML (yml/yaml), or JSON (json).\n
        You can even compress it by specifying this in its extension like xml.gz yaml.gz etc...\n
        With FileStorage you can serialize objects in OpenCV.\n\n
        For example: - create a class and have it serialized\n
                     - use it to read and write matrices.\n
        '''.format(filename)
    )
 
class MyData:
    A = 97
    X = np.pi
    name = 'mydata1234'
 
 def __repr__(self):
        s = '{ name = ' + self.name + ', X = ' + str(self.X)
        s = s + ', A = ' +  str(self.A) + '}'
 return s
 
 
 def write(self, fs, name):
        fs.startWriteStruct(name, cv.FileNode_MAP|cv.FileNode_FLOW)
        fs.write('A', self.A)
        fs.write('X', self.X)
        fs.write('name', self.name)
        fs.endWriteStruct()
 
 def read(self, node):
 if (not node.empty()):
            self.A = int(node.getNode('A').real())
            self.X = node.getNode('X').real()
            self.name = node.getNode('name').string()
 else:
            self.A = self.X = 0
            self.name = ''
 
 
def main(argv):
 if len(argv) != 2:
        help(argv[0])
        filename = 'outputfile.yml.gz'
 else :
        filename = argv[1]
 
 # write
 
    R = np.eye(3,3)
    T = np.zeros((3,1))
 
    m = MyData()
 
 
 
    s = cv.FileStorage(filename, cv.FileStorage_WRITE)
 # or:
 # s = cv.FileStorage()
 # s.open(filename, cv.FileStorage_WRITE)
 
 
 
    s.write('iterationNr', 100)
 
 
 
    s.startWriteStruct('strings', cv.FileNode_SEQ)
 for elem in ['image1.jpg', 'Awesomeness', '../data/baboon.jpg']:
        s.write('', elem)
    s.endWriteStruct()
 
 
 
    s.startWriteStruct('Mapping', cv.FileNode_MAP)
    s.write('One', 1)
    s.write('Two', 2)
    s.endWriteStruct()
 
 
 
    s.write('R_MAT', R)
    s.write('T_MAT', T)
 
 
 
    m.write(s, 'MyData')
 
    s.release()
 
 print ('Write operation to file:', filename, 'completed successfully.')
 
 # read
 print ('\nReading: ')
    s = cv.FileStorage()
    s.open(filename, cv.FileStorage_READ)
 
 
    n = s.getNode('iterationNr')
    itNr = int(n.real())
 
 print (itNr)
 
 if (not s.isOpened()):
 print ('Failed to open ', filename, file=sys.stderr)
        help(argv[0])
        exit(1)
 
 
    n = s.getNode('strings')
 if (not n.isSeq()):
 print ('strings is not a sequence! FAIL', file=sys.stderr)
        exit(1)
 
 for i in range(n.size()):
 print (n.at(i).string())
 
 
 
    n = s.getNode('Mapping')
 print ('Two',int(n.getNode('Two').real()),'; ')
 print ('One',int(n.getNode('One').real()),'\n')
 
 
 
    R = s.getNode('R_MAT').mat()
    T = s.getNode('T_MAT').mat()
 
    m.read(s.getNode('MyData'))
 
 
 print ('\nR =',R)
 print ('T =',T,'\n')
 print ('MyData =','\n',m,'\n')
 
 
 print ('Attempt to read NonExisting (should initialize the data structure',
 'with its default).')
    m.read(s.getNode('NonExisting'))
 print ('\nNonExisting =','\n',m)
 
 
 print ('\nTip: Open up',filename,'with a text editor to see the serialized data.')
 
if __name__ == '__main__':
 main(sys.argv)

解説

ここではXML、YAML、JSONのファイル入力についてのみ説明する。出力（およびそれに対応する入力）ファイルは、これらの拡張子のいずれか1つだけを持ち、それに応じた構造になる。シリアライズできるデータ構造には2種類ある。マッピング（STLのmapやPythonの辞書のようなもの）と要素のシーケンス（STLのvectorのようなもの）である。両者の違いは、mapではすべての要素が一意の名前を持ち、それを通じてアクセスできる点にある。シーケンスの場合は、特定の項目を取得するためにそれらをたどっていく必要がある。

1. XML/YAML/JSONファイルのオープンとクローズ。 そのようなファイルに内容を書き込む前に、ファイルを開き、最後に閉じる必要がある。OpenCVにおけるXML/YAML/JSONデータ構造はcv::FileStorageである。この構造をハードドライブ上のどのファイルに結び付けるかを指定するには、そのコンストラクタかこのopen()関数のいずれかを使う。

   C++

    FileStorage fs(filename, FileStorage::WRITE);
    // or:
    // FileStorage fs;
    // fs.open(filename, FileStorage::WRITE);

   Python

       s = cv.FileStorage(filename, cv.FileStorage_WRITE)
    # or:
    # s = cv.FileStorage()
    # s.open(filename, cv.FileStorage_WRITE)

   どちらを使う場合でも、2番目の引数はそれらに対して実行できる操作の種類を指定する定数である: WRITE、READ、APPEND。ファイル名に指定された拡張子は、使用される出力フォーマットも決定する。.xml.gzのような拡張子を指定すれば、出力を圧縮することさえできる。

   ファイルはcv::FileStorageオブジェクトが破棄されると自動的に閉じられる。ただし、release関数を使って明示的に呼び出すこともできる。

   C++

           fs.release();                                       // explicit close

   Python

       s.release()

2. テキストと数値の入出力。 C++では、このデータ構造はSTLライブラリの << 出力演算子を使う。Pythonでは、代わりにcv::FileStorage::write()を使う。任意の種類のデータ構造を出力するには、まずその名前を指定する必要がある。C++では、その名前をストリームにプッシュするだけでよい。Pythonでは、write関数の最初の引数が名前になる。基本型の場合は、それに続けて値を出力すればよい:
   C++

    fs << "iterationNr" << 100;

   Python

    s.write('iterationNr', 100)

   読み込みは単純なアドレッシング（[] 演算子を介する）とキャスト操作、または >> 演算子を介した読み込みである。Pythonでは、getNode() でアドレス指定し real() を使う:
   C++

    int itNr;
    //fs["iterationNr"] >> itNr;
    itNr = (int) fs["iterationNr"];

   Python

    int itNr;
    //fs["iterationNr"] >> itNr;
    itNr = (int) fs["iterationNr"];

3. OpenCVデータ構造の入出力。 これらは基本的なC++およびPythonの型とまったく同じように振る舞う:
   C++

    Mat R = Mat_<uchar>::eye(3, 3),
    T = Mat_<double>::zeros(3, 1);

    fs << "R" << R; // cv::Mat
    fs << "T" << T;

    fs["R"] >> R; // Read cv::Mat
    fs["T"] >> T;

   Python

    R = np.eye(3,3)
    T = np.zeros((3,1))

    s.write('R_MAT', R)
    s.write('T_MAT', T)

    R = s.getNode('R_MAT').mat()
    T = s.getNode('T_MAT').mat()

4. ベクトル（配列）と連想マップの入出力。 前述のとおり、mapやシーケンス（配列、ベクトル）も出力できる。ここでもまず変数の名前を出力し、その後に出力がシーケンスかmapのどちらであるかを指定する必要がある。

   シーケンスでは、最初の要素の前に "[" 文字を、最後の要素の後に "]" 文字を出力する。Pythonでは、FileStorage.startWriteStruct(structure_name, struct_type) を呼び出して構造の書き込みを開始する。ここで struct_type は cv2.FileNode_MAP または cv2.FileNode_SEQ である。FileStorage.endWriteStruct() を呼び出して構造を終了する。

   C++

           fs << "strings" << "[";                              // text - string sequence
           fs << "image1.jpg" << "Awesomeness" << "../data/baboon.jpg";
           fs << "]";                                           // close sequence

   Python

       s.startWriteStruct('strings', cv.FileNode_SEQ)
    for elem in ['image1.jpg', 'Awesomeness', '../data/baboon.jpg']:
           s.write('', elem)
       s.endWriteStruct()

   mapでも要領は同じだが、今度は "{" と "}" の区切り文字を使う。

   C++

           fs << "Mapping";                              // text - mapping
           fs << "{" << "One" << 1;
           fs <<        "Two" << 2 << "}";

   Python

       s.startWriteStruct('Mapping', cv.FileNode_MAP)
       s.write('One', 1)
       s.write('Two', 2)
       s.endWriteStruct()

   これらから読み込むには、cv::FileNodeとcv::FileNodeIteratorのデータ構造を使う。cv::FileStorageクラスの [] 演算子（またはPythonのgetNode()関数）はcv::FileNodeデータ型を返す。ノードがシーケンスである場合は、cv::FileNodeIteratorを使って項目を反復処理できる。Pythonでは、at()関数を使ってシーケンスの要素にアドレス指定でき、size()関数はシーケンスの長さを返す。

   C++

    FileNode n = fs["strings"];                         // Read string sequence - Get node
    if (n.type() != FileNode::SEQ)
           {
               cerr << "strings is not a sequence! FAIL" << endl;
    return 1;
           }
    
    FileNodeIterator it = n.begin(), it_end = n.end(); // Go through the node
    for (; it != it_end; ++it)
               cout << (string)*it << endl;

   Python

       n = s.getNode('strings')
    if (not n.isSeq()):
    print ('strings is not a sequence! FAIL', file=sys.stderr)
           exit(1)
    
    for i in range(n.size()):
    print (n.at(i).string())

   マップ(map)に対しては、[] 演算子(PythonではAt() 関数)を再び使って指定した要素にアクセスできる(>> 演算子も使える):

   C++

           n = fs["Mapping"];                                // Read mappings from a sequence
           cout << "Two  " << (int)(n["Two"]) << "; ";
           cout << "One  " << (int)(n["One"]) << endl << endl;

   Python

       n = s.getNode('Mapping')
    print ('Two',int(n.getNode('Two').real()),'; ')
    print ('One',int(n.getNode('One').real()),'\n')

5. 独自のデータ構造を読み書きする。 次のようなデータ構造があるとする:

   C++

   class MyData
   {
   public:
         MyData() : A(0), X(0), id() {}
   public:   // Data Members
    int A;
    double X;
    string id;
   };

   Python

   class MyData:
    def __init__(self):
           self.A = self.X = 0
           self.name = ''

   C++では、(OpenCVのデータ構造の場合と同様に)クラスの内側と外側に read 関数と write 関数を追加することで、OpenCVのI/O XML/YAMLインターフェースを通じてこれをシリアライズできる。Pythonでは、クラス内に read 関数と write 関数を実装することでこれに近いことができる。内側の部分については:

   C++

    void write(FileStorage& fs) const //Write serialization for this class
       {
           fs << "{" << "A" << A << "X" << X << "id" << id << "}";
       }
    void read(const FileNode& node)                          //Read serialization for this class
       {
           A = (int)node["A"];
           X = (double)node["X"];
    id = (string)node["id"];
       }

   Python

    def write(self, fs, name):
           fs.startWriteStruct(name, cv.FileNode_MAP|cv.FileNode_FLOW)
           fs.write('A', self.A)
           fs.write('X', self.X)
           fs.write('name', self.name)
           fs.endWriteStruct()
    
    def read(self, node):
    if (not node.empty()):
               self.A = int(node.getNode('A').real())
               self.X = node.getNode('X').real()
               self.name = node.getNode('name').string()
    else:
               self.A = self.X = 0
               self.name = ''

   C++

   C++では、クラスの外側に次の関数定義を追加する必要がある:

   static void write(FileStorage& fs, const std::string&, const MyData& x)
   {
       x.write(fs);
   }
   static void read(const FileNode& node, MyData& x, const MyData& default_value = MyData()){
    if(node.empty())
           x = default_value;
    else
           x.read(node);
   }

   ここでは、read セクションで、ユーザーが存在しないノードを読み込もうとした場合の動作を定義していることが分かる。この場合は単にデフォルトの初期化値を返しているが、より丁寧な解決策としては、たとえばオブジェクトIDに対してマイナス1の値を返すといった方法もある。

   これら4つの関数を追加したら、書き込みには >> 演算子を、読み込みには << 演算子を使う(Pythonでは定義した入出力関数を使う):

   C++

           MyData m(1);

           fs << "MyData" << m;                                // your own data structures

           fs["MyData"] >> m;                                 // Read your own structure_

   Python

       m = MyData()

       m.write(s, 'MyData')

       m.read(s.getNode('MyData'))

   あるいは、存在しないノードの読み込みを試すには:

   C++

           cout << "Attempt to read NonExisting (should initialize the data structure with its default).";
           fs["NonExisting"] >> m;
           cout << endl << "NonExisting = " << endl << m << endl;

   Python

    print ('Attempt to read NonExisting (should initialize the data structure',
    'with its default).')
       m.read(s.getNode('NonExisting'))
    print ('\nNonExisting =','\n',m)

結果

ほとんどの場合、定義した数値を出力するだけである。コンソールの画面には次のように表示されるはずだ:

Write Done.
 
Reading:
100image1.jpg
Awesomeness
baboon.jpg
Two  2; One  1
 
 
R = [1, 0, 0;
  0, 1, 0;
  0, 0, 1]
T = [0; 0; 0]
 
MyData =
{ id = mydata1234, X = 3.14159, A = 97}
 
Attempt to read NonExisting (should initialize the data structure with its default).
NonExisting =
{ id = , X = 0, A = 0}
 
Tip: Open up output.xml with a text editor to see the serialized data.

とはいえ、出力されたXMLファイルの中身の方がはるかに興味深い:

<?xml version="1.0"?>
<opencv_storage>
<iterationNr>100</iterationNr>
<strings>
 image1.jpg Awesomeness baboon.jpg</strings>
<Mapping>
  <One>1</One>
  <Two>2</Two></Mapping>
<R type_id="opencv-matrix">
  <rows>3</rows>
  <cols>3</cols>
  <dt>u</dt>
  <data>
    1 0 0 0 1 0 0 0 1</data></R>
<T type_id="opencv-matrix">
  <rows>3</rows>
  <cols>1</cols>
  <dt>d</dt>
  <data>
    0. 0. 0.</data></T>
<MyData>
  <A>97</A>
  <X>3.1415926535897931e+000</X>
  <id>mydata1234</id></MyData>
</opencv_storage>

あるいはYAMLファイル:

%YAML:1.0
iterationNr: 100
strings:
   - "image1.jpg"
   - Awesomeness
   - "baboon.jpg"
Mapping:
   One: 1
   Two: 2
R: !!opencv-matrix
   rows: 3
   cols: 3
   dt: u
   data: [ 1, 0, 0, 0, 1, 0, 0, 0, 1 ]
T: !!opencv-matrix
   rows: 3
   cols: 1
   dt: d
   data: [ 0., 0., 0. ]
MyData:
   A: 97
   X: 3.1415926535897931e+000
   id: mydata1234

これの実行例は こちらのYouTube で見ることができる。