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:

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.

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.

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

typedefstructCvAttrList{constchar**attr;/* NULL-terminated array of (attribute_name,attribute_value) pairs */structCvAttrList*next;/* pointer to next chunk of the attributes list */}CvAttrList;/* initializes CvAttrList structure */inlineCvAttrListcvAttrList(constchar**attr=NULL,CvAttrList*next=NULL);/* returns attribute value or 0 (NULL) if there is no such attribute */constchar*cvAttrValue(constCvAttrList*attr,constchar*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).

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.

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

map – The parent map. If it is NULL, the function searches in all the top-level nodes (streams), starting with the first one.

name – The file node name

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

len – Length of the name (if it is known apriori), or -1 if it needs to be calculated

create_missing – Flag that specifies, whether an absent key should be added into the hash table

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.

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.

stream_index – Zero-based index of the stream. See StartNextStream() . In most cases, there is only one stream in the file; however, there can be several.

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.

memstorage – Memory storage for dynamic structures, such as CvSeq or CvGraph . It is not used for matrices or images.

name – Optional object name. If it is NULL, the first top-level object in the storage will be loaded.

real_name – Optional output parameter that will contain the name of the loaded object (useful if name=NULL )

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.

memstorage – Memory storage used for temporary data and for
storing dynamic structures, such as CvSeq or CvGraph .
If it is NULL, a temporary memory storage is created and used.

flags –

Can be one of the following:

CV_STORAGE_READ the storage is open for reading

CV_STORAGE_WRITE the storage is open for writing

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.

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

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.

dt – Specification of each array element. It has the same format as in WriteRawData() .

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

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.

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.

name – Name of the written structure. The structure can be accessed by this name when the storage is read.

struct_flags –

A combination one of the following values:

CV_NODE_SEQ the written structure is a sequence (see discussion of CvFileStorage ), that is, its elements do not have a name.

CV_NODE_MAP the written structure is a map (see discussion of CvFileStorage ), that is, all its elements have names.

One and only one of the two above flags must be specified

CV_NODE_FLOW the optional flag that makes sense only for YAML streams. It means that the structure is written as a flow (not as a block), which is more compact. It is recommended to use this flag for structures or arrays whose elements are all scalars.

type_name – Optional parameter - the object type name. In
case of XML it is written as a type_id attribute of the
structure opening tag. In the case of YAML it is written after a colon
following the structure name (see the example in CvFileStorage
description). Mainly it is used with user objects. When the storage
is read, the encoded type name is used to determine the object type
(see CvTypeInfo and FindType() ).

attributes – This parameter is not used in the current implementation

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

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.

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

eol_comment – If non-zero, the function tries to put the comment at the end of current line. If the flag is zero, 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.

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

new_node_name – New name of the file node in the destination file storage. To keep the existing name, use cvGetFileNodeName()

node – The written node

embed – If the written node is a collection and this parameter is not zero, no extra level of hierarchy is created. Instead, all the elements of node are written into the currently written structure. Of course, map elements can only be embedded into another map, and sequence elements can only be embedded into another sequence.

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.

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:

u 8-bit unsigned number

c 8-bit signed number

w 16-bit unsigned number

s 16-bit signed number

i 32-bit signed number

f single precision floating-point number

d double precision floating-point number

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. 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.

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.

name – Name of the written value. Should be NULL if and only if the parent structure is a sequence.

value – The written value

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.

voidwrite_termcriteria(CvFileStorage*fs,constchar*struct_name,CvTermCriteria*termcrit){cvStartWriteStruct(fs,struct_name,CV_NODE_MAP,NULL,cvAttrList(0,0));cvWriteComment(fs,"termination criteria",1);// just a descriptionif(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);}

name – Name of the written string . Should be NULL if and only if the parent structure is a sequence.

str – The written text string

quote – If non-zero, the written string is put in quotes, regardless of whether they are required. Otherwise, if the flag is zero, quotes are used only when they are required (e.g. when the string starts with a digit or contains spaces).