Image module
#include "diplib.h"
dip::Tensor class

Describes the shape of a tensor, but doesn’t actually contain tensor data.

Reference

Used internally by the dip::Image objects. It is default-constructible, movable and copiable.

Constructors, destructors, assignment and conversion operators

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.

Enums

enum class Shape: uint8{ COL_VECTOR, ROW_VECTOR, COL_MAJOR_MATRIX, ROW_MAJOR_MATRIX, DIAGONAL_MATRIX, SYMMETRIC_MATRIX, UPPTRIANG_MATRIX, LOWTRIANG_MATRIX }: Possible shapes the tensor can have.

Functions

auto IsScalar() const -> bool: Tests the tensor shape.
auto IsVector() const -> bool: Tests the tensor shape.
auto IsDiagonal() const -> bool: Tests the tensor shape.
auto IsSymmetric() const -> bool: Tests the tensor shape.
auto IsTriangular() const -> bool: Tests the tensor shape.
auto IsSquare() const -> bool: True if the matrix is square, independently from how it is stored.
auto TensorShape() const -> dip::Tensor::Shape: Returns tensor shape.
auto TensorShapeAsString() const -> dip::String: Return a string representation of the tensor shape.
auto Elements() const -> dip::uint: Gets number of tensor elements.
auto Rows() const -> dip::uint: Gets number of tensor rows.
auto Columns() const -> dip::uint: Gets number of tensor columns.
auto Sizes() const -> dip::UnsignedArray: 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.
auto ExtractRow(dip::uint index, dip::sint& stride) -> dip::sint: 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).
auto ExtractColumn(dip::uint index, dip::sint& stride) -> dip::sint: 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).
auto HasNormalOrder() const -> bool: Returns true for tensors that are stored in column-major order (all vectors and non-transposed full tensors).
auto Index(dip::UnsignedArray const& indices) const -> dip::uint: Returns the linear index corresponding to the given tensor indices.
auto LookUpTable() const -> std::vector<dip::sint>: Returns a look-up table that you can use to find specific tensor elements.
void swap(dip::Tensor& other) noexcept: Swaps the contents of this and other.
static auto ShapeToString(dip::Tensor::Shape shape) -> dip::String: Return a string representation of a tensor shape
static auto ShapeFromString(dip::String const& string) -> dip::Tensor::Shape: Retrieve a tensor shape from a string representation of the tensor shape

Operators

auto operator==(dip::Tensor const& rhs) const -> bool: Compares tensor size and shape.
auto operator!=(dip::Tensor const& rhs) const -> bool: Compares tensor size and shape.

Enum documentation

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

Enumerators
COL_VECTOR = 0	a vector (stores n elements), default vector shape
ROW_VECTOR = 1	a row vector (stores n elements)
COL_MAJOR_MATRIX = 2	a matrix (stores n x m elements), default matrix shape
ROW_MAJOR_MATRIX = 3	a row-major matrix (stores n x m elements)
DIAGONAL_MATRIX = 4	a diagonal matrix (stores n elements)
SYMMETRIC_MATRIX = 5	a symmetric matrix (stores n(n+1)/2 elements)
UPPTRIANG_MATRIX = 6	an upper-triangular matrix (stores n(n+1)/2 elements)
LOWTRIANG_MATRIX = 7	a lower-triangular matrix (stores n(n+1)/2 elements)

Function documentation

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