Class cv::FileStorage#

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

#include <opencv2/core/persistence.hpp>

Collaboration diagram for cv::FileStorage:

Public Types#

file storage mode

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),
    FORMAT_YAML_1_0 = (4<<3),
    BASE64 = 64,
    WRITE_BASE64 = BASE64 | WRITE
}

enum State {
    UNDEFINED = 0,
    VALUE_EXPECTED = 1,
    NAME_EXPECTED = 2,
    INSIDE_MAP = 4
}

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, samples/dnn/classification.cpp, and samples/python/snippets/chromatic_aberration_correction.py.

Member Enumeration Documentation#

enum Mode

file storage mode

`READ` Python: `cv.FileStorage_READ`	value, open the file for reading
`WRITE` Python: `cv.FileStorage_WRITE`	value, open the file for writing
`APPEND` Python: `cv.FileStorage_APPEND`	value, open the file for appending
`MEMORY` Python: `cv.FileStorage_MEMORY`	flag, read data from source or write data to the internal buffer (which is returned by FileStorage::release)
`FORMAT_MASK` Python: `cv.FileStorage_FORMAT_MASK`	mask for format flags
`FORMAT_AUTO` Python: `cv.FileStorage_FORMAT_AUTO`	flag, auto format
`FORMAT_XML` Python: `cv.FileStorage_FORMAT_XML`	flag, XML format
`FORMAT_YAML` Python: `cv.FileStorage_FORMAT_YAML`	flag, YAML format
`FORMAT_JSON` Python: `cv.FileStorage_FORMAT_JSON`	flag, JSON format
`FORMAT_YAML_1_0` Python: `cv.FileStorage_FORMAT_YAML_1_0`	flag, Legacy YAML 1.0 format (strict headers, booleans as ints)
`BASE64` Python: `cv.FileStorage_BASE64`	flag, write rawdata in Base64 by default. (consider using WRITE_BASE64)
`WRITE_BASE64` Python: `cv.FileStorage_WRITE_BASE64`	flag, enable both WRITE and BASE64

enum State

`UNDEFINED` Python: `cv.FileStorage_UNDEFINED`	Initial or uninitialized state.
`VALUE_EXPECTED` Python: `cv.FileStorage_VALUE_EXPECTED`	Expecting a value in the current position.
`NAME_EXPECTED` Python: `cv.FileStorage_NAME_EXPECTED`	Expecting a key/name in the current position.
`INSIDE_MAP` Python: `cv.FileStorage_INSIDE_MAP`	Indicates being inside a map (a set of key-value pairs).

Constructor & Destructor Documentation#

FileStorage()#

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()#

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. You can also specify a compression level from 0 to 9 by appending it to the extension (e.g. “.gz0” for no compression, “.gz9” for high compression). The last digit will be truncated internally to write/read. (e.g. If “a.xml.gz9” is specified, “a.xml.gz” is used for the actual file name.) 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()#

cv::FileStorage::~FileStorage()

the destructor. calls release()

Member Function Documentation#

endWriteStruct()#

void cv::FileStorage::endWriteStruct()

Python:

cv.FileStorage.endWriteStruct()

Finishes writing nested structure (should pair startWriteStruct())

getFirstTopLevelNode()#

FileNode cv::FileStorage::getFirstTopLevelNode()

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()

Python:

cv.FileStorage.getFormat() -> retval

Returns the current format.

Returns

The current format, see FileStorage::Mode

isOpened()#

bool cv::FileStorage::isOpened()

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.

open()#

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

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. You can also specify a compression level from 0 to 9 by appending it to the extension (e.g. “.gz0” for no compression, “.gz9” for high compression). The last digit will be truncated internally to write/read. (e.g. If “a.xml.gz9” is specified, “a.xml.gz” is used for the actual file name.) 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.

operator #

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

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 #

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

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()#

void cv::FileStorage::release()

Python:

cv.FileStorage.release()

Closes the file and releases all the memory buffers.

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

releaseAndGetString()#

String cv::FileStorage::releaseAndGetString()

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)

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])

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()#

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

Python:

cv.FileStorage.write(name, val)

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

write()#

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

Python:

cv.FileStorage.write(name, val)

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

write()#

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

Python:

cv.FileStorage.write(name, val)

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

write()#

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

Python:

cv.FileStorage.write(name, val)

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

write()#

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

Python:

cv.FileStorage.write(name, val)

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

write()#

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

Python:

cv.FileStorage.write(name, val)

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()#

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

Python:

cv.FileStorage.write(name, val)

writeComment()#

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

Python:

cv.FileStorage.writeComment(comment[, append])

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.

getDefaultObjectName()#

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

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

Parameters

filename — Name of a file

Returns

The normalized object name.

Member Data Documentation#

elname#

std::string cv::FileStorage::elname

p#

Ptr< Impl > cv::FileStorage::p

state#

int cv::FileStorage::state

Source file#

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

opencv2/core/persistence.hpp

Class cv::FileStorage#

Public Types#

Detailed Description#

Member Enumeration Documentation#

enum Mode

enum State

Constructor & Destructor Documentation#

FileStorage()#

FileStorage()#

~FileStorage()#

Member Function Documentation#

endWriteStruct()#

getFirstTopLevelNode()#

getFormat()#

isOpened()#

open()#

operator#

operator#

release()#

releaseAndGetString()#

root()#

startWriteStruct()#

write()#

write()#

write()#

write()#

write()#

write()#

write()#

writeComment()#

writeRaw()#

getDefaultObjectName()#

Member Data Documentation#

elname#

p#

state#

Source file#

operator #

operator #