| OpenCV 5.0.0alpha Open Source Computer Vision

Loading...
Searching...
No Matches
Public Types | Public Member Functions | Static Public Member Functions | Public Attributes | List of all members
cv::FileStorage Class Reference
Core functionality » XML/YAML/JSON Persistence

XML/YAML/JSON file storage class that encapsulates all the information necessary for writing or reading data to/from a file. More...

`#include <opencv2/core/persistence.hpp>`

Collaboration diagram for cv::FileStorage:

## Public Types
enum | Mode { READ = 0 , WRITE = 1 , APPEND = 2 , MEMORY = 4 , FORMAT_MASK = (7<<3) , FORMAT_AUTO = 0 , FORMAT_XML = (1<<3) , FORMAT_YAML = (2<<3) , FORMAT_JSON = (3<<3) , BASE64 = 64 , WRITE_BASE64 = BASE64 | WRITE }
| file storage mode More...
enum | State { UNDEFINED = 0 , VALUE_EXPECTED = 1 , NAME_EXPECTED = 2 , INSIDE_MAP = 4 }

## Public Member Functions
| FileStorage ()
| The constructors.
| FileStorage (const String &filename, int flags, const String &encoding=String())
virtual | ~FileStorage ()
| the destructor. calls release()
void | endWriteStruct ()
| Finishes writing nested structure (should pair startWriteStruct())
FileNode | getFirstTopLevelNode () const
| Returns the first element of the top-level mapping.
int | getFormat () const
| Returns the current format.
virtual bool | isOpened () const
| Checks whether the file is opened.
virtual bool | open (const String &filename, int flags, const String &encoding=String())
| Opens a file.
FileNode | operator[] (const char *nodename) const
FileNode | operator[] (const String &nodename) const
| Returns the specified element of the top-level mapping.
virtual void | release ()
| Closes the file and releases all the memory buffers.
virtual String | releaseAndGetString ()
| Closes the file and releases all the memory buffers.
FileNode | root (int streamidx=0) const
| Returns the top-level mapping.
void | startWriteStruct (const String &name, int flags, const String &typeName=String())
| Starts to write a nested structure (sequence or a mapping).
void | write (const String &name, const Mat &val)
| This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
void | write (const String &name, const std::vector< String > &val)
| This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
void | write (const String &name, const String &val)
| This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
void | write (const String &name, double val)
| This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
void | write (const String &name, int val)
| Simplified writing API to use with bindings.
void | write (const String &name, int64_t val)
| This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
void | writeComment (const String &comment, bool append=false)
| Writes a comment.
void | writeRaw (const String &fmt, const void *vec, size_t len)
| Writes multiple numbers.

## Static Public Member Functions
static String | getDefaultObjectName (const String &filename)
| Returns the normalized object name for the specified name of a file.

## Public Attributes
std::string | elname
Ptr< Impl > | p
int | state

## Detailed Description

XML/YAML/JSON file storage class that encapsulates all the information necessary for writing or reading data to/from a file.

Examples
  samples/cpp/tutorial_code/core/file_input_output/file_input_output.cpp, samples/cpp/tutorial_code/features/Homography/decompose_homography.cpp, samples/cpp/tutorial_code/features/Homography/homography_from_camera_displacement.cpp, samples/cpp/tutorial_code/features/Homography/pose_from_homography.cpp, and samples/dnn/classification.cpp.

## Member Enumeration Documentation

## ◆ Mode

enum cv::FileStorage::Mode

file storage mode

Enumerator
READ | value, open the file for reading
WRITE | value, open the file for writing
APPEND | value, open the file for appending
MEMORY | flag, read data from source or write data to the internal buffer (which is returned by FileStorage::release)
FORMAT_MASK | mask for format flags
FORMAT_AUTO | flag, auto format
FORMAT_XML | flag, XML format
FORMAT_YAML | flag, YAML format
FORMAT_JSON | flag, JSON format
BASE64 | flag, write rawdata in Base64 by default. (consider using WRITE_BASE64)
WRITE_BASE64 | flag, enable both WRITE and BASE64

## ◆ State

enum cv::FileStorage::State

Enumerator
UNDEFINED | Initial or uninitialized state.
VALUE_EXPECTED | Expecting a value in the current position.
NAME_EXPECTED | Expecting a key/name in the current position.
INSIDE_MAP | Indicates being inside a map (a set of key-value pairs).

## Constructor & Destructor Documentation

## ◆ FileStorage() [1/2]

cv::FileStorage::FileStorage | ( |  | ) |

Python:
| cv.FileStorage( |  | ) -> | <FileStorage object>
| cv.FileStorage( | filename, flags[, encoding] | ) -> | <FileStorage object>

The constructors.

The full constructor opens the file. Alternatively you can use the default constructor and then call FileStorage::open.

## ◆ FileStorage() [2/2]

cv::FileStorage::FileStorage | ( | const String & | filename,
|  | int | flags,
|  | const String & | encoding = String() )

Python:
| cv.FileStorage( |  | ) -> | <FileStorage object>
| cv.FileStorage( | filename, flags[, encoding] | ) -> | <FileStorage object>

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. Opens a file.

See description of parameters in FileStorage::FileStorage. The method calls FileStorage::release before opening the file.

Parameters

  filename | Name of the file to open or the text string to read the data from. Extension of the file (.xml, .yml/.yaml or .json) determines its format (XML, YAML or JSON 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.). A file name can also contain parameters. You can use this format, "*?base64" (e.g. "file.json?base64" (case sensitive)), as an alternative to FileStorage::BASE64 flag.
  flags | Mode of operation. One of FileStorage::Mode
  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.

## ◆ ~FileStorage()

virtual cv::FileStorage::~FileStorage | ( |  | ) |
| virtual

the destructor. calls release()

## Member Function Documentation

## ◆ endWriteStruct()

void cv::FileStorage::endWriteStruct | ( |  | ) |

Python:
| cv.FileStorage.endWriteStruct( |  | ) -> | None

Finishes writing nested structure (should pair startWriteStruct())

## ◆ getDefaultObjectName()

static String cv::FileStorage::getDefaultObjectName | ( | const String & | filename | ) |
| static

Returns the normalized object name for the specified name of a file.

Parameters

  filename | Name of a file

Returns
  The normalized object name.

## ◆ getFirstTopLevelNode()

FileNode cv::FileStorage::getFirstTopLevelNode | ( |  | ) | const

Python:
| cv.FileStorage.getFirstTopLevelNode( |  | ) -> | retval

Returns the first element of the top-level mapping.

Returns
  The first element of the top-level mapping.

## ◆ getFormat()

int cv::FileStorage::getFormat | ( |  | ) | const

Python:
| cv.FileStorage.getFormat( |  | ) -> | retval

Returns the current format.

Returns
  The current format, see FileStorage::Mode

## ◆ isOpened()

virtual bool cv::FileStorage::isOpened | ( |  | ) | const
| virtual

Python:
| cv.FileStorage.isOpened( |  | ) -> | retval

Checks whether the file is opened.

Returns
  true if the object is associated with the current file and false otherwise. It is a good practice to call this method after you tried to open a file.

Examples
  samples/cpp/tutorial_code/core/file_input_output/file_input_output.cpp.

## ◆ open()

virtual bool cv::FileStorage::open | ( | const String & | filename,
|  | int | flags,
|  | const String & | encoding = String() )
| virtual

Python:
| cv.FileStorage.open( | filename, flags[, encoding] | ) -> | retval

Opens a file.

See description of parameters in FileStorage::FileStorage. The method calls FileStorage::release before opening the file.

Parameters

  filename | Name of the file to open or the text string to read the data from. Extension of the file (.xml, .yml/.yaml or .json) determines its format (XML, YAML or JSON 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.). A file name can also contain parameters. You can use this format, "*?base64" (e.g. "file.json?base64" (case sensitive)), as an alternative to FileStorage::BASE64 flag.
  flags | Mode of operation. One of FileStorage::Mode
  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.

Examples
  samples/cpp/tutorial_code/core/file_input_output/file_input_output.cpp.

## ◆ operator[]() [1/2]

FileNode cv::FileStorage::operator[] | ( | const char * | nodename | ) | const

Python:
| cv.FileStorage.getNode( | nodename | ) -> | retval

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

## ◆ operator[]() [2/2]

FileNode cv::FileStorage::operator[] | ( | const String & | nodename | ) | const

Python:
| cv.FileStorage.getNode( | nodename | ) -> | retval

Returns the specified element of the top-level mapping.

Parameters

  nodename | Name of the file node.

Returns
  Node with the given name.

## ◆ release()

virtual void cv::FileStorage::release | ( |  | ) |
| virtual

Python:
| cv.FileStorage.release( |  | ) -> | None

Closes the file and releases all the memory buffers.

Call this method after all I/O operations with the storage are finished.

Examples
  samples/cpp/tutorial_code/core/file_input_output/file_input_output.cpp.

## ◆ releaseAndGetString()

virtual String cv::FileStorage::releaseAndGetString | ( |  | ) |
| virtual

Python:
| cv.FileStorage.releaseAndGetString( |  | ) -> | retval

Closes the file and releases all the memory buffers.

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

## ◆ root()

FileNode cv::FileStorage::root | ( | int | streamidx = 0 | ) | const

Python:
| cv.FileStorage.root( | [, streamidx] | ) -> | retval

Returns the top-level mapping.

Parameters

  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.

Returns
  The top-level mapping.

## ◆ startWriteStruct()

void cv::FileStorage::startWriteStruct | ( | const String & | name,
|  | int | flags,
|  | const String & | typeName = String() )

Python:
| cv.FileStorage.startWriteStruct( | name, flags[, typeName] | ) -> | None

Starts to write a nested structure (sequence or a mapping).

Parameters

  name | name of the structure. When writing to sequences (a.k.a. "arrays"), pass an empty string.
  flags | type of the structure (FileNode::MAP or FileNode::SEQ (both with optional FileNode::FLOW)).
  typeName | optional name of the type you store. The effect of setting this depends on the storage format. I.e. if the format has a specification for storing type information, this parameter is used.

## ◆ write() [1/6]

void cv::FileStorage::write | ( | const String & | name,
|  | const Mat & | val )

Python:
| cv.FileStorage.write( | name, val | ) -> | None

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

## ◆ write() [2/6]

void cv::FileStorage::write | ( | const String & | name,
|  | const std::vector< String > & | val )

Python:
| cv.FileStorage.write( | name, val | ) -> | None

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

## ◆ write() [3/6]

void cv::FileStorage::write | ( | const String & | name,
|  | const String & | val )

Python:
| cv.FileStorage.write( | name, val | ) -> | None

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

## ◆ write() [4/6]

void cv::FileStorage::write | ( | const String & | name,
|  | double | val )

Python:
| cv.FileStorage.write( | name, val | ) -> | None

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

## ◆ write() [5/6]

void cv::FileStorage::write | ( | const String & | name,
|  | int | val )

Python:
| cv.FileStorage.write( | name, val | ) -> | None

Simplified writing API to use with bindings.

Parameters

  name | Name of the written object. When writing to sequences (a.k.a. "arrays"), pass an empty string.
  val | Value of the written object.

## ◆ write() [6/6]

void cv::FileStorage::write | ( | const String & | name,
|  | int64_t | val )

Python:
| cv.FileStorage.write( | name, val | ) -> | None

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

## ◆ writeComment()

void cv::FileStorage::writeComment | ( | const String & | comment,
|  | bool | append = false )

Python:
| cv.FileStorage.writeComment( | comment[, append] | ) -> | None

Writes a comment.

The function writes a comment into file storage. The comments are skipped when the storage is read.

Parameters

  comment | The written comment, single-line or multi-line
  append | If true, the function tries to put the comment at the end of current line. Else if the comment is multi-line, or if it does not fit at the end of the current line, the comment starts a new line.

## ◆ writeRaw()

void cv::FileStorage::writeRaw | ( | const String & | fmt,
|  | const void * | vec,
|  | size_t | len )

Writes multiple numbers.

Writes one or more numbers of the specified format to the currently written structure. Usually it is more convenient to use operator `<<` instead of this method.

Parameters

  fmt | Specification of each array element, see format specification
  vec | Pointer to the written array.
  len | Number of the uchar elements to write.

## Member Data Documentation

## ◆ elname

std::string cv::FileStorage::elname

## ◆ p

Ptr<Impl> cv::FileStorage::p

## ◆ state

int cv::FileStorage::state

The documentation for this class was generated from the following file:

- opencv2/core/persistence.hpp