Navigation

The section describes OpenCV 1.x API for creating growable sequences and other dynamic data structures allocated in CvMemStorage. If you use the new C++, Python, Java etc interface, you will unlikely need this functionality. Use std::vector or other high-level data structures.

Memory storage is a low-level structure used to store dynamically growing data structures such as sequences, contours, graphs, subdivisions, etc. It is organized as a list of memory blocks of equal size -
bottom field is the beginning of the list of blocks and top is the currently used block, but not necessarily the last block of the list. All blocks between bottom and top, not including the
latter, are considered fully occupied; all blocks between top and the last block, not including top, are considered free and top itself is partly occupied - free_space contains the number of free bytes left in the end of top.

The buffer is put in the end of already allocated space in the top memory block, if there is enough free space. After allocation, free_space is decreased by the size of the allocated buffer plus some padding to keep the proper alignment. When the allocated buffer does not fit into the available portion of
top, the next storage block from the list is taken as top and free_space is reset to the whole block size prior to the allocation.

If there are no more free blocks, a new block is allocated (or borrowed from the parent, see CreateChildMemStorage()) and added to the end of list. Thus, the storage behaves as a stack with bottom indicating bottom of the stack and the pair (top, free_space)
indicating top of the stack. The stack top may be saved via SaveMemStoragePos(), restored via
RestoreMemStoragePos(), or reset via ClearMemStorage().

The structure CvSeq is a base for all of OpenCV dynamic data structures.
There are two types of sequences - dense and sparse. The base type for dense
sequences is CvSeq and such sequences are used to represent
growable 1d arrays - vectors, stacks, queues, and deques. They have no gaps
in the middle - if an element is removed from the middle or inserted
into the middle of the sequence, the elements from the closer end are
shifted. Sparse sequences have CvSet as a base class and they are
discussed later in more detail. They are sequences of nodes; each may be either occupied or free as indicated by the node flag. Such sequences are used for unordered data structures such as sets of elements, graphs, hash tables and so forth.

Some of functions that operate on sequences take a CvSliceslice parameter that is often set to the whole sequence (CV_WHOLE_SEQ) by default. Either of the start_index and end_index may be negative or exceed the sequence length. If they are equal, the slice is considered empty (i.e., contains no elements). Because sequences are treated as circular structures, the slice may select a
few elements in the end of a sequence followed by a few elements at the beginning of the sequence. For example, cvSlice(-2,3) in the case of a 10-element sequence will select a 5-element slice, containing the pre-last (8th), last (9th), the very first (0th), second (1th) and third (2nd)
elements. The functions normalize the slice argument in the following way:

start_index of the slice is normalized similarly to the argument of GetSeqElem() (i.e., negative indices are allowed). The actual slice to process starts at the normalized start_index and lasts SliceLength() elements (again, assuming the sequence is a circular structure).

If a function does not accept a slice argument, but you want to process only a part of the sequence, the sub-sequence may be extracted using the SeqSlice() function, or stored into a continuous
buffer with CvtSeqToArray() (optionally, followed by MakeSeqHeaderForArray()).

The structure CvSet is a base for OpenCV 1.x sparse data structures. It is derived from CvSeq and includes an additional member free_elems - a list of free nodes. Every node of the set, whether free or not, is an element of the underlying sequence. While there are no restrictions on elements of dense sequences, the set (and derived structures) elements must start with an integer field and be able to fit CvSetElem structure, because these two fields (an integer followed by a pointer) are required for the organization of a node set with the list of free nodes. If a node is free, the flags
field is negative (the most-significant bit, or MSB, of the field is set), and the next_free points to the next free node (the first free node is referenced by the free_elems field of CvSet). And if a node is occupied, the flags field is positive and contains the node index that may be retrieved using the (set_elem->flags&CV_SET_ELEM_IDX_MASK) expressions, the rest of the node content is determined by the user. In particular, the occupied nodes are not linked as the free nodes are, so the second field can be used for such a link as well as for some different purpose. The macro CV_IS_SET_ELEM(set_elem_ptr) can be used to determined whether the specified node is occupied or not.

Initially the set and the free node list are empty. When a new node is requested from the set, it is taken from the list of free nodes, which is then updated. If the list appears to be empty, a new sequence block is allocated and all the nodes within the block are joined in the list of free nodes. Thus, the total
field of the set is the total number of nodes both occupied and free. When an occupied node is released, it is added to the list of free nodes. The node released last will be occupied first.

The structure CvGraph is a base for graphs used in OpenCV 1.x. It inherits from
CvSet, that is, it is considered as a set of vertices. Besides, it contains another set as a member, a set of graph edges. Graphs in OpenCV are represented using adjacency lists format.

The function resets the top (free space boundary) of the storage to the very beginning. This function does not deallocate any memory. If the storage has a parent, the function returns
all blocks to the parent.

The function removes all elements from a sequence. The function does not return the memory to the storage block, but this memory is reused later when new elements are added to the sequence. The function has
‘O(1)’ time complexity.

Note

It is impossible to deallocate a sequence, i.e. free space in the memory storage occupied by the sequence. Instead, call ClearMemStorage() or ReleaseMemStorage() from time to time somewhere in a top-level processing loop.

The function creates a full copy of the specified graph. If the
graph vertices or edges have pointers to some external data, it can still be
shared between the copies. The vertex and edge indices in the new graph
may be different from the original because the function defragments
the vertex and edge sets.

The function creates a child memory
storage that is similar to simple memory storage except for the
differences in the memory allocation/deallocation mechanism. When a
child storage needs a new block to add to the block list, it tries
to get this block from the parent. The first unoccupied parent block
available is taken and excluded from the parent block list. If no blocks
are available, the parent either allocates a block or borrows one from
its own parent, if any. In other words, the chain, or a more complex
structure, of memory storages where every storage is a child/parent of
another is possible. When a child storage is released or even cleared,
it returns all blocks to the parent. In other aspects, child storage
is the same as simple storage.

Child storage is useful in the following situation. Imagine
that the user needs to process dynamic data residing in a given storage area and
put the result back to that same storage area. With the simplest approach,
when temporary data is resided in the same storage area as the input and
output data, the storage area will look as follows after processing:

Dynamic data processing without using child storage

That is, garbage appears in the middle of the storage. However, if
one creates a child memory storage at the beginning of processing,
writes temporary data there, and releases the child storage at the end,
no garbage will appear in the source/destination storage:

vtx – Initial vertex to start from. If NULL, the traversal starts from the first vertex (a vertex with the minimal index in the sequence of vertices).

mask –

Event mask indicating which events are of interest to the user (where NextGraphItem() function returns control to the user) It can be CV_GRAPH_ALL_ITEMS (all events are of interest) or a combination of the following flags:

CV_GRAPH_VERTEX stop at the graph vertices visited for the first time

CV_GRAPH_TREE_EDGE stop at tree edges ( treeedge is the edge connecting the last visited vertex and the vertex to be visited next)

CV_GRAPH_BACK_EDGE stop at back edges ( backedge is an edge connecting the last visited vertex with some of its ancestors in the search tree)

CV_GRAPH_FORWARD_EDGE stop at forward edges ( forwardedge is an edge connecting the last visited vertex with some of its descendants in the search tree. The forward edges are only possible during oriented graph traversal)

CV_GRAPH_CROSS_EDGE stop at cross edges ( crossedge is an edge connecting different search trees or branches of the same tree. The crossedges are only possible during oriented graph traversal)

CV_GRAPH_NEW_TREE stop in the beginning of every new search tree. When the traversal procedure visits all vertices and edges reachable from the initial vertex (the visited vertices together with tree edges make up a tree), it searches for some unvisited vertex in the graph and resumes the traversal process from that vertex. Before starting a new tree (including the very first tree when cvNextGraphItem is called for the first time) it generates a CV_GRAPH_NEW_TREE event. For unoriented graphs, each search tree corresponds to a connected component of the graph.

CV_GRAPH_BACKTRACKING stop at every already visited vertex during backtracking - returning to already visited vertexes of the traversal tree.

The function creates a structure for depth-first graph traversal/search. The initialized structure is used in the
NextGraphItem()
function - the incremental traversal procedure.

seq_flags – Flags of the created sequence. If the sequence is not passed to any function working with a specific type of sequences, the sequence value may be set to 0, otherwise the appropriate type must be selected from the list of predefined sequence types.

header_size – Size of the sequence header; must be greater than or equal to sizeof(CvSeq) . If a specific type or its extension is indicated, this type must fit the base type header.

elem_size – Size of the sequence elements in bytes. The size must be consistent with the sequence type. For example, for a sequence of points to be created, the element type CV_SEQ_ELTYPE_POINT should be specified and the parameter elem_size must be equal to sizeof(CvPoint) .

storage – Sequence location

The function creates a sequence and returns
the pointer to it. The function allocates the sequence header in
the storage block as one continuous chunk and sets the structure
fields
flags
,
elemSize
,
headerSize
, and
storage
to passed values, sets
delta_elems
to the
default value (that may be reassigned using the
SetSeqBlockSize()
function), and clears other header fields, including the space following
the first
sizeof(CvSeq)
bytes.

The function finishes the writing process and
returns the pointer to the written sequence. The function also truncates
the last incomplete sequence block to return the remaining part of the
block to memory storage. After that, the sequence can be read and
modified safely. See
StartWriteSeq()
and
StartAppendToSeq()

The function is intended to enable the user to
read sequence elements, whenever required, during the writing process,
e.g., in order to check specific conditions. The function updates the
sequence headers to make reading from the sequence possible. The writer
is not closed, however, so that the writing process can be continued at
any time. If an algorithm requires frequent flushes, consider using
SeqPush()
instead.

The function finds the element with the given
index in the sequence and returns the pointer to it. If the element
is not found, the function returns 0. The function supports negative
indices, where -1 stands for the last sequence element, -2 stands for
the one before last, etc. If the sequence is most likely to consist of
a single sequence block or the desired element is likely to be located
in the first block, then the macro
CV_GET_SEQ_ELEM(elemType,seq,index)
should be used, where the parameter
elemType
is the
type of sequence elements (
CvPoint
for example), the parameter
seq
is a sequence, and the parameter
index
is the index
of the desired element. The macro checks first whether the desired element
belongs to the first block of the sequence and returns it if it does;
otherwise the macro calls the main function
GetSeqElem
. Negative
indices always cause the
GetSeqElem()
call. The function has O(1)
time complexity assuming that the number of blocks is much smaller than the
number of elements.

The function finds a set element by its index. The function returns the pointer to it or 0 if the index is invalid or the corresponding node is free. The function supports negative indices as it uses
GetSeqElem()
to locate the node.

end_idx – Index of the ending vertex of the edge. For an unoriented graph, the order of the vertex parameters does not matter.

edge – Optional input parameter, initialization data for the edge

inserted_edge – Optional output parameter to contain the address of the inserted edge

The function connects two specified vertices. The function returns 1 if the edge has been added successfully, 0 if the edge connecting the two vertices exists already and -1 if either of the vertices was not found, the starting and the ending vertex are the same, or there is some other critical situation. In the latter case (i.e., when the result is negative), the function also reports an error by default.

end_vtx – Pointer to the ending vertex of the edge. For an unoriented graph, the order of the vertex parameters does not matter.

edge – Optional input parameter, initialization data for the edge

inserted_edge – Optional output parameter to contain the address of the inserted edge within the edge set

The function connects two specified vertices. The
function returns 1 if the edge has been added successfully, 0 if the
edge connecting the two vertices exists already, and -1 if either of the
vertices was not found, the starting and the ending vertex are the same
or there is some other critical situation. In the latter case (i.e., when
the result is negative), the function also reports an error by default.

The function removes a vertex from a graph
together with all the edges incident to it. The function reports an error
if the input vertex does not belong to the graph. The return value is the
number of edges deleted, or -1 if the vertex does not belong to the graph.

The function removes a vertex from the graph by using its pointer together with all the edges incident to it. The function reports an error if the vertex does not belong to the graph. The return value is the number of edges deleted, or -1 if the vertex does not belong to the graph.

max_level – The maximal level of the tree ( first node assumed to be at the first level) to traverse up to. For example, 1 means that only nodes at the same level as first should be visited, 2 means that the nodes on the same level as first and their direct children should be visited, and so forth.

The function initializes the tree iterator. The tree is traversed in depth-first order.

header_size – Size of the header of the sequence. Parameter sequence must point to the structure of that size or greater

elem_size – Size of the sequence elements

elements – Elements that will form a sequence

total – Total number of elements in the sequence. The number of array elements must be equal to the value of this parameter.

seq – Pointer to the local variable that is used as the sequence header

block – Pointer to the local variable that is the header of the single sequence block

The function initializes a sequence
header for an array. The sequence header as well as the sequence block are
allocated by the user (for example, on stack). No data is copied by the
function. The resultant sequence will consists of a single block and
have NULL storage pointer; thus, it is possible to read its elements,
but the attempts to add elements to the sequence will raise an error in
most cases.

The function allocates a memory buffer in
a storage block. The buffer size must not exceed the storage block size,
otherwise a runtime error is raised. The buffer address is aligned by
CV_STRUCT_ALIGN=sizeof(double)
(for the moment) bytes.

The function traverses through the graph
until an event of interest to the user (that is, an event, specified
in the
mask
in the
CreateGraphScanner()
call) is met or the
traversal is completed. In the first case, it returns one of the events
listed in the description of the
mask
parameter above and with
the next call it resumes the traversal. In the latter case, it returns
CV_GRAPH_OVER
(-1). When the event is
CV_GRAPH_VERTEX
,
CV_GRAPH_BACKTRACKING
, or
CV_GRAPH_NEW_TREE
,
the currently observed vertex is stored in
scanner-:math:`>`vtx
. And if the
event is edge-related, the edge itself is stored at
scanner-:math:`>`edge
,
the previously visited vertex - at
scanner-:math:`>`vtx
and the other ending
vertex of the edge - at
scanner-:math:`>`dst
.

The function returns the currently observed node and then updates the
iterator - moving it toward the next node. In other words, the function
behavior is similar to the
*p++
expression on a typical C
pointer or C++ collection iterator. The function returns NULL if there
are no more nodes.

The function returns the currently observed node and then updates
the iterator - moving it toward the previous node. In other words,
the function behavior is similar to the
*p--
expression on a
typical C pointer or C++ collection iterator. The function returns NULL
if there are no more nodes.

The function deallocates all storage memory
blocks or returns them to the parent, if any. Then it deallocates the
storage header and clears the pointer to the storage. All child storage
associated with a given parent storage block must be released before the
parent storage block is released.

The function restores the position of the storage top from the parameter
pos
. This function and the function
cvClearMemStorage
are the only methods to release memory occupied in memory blocks. Note again that there is no way to free memory in the middle of an occupied portion of a storage block.

before_index – Index before which the element is inserted. Inserting before 0 (the minimal allowed value of the parameter) is equal to SeqPushFront() and inserting before seq->total (the maximal allowed value of the parameter) is equal to SeqPush() .

element – Inserted element

The function shifts the sequence elements from the inserted position to the nearest end of the sequence and copies the
element
content there if the pointer is not NULL. The function returns a pointer to the inserted element.

The function removes several elements from either end of the sequence. If the number of the elements to be removed exceeds the total number of elements in the sequence, the function removes as many elements as possible.

The function adds several elements to either
end of a sequence. The elements are added to the sequence in the same
order as they are arranged in the input array but they can fall into
different sequence blocks.

The function removes elements with the given
index. If the index is out of range the function reports an error. An
attempt to remove an element from an empty sequence is a special
case of this situation. The function removes an element by shifting
the sequence elements between the nearest end of the sequence and the
index
-th position, not counting the latter.

The function searches for the element in the sequence. If
the sequence is sorted, a binary O(log(N)) search is used; otherwise, a
simple linear search is used. If the element is not found, the function
returns a NULL pointer and the index is set to the number of sequence
elements if a linear search is used, or to the smallest index
i,seq(i)>elem
.

storage – The destination storage block to hold the new sequence header and the copied data, if any. If it is NULL, the function uses the storage block containing the input sequence.

copy_data – The flag that indicates whether to copy the elements of the extracted slice ( copy_data!=0 ) or not ( copy_data=0 )

The function creates a sequence that represents the specified slice of the input sequence. The new sequence either shares the elements with the original sequence or has its own copy of the elements. So if one needs to process a part of sequence but the processing function does not have a slice parameter, the required sub-sequence may be extracted using this function.

func – The comparison function that returns a negative, zero, or positive value depending on the relationships among the elements (see the above declaration and the example below) - a similar function is used by qsort from C runline except that in the latter, userdata is not used

userdata – The user parameter passed to the comparison function; helps to avoid global variables in some cases

The function sorts the sequence in-place using the specified criteria. Below is an example of using this function:

/* Sort 2d points in top-to-bottom left-to-right order */staticintcmp_func(constvoid*_a,constvoid*_b,void*userdata){CvPoint*a=(CvPoint*)_a;CvPoint*b=(CvPoint*)_b;inty_diff=a->y-b->y;intx_diff=a->x-b->x;returny_diff?y_diff:x_diff;}...CvMemStorage*storage=cvCreateMemStorage(0);CvSeq*seq=cvCreateSeq(CV_32SC2,sizeof(CvSeq),sizeof(CvPoint),storage);inti;for(i=0;i<10;i++){CvPointpt;pt.x=rand()pt.y=rand()cvSeqPush(seq,&pt);}cvSeqSort(seq,cmp_func,0/* userdata is not used here */);/* print out the sorted sequence */for(i=0;i<seq->total;i++){CvPoint*pt=(CvPoint*)cvSeqElem(seq,i);printf("(}cvReleaseMemStorage(&storage);

The function allocates a new node, optionally copies
input element data to it, and returns the pointer and the index to the
node. The index value is taken from the lower bits of the
flags
field of the node. The function has O(1) complexity; however, there exists
a faster function for allocating set nodes (see
SetNew()
).

The function removes an element with a specified
index from the set. If the node at the specified location is not occupied,
the function does nothing. The function has O(1) complexity; however,
SetRemoveByPtr()
provides a quicker way to remove a set element
if it is located already.

The function affects memory allocation
granularity. When the free space in the sequence buffers has run out,
the function allocates the space for
delta_elems
sequence
elements. If this block immediately follows the one previously allocated,
the two blocks are concatenated; otherwise, a new sequence block is
created. Therefore, the bigger the parameter is, the lower the possible
sequence fragmentation, but the more space in the storage block is wasted. When
the sequence is created, the parameter
delta_elems
is set to
the default value of about 1K. The function can be called any time after
the sequence is created and affects future allocations. The function
can modify the passed value of the parameter to meet memory storage
constraints.

The function initializes the process of
writing data to a sequence. Written elements are added to the end of the
sequence by using the
CV_WRITE_SEQ_ELEM(written_elem,writer)
macro. Note
that during the writing process, other operations on the sequence may
yield an incorrect result or even corrupt the sequence (see description of
FlushSeqWriter()
, which helps to avoid some of these problems).

reverse – Determines the direction of the sequence traversal. If reverse is 0, the reader is positioned at the first sequence element; otherwise it is positioned at the last element.

The function initializes the reader state. After
that, all the sequence elements from the first one down to the last one
can be read by subsequent calls of the macro
CV_READ_SEQ_ELEM(read_elem,reader)
in the case of forward reading and by using
CV_REV_READ_SEQ_ELEM(read_elem,reader)
in the case of reverse
reading. Both macros put the sequence element to
read_elem
and
move the reading pointer toward the next element. A circular structure
of sequence blocks is used for the reading process, that is, after the
last element has been read by the macro
CV_READ_SEQ_ELEM
, the
first element is read when the macro is called again. The same applies to
CV_REV_READ_SEQ_ELEM
. There is no function to finish the reading
process, since it neither changes the sequence nor creates any temporary
buffers. The reader field
ptr
points to the current element of
the sequence that is to be read next. The code below demonstrates how
to use the sequence writer and reader.

CvMemStorage*storage=cvCreateMemStorage(0);CvSeq*seq=cvCreateSeq(CV_32SC1,sizeof(CvSeq),sizeof(int),storage);CvSeqWriterwriter;CvSeqReaderreader;inti;cvStartAppendToSeq(seq,&writer);for(i=0;i<10;i++){intval=rand()CV_WRITE_SEQ_ELEM(val,writer);printf("}cvEndWriteSeq(&writer);cvStartReadSeq(seq,&reader,0);for(i=0;i<seq->total;i++){intval;#if 1CV_READ_SEQ_ELEM(val,reader);printf("#else /* alternative way, that is prefferable if sequence elements are large, or their size/type is unknown at compile time */printf("CV_NEXT_SEQ_ELEM(seq->elem_size,reader);#endif}...cvReleaseStorage(&storage);

seq_flags – Flags of the created sequence. If the sequence is not passed to any function working with a specific type of sequences, the sequence value may be equal to 0; otherwise the appropriate type must be selected from the list of predefined sequence types.

header_size – Size of the sequence header. The parameter value may not be less than sizeof(CvSeq) . If a certain type or extension is specified, it must fit within the base type header.

elem_size – Size of the sequence elements in bytes; must be consistent with the sequence type. For example, if a sequence of points is created (element type CV_SEQ_ELTYPE_POINT ), then the parameter elem_size must be equal to sizeof(CvPoint) .

storage – Sequence location

writer – Writer state; initialized by the function

The function is a combination of
CreateSeq()
and
StartAppendToSeq()
. The pointer to the
created sequence is stored at
writer->seq
and is also returned by the
EndWriteSeq()
function that should be called at the end.