OpenCV  2.4.13.5
Open Source Computer Vision
cv::SparseMat Class Reference

#include <core.hpp>

Inheritance diagram for cv::SparseMat:
cv::SparseMat_< _Tp >

Classes

struct  Hdr
 the sparse matrix header More...
 
struct  Node
 sparse matrix node - element of a hash table More...
 

Public Types

enum  { MAGIC_VAL =0x42FD0000, MAX_DIM =CV_MAX_DIM, HASH_SCALE =0x5bd1e995, HASH_BIT =0x80000000 }
 
typedef SparseMatIterator iterator
 
typedef SparseMatConstIterator const_iterator
 

Public Member Functions

 SparseMat ()
 default constructor More...
 
 SparseMat (int dims, const int *_sizes, int _type)
 creates matrix of the specified size and type More...
 
 SparseMat (const SparseMat &m)
 copy constructor More...
 
 SparseMat (const Mat &m)
 converts dense 2d matrix to the sparse form More...
 
 SparseMat (const CvSparseMat *m)
 converts old-style sparse matrix to the new-style. All the data is copied More...
 
 ~SparseMat ()
 the destructor More...
 
SparseMatoperator= (const SparseMat &m)
 assignment operator. This is O(1) operation, i.e. no data is copied More...
 
SparseMatoperator= (const Mat &m)
 equivalent to the corresponding constructor More...
 
SparseMat clone () const
 creates full copy of the matrix More...
 
void copyTo (SparseMat &m) const
 copies all the data to the destination matrix. All the previous content of m is erased More...
 
void copyTo (Mat &m) const
 converts sparse matrix to dense matrix. More...
 
void convertTo (SparseMat &m, int rtype, double alpha=1) const
 multiplies all the matrix elements by the specified scale factor alpha and converts the results to the specified data type More...
 
void convertTo (Mat &m, int rtype, double alpha=1, double beta=0) const
 converts sparse matrix to dense n-dim matrix with optional type conversion and scaling. More...
 
void assignTo (SparseMat &m, int type=-1) const
 
void create (int dims, const int *_sizes, int _type)
 reallocates sparse matrix. More...
 
void clear ()
 sets all the sparse matrix elements to 0, which means clearing the hash table. More...
 
void addref ()
 manually increments the reference counter to the header. More...
 
void release ()
 
 operator CvSparseMat * () const
 converts sparse matrix to the old-style representation; all the elements are copied. More...
 
size_t elemSize () const
 returns the size of each element in bytes (not including the overhead - the space occupied by SparseMat::Node elements) More...
 
size_t elemSize1 () const
 returns elemSize()/channels() More...
 
int type () const
 returns type of sparse matrix elements More...
 
int depth () const
 returns the depth of sparse matrix elements More...
 
int channels () const
 returns the number of channels More...
 
const intsize () const
 returns the array of sizes, or NULL if the matrix is not allocated More...
 
int size (int i) const
 returns the size of i-th matrix dimension (or 0) More...
 
int dims () const
 returns the matrix dimensionality More...
 
size_t nzcount () const
 returns the number of non-zero elements (=the number of hash table nodes) More...
 
size_t hash (int i0) const
 computes the element hash value (1D case) More...
 
size_t hash (int i0, int i1) const
 computes the element hash value (2D case) More...
 
size_t hash (int i0, int i1, int i2) const
 computes the element hash value (3D case) More...
 
size_t hash (const int *idx) const
 computes the element hash value (nD case) More...
 
SparseMatIterator end ()
 returns the sparse matrix iterator at the matrix end More...
 
SparseMatConstIterator end () const
 returns the read-only sparse matrix iterator at the matrix end More...
 
template<typename _Tp >
SparseMatIterator_< _Tp > end ()
 returns the typed sparse matrix iterator at the matrix end More...
 
template<typename _Tp >
SparseMatConstIterator_< _Tp > end () const
 returns the typed read-only sparse matrix iterator at the matrix end More...
 
template<typename _Tp >
_Tp & value (Node *n)
 returns the value stored in the sparse martix node More...
 
template<typename _Tp >
const _Tp & value (const Node *n) const
 returns the value stored in the sparse martix node More...
 
Nodenode (size_t nidx)
 
const Nodenode (size_t nidx) const
 
ucharnewNode (const int *idx, size_t hashval)
 
void removeNode (size_t hidx, size_t nidx, size_t previdx)
 
void resizeHashTab (size_t newsize)
 
ucharptr (int i0, bool createMissing, size_t *hashval=0)
 returns pointer to the specified element (1D case) More...
 
ucharptr (int i0, int i1, bool createMissing, size_t *hashval=0)
 returns pointer to the specified element (2D case) More...
 
ucharptr (int i0, int i1, int i2, bool createMissing, size_t *hashval=0)
 returns pointer to the specified element (3D case) More...
 
ucharptr (const int *idx, bool createMissing, size_t *hashval=0)
 returns pointer to the specified element (nD case) More...
 
template<typename _Tp >
_Tp & ref (int i0, size_t *hashval=0)
 returns reference to the specified element (1D case) More...
 
template<typename _Tp >
_Tp & ref (int i0, int i1, size_t *hashval=0)
 returns reference to the specified element (2D case) More...
 
template<typename _Tp >
_Tp & ref (int i0, int i1, int i2, size_t *hashval=0)
 returns reference to the specified element (3D case) More...
 
template<typename _Tp >
_Tp & ref (const int *idx, size_t *hashval=0)
 returns reference to the specified element (nD case) More...
 
template<typename _Tp >
_Tp value (int i0, size_t *hashval=0) const
 returns value of the specified element (1D case) More...
 
template<typename _Tp >
_Tp value (int i0, int i1, size_t *hashval=0) const
 returns value of the specified element (2D case) More...
 
template<typename _Tp >
_Tp value (int i0, int i1, int i2, size_t *hashval=0) const
 returns value of the specified element (3D case) More...
 
template<typename _Tp >
_Tp value (const int *idx, size_t *hashval=0) const
 returns value of the specified element (nD case) More...
 
template<typename _Tp >
const _Tp * find (int i0, size_t *hashval=0) const
 returns pointer to the specified element (1D case) More...
 
template<typename _Tp >
const _Tp * find (int i0, int i1, size_t *hashval=0) const
 returns pointer to the specified element (2D case) More...
 
template<typename _Tp >
const _Tp * find (int i0, int i1, int i2, size_t *hashval=0) const
 returns pointer to the specified element (3D case) More...
 
template<typename _Tp >
const _Tp * find (const int *idx, size_t *hashval=0) const
 returns pointer to the specified element (nD case) More...
 
void erase (int i0, int i1, size_t *hashval=0)
 erases the specified element (2D case) More...
 
void erase (int i0, int i1, int i2, size_t *hashval=0)
 erases the specified element (3D case) More...
 
void erase (const int *idx, size_t *hashval=0)
 erases the specified element (nD case) More...
 
SparseMatIterator begin ()
 returns the sparse matrix iterator at the matrix beginning More...
 
template<typename _Tp >
SparseMatIterator_< _Tp > begin ()
 returns the sparse matrix iterator at the matrix beginning More...
 
SparseMatConstIterator begin () const
 returns the read-only sparse matrix iterator at the matrix beginning More...
 
template<typename _Tp >
SparseMatConstIterator_< _Tp > begin () const
 returns the read-only sparse matrix iterator at the matrix beginning More...
 

Public Attributes

int flags
 
Hdrhdr
 

Detailed Description

Sparse matrix class.

The class represents multi-dimensional sparse numerical arrays. Such a sparse array can store elements of any type that cv::Mat is able to store. "Sparse" means that only non-zero elements are stored (though, as a result of some operations on a sparse matrix, some of its stored elements can actually become 0. It's user responsibility to detect such elements and delete them using cv::SparseMat::erase(). The non-zero elements are stored in a hash table that grows when it's filled enough, so that the search time remains O(1) in average. Elements can be accessed using the following methods:

  1. Query operations: cv::SparseMat::ptr() and the higher-level cv::SparseMat::ref(), cv::SparseMat::value() and cv::SparseMat::find, for example:

    const int dims = 5;
    int size[] = {10, 10, 10, 10, 10};
    SparseMat sparse_mat(dims, size, CV_32F);
    for(int i = 0; i < 1000; i++)
    {
    int idx[dims];
    for(int k = 0; k < dims; k++)
    idx[k] = rand()%sparse_mat.size(k);
    sparse_mat.ref<float>(idx) += 1.f;
    }

  2. Sparse matrix iterators. Like cv::Mat iterators and unlike cv::Mat iterators, the sparse matrix iterators are STL-style, that is, the iteration is done as following:

    // prints elements of a sparse floating-point matrix and the sum of elements.
    SparseMatConstIterator_<float>
    it = sparse_mat.begin<float>(),
    it_end = sparse_mat.end<float>();
    double s = 0;
    int dims = sparse_mat.dims();
    for(; it != it_end; ++it)
    {
    // print element indices and the element value
    const Node* n = it.node();
    printf("(")
    for(int i = 0; i < dims; i++)
    printf("%3d%c", n->idx[i], i < dims-1 ? ',' : ')');
    printf(": %f\n", *it);
    s += *it;
    }
    printf("Element sum is %g\n", s);

    If you run this loop, you will notice that elements are enumerated in no any logical order (lexicographical etc.), they come in the same order as they stored in the hash table, i.e. semi-randomly.

    You may collect pointers to the nodes and sort them to get the proper ordering. Note, however, that pointers to the nodes may become invalid when you add more elements to the matrix; this is because of possible buffer reallocation.

  3. A combination of the above 2 methods when you need to process 2 or more sparse matrices simultaneously, e.g. this is how you can compute unnormalized cross-correlation of the 2 floating-point sparse matrices:
    double crossCorr(const SparseMat& a, const SparseMat& b)
    {
    const SparseMat *_a = &a, *_b = &b;
    // if b contains less elements than a,
    // it's faster to iterate through b
    if(_a->nzcount() > _b->nzcount())
    std::swap(_a, _b);
    SparseMatConstIterator_<float> it = _a->begin<float>(),
    it_end = _a->end<float>();
    double ccorr = 0;
    for(; it != it_end; ++it)
    {
    // take the next element from the first matrix
    float avalue = *it;
    const Node* anode = it.node();
    // and try to find element with the same index in the second matrix.
    // since the hash value depends only on the element index,
    // we reuse hashvalue stored in the node
    float bvalue = _b->value<float>(anode->idx,&anode->hashval);
    ccorr += avalue*bvalue;
    }
    return ccorr;
    }

Member Typedef Documentation

§ const_iterator

§ iterator

Member Enumeration Documentation

§ anonymous enum

anonymous enum
Enumerator
MAGIC_VAL 
MAX_DIM 
HASH_SCALE 
HASH_BIT 

Constructor & Destructor Documentation

§ SparseMat() [1/5]

cv::SparseMat::SparseMat ( )
inline

default constructor

§ SparseMat() [2/5]

cv::SparseMat::SparseMat ( int  dims,
const int _sizes,
int  _type 
)
inline

creates matrix of the specified size and type

§ SparseMat() [3/5]

cv::SparseMat::SparseMat ( const SparseMat m)
inline

copy constructor

§ SparseMat() [4/5]

cv::SparseMat::SparseMat ( const Mat m)
explicit

converts dense 2d matrix to the sparse form

Parameters
mthe input matrix

§ SparseMat() [5/5]

cv::SparseMat::SparseMat ( const CvSparseMat m)

converts old-style sparse matrix to the new-style. All the data is copied

§ ~SparseMat()

cv::SparseMat::~SparseMat ( )
inline

the destructor

Member Function Documentation

§ addref()

void cv::SparseMat::addref ( )
inline

manually increments the reference counter to the header.

§ assignTo()

void cv::SparseMat::assignTo ( SparseMat m,
int  type = -1 
) const
inline

§ begin() [1/4]

SparseMatIterator cv::SparseMat::begin ( )
inline

returns the sparse matrix iterator at the matrix beginning

return the sparse matrix iterator pointing to the first sparse matrix element

§ begin() [2/4]

template<typename _Tp >
SparseMatIterator_< _Tp > cv::SparseMat::begin ( )
inline

returns the sparse matrix iterator at the matrix beginning

§ begin() [3/4]

SparseMatConstIterator cv::SparseMat::begin ( ) const
inline

returns the read-only sparse matrix iterator at the matrix beginning

§ begin() [4/4]

template<typename _Tp >
SparseMatConstIterator_< _Tp > cv::SparseMat::begin ( ) const
inline

returns the read-only sparse matrix iterator at the matrix beginning

§ channels()

int cv::SparseMat::channels ( ) const
inline

returns the number of channels

§ clear()

void cv::SparseMat::clear ( )

sets all the sparse matrix elements to 0, which means clearing the hash table.

§ clone()

SparseMat cv::SparseMat::clone ( ) const
inline

creates full copy of the matrix

§ convertTo() [1/2]

void cv::SparseMat::convertTo ( SparseMat m,
int  rtype,
double  alpha = 1 
) const

multiplies all the matrix elements by the specified scale factor alpha and converts the results to the specified data type

§ convertTo() [2/2]

void cv::SparseMat::convertTo ( Mat m,
int  rtype,
double  alpha = 1,
double  beta = 0 
) const

converts sparse matrix to dense n-dim matrix with optional type conversion and scaling.

Parameters
mDestination matrix
rtypeThe output matrix data type. When it is =-1, the output array will have the same data type as (*this)
alphaThe scale factor
betaThe optional delta added to the scaled values before the conversion

§ copyTo() [1/2]

void cv::SparseMat::copyTo ( SparseMat m) const

copies all the data to the destination matrix. All the previous content of m is erased

§ copyTo() [2/2]

void cv::SparseMat::copyTo ( Mat m) const

converts sparse matrix to dense matrix.

§ create()

void cv::SparseMat::create ( int  dims,
const int _sizes,
int  _type 
)

reallocates sparse matrix.

If the matrix already had the proper size and type, it is simply cleared with clear(), otherwise, the old matrix is released (using release()) and the new one is allocated.

§ depth()

int cv::SparseMat::depth ( ) const
inline

returns the depth of sparse matrix elements

§ dims()

int cv::SparseMat::dims ( ) const
inline

returns the matrix dimensionality

§ elemSize()

size_t cv::SparseMat::elemSize ( ) const
inline

returns the size of each element in bytes (not including the overhead - the space occupied by SparseMat::Node elements)

§ elemSize1()

size_t cv::SparseMat::elemSize1 ( ) const
inline

returns elemSize()/channels()

§ end() [1/4]

SparseMatIterator cv::SparseMat::end ( )
inline

returns the sparse matrix iterator at the matrix end

return the sparse matrix iterator pointing to the element following the last sparse matrix element

§ end() [2/4]

SparseMatConstIterator cv::SparseMat::end ( ) const
inline

returns the read-only sparse matrix iterator at the matrix end

§ end() [3/4]

template<typename _Tp >
SparseMatIterator_< _Tp > cv::SparseMat::end ( )
inline

returns the typed sparse matrix iterator at the matrix end

§ end() [4/4]

template<typename _Tp >
SparseMatConstIterator_< _Tp > cv::SparseMat::end ( ) const
inline

returns the typed read-only sparse matrix iterator at the matrix end

§ erase() [1/3]

void cv::SparseMat::erase ( int  i0,
int  i1,
size_t *  hashval = 0 
)

erases the specified element (2D case)

§ erase() [2/3]

void cv::SparseMat::erase ( int  i0,
int  i1,
int  i2,
size_t *  hashval = 0 
)

erases the specified element (3D case)

§ erase() [3/3]

void cv::SparseMat::erase ( const int idx,
size_t *  hashval = 0 
)

erases the specified element (nD case)

§ find() [1/4]

template<typename _Tp >
const _Tp * cv::SparseMat::find ( int  i0,
size_t *  hashval = 0 
) const
inline

returns pointer to the specified element (1D case)

Return pointer to the specified sparse matrix element if it exists

find<_Tp>(i0,...[,hashval]) is equivalent to (_const Tp*)ptr(i0,...false[,hashval]).

If the specified element does not exist, the methods return NULL.

§ find() [2/4]

template<typename _Tp >
const _Tp * cv::SparseMat::find ( int  i0,
int  i1,
size_t *  hashval = 0 
) const
inline

returns pointer to the specified element (2D case)

§ find() [3/4]

template<typename _Tp >
const _Tp * cv::SparseMat::find ( int  i0,
int  i1,
int  i2,
size_t *  hashval = 0 
) const
inline

returns pointer to the specified element (3D case)

§ find() [4/4]

template<typename _Tp >
const _Tp * cv::SparseMat::find ( const int idx,
size_t *  hashval = 0 
) const
inline

returns pointer to the specified element (nD case)

§ hash() [1/4]

size_t cv::SparseMat::hash ( int  i0) const
inline

computes the element hash value (1D case)

§ hash() [2/4]

size_t cv::SparseMat::hash ( int  i0,
int  i1 
) const
inline

computes the element hash value (2D case)

§ hash() [3/4]

size_t cv::SparseMat::hash ( int  i0,
int  i1,
int  i2 
) const
inline

computes the element hash value (3D case)

§ hash() [4/4]

size_t cv::SparseMat::hash ( const int idx) const
inline

computes the element hash value (nD case)

§ newNode()

uchar* cv::SparseMat::newNode ( const int idx,
size_t  hashval 
)

§ node() [1/2]

SparseMat::Node * cv::SparseMat::node ( size_t  nidx)
inline

§ node() [2/2]

const SparseMat::Node * cv::SparseMat::node ( size_t  nidx) const
inline

§ nzcount()

size_t cv::SparseMat::nzcount ( ) const
inline

returns the number of non-zero elements (=the number of hash table nodes)

§ operator CvSparseMat *()

cv::SparseMat::operator CvSparseMat * ( ) const

converts sparse matrix to the old-style representation; all the elements are copied.

§ operator=() [1/2]

SparseMat & cv::SparseMat::operator= ( const SparseMat m)
inline

assignment operator. This is O(1) operation, i.e. no data is copied

§ operator=() [2/2]

SparseMat & cv::SparseMat::operator= ( const Mat m)
inline

equivalent to the corresponding constructor

§ ptr() [1/4]

uchar* cv::SparseMat::ptr ( int  i0,
bool  createMissing,
size_t *  hashval = 0 
)

returns pointer to the specified element (1D case)

specialized variants for 1D, 2D, 3D cases and the generic_type one for n-D case.

return pointer to the matrix element.

  • if the element is there (it's non-zero), the pointer to it is returned
  • if it's not there and createMissing=false, NULL pointer is returned
  • if it's not there and createMissing=true, then the new element is created and initialized with 0. Pointer to it is returned
  • if the optional hashval pointer is not NULL, the element hash value is not computed, but *hashval is taken instead.

§ ptr() [2/4]

uchar* cv::SparseMat::ptr ( int  i0,
int  i1,
bool  createMissing,
size_t *  hashval = 0 
)

returns pointer to the specified element (2D case)

§ ptr() [3/4]

uchar* cv::SparseMat::ptr ( int  i0,
int  i1,
int  i2,
bool  createMissing,
size_t *  hashval = 0 
)

returns pointer to the specified element (3D case)

§ ptr() [4/4]

uchar* cv::SparseMat::ptr ( const int idx,
bool  createMissing,
size_t *  hashval = 0 
)

returns pointer to the specified element (nD case)

§ ref() [1/4]

template<typename _Tp >
_Tp & cv::SparseMat::ref ( int  i0,
size_t *  hashval = 0 
)
inline

returns reference to the specified element (1D case)

return read-write reference to the specified sparse matrix element.

ref<_Tp>(i0,...[,hashval]) is equivalent to *(_Tp*)ptr(i0,...,true[,hashval]). The methods always return a valid reference. If the element did not exist, it is created and initialiazed with 0.

§ ref() [2/4]

template<typename _Tp >
_Tp & cv::SparseMat::ref ( int  i0,
int  i1,
size_t *  hashval = 0 
)
inline

returns reference to the specified element (2D case)

§ ref() [3/4]

template<typename _Tp >
_Tp & cv::SparseMat::ref ( int  i0,
int  i1,
int  i2,
size_t *  hashval = 0 
)
inline

returns reference to the specified element (3D case)

§ ref() [4/4]

template<typename _Tp >
_Tp & cv::SparseMat::ref ( const int idx,
size_t *  hashval = 0 
)
inline

returns reference to the specified element (nD case)

§ release()

void cv::SparseMat::release ( )
inline

§ removeNode()

void cv::SparseMat::removeNode ( size_t  hidx,
size_t  nidx,
size_t  previdx 
)

§ resizeHashTab()

void cv::SparseMat::resizeHashTab ( size_t  newsize)

§ size() [1/2]

const int * cv::SparseMat::size ( ) const
inline

returns the array of sizes, or NULL if the matrix is not allocated

§ size() [2/2]

int cv::SparseMat::size ( int  i) const
inline

returns the size of i-th matrix dimension (or 0)

§ type()

int cv::SparseMat::type ( ) const
inline

returns type of sparse matrix elements

§ value() [1/6]

template<typename _Tp >
_Tp cv::SparseMat::value ( int  i0,
size_t *  hashval = 0 
) const
inline

returns value of the specified element (1D case)

return value of the specified sparse matrix element.

value<_Tp>(i0,...[,hashval]) is equivalent

{ const _Tp* p = find<_Tp>(i0,...[,hashval]); return p ? *p : _Tp(); }

That is, if the element did not exist, the methods return 0.

§ value() [2/6]

template<typename _Tp >
_Tp cv::SparseMat::value ( int  i0,
int  i1,
size_t *  hashval = 0 
) const
inline

returns value of the specified element (2D case)

§ value() [3/6]

template<typename _Tp >
_Tp cv::SparseMat::value ( int  i0,
int  i1,
int  i2,
size_t *  hashval = 0 
) const
inline

returns value of the specified element (3D case)

§ value() [4/6]

template<typename _Tp >
_Tp cv::SparseMat::value ( const int idx,
size_t *  hashval = 0 
) const
inline

returns value of the specified element (nD case)

§ value() [5/6]

template<typename _Tp >
_Tp & cv::SparseMat::value ( Node n)
inline

returns the value stored in the sparse martix node

§ value() [6/6]

template<typename _Tp >
const _Tp & cv::SparseMat::value ( const Node n) const
inline

returns the value stored in the sparse martix node

Member Data Documentation

§ flags

int cv::SparseMat::flags

§ hdr

Hdr* cv::SparseMat::hdr

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