OpenCV  3.0.0-rc1
Open Source Computer Vision
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Properties Friends Macros Groups Pages
File Input and Output using XML and YAML files

Goal

You'll find answers for the following questions:

Source code

You can download this from here or find it in the samples/cpp/tutorial_code/core/file_input_output/file_input_output.cpp of the OpenCV source code library.

Here's a sample code of how to achieve all the stuff enumerated at the goal list.

1 #include <opencv2/core/core.hpp>
2 #include <iostream>
3 #include <string>
4 
5 using namespace cv;
6 using namespace std;
7 
8 static void help(char** av)
9 {
10  cout << endl
11  << av[0] << " shows the usage of the OpenCV serialization functionality." << endl
12  << "usage: " << endl
13  << av[0] << " outputfile.yml.gz" << endl
14  << "The output file may be either XML (xml) or YAML (yml/yaml). You can even compress it by "
15  << "specifying this in its extension like xml.gz yaml.gz etc... " << endl
16  << "With FileStorage you can serialize objects in OpenCV by using the << and >> operators" << endl
17  << "For example: - create a class and have it serialized" << endl
18  << " - use it to read and write matrices." << endl;
19 }
20 
21 class MyData
22 {
23 public:
24  MyData() : A(0), X(0), id()
25  {}
26  explicit MyData(int) : A(97), X(CV_PI), id("mydata1234") // explicit to avoid implicit conversion
27  {}
28  void write(FileStorage& fs) const //Write serialization for this class
29  {
30  fs << "{" << "A" << A << "X" << X << "id" << id << "}";
31  }
32  void read(const FileNode& node) //Read serialization for this class
33  {
34  A = (int)node["A"];
35  X = (double)node["X"];
36  id = (string)node["id"];
37  }
38 public: // Data Members
39  int A;
40  double X;
41  string id;
42 };
43 
44 //These write and read functions must be defined for the serialization in FileStorage to work
45 static void write(FileStorage& fs, const std::string&, const MyData& x)
46 {
47  x.write(fs);
48 }
49 static void read(const FileNode& node, MyData& x, const MyData& default_value = MyData()){
50  if(node.empty())
51  x = default_value;
52  else
53  x.read(node);
54 }
55 
56 // This function will print our custom class to the console
57 static ostream& operator<<(ostream& out, const MyData& m)
58 {
59  out << "{ id = " << m.id << ", ";
60  out << "X = " << m.X << ", ";
61  out << "A = " << m.A << "}";
62  return out;
63 }
64 
65 int main(int ac, char** av)
66 {
67  if (ac != 2)
68  {
69  help(av);
70  return 1;
71  }
72 
73  string filename = av[1];
74  { //write
75  Mat R = Mat_<uchar>::eye(3, 3),
76  T = Mat_<double>::zeros(3, 1);
77  MyData m(1);
78 
79  FileStorage fs(filename, FileStorage::WRITE);
80 
81  fs << "iterationNr" << 100;
82  fs << "strings" << "["; // text - string sequence
83  fs << "image1.jpg" << "Awesomeness" << "../data/baboon.jpg";
84  fs << "]"; // close sequence
85 
86  fs << "Mapping"; // text - mapping
87  fs << "{" << "One" << 1;
88  fs << "Two" << 2 << "}";
89 
90  fs << "R" << R; // cv::Mat
91  fs << "T" << T;
92 
93  fs << "MyData" << m; // your own data structures
94 
95  fs.release(); // explicit close
96  cout << "Write Done." << endl;
97  }
98 
99  {//read
100  cout << endl << "Reading: " << endl;
101  FileStorage fs;
102  fs.open(filename, FileStorage::READ);
103 
104  int itNr;
105  //fs["iterationNr"] >> itNr;
106  itNr = (int) fs["iterationNr"];
107  cout << itNr;
108  if (!fs.isOpened())
109  {
110  cerr << "Failed to open " << filename << endl;
111  help(av);
112  return 1;
113  }
114 
115  FileNode n = fs["strings"]; // Read string sequence - Get node
116  if (n.type() != FileNode::SEQ)
117  {
118  cerr << "strings is not a sequence! FAIL" << endl;
119  return 1;
120  }
121 
122  FileNodeIterator it = n.begin(), it_end = n.end(); // Go through the node
123  for (; it != it_end; ++it)
124  cout << (string)*it << endl;
125 
126 
127  n = fs["Mapping"]; // Read mappings from a sequence
128  cout << "Two " << (int)(n["Two"]) << "; ";
129  cout << "One " << (int)(n["One"]) << endl << endl;
130 
131 
132  MyData m;
133  Mat R, T;
134 
135  fs["R"] >> R; // Read cv::Mat
136  fs["T"] >> T;
137  fs["MyData"] >> m; // Read your own structure_
138 
139  cout << endl
140  << "R = " << R << endl;
141  cout << "T = " << T << endl << endl;
142  cout << "MyData = " << endl << m << endl << endl;
143 
144  //Show default behavior for non existing nodes
145  cout << "Attempt to read NonExisting (should initialize the data structure with its default).";
146  fs["NonExisting"] >> m;
147  cout << endl << "NonExisting = " << endl << m << endl;
148  }
149 
150  cout << endl
151  << "Tip: Open up " << filename << " with a text editor to see the serialized data." << endl;
152 
153  return 0;
154 }
value, open the file for reading
Definition: persistence.hpp:304
int type() const
Returns type of the node.
v_reg< _Tp, n > operator<<(const v_reg< _Tp, n > &a, int imm)
Definition: intrin_cpp.hpp:345
void write(FileStorage &fs, String &, const Stump &s)
FileNodeIterator begin() const
returns iterator pointing to the first node element
value, open the file for writing
Definition: persistence.hpp:305
virtual bool open(const String &filename, int flags, const String &encoding=String())
Opens a file.
virtual void release()
Closes the file and releases all the memory buffers.
virtual bool isOpened() const
Checks whether the file is opened.
static MatExpr zeros(int rows, int cols)
overridden forms of Mat::zeros() etc. Data type is omitted, of course
XML/YAML file storage class that encapsulates all the information necessary for writing or reading da...
Definition: persistence.hpp:298
void read(const FileNode &node, Stump &s, const Stump &default_value=Stump())
static MatExpr eye(int rows, int cols)
bool empty() const
returns true if the node is empty
File Storage Node class.
Definition: persistence.hpp:454
#define CV_PI
Definition: defs.h:301
int main(int argc, const char *argv[])
Definition: facerec_demo.cpp:67
n-dimensional dense array class
Definition: mat.hpp:726
FileNodeIterator end() const
returns iterator pointing to the element following the last node element
used to iterate through sequences and mappings.
Definition: persistence.hpp:580
sequence
Definition: persistence.hpp:467

Explanation

Here we talk only about XML and YAML file inputs. Your output (and its respective input) file may have only one of these extensions and the structure coming from this. They are two kinds of data structures you may serialize: mappings (like the STL map) and element sequence (like the STL vector). The difference between these is that in a map every element has a unique name through what you may access it. For sequences you need to go through them to query a specific item.

  1. XML/YAML File Open and Close. Before you write any content to such file you need to open it and at the end to close it. The XML/YAML data structure in OpenCV is cv::FileStorage . To specify that this structure to which file binds on your hard drive you can use either its constructor or the open() function of this:

    string filename = "I.xml";
    FileStorage fs(filename, FileStorage::WRITE);
    //...
    fs.open(filename, FileStorage::READ);

    Either one of this you use the second argument is a constant specifying the type of operations you'll be able to on them: WRITE, READ or APPEND. The extension specified in the file name also determinates the output format that will be used. The output may be even compressed if you specify an extension such as *.xml.gz*.

    The file automatically closes when the cv::FileStorage objects is destroyed. However, you may explicitly call for this by using the release function:

    fs.release(); // explicit close
  2. Input and Output of text and numbers. The data structure uses the same << output operator that the STL library. For outputting any type of data structure we need first to specify its name. We do this by just simply printing out the name of this. For basic types you may follow this with the print of the value :
    fs << "iterationNr" << 100;
    Reading in is a simple addressing (via the [] operator) and casting operation or a read via the >> operator :
    int itNr;
    fs["iterationNr"] >> itNr;
    itNr = (int) fs["iterationNr"];
  3. Input/Output of OpenCV Data structures. Well these behave exactly just as the basic C++ types:
    Mat R = Mat_<uchar >::eye (3, 3),
    fs << "R" << R; // Write cv::Mat
    fs << "T" << T;
    fs["R"] >> R; // Read cv::Mat
    fs["T"] >> T;
  4. Input/Output of vectors (arrays) and associative maps. As I mentioned beforehand, we can output maps and sequences (array, vector) too. Again we first print the name of the variable and then we have to specify if our output is either a sequence or map.

    For sequence before the first element print the "[" character and after the last one the "]" character:

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

    For maps the drill is the same however now we use the "{" and "}" delimiter characters:

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

    To read from these we use the cv::FileNode and the cv::FileNodeIterator data structures. The [] operator of the cv::FileStorage class returns a cv::FileNode data type. If the node is sequential we can use the cv::FileNodeIterator to iterate through the items:

    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;

    For maps you can use the [] operator again to acces the given item (or the >> operator too):

    n = fs["Mapping"]; // Read mappings from a sequence
    cout << "Two " << (int)(n["Two"]) << "; ";
    cout << "One " << (int)(n["One"]) << endl << endl;
  5. Read and write your own data structures. Suppose you have a data structure such as:

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

    It's possible to serialize this through the OpenCV I/O XML/YAML interface (just as in case of the OpenCV data structures) by adding a read and a write function inside and outside of your class. For the inside part:

    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"];
    }

    Then you need to add the following functions definitions outside the class:

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

    Here you can observe that in the read section we defined what happens if the user tries to read a non-existing node. In this case we just return the default initialization value, however a more verbose solution would be to return for instance a minus one value for an object ID.

    Once you added these four functions use the >> operator for write and the << operator for read:

    MyData m(1);
    fs << "MyData" << m; // your own data structures
    fs["MyData"] >> m; // Read your own structure_

    Or to try out reading a non-existing read:

    fs["NonExisting"] >> m; // Do not add a fs << "NonExisting" << m command for this to work
    cout << endl << "NonExisting = " << endl << m << endl;

Result

Well mostly we just print out the defined numbers. On the screen of your console you could see:

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.

Nevertheless, it's much more interesting what you may see in the output xml file:

<?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>

Or the YAML file:

%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

You may observe a runtime instance of this on the YouTube here .