class cv::SparseMat

Overview

The class SparseMat represents multi-dimensional sparse numerical arrays. More…

#include <mat.hpp>

class SparseMat
{
public:
    // typedefs

    typedef SparseMatConstIterator const_iterator;
    typedef SparseMatIterator iterator;

    // enums

    enum
    {
        MAGIC_VAL  =0x42FD0000,
        MAX_DIM    =32,
        HASH_SCALE =0x5bd1e995,
        HASH_BIT   =0x80000000,
    };

    // structs

    struct Hdr;
    struct Node;

    // fields

    int flags;
    Hdr* hdr;

    // construction

    SparseMat();

    SparseMat(
        int dims,
        const int* _sizes,
        int _type
        );

    SparseMat(const SparseMat& m);
    SparseMat(const Mat& m);

    // methods

    uchar*
    ptr(
        int i0,
        bool createMissing,
        size_t* hashval = 0
        );

    uchar*
    ptr(
        int i0,
        int i1,
        bool createMissing,
        size_t* hashval = 0
        );

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

    uchar*
    ptr(
        const int* idx,
        bool createMissing,
        size_t* hashval = 0
        );

    template <typename _Tp>
    _Tp&
    ref(
        int i0,
        size_t* hashval = 0
        );

    template <typename _Tp>
    _Tp&
    ref(
        int i0,
        int i1,
        size_t* hashval = 0
        );

    template <typename _Tp>
    _Tp&
    ref(
        int i0,
        int i1,
        int i2,
        size_t* hashval = 0
        );

    template <typename _Tp>
    _Tp&
    ref(
        const int* idx,
        size_t* hashval = 0
        );

    template <typename _Tp>
    _Tp
    value(
        int i0,
        size_t* hashval = 0
        ) const;

    template <typename _Tp>
    _Tp
    value(
        int i0,
        int i1,
        size_t* hashval = 0
        ) const;

    template <typename _Tp>
    _Tp
    value(
        int i0,
        int i1,
        int i2,
        size_t* hashval = 0
        ) const;

    template <typename _Tp>
    _Tp
    value(
        const int* idx,
        size_t* hashval = 0
        ) const;

    template <typename _Tp>
    const _Tp*
    find(
        int i0,
        size_t* hashval = 0
        ) const;

    template <typename _Tp>
    const _Tp*
    find(
        int i0,
        int i1,
        size_t* hashval = 0
        ) const;

    template <typename _Tp>
    const _Tp*
    find(
        int i0,
        int i1,
        int i2,
        size_t* hashval = 0
        ) const;

    template <typename _Tp>
    const _Tp*
    find(
        const int* idx,
        size_t* hashval = 0
        ) const;

    SparseMatIterator
    begin();

    template <typename _Tp>
    SparseMatIterator_<_Tp>
    begin();

    SparseMatConstIterator
    begin() const;

    template <typename _Tp>
    SparseMatConstIterator_<_Tp>
    begin() const;

    void
    addref();

    void
    assignTo(
        SparseMat& m,
        int type = -1
        ) const;

    int
    channels() const;

    void
    clear();

    SparseMat
    clone() const;

    void
    convertTo(
        SparseMat& m,
        int rtype,
        double alpha = 1
        ) const;

    void
    convertTo(
        Mat& m,
        int rtype,
        double alpha = 1,
        double beta = 0
        ) const;

    void
    copyTo(SparseMat& m) const;

    void
    copyTo(Mat& m) const;

    void
    create(
        int dims,
        const int* _sizes,
        int _type
        );

    int
    depth() const;

    int
    dims() const;

    size_t
    elemSize() const;

    size_t
    elemSize1() const;

    SparseMatIterator
    end();

    SparseMatConstIterator
    end() const;

    template <typename _Tp>
    SparseMatIterator_<_Tp>
    end();

    template <typename _Tp>
    SparseMatConstIterator_<_Tp>
    end() const;

    void
    erase(
        int i0,
        int i1,
        size_t* hashval = 0
        );

    void
    erase(
        int i0,
        int i1,
        int i2,
        size_t* hashval = 0
        );

    void
    erase(
        const int* idx,
        size_t* hashval = 0
        );

    size_t
    hash(int i0) const;

    size_t
    hash(
        int i0,
        int i1
        ) const;

    size_t
    hash(
        int i0,
        int i1,
        int i2
        ) const;

    size_t
    hash(const int* idx) const;

    uchar*
    newNode(
        const int* idx,
        size_t hashval
        );

    Node*
    node(size_t nidx);

    const Node*
    node(size_t nidx) const;

    size_t
    nzcount() const;

    SparseMat&
    operator=(const SparseMat& m);

    SparseMat&
    operator=(const Mat& m);

    void
    release();

    void
    removeNode(
        size_t hidx,
        size_t nidx,
        size_t previdx
        );

    void
    resizeHashTab(size_t newsize);

    const int*
    size() const;

    int
    size(int i) const;

    int
    type() const;

    template <typename _Tp>
    _Tp&
    value(Node* n);

    template <typename _Tp>
    const _Tp&
    value(const Node* n) const;
};

// direct descendants

template <typename _Tp>
class SparseMat_;

Detailed Documentation

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;
  }
  

Construction

SparseMat()

Various SparseMat constructors.

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

Methods

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

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

returns pointer to the specified element (2D case)

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

returns pointer to the specified element (3D case)

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

returns pointer to the specified element (nD case)

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

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.

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

returns reference to the specified element (2D case)

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

returns reference to the specified element (3D case)

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

returns reference to the specified element (nD case)

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

returns value of the specified element (1D case)

return value of the specified sparse matrix element.

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

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

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

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

returns value of the specified element (2D case)

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

returns value of the specified element (3D case)

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

returns value of the specified element (nD case)

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

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.

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

returns pointer to the specified element (2D case)

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)

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

returns pointer to the specified element (nD case)

SparseMatIterator
begin()

returns the sparse matrix iterator at the matrix beginning

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

template <typename _Tp>
SparseMatIterator_<_Tp>
begin()

returns the sparse matrix iterator at the matrix beginning

SparseMatConstIterator
begin() const

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

template <typename _Tp>
SparseMatConstIterator_<_Tp>
begin() const

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

void
addref()

manually increments the reference counter to the header.

int
channels() const

returns the number of channels

void
clear()

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

SparseMat
clone() const

creates full copy of the matrix

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

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.

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

void
copyTo(SparseMat& m) const

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

void
copyTo(Mat& m) const

converts sparse matrix to dense matrix.

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

int
depth() const

returns the depth of sparse matrix elements

int
dims() const

returns the matrix dimensionality

size_t
elemSize() const

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)

size_t
elemSize1() const

returns elemSize() /channels()

SparseMatIterator
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

SparseMatConstIterator
end() const

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

template <typename _Tp>
SparseMatIterator_<_Tp>
end()

returns the typed sparse matrix iterator at the matrix end

template <typename _Tp>
SparseMatConstIterator_<_Tp>
end() const

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

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

erases the specified element (2D case)

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

erases the specified element (3D case)

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

erases the specified element (nD case)

size_t
hash(int i0) const

computes the element hash value (1D case)

size_t
hash(
    int i0,
    int i1
    ) const

computes the element hash value (2D case)

size_t
hash(
    int i0,
    int i1,
    int i2
    ) const

computes the element hash value (3D case)

size_t
hash(const int* idx) const

computes the element hash value (nD case)

size_t
nzcount() const

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

SparseMat&
operator=(const SparseMat& m)

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

SparseMat&
operator=(const Mat& m)

equivalent to the corresponding constructor

const int*
size() const

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

int
size(int i) const

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

int
type() const

returns type of sparse matrix elements

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

returns the value stored in the sparse martix node

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

returns the value stored in the sparse martix node