Image module
#include "diplib.h"

dip::Tensor class

enum class Shape: uint8

Possible shapes the tensor can have.

Shape::COL_MAJOR_MATRIX is stored as follows:

 |0 3 6|
 |1 4 7|
 |2 5 8|

Shape::ROW_MAJOR_MATRIX is its transpose. These two shapes always have more than one column and row. A tensor with only one row or one column is a vector (Shape::COL_VECTOR or Shape::ROW_VECTOR).

Shape::DIAGONAL_MATRIX stores only the diagonal elements.

Shape::SYMMETRIC_MATRIX and Shape::UPPTRIANG_MATRIX store the values in the upper triangle only, as follows:

 |0 4 5 7|
 |x 1 6 8|
 |x x 2 9|
 |x x x 3|

Here, x indicates values that are not stored.

Shape::LOWTRIANG_MATRIX is the transpose of Shape::UPPTRIANG_MATRIX.

We use the given ordering for symmetric and triangular matrices because this makes it easy to extract the diagonal without having to copy data (it’s just a window over the full tensor). Because it is a little awkward finding the right elements given this ordering, the function dip::Tensor::LookUpTable prepares a table that can be used to access any tensor element given the row and column number. This function should help make more generic functions that can access tensor elements without paying attention to the tensor’s Shape value.

To access each of the elements of a symmetric or triangular matrix, use the following code:

dip::uint index = 0;
for( dip::uint ii = 0; ii < nDims; ++ii ) { // Symmetric matrix stores diagonal elements first
   // value at index * tensorStride is tensor element ( ii, ii ).
   ++index;
}
for( dip::uint jj = 1; jj < nDims; ++jj ) { // Elements above diagonal stored column-wise
   for( dip::uint ii = 0; ii < jj; ++ii ) {
      // value at index * tensorStride is tensor element ( ii, jj ).
      ++index;
   }
}

Tensor( )

Creates a dip::Tensor::Shape::COL_VECTOR with one element (scalar).

Tensor( dip::uint n) explicit

Creates a dip::Tensor::Shape::COL_VECTOR.

Tensor( dip::uint rows, dip::uint cols)

Creates a dip::Tensor::Shape::COL_MAJOR_MATRIX.

Tensor( dip::Tensor::Shape shape, dip::uint rows, dip::uint cols)

Constructor for arbitrary shape.

Tensor( dip::String const& shape, dip::uint rows, dip::uint cols)

Constructor for arbitrary shape.

bool IsScalar( ) const

Tests the tensor shape.

bool IsVector( ) const

Tests the tensor shape.

bool IsDiagonal( ) const

Tests the tensor shape.

bool IsSymmetric( ) const

Tests the tensor shape.

bool IsTriangular( ) const

Tests the tensor shape.

bool IsSquare( ) const

True if the matrix is square, independently from how it is stored.

dip::Tensor::Shape TensorShape( ) const

Returns tensor shape.

dip::String TensorShapeAsString( ) const

Return a string representation of the tensor shape.

dip::uint Elements( ) const

Gets number of tensor elements.

dip::uint Rows( ) const

Gets number of tensor rows.

dip::uint Columns( ) const

Gets number of tensor columns.

dip::UnsignedArray Sizes( ) const

Gets the tensor size.

void SetShape( dip::Tensor::Shape shape, dip::uint rows, dip::uint cols)

Sets the tensor shape.

void SetScalar( )

Sets the tensor shape, results in a dip::Tensor::Shape::COL_VECTOR with one element (scalar).

void SetVector( dip::uint n)

Sets the tensor shape, results in a dip::Tensor::Shape::COL_VECTOR.

void SetMatrix( dip::uint rows, dip::uint cols)

Sets the tensor shape, results in a dip::Tensor::Shape::COL_MAJOR_MATRIX.

void SetSizes( dip::UnsignedArray const& sizes)

Sets the tensor size, always results in a dip::Tensor::Shape::COL_VECTOR or dip::Tensor::Shape::COL_MAJOR_MATRIX.

void ChangeShape( dip::uint rows)

Changes the tensor shape without changing the number of elements, results in a dip::Tensor::Shape::COL_MAJOR_MATRIX.

void ChangeShape( )

Changes the tensor shape without changing the number of elements, results in a dip::Tensor::Shape::COL_VECTOR.

void ChangeShape( dip::Tensor const& example)

Changes the tensor shape without changing the number of elements, resulting in the shape described by example.

void Transpose( )

Transposes the tensor, causing a change of shape without a change of number of elements.

void ExtractDiagonal( dip::sint& stride)

Transforms the tensor such that it becomes a vector referencing the elements along the diagonal. The value of stride is adjusted.

dip::sint ExtractRow( dip::uint index, dip::sint& stride)

Transforms the tensor such that it becomes a vector referencing the elements along the given row. The value of stride is adjusted. The tensor representation must be full (i.e. no symmetric or triangular matrices).

dip::sint ExtractColumn( dip::uint index, dip::sint& stride)

Transforms the tensor such that it becomes a vector referencing the elements along the given column. The value of stride is adjusted. The tensor representation must be full (i.e. no symmetric or triangular matrices).

bool HasNormalOrder( ) const

Returns true for tensors that are stored in column-major order (all vectors and non-transposed full tensors).

dip::uint Index( dip::UnsignedArray const& indices) const

Returns the linear index corresponding to the given tensor indices.

Tensor element (m,n) can be found by adding Tensor::Index({m,m}) * tstride to the pixel’s pointer. Throws if the indices do not point to a stored tensor element (for example, in a diagonal matrix, only the diagonal elements are stored; trying to access an off-diagonal element through Index causes an exception to be thrown).

std::vector<dip::sint> LookUpTable( ) const

Returns a look-up table that you can use to find specific tensor elements.

Given a tensor with M rows and N columns, tensor element (m,n) can be found by adding Tensor::LookUpTable()[n*M+m] * tstride to the pixel’s pointer. If the value in the look-up table is -1, the tensor element is not stored, and presumed to be 0 (happens with triangular and diagonal matrices only).

void swap( dip::Tensor& other) noexcept

Swaps the contents of this and other.

static dip::String ShapeToString( dip::Tensor::Shape shape)

Return a string representation of a tensor shape

static dip::Tensor::Shape ShapeFromString( dip::String const& string)

Retrieve a tensor shape from a string representation of the tensor shape

bool operator==( dip::Tensor const& rhs) const

Compares tensor size and shape.

bool operator!=( dip::Tensor const& rhs) const

Compares tensor size and shape.

std::ostream& dip::operator<<( std::ostream& os, dip::Tensor const& tensor)

Prints information about the tensor.