# Math and statistics » Tensor operators module#include "diplib/math.h"

Operators specific to tensor images.

• Reference

## Functions

auto dip::Transpose(dip::Image const& in) -> dip::Image
Transposes the tensor image, the data are not copied.
dip::Image const& in, dip::Image& out)
Computes the conjugate transpose of the tensor image `in`.
void dip::DotProduct(dip::Image const& lhs, dip::Image const& rhs, dip::Image& out)
Computes the dot product (inner product) of two vector images.
void dip::CrossProduct(dip::Image const& lhs, dip::Image const& rhs, dip::Image& out)
Computes the cross product (inner product) of two vector images.
void dip::Norm(dip::Image const& in, dip::Image& out)
Computes the norm of the vector at each pixel in image `in`.
void dip::SquareNorm(dip::Image const& in, dip::Image& out)
Computes the square of the norm of the vector at each pixel in image `in`.
void dip::Angle(dip::Image const& in, dip::Image& out)
Computes the angle of the vector at each pixel in image `in`.
void dip::Orientation(dip::Image const& in, dip::Image& out)
Computes the orientation of the vector at each pixel in image `in`.
dip::Image const& in, dip::Image& out)
Converts the vector at each pixel in image `in` from Cartesian coordinates to polar (or spherical) coordinates.
dip::Image const& in, dip::Image& out)
Converts the vector at each pixel in image `in` from polar (or spherical) coordinates to Cartesian coordinates.
void dip::Determinant(dip::Image const& in, dip::Image& out)
Computes the determinant of the square matrix at each pixel in image `in`.
void dip::Trace(dip::Image const& in, dip::Image& out)
Computes the trace of the square matrix at each pixel in image `in`.
void dip::Rank(dip::Image const& in, dip::Image& out)
Computes the rank of the square matrix at each pixel in image `in`. The output is DT_UINT8, under the assumption that we won’t have tensor images with a rank higher than 255.
void dip::Eigenvalues(dip::Image const& in, dip::Image& out)
Computes the eigenvalues of the square matrix at each pixel in image `in`.
dip::Image const& in, dip::Image& out)
Finds the largest eigenvalue of the square matrix at each pixel in image `in`.
dip::Image const& in, dip::Image& out)
Finds the smallest eigenvalue of the square matrix at each pixel in image `in`.
dip::Image const& in, dip::Image& out, dip::Image& eigenvectors)
Computes the eigenvalues and eigenvectors of the square matrix at each pixel in image `in`.
dip::Image const& in, dip::Image& out)
Finds the largest eigenvector of the symmetric matrix at each pixel in image `in`.
dip::Image const& in, dip::Image& out)
Finds the smallest eigenvector of the symmetric matrix at each pixel in image `in`.
void dip::Inverse(dip::Image const& in, dip::Image& out)
Computes the inverse of the square matrix at each pixel in image `in`.
void dip::PseudoInverse(dip::Image const& in, dip::Image& out, dip::dfloat tolerance = 1e-7)
Computes the pseudo-inverse of the matrix at each pixel in image `in`.
void dip::SingularValues(dip::Image const& in, dip::Image& out)
Computes the “thin” singular value decomposition of the matrix at each pixel in image `in`.
dip::Image const& A, dip::Image& U, dip::Image& S, dip::Image& V)
Computes the “thin” singular value decomposition of the matrix at each pixel in image `in`.
void dip::Identity(dip::Image const& in, dip::Image& out)
Creates an image whose pixels are identity matrices.
dip::Image const& in, dip::Image& out)
Adds all tensor elements, producing a scalar image.
dip::Image const& in, dip::Image& out)
Multiplies all tensor elements, producing a scalar image.
dip::Image const& in, dip::Image& out)
Determines if all tensor elements are non-zero, producing a binary scalar image.
dip::Image const& in, dip::Image& out)
Determines if any tensor element is non-zero, producing a binary scalar image.
dip::Image const& in, dip::Image& out)
Takes the maximum tensor element at each pixel, producing a scalar image.
dip::Image const& in, dip::Image& out)
Takes the maximum absolute tensor element at each pixel, producing a scalar image. For float and complex images only.
dip::Image const& in, dip::Image& out)
Takes the minimum tensor element at each pixel, producing a scalar image.
dip::Image const& in, dip::Image& out)
Takes the minimum absolute tensor element at each pixel, producing a scalar image. For float and complex images only.
dip::Image const& in, dip::Image& out)
Computes the mean tensor element value at each pixel, producing a scalar image.
dip::Image const& in, dip::Image& out)
Computes the geometric mean tensor element value at each pixel, producing a scalar image.
dip::Image& out)
Sorts the tensor elements within each pixel from largest to smallest. Works in-place. `out` must be real-valued.
dip::Image& out)
Sorts the tensor elements within each pixel by magnitude from largest to smallest. Works in-place. `out` must be of a floating point or complex type.

## Function documentation

### void dip::CrossProduct(dip::Image const& lhs, dip::Image const& rhs, dip::Image& out)

Computes the cross product (inner product) of two vector images.

Input image tensors must be 2-vectors or 3-vectors. For 3-vectors, the cross product is as commonly defined in 3D. For 2-vectors, we define the cross product as the z-component of the cross product of the 3D vectors obtained by adding a 0 z-component to the inputs. That is, it is the area of the parallelogram formed by the two 2D vectors.

### void dip::Angle(dip::Image const& in, dip::Image& out)

Computes the angle of the vector at each pixel in image `in`.

`in` must be a 2-vector or a 3-vector. For a 2-vector, `out` is a scalar image representing phi, the angle from the x-axis. For a 3-vector, `out` has 2 tensor components, corresponding to phi and theta. phi, as in the 2D case, is the angle from the x-axis within the x-y plane (azimuth). theta is the angle from the z-axis (inclination). See `dip::CartesianToPolar` for more details. This function yields the same output as `dip::CartesianToPolar`, but without the first tensor component.

### void dip::Orientation(dip::Image const& in, dip::Image& out)

Computes the orientation of the vector at each pixel in image `in`.

Orientation is defined as the angle mapped to the half-circle or half-sphere with positive x-coordinate. That is, in 2D it is an angle in the range (-π/2, π/2), and in 3D the phi component is mapped to that same range. See `dip::Angle` for more information.

### void dip::CartesianToPolar(dip::Image const& in, dip::Image& out)

Converts the vector at each pixel in image `in` from Cartesian coordinates to polar (or spherical) coordinates.

`in` must be a 2-vector or a 3-vector. `out` is a same-size vector containing r and phi in the 2D case, and r, phi and theta in the 3D case. phi is the angle to the x-axis within the x-y plane (azimuth). theta is the angle from the z-axis (inclination).

That is, in 2D:

```in[ 0 ] == out[ 0 ] * Cos( out[ 1 ] );
in[ 1 ] == out[ 0 ] * Sin( out[ 1 ] );
```

and in 3D:

```in[ 0 ] == out[ 0 ] * Cos( out[ 1 ] ) * Sin( out[ 2 ] );
in[ 1 ] == out[ 0 ] * Sin( out[ 1 ] ) * Sin( out[ 2 ] );
in[ 2 ] == out[ 0 ] * Cos( out[ 2 ] );
```

### void dip::PolarToCartesian(dip::Image const& in, dip::Image& out)

Converts the vector at each pixel in image `in` from polar (or spherical) coordinates to Cartesian coordinates.

`in` must be a 2-vector or a 3-vector. See `dip::CartesianToPolar` for a description of the polar coordinates used.

### void dip::Eigenvalues(dip::Image const& in, dip::Image& out)

Computes the eigenvalues of the square matrix at each pixel in image `in`.

`out` is a vector image containing the eigenvalues. If `in` is symmetric and real-valued, then `out` is real-valued, otherwise, `out` is complex-valued. The eigenvalues are sorted by magnitude, in descending order.

### void dip::LargestEigenvalue(dip::Image const& in, dip::Image& out)

Finds the largest eigenvalue of the square matrix at each pixel in image `in`.

Computes the eigenvalues in the same way as `dip::Eigenvalues`, but outputs only the eigenvector with the largest magnitude.

### void dip::SmallestEigenvalue(dip::Image const& in, dip::Image& out)

Finds the smallest eigenvalue of the square matrix at each pixel in image `in`.

Computes the eigenvalues in the same way as `dip::Eigenvalues`, but outputs only the eigenvector with the smallest magnitude.

### void dip::EigenDecomposition(dip::Image const& in, dip::Image& out, dip::Image& eigenvectors)

Computes the eigenvalues and eigenvectors of the square matrix at each pixel in image `in`.

The decomposition is such that `in * eigenvectors == eigenvectors * out`. `eigenvectors` is almost always invertible, in which case one can write `in == eigenvectors * out * Inverse( eigenvectors )`.

`out` is a diagonal matrix image containing the eigenvalues. If `in` is symmetric and real-valued, then `out` is real-valued, otherwise, `out` is complex-valued. The eigenvalues are sorted by magnitude, in descending order.

The eigenvectors are the columns `eigenvectors`. It has the same data type as `out`.

### void dip::LargestEigenvector(dip::Image const& in, dip::Image& out)

Finds the largest eigenvector of the symmetric matrix at each pixel in image `in`.

Computes the eigen decomposition in the same way as `dip::EigenDecomposition`, but outputs only the eigenvector that corresponds to the eigenvalue with largest magnitude.

`in` must be symmetric and real-valued.

### void dip::SmallestEigenvector(dip::Image const& in, dip::Image& out)

Finds the smallest eigenvector of the symmetric matrix at each pixel in image `in`.

Computes the eigen decomposition in the same way as `dip::EigenDecomposition`, but outputs only the eigenvector that corresponds to the eigenvalue with smallest magnitude.

`in` must be symmetric and real-valued.

### void dip::Inverse(dip::Image const& in, dip::Image& out)

Computes the inverse of the square matrix at each pixel in image `in`.

The result is undetermined if the matrix is not invertible.

### void dip::PseudoInverse(dip::Image const& in, dip::Image& out, dip::dfloat tolerance = 1e-7)

Computes the pseudo-inverse of the matrix at each pixel in image `in`.

Computes the Moore-Penrose pseudo-inverse using `tolerance`. Singular values smaller than `tolerance * max(rows,cols) * p`, with `p` the largest singular value, will be set to zero in the inverse.

### void dip::SingularValues(dip::Image const& in, dip::Image& out)

Computes the “thin” singular value decomposition of the matrix at each pixel in image `in`.

For an input image `in` with a tensor size of NxP, and with M the smaller of N and P, `out` is a vector image with M elements, corresponding to the singular values, sorted in decreasing order.

Use `dip::SingularValueDecomposition` if you need the full decomposition.

This function uses the two-sided Jacobi SVD decomposition algorithm. This is efficient for small matrices only.

### void dip::SingularValueDecomposition(dip::Image const& A, dip::Image& U, dip::Image& S, dip::Image& V)

Computes the “thin” singular value decomposition of the matrix at each pixel in image `in`.

For an input image `A` with a tensor size of NxP, and with M the smaller of N and P, `S` is a square diagonal MxM matrix, `U` is a NxM matrix, and V is a PxM matrix. These matrices satisfy the relation .

The (diagonal) elements of `S` are the singular values, sorted in decreasing order. You can use `dip::SingularValues` if you are not interested in computing `U` and `V`.

This function uses the two-sided Jacobi SVD decomposition algorithm. This is efficient for small matrices only.

### void dip::Identity(dip::Image const& in, dip::Image& out)

Creates an image whose pixels are identity matrices.

`out` will have the same sizes as `in`, and with a tensor representation of a diagonal matrix with a size concordant to that of the tensor representation of `in`. For example, for an N-vector image, the resulting output matrix image will be NxN. `out` will be of type `dip::DT_SFLOAT`.