Struct opencv::core::SparseMat

pub struct SparseMat { /* private fields */ }

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

Implementations

impl SparseMat

pub fn default() -> Result<SparseMat>

Various SparseMat constructors.

pub fn new(dims: i32, _sizes: &i32, _type: i32) -> Result<SparseMat>

Various SparseMat constructors.

Overloaded parameters

Parameters

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

pub fn copy(m: &SparseMat) -> Result<SparseMat>

Various SparseMat constructors.

Overloaded parameters

Parameters

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

pub fn from_mat(m: &Mat) -> Result<SparseMat>

Various SparseMat constructors.

Overloaded parameters

Parameters

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

Trait Implementations

impl Boxed for SparseMat

unsafe fn from_raw(ptr: *mut c_void) -> Self

Wrap the specified raw pointer

fn into_raw(self) -> *mut c_void

Return an the underlying raw pointer while consuming this wrapper.

fn as_raw(&self) -> *const c_void

Return the underlying raw pointer.

fn as_raw_mut(&mut self) -> *mut c_void

Return the underlying mutable raw pointer

impl Clone for SparseMat

fn clone(&self) -> Self

Calls try_clone() and panics if that fails

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Drop for SparseMat

fn drop(&mut self)

Executes the destructor for this type.

impl SparseMatTrait for SparseMat

fn as_raw_mut_SparseMat(&mut self) -> *mut c_void

fn set_flags(&mut self, val: i32)

fn hdr(&mut self) -> SparseMat_Hdr

fn set_hdr(&mut self, val: &mut SparseMat_Hdr)

fn create(&mut self, dims: i32, _sizes: &i32, _type: i32) -> Result<()>

reallocates sparse matrix.

fn clear(&mut self) -> Result<()>

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

fn addref(&mut self) -> Result<()>

manually increments the reference counter to the header.

fn release(&mut self) -> Result<()>

fn ptr(
    &mut self,
    i0: i32,
    create_missing: bool,
    hashval: &mut size_t
) -> Result<*mut u8>

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.

fn ptr_1(
    &mut self,
    i0: i32,
    i1: i32,
    create_missing: bool,
    hashval: &mut size_t
) -> Result<*mut u8>

returns pointer to the specified element (2D case)

fn ptr_2(
    &mut self,
    i0: i32,
    i1: i32,
    i2: i32,
    create_missing: bool,
    hashval: &mut size_t
) -> Result<*mut u8>

returns pointer to the specified element (3D case)

fn ptr_3(
    &mut self,
    idx: &i32,
    create_missing: bool,
    hashval: &mut size_t
) -> Result<*mut u8>

returns pointer to the specified element (nD case)

fn erase(&mut self, i0: i32, i1: i32, hashval: &mut size_t) -> Result<()>

erases the specified element (2D case)

fn erase_1(&mut self, i0: i32, i1: i32, i2: i32, hashval: &mut size_t) -> Result<()>

erases the specified element (3D case)

fn erase_2(&mut self, idx: &i32, hashval: &mut size_t) -> Result<()>

erases the specified element (nD case)

fn begin_mut(&mut self) -> Result<SparseMatIterator>

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

fn end_mut(&mut self) -> Result<SparseMatIterator>

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

fn node_1(&mut self, nidx: size_t) -> Result<SparseMat_Node>

/////////// some internal-use methods ///////////////

fn new_node(&mut self, idx: &i32, hashval: size_t) -> Result<*mut u8>

fn remove_node(
    &mut self,
    hidx: size_t,
    nidx: size_t,
    previdx: size_t
) -> Result<()>

fn resize_hash_tab(&mut self, newsize: size_t) -> Result<()>

impl SparseMatTraitConst for SparseMat

fn as_raw_SparseMat(&self) -> *const c_void

fn flags(&self) -> i32

fn try_clone(&self) -> Result<SparseMat>

creates full copy of the matrix

fn copy_to(&self, m: &mut SparseMat) -> Result<()>

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

fn copy_to_mat(&self, m: &mut Mat) -> Result<()>

converts sparse matrix to dense matrix.

fn convert_to(&self, m: &mut SparseMat, rtype: i32, alpha: f64) -> Result<()>

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

fn convert_to_1(&self, m: &mut Mat, rtype: i32, alpha: f64, beta: f64) -> Result<()>

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

fn assign_to(&self, m: &mut SparseMat, typ: i32) -> Result<()>

C++ default parameters

fn elem_size(&self) -> size_t

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

fn elem_size1(&self) -> size_t

returns elemSize()/channels()

fn typ(&self) -> i32

returns type of sparse matrix elements

fn depth(&self) -> i32

returns the depth of sparse matrix elements

fn channels(&self) -> i32

returns the number of channels

fn size(&self) -> Result<*const i32>

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

fn size_1(&self, i: i32) -> Result<i32>

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

fn dims(&self) -> Result<i32>

returns the matrix dimensionality

fn nzcount(&self) -> Result<size_t>

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

fn hash(&self, i0: i32) -> Result<size_t>

computes the element hash value (1D case)

fn hash_1(&self, i0: i32, i1: i32) -> Result<size_t>

computes the element hash value (2D case)

fn hash_2(&self, i0: i32, i1: i32, i2: i32) -> Result<size_t>

computes the element hash value (3D case)

fn hash_3(&self, idx: &i32) -> Result<size_t>

computes the element hash value (nD case)

fn begin(&self) -> Result<SparseMatConstIterator>

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

fn end(&self) -> Result<SparseMatConstIterator>

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

fn node(&self, nidx: size_t) -> Result<SparseMat_Node>

impl Send for SparseMat