The section describes the OpenCV 1.x API for reading and writing data structures to/from XML or YAML files. It is now recommended to use the new C++ interface for reading and writing data.
CvFileStorage
¶The structure CvFileStorage
is a “black box” representation of the file storage associated with a file on disk. Several functions that are described below take CvFileStorage*
as inputs and allow the user to save or to load hierarchical collections that consist of scalar values, standard CXCore objects (such as matrices, sequences, graphs), and user-defined objects.
OpenCV can read and write data in XML (http://www.w3c.org/XML) or YAML
(http://www.yaml.org) formats. Below is an example of 3x3 floating-point identity matrix A
, stored in XML and YAML files using CXCore functions:
XML:
<?xml version="1.0">
<opencv_storage>
<A type_id="opencv-matrix">
<rows>3</rows>
<cols>3</cols>
<dt>f</dt>
<data>1. 0. 0. 0. 1. 0. 0. 0. 1.</data>
</A>
</opencv_storage>
YAML:
%YAML:1.0
A: !!opencv-matrix
rows: 3
cols: 3
dt: f
data: [ 1., 0., 0., 0., 1., 0., 0., 0., 1.]
As it can be seen from the examples, XML uses nested tags to represent hierarchy, while YAML uses indentation for that purpose (similar to the Python programming language).
The same functions can read and write data in both formats; the particular format is determined by the extension of the opened file, ”.xml” for XML files and ”.yml” or ”.yaml” for YAML.
CvFileNode
¶File storage node. 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. Collections are also referenced to as “structures” in the data writing functions. There can be named collections (mappings), where each element has a name and is accessed by a name, and ordered collections (sequences), where elements do not have names, but rather accessed by index.
tag
¶type of the file node:
- CV_NODE_NONE - empty node
- CV_NODE_INT - an integer
- CV_NODE_REAL - a floating-point number
- CV_NODE_STR - text string
- CV_NODE_SEQ - a sequence
- CV_NODE_MAP - a mapping
type of the node can be retrieved using CV_NODE_TYPE(node->tag)
macro.
info
¶optional pointer to the user type information. If you look at the matrix representation in XML and YAML, shown above, you may notice type_id="opencv-matrix"
or !!opencv-matrix
strings. They are used to specify that the certain element of a file is a representation of a data structure of certain type (“opencv-matrix” corresponds to CvMat
). When a file is parsed, such type identifiers are passed to FindType()
to find type information and the pointer to it is stored in the file node. See CvTypeInfo
for more details.
data
¶the node data, declared as:
union
{
double f; /* scalar floating-point number */
int i; /* scalar integer number */
CvString str; /* text string */
CvSeq* seq; /* sequence (ordered collection of file nodes) */
struct CvMap* map; /* map (collection of named file nodes) */
} data;
Primitive nodes are read using ReadInt()
, ReadReal()
and ReadString()
. Sequences are read by iterating through node->data.seq
(see “Dynamic Data Structures” section). Mappings are read using GetFileNodeByName()
. Nodes with the specified type (so that node->info != NULL
) can be read using Read()
.
CvAttrList
¶List of attributes.
typedef struct CvAttrList
{
const char** attr; /* NULL-terminated array of (attribute_name,attribute_value) pairs */
struct CvAttrList* next; /* pointer to next chunk of the attributes list */
}
CvAttrList;
/* initializes CvAttrList structure */
inline CvAttrList cvAttrList( const char** attr=NULL, CvAttrList* next=NULL );
/* returns attribute value or 0 (NULL) if there is no such attribute */
const char* cvAttrValue( const CvAttrList* attr, const char* attr_name );
In the current implementation, attributes are used to pass extra parameters when writing user objects (see
Write()
). XML attributes inside tags are not supported, aside from the object type specification (type_id
attribute).
CvTypeInfo
¶Type information.
typedef int (CV_CDECL *CvIsInstanceFunc)( const void* structPtr );
typedef void (CV_CDECL *CvReleaseFunc)( void** structDblPtr );
typedef void* (CV_CDECL *CvReadFunc)( CvFileStorage* storage, CvFileNode* node );
typedef void (CV_CDECL *CvWriteFunc)( CvFileStorage* storage,
const char* name,
const void* structPtr,
CvAttrList attributes );
typedef void* (CV_CDECL *CvCloneFunc)( const void* structPtr );
typedef struct CvTypeInfo
{
int flags; /* not used */
int header_size; /* sizeof(CvTypeInfo) */
struct CvTypeInfo* prev; /* previous registered type in the list */
struct CvTypeInfo* next; /* next registered type in the list */
const char* type_name; /* type name, written to file storage */
/* methods */
CvIsInstanceFunc is_instance; /* checks if the passed object belongs to the type */
CvReleaseFunc release; /* releases object (memory etc.) */
CvReadFunc read; /* reads object from file storage */
CvWriteFunc write; /* writes object to file storage */
CvCloneFunc clone; /* creates a copy of the object */
}
CvTypeInfo;
The structure contains information about one of the standard or user-defined types. Instances of the type may or may not contain a pointer to the corresponding CvTypeInfo
structure. In any case, there is a way to find the type info structure for a given object using the TypeOf()
function. Alternatively, type info can be found by type name using FindType()
, which is used when an object is read from file storage. The user can register a new type with RegisterType()
that adds the type information structure into the beginning of the type list. Thus, it is possible to create specialized types from generic standard types and override the basic methods.
Makes a clone of an object.
void* cvClone
(const void* struct_ptr)¶Parameters: |
|
---|
The function finds the type of a given object and calls clone
with the passed object. Of course, if you know the object type, for example, struct_ptr
is CvMat*
, it is faster to call the specific function, like CloneMat()
.
Finishes writing to a file node collection.
void cvEndWriteStruct
(CvFileStorage* fs)¶Parameters: |
|
---|
See also
Finds a type by its name.
CvTypeInfo* cvFindType
(const char* type_name)¶Parameters: |
|
---|
The function finds a registered type by its name. It returns NULL if there is no type with the specified name.
Returns the beginning of a type list.
CvTypeInfo* cvFirstType
(void None)¶The function returns the first type in the list of registered types. Navigation through the list can be done via the prev
and next
fields of the CvTypeInfo
structure.
Finds a node in a map or file storage.
CvFileNode* cvGetFileNode
(CvFileStorage* fs, CvFileNode* map, const CvStringHashNode* key, int create_missing=0 )¶Parameters: |
|
---|
The function finds a file node. It is a faster version of GetFileNodeByName()
(see GetHashedKey()
discussion). Also, the function can insert a new node, if it is not in the map yet.
Finds a node in a map or file storage.
CvFileNode* cvGetFileNodeByName
(const CvFileStorage* fs, const CvFileNode* map, const char* name)¶Parameters: |
|
---|
The function finds a file node by name
. The node is searched either in map
or, if the pointer is NULL, among the top-level file storage nodes. Using this function for maps and GetSeqElem()
(or sequence reader) for sequences, it is possible to navigate through the file storage. To speed up multiple queries for a certain key (e.g., in the case of an array of structures) one may use a combination of GetHashedKey()
and GetFileNode()
.
Returns the name of a file node.
const char* cvGetFileNodeName
(const CvFileNode* node)¶Parameters: |
|
---|
The function returns the name of a file node or NULL, if the file node does not have a name or if node
is NULL
.
Returns a unique pointer for a given name.
CvStringHashNode* cvGetHashedKey
(CvFileStorage* fs, const char* name, int len=-1, int create_missing=0 )¶Parameters: |
|
---|
The function returns a unique pointer for each particular file node name. This pointer can be then passed to the GetFileNode()
function that is faster than GetFileNodeByName()
because it compares text strings by comparing pointers rather than the strings’ content.
Consider the following example where an array of points is encoded as a sequence of 2-entry maps:
points:
- { x: 10, y: 10 }
- { x: 20, y: 20 }
- { x: 30, y: 30 }
# ...
Then, it is possible to get hashed “x” and “y” pointers to speed up decoding of the points.
#include "cxcore.h"
int main( int argc, char** argv )
{
CvFileStorage* fs = cvOpenFileStorage( "points.yml", 0, CV_STORAGE_READ );
CvStringHashNode* x_key = cvGetHashedNode( fs, "x", -1, 1 );
CvStringHashNode* y_key = cvGetHashedNode( fs, "y", -1, 1 );
CvFileNode* points = cvGetFileNodeByName( fs, 0, "points" );
if( CV_NODE_IS_SEQ(points->tag) )
{
CvSeq* seq = points->data.seq;
int i, total = seq->total;
CvSeqReader reader;
cvStartReadSeq( seq, &reader, 0 );
for( i = 0; i < total; i++ )
{
CvFileNode* pt = (CvFileNode*)reader.ptr;
#if 1 /* faster variant */
CvFileNode* xnode = cvGetFileNode( fs, pt, x_key, 0 );
CvFileNode* ynode = cvGetFileNode( fs, pt, y_key, 0 );
assert( xnode && CV_NODE_IS_INT(xnode->tag) &&
ynode && CV_NODE_IS_INT(ynode->tag));
int x = xnode->data.i; // or x = cvReadInt( xnode, 0 );
int y = ynode->data.i; // or y = cvReadInt( ynode, 0 );
#elif 1 /* slower variant; does not use x_key & y_key */
CvFileNode* xnode = cvGetFileNodeByName( fs, pt, "x" );
CvFileNode* ynode = cvGetFileNodeByName( fs, pt, "y" );
assert( xnode && CV_NODE_IS_INT(xnode->tag) &&
ynode && CV_NODE_IS_INT(ynode->tag));
int x = xnode->data.i; // or x = cvReadInt( xnode, 0 );
int y = ynode->data.i; // or y = cvReadInt( ynode, 0 );
#else /* the slowest yet the easiest to use variant */
int x = cvReadIntByName( fs, pt, "x", 0 /* default value */ );
int y = cvReadIntByName( fs, pt, "y", 0 /* default value */ );
#endif
CV_NEXT_SEQ_ELEM( seq->elem_size, reader );
printf("
}
}
cvReleaseFileStorage( &fs );
return 0;
}
Please note that whatever method of accessing a map you are using, it is still much slower than using plain sequences; for example, in the above example, it is more efficient to encode the points as pairs of integers in a single numeric sequence.
Retrieves one of the top-level nodes of the file storage.
CvFileNode* cvGetRootFileNode
(const CvFileStorage* fs, int stream_index=0 )¶Parameters: |
|
---|
The function returns one of the top-level file nodes. The top-level nodes do not have a name, they correspond to the streams that are stored one after another in the file storage. If the index is out of range, the function returns a NULL pointer, so all the top-level nodes can be iterated by subsequent calls to the function with stream_index=0,1,...
, until the NULL pointer is returned. This function
can be used as a base for recursive traversal of the file storage.
Loads an object from a file.
void* cvLoad
(const char* filename, CvMemStorage* memstorage=NULL, const char* name=NULL, const char** real_name=NULL )¶
cv.
Load
(filename, storage=None, name=None) → generic¶Parameters: |
|
---|
The function loads an object from a file. It basically reads the specified file, find the first top-level node and calls Read()
for that node. If the file node does not have type information or the type information can not be found by the type name, the function returns NULL. After the object is loaded, the file storage is closed and all the temporary buffers are deleted. Thus, to load a dynamic structure, such as a sequence, contour, or graph, one should pass a valid memory storage destination to the function.
Opens file storage for reading or writing data.
CvFileStorage* cvOpenFileStorage
(const char* filename, CvMemStorage* memstorage, int flags, const char* encoding=NULL )¶Parameters: |
|
---|
The function opens file storage for reading or writing data. In the latter case, a new file is created or an existing file is rewritten. The type of the read or written file is determined by the filename extension: .xml
for XML
and .yml
or .yaml
for YAML
. The function returns a pointer to the CvFileStorage
structure. If the file cannot be opened then the function returns NULL
.
Decodes an object and returns a pointer to it.
void* cvRead
(CvFileStorage* fs, CvFileNode* node, CvAttrList* attributes=NULL )¶Parameters: |
|
---|
The function decodes a user object (creates an object in a native representation from the file storage subtree) and returns it. The object to be decoded must be an instance of a registered type that supports the read
method (see CvTypeInfo
). The type of the object is determined by the type name that is encoded in the file. If the object is a dynamic structure, it is created either in memory storage and passed to OpenFileStorage()
or, if a NULL pointer was passed, in temporary
memory storage, which is released when ReleaseFileStorage()
is called. Otherwise, if the object is not a dynamic structure, it is created in a heap and should be released with a specialized function or by using the generic Release()
.
Finds an object by name and decodes it.
void* cvReadByName
(CvFileStorage* fs, const CvFileNode* map, const char* name, CvAttrList* attributes=NULL )¶Parameters: |
|
---|
The function is a simple superposition of GetFileNodeByName()
and Read()
.
Retrieves an integer value from a file node.
int cvReadInt
(const CvFileNode* node, int default_value=0 )¶Parameters: |
|
---|
The function returns an integer that is represented by the file node. If the file node is NULL, the
default_value
is returned (thus, it is convenient to call the function right after GetFileNode()
without checking for a NULL pointer). If the file node has type CV_NODE_INT
, then node->data.i
is returned. If the file node has type CV_NODE_REAL
, then node->data.f
is converted to an integer and returned. Otherwise the error is reported.
Finds a file node and returns its value.
int cvReadIntByName
(const CvFileStorage* fs, const CvFileNode* map, const char* name, int default_value=0 )¶Parameters: |
|
---|
The function is a simple superposition of GetFileNodeByName()
and ReadInt()
.
Reads multiple numbers.
void cvReadRawData
(const CvFileStorage* fs, const CvFileNode* src, void* dst, const char* dt)¶Parameters: |
|
---|
The function reads elements from a file node that represents a sequence of scalars.
Initializes file node sequence reader.
void cvReadRawDataSlice
(const CvFileStorage* fs, CvSeqReader* reader, int count, void* dst, const char* dt)¶Parameters: |
|
---|
The function reads one or more elements from the file node, representing a sequence, to a user-specified array. The total number of read sequence elements is a product of total
and the number of components in each array element. For example, if dt=2if
, the function will read total*3
sequence elements. As with any sequence, some parts of the file node sequence can be skipped or read repeatedly by repositioning the reader using SetSeqReaderPos()
.
Retrieves a floating-point value from a file node.
double cvReadReal
(const CvFileNode* node, double default_value=0. )¶Parameters: |
|
---|
The function returns a floating-point value
that is represented by the file node. If the file node is NULL, the
default_value
is returned (thus, it is convenient to call
the function right after
GetFileNode()
without checking for a NULL
pointer). If the file node has type
CV_NODE_REAL
,
then
node->data.f
is returned. If the file node has type
CV_NODE_INT
, then
node-:math:`>`data.f
is converted to floating-point
and returned. Otherwise the result is not determined.
Finds a file node and returns its value.
double cvReadRealByName
(const CvFileStorage* fs, const CvFileNode* map, const char* name, double default_value=0. )¶Parameters: |
|
---|
The function is a simple superposition of
GetFileNodeByName()
and
ReadReal()
.
Retrieves a text string from a file node.
const char* cvReadString
(const CvFileNode* node, const char* default_value=NULL )¶Parameters: |
|
---|
The function returns a text string that is represented
by the file node. If the file node is NULL, the
default_value
is returned (thus, it is convenient to call the function right after
GetFileNode()
without checking for a NULL pointer). If
the file node has type
CV_NODE_STR
, then
node-:math:`>`data.str.ptr
is returned. Otherwise the result is not determined.
Finds a file node by its name and returns its value.
const char* cvReadStringByName
(const CvFileStorage* fs, const CvFileNode* map, const char* name, const char* default_value=NULL )¶Parameters: |
|
---|
The function is a simple superposition of
GetFileNodeByName()
and
ReadString()
.
Registers a new type.
void cvRegisterType
(const CvTypeInfo* info)¶Parameters: |
|
---|
The function registers a new type, which is
described by
info
. The function creates a copy of the structure,
so the user should delete it after calling the function.
Releases an object.
void cvRelease
(void** struct_ptr)¶Parameters: |
|
---|
The function finds the type of a given object and calls
release
with the double pointer.
Releases file storage.
void cvReleaseFileStorage
(CvFileStorage** fs)¶Parameters: |
|
---|
The function closes the file associated with the storage and releases all the temporary structures. It must be called after all I/O operations with the storage are finished.
Saves an object to a file.
void cvSave
(const char* filename, const void* struct_ptr, const char* name=NULL, const char* comment=NULL, CvAttrList attributes=cvAttrList() )¶
cv.
Save
(filename, structPtr, name=None, comment=None) → None¶Parameters: |
|
---|
The function saves an object to a file. It provides a simple interface to
Write()
.
Starts the next stream.
void cvStartNextStream
(CvFileStorage* fs)¶Parameters: |
|
---|
The function finishes the currently written stream and starts the next stream. In the case of XML the file with multiple streams looks like this:
<opencv_storage>
<!-- stream #1 data -->
</opencv_storage>
<opencv_storage>
<!-- stream #2 data -->
</opencv_storage>
...
The YAML file will look like this:
%YAML:1.0
# stream #1 data
...
---
# stream #2 data
This is useful for concatenating files or for resuming the writing process.
Initializes the file node sequence reader.
void cvStartReadRawData
(const CvFileStorage* fs, const CvFileNode* src, CvSeqReader* reader)¶Parameters: |
|
---|
The function initializes the sequence reader to read data from a file node. The initialized reader can be then passed to ReadRawDataSlice()
.
Starts writing a new structure.
void cvStartWriteStruct
(CvFileStorage* fs, const char* name, int struct_flags, const char* type_name=NULL, CvAttrList attributes=cvAttrList() )¶Parameters: |
|
---|
The function starts writing a compound structure (collection) that can be a sequence or a map. After all the structure fields, which can be scalars or structures, are written, EndWriteStruct()
should be called. The function can be used to group some objects or to implement the write
function for a some user object (see CvTypeInfo
).
Returns the type of an object.
CvTypeInfo* cvTypeOf
(const void* struct_ptr)¶Parameters: |
|
---|
The function finds the type of a given object. It iterates through the list of registered types and calls the is_instance
function/method for every type info structure with that object until one of them returns non-zero or until the whole list has been traversed. In the latter case, the function returns NULL.
Unregisters the type.
void cvUnregisterType
(const char* type_name)¶Parameters: |
|
---|
The function unregisters a type with a specified name. If the name is unknown, it is possible to locate the type info by an instance of the type using TypeOf()
or by iterating the type list, starting from FirstType()
, and then calling cvUnregisterType(info->typeName)
.
Writes an object to file storage.
void cvWrite
(CvFileStorage* fs, const char* name, const void* ptr, CvAttrList attributes=cvAttrList() )¶Parameters: |
|
---|
The function writes an object to file storage. First, the appropriate type info is found using TypeOf()
. Then, the write
method associated with the type info is called.
Attributes are used to customize the writing procedure. The standard types support the following attributes (all the dt
attributes have the same format as in WriteRawData()
):
CvSeq
- header_dt description of user fields of the sequence header that follow CvSeq, or CvChain (if the sequence is a Freeman chain) or CvContour (if the sequence is a contour or point sequence)
- dt description of the sequence elements.
- recursive if the attribute is present and is not equal to “0” or “false”, the whole tree of sequences (contours) is stored.
CvGraph
- header_dt description of user fields of the graph header that follows CvGraph;
- vertex_dt description of user fields of graph vertices
- edge_dt description of user fields of graph edges (note that the edge weight is always written, so there is no need to specify it explicitly)
Below is the code that creates the YAML file shown in the
CvFileStorage
description:
#include "cxcore.h"
int main( int argc, char** argv )
{
CvMat* mat = cvCreateMat( 3, 3, CV_32F );
CvFileStorage* fs = cvOpenFileStorage( "example.yml", 0, CV_STORAGE_WRITE );
cvSetIdentity( mat );
cvWrite( fs, "A", mat, cvAttrList(0,0) );
cvReleaseFileStorage( &fs );
cvReleaseMat( &mat );
return 0;
}
Writes a comment.
void cvWriteComment
(CvFileStorage* fs, const char* comment, int eol_comment)¶Parameters: |
|
---|
The function writes a comment into file storage. The comments are skipped when the storage is read.
Writes a file node to another file storage.
void cvWriteFileNode
(CvFileStorage* fs, const char* new_node_name, const CvFileNode* node, int embed)¶Parameters: |
|
---|
The function writes a copy of a file node to file storage. Possible applications of the function are merging several file storages into one and conversion between XML and YAML formats.
Writes an integer value.
void cvWriteInt
(CvFileStorage* fs, const char* name, int value)¶Parameters: |
|
---|
The function writes a single integer value (with or without a name) to the file storage.
Writes multiple numbers.
void cvWriteRawData
(CvFileStorage* fs, const void* src, int len, const char* dt)¶Parameters: |
|
---|
The function writes an array, whose elements consist
of single or multiple numbers. The function call can be replaced with
a loop containing a few
WriteInt()
and
WriteReal()
calls, but
a single call is more efficient. Note that because none of the elements
have a name, they should be written to a sequence rather than a map.
Writes a floating-point value.
void cvWriteReal
(CvFileStorage* fs, const char* name, double value)¶Parameters: |
|
---|
The function writes a single floating-point value (with or without a name) to file storage. Special values are encoded as follows: NaN (Not A Number) as .NaN, infinity as +.Inf or -.Inf.
The following example shows how to use the low-level writing functions to store custom structures, such as termination criteria, without registering a new type.
void write_termcriteria( CvFileStorage* fs, const char* struct_name,
CvTermCriteria* termcrit )
{
cvStartWriteStruct( fs, struct_name, CV_NODE_MAP, NULL, cvAttrList(0,0));
cvWriteComment( fs, "termination criteria", 1 ); // just a description
if( termcrit->type & CV_TERMCRIT_ITER )
cvWriteInteger( fs, "max_iterations", termcrit->max_iter );
if( termcrit->type & CV_TERMCRIT_EPS )
cvWriteReal( fs, "accuracy", termcrit->epsilon );
cvEndWriteStruct( fs );
}
Writes a text string.
void cvWriteString
(CvFileStorage* fs, const char* name, const char* str, int quote=0 )¶Parameters: |
|
---|
The function writes a text string to file storage.