OpenCV  4.5.1
Open Source Computer Vision
Public Types | Public Member Functions | Static Public Member Functions | Public Attributes | Related Functions | List of all members
cv::FileStorage Class Reference

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>

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. More...
 
 FileStorage (const String &filename, int flags, const String &encoding=String())
 Opens a file. More...
 
virtual ~FileStorage ()
 the destructor. calls release() More...
 
void endWriteStruct ()
 Finishes writing nested structure (should pair startWriteStruct()) More...
 
FileNode getFirstTopLevelNode () const
 Returns the first element of the top-level mapping. More...
 
int getFormat () const
 Returns the current format. More...
 
virtual bool isOpened () const
 Checks whether the file is opened. More...
 
virtual bool open (const String &filename, int flags, const String &encoding=String())
 Opens a file. More...
 
FileNode operator[] (const String &nodename) const
 Returns the specified element of the top-level mapping. More...
 
FileNode operator[] (const char *nodename) const
 
virtual void release ()
 Closes the file and releases all the memory buffers. More...
 
virtual String releaseAndGetString ()
 Closes the file and releases all the memory buffers. More...
 
FileNode root (int streamidx=0) const
 Returns the top-level mapping. More...
 
void startWriteStruct (const String &name, int flags, const String &typeName=String())
 Starts to write a nested structure (sequence or a mapping). More...
 
void write (const String &name, int val)
 Simplified writing API to use with bindings. More...
 
void write (const String &name, double val)
 
void write (const String &name, const String &val)
 
void write (const String &name, const Mat &val)
 
void write (const String &name, const std::vector< String > &val)
 
void writeComment (const String &comment, bool append=false)
 Writes a comment. More...
 
void writeRaw (const String &fmt, const void *vec, size_t len)
 Writes multiple numbers. More...
 

Static Public Member Functions

static String getDefaultObjectName (const String &filename)
 Returns the normalized object name for the specified name of a file. More...
 

Public Attributes

std::string elname
 
Ptr< Impl > p
 
int state
 

Related Functions

(Note that these are not member functions.)

FileStorageoperator<< (FileStorage &fs, const String &str)
 Writes string to a file storage. More...
 
void write (FileStorage &fs, const String &name, int value)
 
void write (FileStorage &fs, const String &name, float value)
 
void write (FileStorage &fs, const String &name, double value)
 
void write (FileStorage &fs, const String &name, const String &value)
 
void write (FileStorage &fs, const String &name, const Mat &value)
 
void write (FileStorage &fs, const String &name, const SparseMat &value)
 
void writeScalar (FileStorage &fs, int value)
 
void writeScalar (FileStorage &fs, float value)
 
void writeScalar (FileStorage &fs, double value)
 
void writeScalar (FileStorage &fs, const String &value)
 
template<typename _Tp >
static void write (FileStorage &fs, const _Tp &value)
 
template<>
void write (FileStorage &fs, const int &value)
 
template<>
void write (FileStorage &fs, const float &value)
 
template<>
void write (FileStorage &fs, const double &value)
 
template<>
void write (FileStorage &fs, const String &value)
 
template<typename _Tp >
static void write (FileStorage &fs, const Point_< _Tp > &pt)
 
template<typename _Tp >
static void write (FileStorage &fs, const Point3_< _Tp > &pt)
 
template<typename _Tp >
static void write (FileStorage &fs, const Size_< _Tp > &sz)
 
template<typename _Tp >
static void write (FileStorage &fs, const Complex< _Tp > &c)
 
template<typename _Tp >
static void write (FileStorage &fs, const Rect_< _Tp > &r)
 
template<typename _Tp , int cn>
static void write (FileStorage &fs, const Vec< _Tp, cn > &v)
 
template<typename _Tp , int m, int n>
static void write (FileStorage &fs, const Matx< _Tp, m, n > &x)
 
template<typename _Tp >
static void write (FileStorage &fs, const Scalar_< _Tp > &s)
 
static void write (FileStorage &fs, const Range &r)
 
template<typename _Tp >
static void write (FileStorage &fs, const std::vector< _Tp > &vec)
 
template<typename _Tp >
static void write (FileStorage &fs, const String &name, const Point_< _Tp > &pt)
 
template<typename _Tp >
static void write (FileStorage &fs, const String &name, const Point3_< _Tp > &pt)
 
template<typename _Tp >
static void write (FileStorage &fs, const String &name, const Size_< _Tp > &sz)
 
template<typename _Tp >
static void write (FileStorage &fs, const String &name, const Complex< _Tp > &c)
 
template<typename _Tp >
static void write (FileStorage &fs, const String &name, const Rect_< _Tp > &r)
 
template<typename _Tp , int cn>
static void write (FileStorage &fs, const String &name, const Vec< _Tp, cn > &v)
 
template<typename _Tp , int m, int n>
static void write (FileStorage &fs, const String &name, const Matx< _Tp, m, n > &x)
 
template<typename _Tp >
static void write (FileStorage &fs, const String &name, const Scalar_< _Tp > &s)
 
static void write (FileStorage &fs, const String &name, const Range &r)
 
static void write (FileStorage &fs, const String &name, const KeyPoint &kpt)
 
static void write (FileStorage &fs, const String &name, const DMatch &m)
 
template<typename _Tp , typename std::enable_if< std::is_enum< _Tp >::value >::type * = nullptr>
static void write (FileStorage &fs, const String &name, const _Tp &val)
 
template<typename _Tp >
static void write (FileStorage &fs, const String &name, const std::vector< _Tp > &vec)
 
template<typename _Tp >
static void write (FileStorage &fs, const String &name, const std::vector< std::vector< _Tp > > &vec)
 
template<typename _Tp >
static FileStorageoperator<< (FileStorage &fs, const _Tp &value)
 Writes data to a file storage. More...
 
static FileStorageoperator<< (FileStorage &fs, const char *str)
 Writes data to a file storage. More...
 
static FileStorageoperator<< (FileStorage &fs, char *value)
 Writes data to a file storage. More...
 

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/filestorage.cpp, samples/cpp/tutorial_code/features2D/Homography/decompose_homography.cpp, samples/cpp/tutorial_code/features2D/Homography/homography_from_camera_displacement.cpp, and samples/cpp/tutorial_code/features2D/Homography/pose_from_homography.cpp.

Member Enumeration Documentation

◆ 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 

returned by FileStorage::release)

flag, read data from source or write data to the internal buffer (which is

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

Enumerator
UNDEFINED 
VALUE_EXPECTED 
NAME_EXPECTED 
INSIDE_MAP 

Constructor & Destructor Documentation

◆ FileStorage() [1/2]

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

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:
<FileStorage object>=cv.FileStorage()
<FileStorage object>=cv.FileStorage(filename, flags[, encoding])

Opens a file.

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. See description of parameters in FileStorage::FileStorage. The method calls FileStorage::release before opening the file.

Parameters
filenameName 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.
flagsMode of operation. One of FileStorage::Mode
encodingEncoding 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:
None=cv.FileStorage.endWriteStruct()

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
filenameName of a file
Returns
The normalized object name.

◆ getFirstTopLevelNode()

FileNode cv::FileStorage::getFirstTopLevelNode ( ) const
Python:
retval=cv.FileStorage.getFirstTopLevelNode()

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:
retval=cv.FileStorage.getFormat()

Returns the current format.

Returns
The current format, see FileStorage::Mode

◆ isOpened()

virtual bool cv::FileStorage::isOpened ( ) const
virtual
Python:
retval=cv.FileStorage.isOpened()

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/filestorage.cpp.

◆ open()

virtual bool cv::FileStorage::open ( const String filename,
int  flags,
const String encoding = String() 
)
virtual
Python:
retval=cv.FileStorage.open(filename, flags[, encoding])

Opens a file.

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

Parameters
filenameName 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.
flagsMode of operation. One of FileStorage::Mode
encodingEncoding of the file. Note that UTF-16 XML encoding is not supported currently and you should use 8-bit encoding instead of it.

◆ operator[]() [1/2]

FileNode cv::FileStorage::operator[] ( const String nodename) const
Python:
retval=cv.FileStorage.getNode(nodename)

Returns the specified element of the top-level mapping.

Parameters
nodenameName of the file node.
Returns
Node with the given name.

◆ operator[]() [2/2]

FileNode cv::FileStorage::operator[] ( const char *  nodename) const
Python:
retval=cv.FileStorage.getNode(nodename)

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

◆ release()

virtual void cv::FileStorage::release ( )
virtual
Python:
None=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()

virtual String cv::FileStorage::releaseAndGetString ( )
virtual
Python:
retval=cv.FileStorage.releaseAndGetString()

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

Examples:
samples/cpp/filestorage.cpp.

◆ root()

FileNode cv::FileStorage::root ( int  streamidx = 0) const
Python:
retval=cv.FileStorage.root([, streamidx])

Returns the top-level mapping.

Parameters
streamidxZero-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:
None=cv.FileStorage.startWriteStruct(name, flags[, typeName])

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

Parameters
namename of the structure. When writing to sequences (a.k.a. "arrays"), pass an empty string.
flagstype of the structure (FileNode::MAP or FileNode::SEQ (both with optional FileNode::FLOW)).
typeNameoptional 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/5]

void cv::FileStorage::write ( const String name,
int  val 
)
Python:
None=cv.FileStorage.write(name, val)

Simplified writing API to use with bindings.

Parameters
nameName of the written object. When writing to sequences (a.k.a. "arrays"), pass an empty string.
valValue of the written object.

◆ write() [2/5]

void cv::FileStorage::write ( const String name,
double  val 
)
Python:
None=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() [3/5]

void cv::FileStorage::write ( const String name,
const String val 
)
Python:
None=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() [4/5]

void cv::FileStorage::write ( const String name,
const Mat val 
)
Python:
None=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() [5/5]

void cv::FileStorage::write ( const String name,
const std::vector< String > &  val 
)
Python:
None=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.

◆ writeComment()

void cv::FileStorage::writeComment ( const String comment,
bool  append = false 
)
Python:
None=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
commentThe written comment, single-line or multi-line
appendIf 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
fmtSpecification of each array element, see format specification
vecPointer to the written array.
lenNumber of the uchar elements to write.

Friends And Related Function Documentation

◆ operator<<() [1/4]

FileStorage & operator<< ( FileStorage fs,
const String str 
)
related

Writes string to a file storage.

◆ operator<<() [2/4]

template<typename _Tp >
static FileStorage & operator<< ( FileStorage fs,
const _Tp &  value 
)
related

Writes data to a file storage.

◆ operator<<() [3/4]

static FileStorage & operator<< ( FileStorage fs,
const char *  str 
)
related

Writes data to a file storage.

◆ operator<<() [4/4]

static FileStorage & operator<< ( FileStorage fs,
char *  value 
)
related

Writes data to a file storage.

◆ write() [1/35]

void write ( FileStorage fs,
const String name,
int  value 
)
related
Python:
None=cv.FileStorage.write(name, val)

◆ write() [2/35]

void write ( FileStorage fs,
const String name,
float  value 
)
related
Python:
None=cv.FileStorage.write(name, val)

◆ write() [3/35]

void write ( FileStorage fs,
const String name,
double  value 
)
related
Python:
None=cv.FileStorage.write(name, val)

◆ write() [4/35]

void write ( FileStorage fs,
const String name,
const String value 
)
related
Python:
None=cv.FileStorage.write(name, val)

◆ write() [5/35]

void write ( FileStorage fs,
const String name,
const Mat value 
)
related
Python:
None=cv.FileStorage.write(name, val)

◆ write() [6/35]

void write ( FileStorage fs,
const String name,
const SparseMat value 
)
related
Python:
None=cv.FileStorage.write(name, val)

◆ write() [7/35]

template<typename _Tp >
static void write ( FileStorage fs,
const _Tp &  value 
)
related
Python:
None=cv.FileStorage.write(name, val)

◆ write() [8/35]

void write ( FileStorage fs,
const int &  value 
)
related
Python:
None=cv.FileStorage.write(name, val)

◆ write() [9/35]

void write ( FileStorage fs,
const float &  value 
)
related
Python:
None=cv.FileStorage.write(name, val)

◆ write() [10/35]

void write ( FileStorage fs,
const double &  value 
)
related
Python:
None=cv.FileStorage.write(name, val)

◆ write() [11/35]

void write ( FileStorage fs,
const String value 
)
related
Python:
None=cv.FileStorage.write(name, val)

◆ write() [12/35]

template<typename _Tp >
static void write ( FileStorage fs,
const Point_< _Tp > &  pt 
)
related
Python:
None=cv.FileStorage.write(name, val)

◆ write() [13/35]

template<typename _Tp >
static void write ( FileStorage fs,
const Point3_< _Tp > &  pt 
)
related
Python:
None=cv.FileStorage.write(name, val)

◆ write() [14/35]

template<typename _Tp >
static void write ( FileStorage fs,
const Size_< _Tp > &  sz 
)
related
Python:
None=cv.FileStorage.write(name, val)

◆ write() [15/35]

template<typename _Tp >
static void write ( FileStorage fs,
const Complex< _Tp > &  c 
)
related
Python:
None=cv.FileStorage.write(name, val)

◆ write() [16/35]

template<typename _Tp >
static void write ( FileStorage fs,
const Rect_< _Tp > &  r 
)
related
Python:
None=cv.FileStorage.write(name, val)

◆ write() [17/35]

template<typename _Tp , int cn>
static void write ( FileStorage fs,
const Vec< _Tp, cn > &  v 
)
related
Python:
None=cv.FileStorage.write(name, val)

◆ write() [18/35]

template<typename _Tp , int m, int n>
static void write ( FileStorage fs,
const Matx< _Tp, m, n > &  x 
)
related
Python:
None=cv.FileStorage.write(name, val)

◆ write() [19/35]

template<typename _Tp >
static void write ( FileStorage fs,
const Scalar_< _Tp > &  s 
)
related
Python:
None=cv.FileStorage.write(name, val)

◆ write() [20/35]

static void write ( FileStorage fs,
const Range r 
)
related
Python:
None=cv.FileStorage.write(name, val)

◆ write() [21/35]

template<typename _Tp >
static void write ( FileStorage fs,
const std::vector< _Tp > &  vec 
)
related
Python:
None=cv.FileStorage.write(name, val)

◆ write() [22/35]

template<typename _Tp >
static void write ( FileStorage fs,
const String name,
const Point_< _Tp > &  pt 
)
related
Python:
None=cv.FileStorage.write(name, val)

◆ write() [23/35]

template<typename _Tp >
static void write ( FileStorage fs,
const String name,
const Point3_< _Tp > &  pt 
)
related
Python:
None=cv.FileStorage.write(name, val)

◆ write() [24/35]

template<typename _Tp >
static void write ( FileStorage fs,
const String name,
const Size_< _Tp > &  sz 
)
related
Python:
None=cv.FileStorage.write(name, val)

◆ write() [25/35]

template<typename _Tp >
static void write ( FileStorage fs,
const String name,
const Complex< _Tp > &  c 
)
related
Python:
None=cv.FileStorage.write(name, val)

◆ write() [26/35]

template<typename _Tp >
static void write ( FileStorage fs,
const String name,
const Rect_< _Tp > &  r 
)
related
Python:
None=cv.FileStorage.write(name, val)

◆ write() [27/35]

template<typename _Tp , int cn>
static void write ( FileStorage fs,
const String name,
const Vec< _Tp, cn > &  v 
)
related
Python:
None=cv.FileStorage.write(name, val)

◆ write() [28/35]

template<typename _Tp , int m, int n>
static void write ( FileStorage fs,
const String name,
const Matx< _Tp, m, n > &  x 
)
related
Python:
None=cv.FileStorage.write(name, val)

◆ write() [29/35]

template<typename _Tp >
static void write ( FileStorage fs,
const String name,
const Scalar_< _Tp > &  s 
)
related
Python:
None=cv.FileStorage.write(name, val)

◆ write() [30/35]

static void write ( FileStorage fs,
const String name,
const Range r 
)
related
Python:
None=cv.FileStorage.write(name, val)

◆ write() [31/35]

static void write ( FileStorage fs,
const String name,
const KeyPoint kpt 
)
related
Python:
None=cv.FileStorage.write(name, val)

◆ write() [32/35]

static void write ( FileStorage fs,
const String name,
const DMatch m 
)
related
Python:
None=cv.FileStorage.write(name, val)

◆ write() [33/35]

template<typename _Tp , typename std::enable_if< std::is_enum< _Tp >::value >::type * = nullptr>
static void write ( FileStorage fs,
const String name,
const _Tp &  val 
)
related
Python:
None=cv.FileStorage.write(name, val)

◆ write() [34/35]

template<typename _Tp >
static void write ( FileStorage fs,
const String name,
const std::vector< _Tp > &  vec 
)
related
Python:
None=cv.FileStorage.write(name, val)

◆ write() [35/35]

template<typename _Tp >
static void write ( FileStorage fs,
const String name,
const std::vector< std::vector< _Tp > > &  vec 
)
related
Python:
None=cv.FileStorage.write(name, val)

◆ writeScalar() [1/4]

void writeScalar ( FileStorage fs,
int  value 
)
related

◆ writeScalar() [2/4]

void writeScalar ( FileStorage fs,
float  value 
)
related

◆ writeScalar() [3/4]

void writeScalar ( FileStorage fs,
double  value 
)
related

◆ writeScalar() [4/4]

void writeScalar ( FileStorage fs,
const String value 
)
related

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: