Class cv::SparseMat#

The class SparseMat represents multi-dimensional sparse numerical arrays. View details

#include <opencv2/core/mat.hpp>

Collaboration diagram for cv::SparseMat:

Public Types#

enum cv::SparseMat {
    cv::MAGIC_VAL =0x42FD0000,
    cv::MAX_DIM =32,
    cv::HASH_SCALE =0x5bd1e995,
    cv::HASH_BIT =0x80000000
}

Detailed Description#

The class SparseMat represents multi-dimensional sparse numerical arrays.

Such a sparse array can store elements of any type that Mat can store. Sparse means that only non-zero elements are stored (though, as a result of operations on a sparse matrix, some of its stored elements can actually become 0. It is up to you to detect such elements and delete them using SparseMat::erase ). The non-zero elements are stored in a hash table that grows when it is filled so that the search time is O(1) in average (regardless of whether element is there or not). Elements can be accessed using the following methods:

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

const int dims = 5;
int size[5] = {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() % size[k];
    sparse_mat.ref<float>(idx) += 1.f;
}
cout << "nnz = " << sparse_mat.nzcount() << endl;

Sparse matrix iterators. They are similar to MatIterator but different from NAryMatIterator. That is, the iteration loop is familiar to STL users:
```
// 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 SparseMat::Node* n = it.node();
    printf("(");
    for(int i = 0; i < dims; i++)
        printf("%d%s", n->idx[i], i < dims-1 ? ", " : ")");
    printf(": %g\n", it.value<float>());
    s += *it;
}
printf("Element sum is %g\n", s);
```
If you run this loop, you will notice that elements are not enumerated in a logical order (lexicographical, and so on). They come in the same order as they are stored in the hash table (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 may happen due to possible buffer reallocation.

Combination of the above 2 methods when you need to process 2 or more sparse matrices simultaneously. For example, this is how you can compute unnormalized cross-correlation of the 2 floating-point sparse matrices:

double cross_corr(const SparseMat& a, const SparseMat& b)
{
    const SparseMat *_a = &a, *_b = &b;
    // if b contains less elements than a,
    // it is 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 an element with the same index in the second matrix.
        // since the hash value depends only on the element index,
        // reuse the hash value stored in the node
        float bvalue = _b->value<float>(anode->idx,&anode->hashval);
        ccorr += avalue*bvalue;
    }
    return ccorr;
}

Member Typedef Documentation#

const_iterator#

typedef SparseMatConstIterator cv::SparseMat::const_iterator

iterator#

typedef SparseMatIterator cv::SparseMat::iterator

Member Enumeration Documentation#

enum SparseMat

MAGIC_VAL

MAX_DIM

HASH_SCALE

HASH_BIT

Constructor & Destructor Documentation#

SparseMat()#

cv::SparseMat::SparseMat()

Various SparseMat constructors.

SparseMat()#

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

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

Parameters

m — Source matrix for copy constructor. If m is dense matrix (ocvMat) then it will be converted to sparse representation.

SparseMat()#

cv::SparseMat::SparseMat(const SparseMat & m)

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

Parameters

m — Source matrix for copy constructor. If m is dense matrix (ocvMat) then it will be converted to sparse representation.

SparseMat()#

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

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

Parameters

dims — Array dimensionality.
_sizes — Sparce matrix size on all dementions.
_type — Sparse matrix data type.

~SparseMat()#

cv::SparseMat::~SparseMat()

the destructor

Member Function Documentation#

begin()#

SparseMatIterator cv::SparseMat::begin()

returns the sparse matrix iterator at the matrix beginning

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

begin()#

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

returns the sparse matrix iterator at the matrix beginning

begin()#

SparseMatConstIterator cv::SparseMat::begin()

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

begin()#

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

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

addref()#

void cv::SparseMat::addref()

manually increments the reference counter to the header.

assignTo()#

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

channels()#

int cv::SparseMat::channels()

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

CV_NODISCARD_STD SparseMat cv::SparseMat::clone()

creates full copy of the matrix

convertTo()#

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

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

Parameters

m — - output matrix; if it does not have a proper size or type before the operation, it is reallocated
rtype — - desired output matrix type or, rather, the depth since the number of channels are the same as the input has; if rtype is negative, the output matrix will have the same type as the input.
alpha — - optional scale factor
beta — - optional delta added to the scaled values

convertTo()#

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

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

copyTo()#

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

converts sparse matrix to dense matrix.

copyTo()#

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

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

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

returns the depth of sparse matrix elements

dims()#

int cv::SparseMat::dims()

returns the matrix dimensionality

elemSize()#

size_t cv::SparseMat::elemSize()

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

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

returns elemSize()/channels()

end()#

SparseMatIterator cv::SparseMat::end()

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

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

returns the typed sparse matrix iterator at the matrix end

end()#

SparseMatConstIterator cv::SparseMat::end()

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

end()#

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

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

erase()#

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

erases the specified element (nD case)

erase()#

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

erases the specified element (3D case)

erase()#

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

erases the specified element (2D case)

hash()#

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

computes the element hash value (nD case)

hash()#

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

computes the element hash value (1D case)

hash()#

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

computes the element hash value (2D case)

hash()#

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

computes the element hash value (3D case)

newNode()#

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

node()#

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

node()#

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

nzcount()#

size_t cv::SparseMat::nzcount()

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

operator=()#

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

equivalent to the corresponding constructor

operator=()#

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

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

release()#

void cv::SparseMat::release()

removeNode()#

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

resizeHashTab()#

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

size()#

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

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

size()#

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

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

type()#

int cv::SparseMat::type()

returns type of sparse matrix elements

value()#

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

returns the value stored in the sparse martix node

value()#

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

returns the value stored in the sparse martix node

Member Data Documentation#

flags#

int cv::SparseMat::flags

hdr#

Hdr * cv::SparseMat::hdr

Source file#

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

opencv2/core/mat.hpp