modules/core/doc/xml_yaml_persistence.rst

   1 XML/YAML Persistence
   2 ====================
   3
   4 .. highlight:: cpp
   5
   6 XML/YAML file storages. Writing to a file storage.
   7 --------------------------------------------------
   8
   9 You can store and then restore various OpenCV data structures to/from XML (http://www.w3c.org/XML) or YAML
  10 (http://www.yaml.org) formats. Also, it is possible store and load arbitrarily complex data structures, which include OpenCV data structures, as well as primitive data types (integer and floating-point numbers and text strings) as their elements.
  11
  12 Use the following procedure to write something to XML or YAML:
  13  #. Create new :ocv:class:`FileStorage` and open it for writing. It can be done with a single call to :ocv:func:`FileStorage::FileStorage` constructor that takes a filename, or you can use the default constructor and then call :ocv:func:`FileStorage::open`. Format of the file (XML or YAML) is determined from the filename extension (".xml" and ".yml"/".yaml", respectively)
  14  #. Write all the data you want using the streaming operator ``<<``, just like in the case of STL streams.
  15  #. Close the file using :ocv:func:`FileStorage::release`. ``FileStorage`` destructor also closes the file.
  16
  17 Here is an example: ::
  18
  19     #include "opencv2/opencv.hpp"
  20     #include <time.h>
  21
  22     using namespace cv;
  23
  24     int main(int, char** argv)
  25     {
  26         FileStorage fs("test.yml", FileStorage::WRITE);
  27
  28         fs << "frameCount" << 5;
  29         time_t rawtime; time(&rawtime);
  30         fs << "calibrationDate" << asctime(localtime(&rawtime));
  31         Mat cameraMatrix = (Mat_<double>(3,3) << 1000, 0, 320, 0, 1000, 240, 0, 0, 1);
  32         Mat distCoeffs = (Mat_<double>(5,1) << 0.1, 0.01, -0.001, 0, 0);
  33         fs << "cameraMatrix" << cameraMatrix << "distCoeffs" << distCoeffs;
  34         fs << "features" << "[";
  35         for( int i = 0; i < 3; i++ )
  36         {
  37             int x = rand() % 640;
  38             int y = rand() % 480;
  39             uchar lbp = rand() % 256;
  40
  41             fs << "{:" << "x" << x << "y" << y << "lbp" << "[:";
  42             for( int j = 0; j < 8; j++ )
  43                 fs << ((lbp >> j) & 1);
  44             fs << "]" << "}";
  45         }
  46         fs << "]";
  47         fs.release();
  48         return 0;
  49     }
  50
  51 The sample above stores to XML and integer, text string (calibration date), 2 matrices, and a custom structure "feature", which includes feature coordinates and LBP (local binary pattern) value. Here is output of the sample:
  52
  53 .. code-block:: yaml
  54
  55     %YAML:1.0
  56     frameCount: 5
  57     calibrationDate: "Fri Jun 17 14:09:29 2011\n"
  58     cameraMatrix: !!opencv-matrix
  59        rows: 3
  60        cols: 3
  61        dt: d
  62        data: [ 1000., 0., 320., 0., 1000., 240., 0., 0., 1. ]
  63     distCoeffs: !!opencv-matrix
  64        rows: 5
  65        cols: 1
  66        dt: d
  67        data: [ 1.0000000000000001e-01, 1.0000000000000000e-02,
  68            -1.0000000000000000e-03, 0., 0. ]
  69     features:
  70        - { x:167, y:49, lbp:[ 1, 0, 0, 1, 1, 0, 1, 1 ] }
  71        - { x:298, y:130, lbp:[ 0, 0, 0, 1, 0, 0, 1, 1 ] }
  72        - { x:344, y:158, lbp:[ 1, 1, 0, 0, 0, 0, 1, 0 ] }
  73
  74 As an exercise, you can replace ".yml" with ".xml" in the sample above and see, how the corresponding XML file will look like.
  75
  76 Several things can be noted by looking at the sample code and the output:
  77  *
  78    The produced YAML (and XML) consists of heterogeneous collections that can be nested. There are 2 types of collections: named collections (mappings) and unnamed collections (sequences). In mappings each element has a name and is accessed by name. This is similar to structures and ``std::map`` in C/C++ and dictionaries in Python. In sequences elements do not have names, they are accessed by indices. This is similar to arrays and ``std::vector`` in C/C++ and lists, tuples in Python. "Heterogeneous" means that elements of each single collection can have different types.
  79
  80    Top-level collection in YAML/XML is a mapping. Each matrix is stored as a mapping, and the matrix elements are stored as a sequence. Then, there is a sequence of features, where each feature is represented a mapping, and lbp value in a nested sequence.
  81
  82  *
  83    When you write to a mapping (a structure), you write element name followed by its value. When you write to a sequence, you simply write the elements one by one. OpenCV data structures (such as cv::Mat) are written in absolutely the same way as simple C data structures - using **``<<``** operator.
  84
  85  *
  86    To write a mapping, you first write the special string **"{"** to the storage, then write the elements as pairs (``fs << <element_name> << <element_value>``) and then write the closing **"}"**.
  87
  88  *
  89    To write a sequence, you first write the special string **"["**, then write the elements, then write the closing **"]"**.
  90
  91  *
  92    In YAML (but not XML), mappings and sequences can be written in a compact Python-like inline form. In the sample above matrix elements, as well as each feature, including its lbp value, is stored in such inline form. To store a mapping/sequence in a compact form, put ":" after the opening character, e.g. use **"{:"** instead of **"{"** and **"[:"** instead of **"["**. When the data is written to XML, those extra ":" are ignored.
  93
  94 .. note::
  95
  96    * A complete example using the FileStorage interface can be found at opencv_source_code/samples/cpp/filestorage.cpp
  97
  98
  99 Reading data from a file storage.
 100 ---------------------------------
 101
 102 To read the previously written XML or YAML file, do the following:
 103
 104  #.
 105    Open the file storage using :ocv:func:`FileStorage::FileStorage` constructor or :ocv:func:`FileStorage::open` method. In the current implementation the whole file is parsed and the whole representation of file storage is built in memory as a hierarchy of file nodes (see :ocv:class:`FileNode`)
 106
 107  #.
 108    Read the data you are interested in. Use :ocv:func:`FileStorage::operator []`, :ocv:func:`FileNode::operator []` and/or :ocv:class:`FileNodeIterator`.
 109
 110  #.
 111    Close the storage using :ocv:func:`FileStorage::release`.
 112
 113 Here is how to read the file created by the code sample above: ::
 114
 115     FileStorage fs2("test.yml", FileStorage::READ);
 116
 117     // first method: use (type) operator on FileNode.
 118     int frameCount = (int)fs2["frameCount"];
 119
 120     std::string date;
 121     // second method: use FileNode::operator >>
 122     fs2["calibrationDate"] >> date;
 123
 124     Mat cameraMatrix2, distCoeffs2;
 125     fs2["cameraMatrix"] >> cameraMatrix2;
 126     fs2["distCoeffs"] >> distCoeffs2;
 127
 128     cout << "frameCount: " << frameCount << endl
 129          << "calibration date: " << date << endl
 130          << "camera matrix: " << cameraMatrix2 << endl
 131          << "distortion coeffs: " << distCoeffs2 << endl;
 132
 133     FileNode features = fs2["features"];
 134     FileNodeIterator it = features.begin(), it_end = features.end();
 135     int idx = 0;
 136     std::vector<uchar> lbpval;
 137
 138     // iterate through a sequence using FileNodeIterator
 139     for( ; it != it_end; ++it, idx++ )
 140     {
 141         cout << "feature #" << idx << ": ";
 142         cout << "x=" << (int)(*it)["x"] << ", y=" << (int)(*it)["y"] << ", lbp: (";
 143         // you can also easily read numerical arrays using FileNode >> std::vector operator.
 144         (*it)["lbp"] >> lbpval;
 145         for( int i = 0; i < (int)lbpval.size(); i++ )
 146             cout << " " << (int)lbpval[i];
 147         cout << ")" << endl;
 148     }
 149     fs.release();
 150
 151 FileStorage
 152 -----------
 153 .. ocv:class:: FileStorage
 154
 155 XML/YAML file storage class that encapsulates all the information necessary for writing or reading data to/from a file.
 156
 157 FileStorage::FileStorage
 158 ------------------------
 159 The constructors.
 160
 161 .. ocv:function:: FileStorage::FileStorage()
 162
 163 .. ocv:function:: FileStorage::FileStorage(const string& source, int flags, const string& encoding=string())
 164
 165     :param source: Name of the file to open or the text string to read the data from. Extension of the file (``.xml`` or ``.yml``/``.yaml``) determines its format (XML or YAML respectively). Also you can append ``.gz`` to work with compressed files, for example ``myHugeMatrix.xml.gz``. If both ``FileStorage::WRITE`` and ``FileStorage::MEMORY`` flags are specified, ``source`` is used just to specify the output file format (e.g. ``mydata.xml``, ``.yml`` etc.).
 166
 167     :param flags: Mode of operation. Possible values are:
 168
 169         * **FileStorage::READ** Open the file for reading.
 170
 171         * **FileStorage::WRITE** Open the file for writing.
 172
 173         * **FileStorage::APPEND** Open the file for appending.
 174
 175         * **FileStorage::MEMORY** Read data from ``source`` or write data to the internal buffer (which is returned by ``FileStorage::release``)
 176
 177     :param encoding: Encoding of the file. Note that UTF-16 XML encoding is not supported currently and you should use 8-bit encoding instead of it.
 178
 179 The full constructor opens the file. Alternatively you can use the default constructor and then call :ocv:func:`FileStorage::open`.
 180
 181
 182 FileStorage::open
 183 -----------------
 184 Opens a file.
 185
 186 .. ocv:function:: bool FileStorage::open(const string& filename, int flags, const string& encoding=string())
 187
 188     :param filename: Name of the file to open or the text string to read the data from.
 189                      Extension of the file (``.xml`` or ``.yml``/``.yaml``) determines its format (XML or YAML respectively).
 190                      Also you can append ``.gz`` to work with compressed files, for example ``myHugeMatrix.xml.gz``.
 191                      If both ``FileStorage::WRITE`` and ``FileStorage::MEMORY`` flags are specified, ``source``
 192                      is used just to specify the output file format (e.g. ``mydata.xml``, ``.yml`` etc.).
 193
 194     :param flags: Mode of operation. See FileStorage constructor for more details.
 195
 196     :param encoding: Encoding of the file. Note that UTF-16 XML encoding is not supported currently and you should use 8-bit encoding instead of it.
 197
 198
 199 See description of parameters in :ocv:func:`FileStorage::FileStorage`. The method calls :ocv:func:`FileStorage::release` before opening the file.
 200
 201
 202 FileStorage::isOpened
 203 ---------------------
 204 Checks whether the file is opened.
 205
 206 .. ocv:function:: bool FileStorage::isOpened() const
 207
 208     :returns: ``true`` if the object is associated with the current file and ``false`` otherwise.
 209
 210 It is a good practice to call this method after you tried to open a file.
 211
 212
 213 FileStorage::release
 214 --------------------
 215 Closes the file and releases all the memory buffers.
 216
 217 .. ocv:function:: void FileStorage::release()
 218
 219 Call this method after all I/O operations with the storage are finished.
 220
 221
 222 FileStorage::releaseAndGetString
 223 --------------------------------
 224 Closes the file and releases all the memory buffers.
 225
 226 .. ocv:function:: string FileStorage::releaseAndGetString()
 227
 228 Call this method after all I/O operations with the storage are finished. If the storage was opened for writing data and ``FileStorage::WRITE`` was specified
 229
 230
 231 FileStorage::getFirstTopLevelNode
 232 ---------------------------------
 233 Returns the first element of the top-level mapping.
 234
 235 .. ocv:function:: FileNode FileStorage::getFirstTopLevelNode() const
 236
 237     :returns: The first element of the top-level mapping.
 238
 239
 240 FileStorage::root
 241 -----------------
 242 Returns the top-level mapping
 243
 244 .. ocv:function:: FileNode FileStorage::root(int streamidx=0) const
 245
 246     :param streamidx: Zero-based index of the stream. In most cases there is only one stream in the file. However, YAML supports multiple streams and so there can be several.
 247
 248     :returns: The top-level mapping.
 249
 250
 251 FileStorage::operator[]
 252 -----------------------
 253 Returns the specified element of the top-level mapping.
 254
 255 .. ocv:function:: FileNode FileStorage::operator[](const string& nodename) const
 256
 257 .. ocv:function:: FileNode FileStorage::operator[](const char* nodename) const
 258
 259     :param nodename: Name of the file node.
 260
 261     :returns: Node with the given name.
 262
 263
 264 FileStorage::operator*
 265 ----------------------
 266 Returns the obsolete C FileStorage structure.
 267
 268 .. ocv:function:: CvFileStorage* FileStorage::operator *()
 269
 270 .. ocv:function:: const CvFileStorage* FileStorage::operator *() const
 271
 272     :returns: Pointer to the underlying C FileStorage structure
 273
 274
 275 FileStorage::writeRaw
 276 ---------------------
 277 Writes multiple numbers.
 278
 279 .. ocv:function:: void FileStorage::writeRaw( const string& fmt, const uchar* vec, size_t len )
 280
 281      :param fmt: Specification of each array element that has the following format  ``([count]{'u'|'c'|'w'|'s'|'i'|'f'|'d'})...`` where the characters correspond to fundamental C++ types:
 282
 283             * **u** 8-bit unsigned number
 284
 285             * **c** 8-bit signed number
 286
 287             * **w** 16-bit unsigned number
 288
 289             * **s** 16-bit signed number
 290
 291             * **i** 32-bit signed number
 292
 293             * **f** single precision floating-point number
 294
 295             * **d** double precision floating-point number
 296
 297             * **r** pointer, 32 lower bits of which are written as a signed integer. The type can be used to store structures with links between the elements.
 298
 299             ``count``  is the optional counter of values of a given type. For example,  ``2if``  means that each array element is a structure of 2 integers, followed by a single-precision floating-point number. The equivalent notations of the above specification are ' ``iif`` ', ' ``2i1f`` ' and so forth. Other examples:  ``u``  means that the array consists of bytes, and  ``2d``  means the array consists of pairs  of doubles.
 300
 301      :param vec: Pointer to the written array.
 302
 303      :param len: Number of the ``uchar`` elements to write.
 304
 305 Writes one or more numbers of the specified format to the currently written structure. Usually it is more convenient to use :ocv:func:`operator <<` instead of this method.
 306
 307 FileStorage::writeObj
 308 ---------------------
 309 Writes the registered C structure (CvMat, CvMatND, CvSeq).
 310
 311 .. ocv:function:: void FileStorage::writeObj( const string& name, const void* obj )
 312
 313     :param name: Name of the written object.
 314
 315     :param obj: Pointer to the object.
 316
 317 See :ocv:cfunc:`Write` for details.
 318
 319
 320 FileStorage::getDefaultObjectName
 321 ---------------------------------
 322 Returns the normalized object name for the specified name of a file.
 323
 324 .. ocv:function:: static string FileStorage::getDefaultObjectName(const string& filename)
 325
 326    :param filename: Name of a file
 327
 328    :returns: The normalized object name.
 329
 330
 331 operator <<
 332 -----------
 333 Writes data to a file storage.
 334
 335 .. ocv:function:: template<typename _Tp> FileStorage& operator << (FileStorage& fs, const _Tp& value)
 336
 337 .. ocv:function:: template<typename _Tp> FileStorage& operator << ( FileStorage& fs, const vector<_Tp>& vec )
 338
 339     :param fs: Opened file storage to write data.
 340
 341     :param value: Value to be written to the file storage.
 342
 343     :param vec: Vector of values to be written to the file storage.
 344
 345 It is the main function to write data to a file storage. See an example of its usage at the beginning of the section.
 346
 347
 348 operator >>
 349 -----------
 350 Reads data from a file storage.
 351
 352 .. ocv:function:: template<typename _Tp> void operator >> (const FileNode& n, _Tp& value)
 353
 354 .. ocv:function:: template<typename _Tp> void operator >> (const FileNode& n, vector<_Tp>& vec)
 355
 356 .. ocv:function:: template<typename _Tp> FileNodeIterator& operator >> (FileNodeIterator& it, _Tp& value)
 357
 358 .. ocv:function:: template<typename _Tp> FileNodeIterator& operator >> (FileNodeIterator& it, vector<_Tp>& vec)
 359
 360     :param n: Node from which data will be read.
 361
 362     :param it: Iterator from which data will be read.
 363
 364     :param value: Value to be read from the file storage.
 365
 366     :param vec: Vector of values to be read from the file storage.
 367
 368 It is the main function to read data from a file storage. See an example of its usage at the beginning of the section.
 369
 370
 371 FileNode
 372 --------
 373 .. ocv:class:: FileNode
 374
 375 File Storage Node class. The node is used to store each and every element of the file storage opened for reading. When XML/YAML file is read, it is first parsed and stored in the memory as a hierarchical collection of nodes. Each node can be a “leaf” that is contain a single number or a string, or be a collection of other nodes. There can be named collections (mappings) where each element has a name and it is accessed by a name, and ordered collections (sequences) where elements do not have names but rather accessed by index. Type of the file node can be determined using :ocv:func:`FileNode::type` method.
 376
 377 Note that file nodes are only used for navigating file storages opened for reading. When a file storage is opened for writing, no data is stored in memory after it is written.
 378
 379
 380 FileNode::FileNode
 381 ------------------
 382 The constructors.
 383
 384 .. ocv:function:: FileNode::FileNode()
 385
 386 .. ocv:function:: FileNode::FileNode(const CvFileStorage* fs, const CvFileNode* node)
 387
 388 .. ocv:function:: FileNode::FileNode(const FileNode& node)
 389
 390     :param fs: Pointer to the obsolete file storage structure.
 391
 392     :param node: File node to be used as initialization for the created file node.
 393
 394 These constructors are used to create a default file node, construct it from obsolete structures or from the another file node.
 395
 396
 397 FileNode::operator[]
 398 --------------------
 399 Returns element of a mapping node or a sequence node.
 400
 401 .. ocv:function:: FileNode FileNode::operator[](const string& nodename) const
 402
 403 .. ocv:function:: FileNode FileNode::operator[](const char* nodename) const
 404
 405 .. ocv:function:: FileNode FileNode::operator[](int i) const
 406
 407     :param nodename: Name of an element in the mapping node.
 408
 409     :param i: Index of an element in the sequence node.
 410
 411     :returns: Returns the element with the given identifier.
 412
 413
 414 FileNode::type
 415 --------------
 416 Returns type of the node.
 417
 418 .. ocv:function:: int FileNode::type() const
 419
 420     :returns: Type of the node. Possible values are:
 421
 422         * **FileNode::NONE** Empty node.
 423
 424         * **FileNode::INT** Integer.
 425
 426         * **FileNode::REAL** Floating-point number.
 427
 428         * **FileNode::FLOAT** Synonym or ``REAL``.
 429
 430         * **FileNode::STR** Text string in UTF-8 encoding.
 431
 432         * **FileNode::STRING** Synonym for ``STR``.
 433
 434         * **FileNode::REF** Integer of type ``size_t``. Typically used for storing complex dynamic structures where some elements reference the others.
 435
 436         * **FileNode::SEQ** Sequence.
 437
 438         * **FileNode::MAP** Mapping.
 439
 440         * **FileNode::FLOW** Compact representation of a sequence or mapping. Used only by the YAML writer.
 441
 442         * **FileNode::USER** Registered object (e.g. a matrix).
 443
 444         * **FileNode::EMPTY** Empty structure (sequence or mapping).
 445
 446         * **FileNode::NAMED** The node has a name (i.e. it is an element of a mapping).
 447
 448
 449 FileNode::empty
 450 ---------------
 451 Checks whether the node is empty.
 452
 453 .. ocv:function:: bool FileNode::empty() const
 454
 455     :returns: ``true`` if the node is empty.
 456
 457
 458 FileNode::isNone
 459 ----------------
 460 Checks whether the node is a "none" object
 461
 462 .. ocv:function:: bool FileNode::isNone() const
 463
 464     :returns: ``true`` if the node is a "none" object.
 465
 466
 467 FileNode::isSeq
 468 ---------------
 469 Checks whether the node is a sequence.
 470
 471 .. ocv:function:: bool FileNode::isSeq() const
 472
 473     :returns: ``true`` if the node is a sequence.
 474
 475
 476 FileNode::isMap
 477 ---------------
 478 Checks whether the node is a mapping.
 479
 480 .. ocv:function:: bool FileNode::isMap() const
 481
 482     :returns: ``true`` if the node is a mapping.
 483
 484
 485 FileNode::isInt
 486 ---------------
 487 Checks whether the node is an integer.
 488
 489 .. ocv:function:: bool FileNode::isInt() const
 490
 491     :returns: ``true`` if the node is an integer.
 492
 493
 494 FileNode::isReal
 495 ----------------
 496 Checks whether the node is a floating-point number.
 497
 498 .. ocv:function:: bool FileNode::isReal() const
 499
 500     :returns: ``true`` if the node is a floating-point number.
 501
 502
 503 FileNode::isString
 504 ------------------
 505 Checks whether the node is a text string.
 506
 507 .. ocv:function:: bool FileNode::isString() const
 508
 509     :returns: ``true`` if the node is a text string.
 510
 511
 512 FileNode::isNamed
 513 -----------------
 514 Checks whether the node has a name.
 515
 516 .. ocv:function:: bool FileNode::isNamed() const
 517
 518     :returns: ``true`` if the node has a name.
 519
 520
 521 FileNode::name
 522 --------------
 523 Returns the node name.
 524
 525 .. ocv:function:: string FileNode::name() const
 526
 527     :returns: The node name or an empty string if the node is nameless.
 528
 529
 530 FileNode::size
 531 --------------
 532 Returns the number of elements in the node.
 533
 534 .. ocv:function:: size_t FileNode::size() const
 535
 536     :returns: The number of elements in the node, if it is a sequence or mapping, or 1 otherwise.
 537
 538
 539 FileNode::operator int
 540 ----------------------
 541 Returns the node content as an integer.
 542
 543 .. ocv:function:: FileNode::operator int() const
 544
 545     :returns: The node content as an integer. If the node stores a floating-point number, it is rounded.
 546
 547
 548 FileNode::operator float
 549 ------------------------
 550 Returns the node content as float.
 551
 552 .. ocv:function:: FileNode::operator float() const
 553
 554     :returns: The node content as float.
 555
 556
 557 FileNode::operator double
 558 -------------------------
 559 Returns the node content as double.
 560
 561 .. ocv:function:: FileNode::operator double() const
 562
 563     :returns: The node content as double.
 564
 565
 566 FileNode::operator string
 567 -------------------------
 568 Returns the node content as text string.
 569
 570 .. ocv:function:: FileNode::operator string() const
 571
 572     :returns: The node content as a text string.
 573
 574
 575 FileNode::operator*
 576 -------------------
 577 Returns pointer to the underlying obsolete file node structure.
 578
 579 .. ocv:function:: CvFileNode* FileNode::operator *()
 580
 581     :returns: Pointer to the underlying obsolete file node structure.
 582
 583
 584 FileNode::begin
 585 ---------------
 586 Returns the iterator pointing to the first node element.
 587
 588 .. ocv:function:: FileNodeIterator FileNode::begin() const
 589
 590    :returns: Iterator pointing to the first node element.
 591
 592
 593 FileNode::end
 594 -------------
 595 Returns the iterator pointing to the element following the last node element.
 596
 597 .. ocv:function:: FileNodeIterator FileNode::end() const
 598
 599     :returns: Iterator pointing to the element following the last node element.
 600
 601
 602 FileNode::readRaw
 603 -----------------
 604 Reads node elements to the buffer with the specified format.
 605
 606 .. ocv:function:: void FileNode::readRaw( const string& fmt, uchar* vec, size_t len ) const
 607
 608     :param fmt: Specification of each array element. It has the same format as in :ocv:func:`FileStorage::writeRaw`.
 609
 610     :param vec: Pointer to the destination array.
 611
 612     :param len: Number of elements to read. If it is greater than number of remaining elements then all of them will be read.
 613
 614 Usually it is more convenient to use :ocv:func:`operator >>` instead of this method.
 615
 616 FileNode::readObj
 617 -----------------
 618 Reads the registered object.
 619
 620 .. ocv:function:: void* FileNode::readObj() const
 621
 622     :returns: Pointer to the read object.
 623
 624 See :ocv:cfunc:`Read` for details.
 625
 626 FileNodeIterator
 627 ----------------
 628 .. ocv:class:: FileNodeIterator
 629
 630 The class ``FileNodeIterator`` is used to iterate through sequences and mappings. A standard STL notation, with ``node.begin()``, ``node.end()`` denoting the beginning and the end of a sequence, stored in ``node``.  See the data reading sample in the beginning of the section.
 631
 632
 633 FileNodeIterator::FileNodeIterator
 634 ----------------------------------
 635 The constructors.
 636
 637 .. ocv:function:: FileNodeIterator::FileNodeIterator()
 638
 639 .. ocv:function:: FileNodeIterator::FileNodeIterator(const CvFileStorage* fs, const CvFileNode* node, size_t ofs=0)
 640
 641 .. ocv:function:: FileNodeIterator::FileNodeIterator(const FileNodeIterator& it)
 642
 643     :param fs: File storage for the iterator.
 644
 645     :param node: File node for the iterator.
 646
 647     :param ofs: Index of the element in the node. The created iterator will point to this element.
 648
 649     :param it: Iterator to be used as initialization for the created iterator.
 650
 651 These constructors are used to create a default iterator, set it to specific element in a file node or construct it from another iterator.
 652
 653
 654 FileNodeIterator::operator*
 655 ---------------------------
 656 Returns the currently observed element.
 657
 658 .. ocv:function:: FileNode FileNodeIterator::operator *() const
 659
 660     :returns: Currently observed element.
 661
 662
 663 FileNodeIterator::operator->
 664 ----------------------------
 665 Accesses methods of the currently observed element.
 666
 667 .. ocv:function:: FileNode FileNodeIterator::operator ->() const
 668
 669
 670 FileNodeIterator::operator ++
 671 -----------------------------
 672 Moves iterator to the next node.
 673
 674 .. ocv:function:: FileNodeIterator& FileNodeIterator::operator ++ ()
 675
 676 .. ocv:function:: FileNodeIterator FileNodeIterator::operator ++ (int)
 677
 678
 679 FileNodeIterator::operator --
 680 -----------------------------
 681 Moves iterator to the previous node.
 682
 683 .. ocv:function:: FileNodeIterator& FileNodeIterator::operator -- ()
 684
 685 .. ocv:function:: FileNodeIterator FileNodeIterator::operator -- (int)
 686
 687
 688 FileNodeIterator::operator +=
 689 -----------------------------
 690 Moves iterator forward by the specified offset.
 691
 692 .. ocv:function:: FileNodeIterator& FileNodeIterator::operator +=( int ofs )
 693
 694     :param ofs: Offset (possibly negative) to move the iterator.
 695
 696
 697 FileNodeIterator::operator -=
 698 -----------------------------
 699 Moves iterator backward by the specified offset (possibly negative).
 700
 701 .. ocv:function:: FileNodeIterator& FileNodeIterator::operator -=( int ofs )
 702
 703     :param ofs: Offset (possibly negative) to move the iterator.
 704
 705
 706 FileNodeIterator::readRaw
 707 -------------------------
 708 Reads node elements to the buffer with the specified format.
 709
 710 .. ocv:function:: FileNodeIterator& FileNodeIterator::readRaw( const string& fmt, uchar* vec, size_t maxCount=(size_t)INT_MAX )
 711
 712     :param fmt: Specification of each array element. It has the same format as in :ocv:func:`FileStorage::writeRaw`.
 713
 714     :param vec: Pointer to the destination array.
 715
 716     :param maxCount: Number of elements to read. If it is greater than number of remaining elements then all of them will be read.
 717
 718 Usually it is more convenient to use :ocv:func:`operator >>` instead of this method.