Physical dimensions module
#include "diplib.h"
dip::PixelSize class

Specifies an image’s pixel size as physical quantities.

Reference

The object works like an array with unlimited number of elements. It is possible to set only one value, and that value will be used for all dimensions. In general, if N dimensions are set (i.e. the array has N elements defined), then dimensions N and further have the same value as dimension N-1.

When setting dimension N-1, all further dimensions are affected. When setting dimension N+K, the new array size will be N+K+1. Dimensions N through N+K-1 are assigned the same value as dimension N-1, then dimension N+K will be assigned the new value, and all subsequent dimensions will implicitly have the same value.

Thus, it is important to know how many elements are set in the array to know how any modifications will affect it.

However, dip::PixelSize::SwapDimensions, dip::PixelSize::InsertDimension and dip::PixelSize::EraseDimension will expand the array by one element before modifying the last element in the array. This prevents the implicit elements after the defined ones to be modified. For example, inserting dimension N+K first expands the array to size N+K+2 by setting all the new elements to the same value as element N-1, then sets a new value for dimension N+K. Dimension N+K+1 now still has the same value as before (though now it is explicitly defined, whereas before it was implicitly defined).

The pixel size always needs a unit. Any dimensionless quantity is interpreted as a quantity in pixels (px). Pixels are not considered physical units, and are consistently used to represent relative pixel sizes (i.e. sizes in unknown or arbitrary units). Thus, a pixel size of 1 px x 2 px indicates a specific aspect ratio, but does not represent an actual physical size. Use dip::PhysicalQuantity::IsPhysical to test for the pixel size being a physical quantity. Angles, measured in radian, are not considered dimensionless here (though radian actually are dimensionless units, see dip::Units).

Constructors, destructors, assignment and conversion operators

PixelSize() defaulted: By default, an image has no physical dimensions. The pixel size is given as “1 pixel”.
PixelSize(dip::PhysicalQuantity const& m): Create an isotropic pixel size based on a physical quantity.
PixelSize(dip::PhysicalQuantityArray const& m): Create a pixel size based on an array of physical quantities.

Functions

auto ApproximatelyEquals(dip::PixelSize const& rhs, dip::uint nDims, double tolerance = 1e-6) const -> bool: Compares two pixels for the first nDims dimensions, magnitudes are compared with a relative tolerance of tolerance
auto AspectRatio(dip::uint d) const -> dip::FloatArray: Returns the aspect ratio of the first d dimensions, with respect to the first dimension. That is, the output array has d elements, where the first one is 1.0. If units differ, the aspect ratio is 0 for that dimension.
void Clear(): Clears the pixel sizes, reverting to the default undefined state.
void EraseDimension(dip::uint d): Erases a dimension
void ForcePhysical(): Any dimension that is not a physical dimension will be set to 1 px.
auto Get(dip::uint d) const -> dip::PhysicalQuantity: Returns the pixel size for the given dimension.
void InsertDimension(dip::uint d, dip::PhysicalQuantity m = 1): Inserts a dimension, undefined by default.
void Invert(dip::uint d): Inverts the pixel size in the given dimension, if it is defined.
void Invert(): Inverts the pixel size in all dimensions, where defined.
auto IsDefined() const -> bool: Tests to see if the pixel size is defined.
auto IsIsotropic() const -> bool: Tests the pixel size for isotropy (the pixel has the same size in all dimensions).
auto IsPhysical() const -> bool: Tests to see if the pixel size is physical (i.e. has known physical units).
void Permute(dip::UnsignedArray const& order): Permutes dimensions according to order, such that, after the call, Get(ii) returns the value that Get(order[ii]) returned before the call. more...
auto Product(dip::uint d) const -> dip::PhysicalQuantity: Multiplies together the sizes for the first d dimensions.
void Resize(dip::uint d): Removes stored dimensions, keeping the first d dimensions only.
void Reverse(dip::uint d): Reverses the dimensions, assuming that there are d dimensions. more...
auto SameUnits() const -> bool: Tests to see if the units are the same (and physical) for all dimensions. Note that the prefix more...
void Scale(dip::uint d, dip::dfloat s): Scales the pixel size in the given dimension, if it is defined.
void Scale(dip::dfloat s): Scales the pixel size isotropically.
void Scale(dip::FloatArray const& s): Scales the pixel size non-isotropically in all dimensions, where defined.
void Set(dip::uint d, dip::PhysicalQuantity m): Sets the pixel size in the given dimension. Note that any subsequent dimension, if not explicitly set, will have the same size.
void Set(dip::PhysicalQuantity const& m): Sets the isotropic pixel size in all dimensions.
void Set(dip::PhysicalQuantityArray const& m): Sets a non-isotropic pixel size.
void SetKilometers(dip::uint d, dip::dfloat m): Sets the pixel size in the given dimension, in kilometers.
void SetKilometers(dip::dfloat m): Sets the isotropic pixel size, in kilometers.
void SetMeters(dip::uint d, dip::dfloat m): Sets the pixel size in the given dimension, in meters.
void SetMeters(dip::dfloat m): Sets the isotropic pixel size, in meters.
void SetMicrometers(dip::uint d, dip::dfloat m): Sets the pixel size in the given dimension, in micrometers.
void SetMicrometers(dip::dfloat m): Sets the isotropic pixel size, in micrometers.
void SetMillimeters(dip::uint d, dip::dfloat m): Sets the pixel size in the given dimension, in millimeters.
void SetMillimeters(dip::dfloat m): Sets the isotropic pixel size, in millimeters.
void SetNanometers(dip::uint d, dip::dfloat m): Sets the pixel size in the given dimension, in nanometers.
void SetNanometers(dip::dfloat m): Sets the isotropic pixel size, in nanometers.
auto Size() const -> dip::uint: Returns the number of dimensions stored.
void swap(dip::PixelSize& other) noexcept: Swaps the values of this and other.
void SwapDimensions(dip::uint d1, dip::uint d2): Swaps two dimensions.
auto ToPhysical(dip::FloatArray const& in) const -> dip::PhysicalQuantityArray: Converts pixels to meters.
auto ToPixels(dip::PhysicalQuantityArray const& in) const -> dip::FloatArray: Converts physical units to pixels.
auto UnitLength() const -> dip::PhysicalQuantity: Returns the scale and units to use for length measurements. Equal to the size of a pixel if it is isotropic, or 1 px otherwise.
auto UnitSize(dip::uint d) const -> dip::PhysicalQuantity: Returns the scale and units to use for size (area/volume) measurements. Equal to the product of the pixel sizes if that product is physical, or 1 px^d otherwise.

Operators

auto operator!=(dip::PixelSize const& rhs) const -> bool: Compares two pixel sizes, magnitudes are compared with a 10^-6 relative tolerance
auto operator==(dip::PixelSize const& rhs) const -> bool: Compares two pixel sizes, magnitudes are compared with a 10^-6 relative tolerance
auto operator[](dip::uint d) const -> dip::PhysicalQuantity: Returns the pixel size for the given dimension. Cannot be used to write to the array, see Set.

Function documentation

PixelSize( ) defaulted

By default, an image has no physical dimensions. The pixel size is given as “1 pixel”.

PixelSize( dip::PhysicalQuantity const& m)

Create an isotropic pixel size based on a physical quantity.

PixelSize( dip::PhysicalQuantityArray const& m)

Create a pixel size based on an array of physical quantities.

dip::PhysicalQuantity Get( dip::uint d) const

Returns the pixel size for the given dimension.

void Set( dip::uint d, dip::PhysicalQuantity m)

Sets the pixel size in the given dimension. Note that any subsequent dimension, if not explicitly set, will have the same size.

void Set( dip::PhysicalQuantity const& m)

Sets the isotropic pixel size in all dimensions.

void Set( dip::PhysicalQuantityArray const& m)

Sets a non-isotropic pixel size.

void SetNanometers( dip::uint d, dip::dfloat m)

Sets the pixel size in the given dimension, in nanometers.

void SetNanometers( dip::dfloat m)

Sets the isotropic pixel size, in nanometers.

void SetMicrometers( dip::uint d, dip::dfloat m)

Sets the pixel size in the given dimension, in micrometers.

void SetMicrometers( dip::dfloat m)

Sets the isotropic pixel size, in micrometers.

void SetMillimeters( dip::uint d, dip::dfloat m)

Sets the pixel size in the given dimension, in millimeters.

void SetMillimeters( dip::dfloat m)

Sets the isotropic pixel size, in millimeters.

void SetMeters( dip::uint d, dip::dfloat m)

Sets the pixel size in the given dimension, in meters.

void SetMeters( dip::dfloat m)

Sets the isotropic pixel size, in meters.

void SetKilometers( dip::uint d, dip::dfloat m)

Sets the pixel size in the given dimension, in kilometers.

void SetKilometers( dip::dfloat m)

Sets the isotropic pixel size, in kilometers.

void Scale( dip::uint d, dip::dfloat s)

Scales the pixel size in the given dimension, if it is defined.

void Scale( dip::dfloat s)

Scales the pixel size isotropically.

void Scale( dip::FloatArray const& s)

Scales the pixel size non-isotropically in all dimensions, where defined.

void Invert( dip::uint d)

Inverts the pixel size in the given dimension, if it is defined.

void Invert( )

Inverts the pixel size in all dimensions, where defined.

void SwapDimensions( dip::uint d1, dip::uint d2)

Swaps two dimensions.

void Reverse( dip::uint d)

Reverses the dimensions, assuming that there are d dimensions.

With this call, dimension 0 becomes dimension d-1, dimension 1 becomes dimension d-2, etc. and dimension d-1 becomes dimension 0.

void Permute( dip::UnsignedArray const& order)

Permutes dimensions according to order, such that, after the call, Get(ii) returns the value that Get(order[ii]) returned before the call.

The values for any dimension not indexed by order will be lost.

void InsertDimension( dip::uint d, dip::PhysicalQuantity m = 1)

Inserts a dimension, undefined by default.

void EraseDimension( dip::uint d)

Erases a dimension

void Clear( )

Clears the pixel sizes, reverting to the default undefined state.

dip::uint Size( ) const

Returns the number of dimensions stored.

void Resize( dip::uint d)

Removes stored dimensions, keeping the first d dimensions only.

bool IsIsotropic( ) const

Tests the pixel size for isotropy (the pixel has the same size in all dimensions).

dip::FloatArray AspectRatio( dip::uint d) const

Returns the aspect ratio of the first d dimensions, with respect to the first dimension. That is, the output array has d elements, where the first one is 1.0. If units differ, the aspect ratio is 0 for that dimension.

bool IsDefined( ) const

Tests to see if the pixel size is defined.

bool IsPhysical( ) const

Tests to see if the pixel size is physical (i.e. has known physical units).

bool SameUnits( ) const

Tests to see if the units are the same (and physical) for all dimensions. Note that the prefix

(thousands scaling) is considered part of the units.

dip::PhysicalQuantity Product( dip::uint d) const

Multiplies together the sizes for the first d dimensions.

dip::PhysicalQuantity UnitLength( ) const

Returns the scale and units to use for length measurements. Equal to the size of a pixel if it is isotropic, or 1 px otherwise.

dip::PhysicalQuantity UnitSize( dip::uint d) const

Returns the scale and units to use for size (area/volume) measurements. Equal to the product of the pixel sizes if that product is physical, or 1 px^d otherwise.

void ForcePhysical( )

Any dimension that is not a physical dimension will be set to 1 px.

bool ApproximatelyEquals( dip::PixelSize const& rhs, dip::uint nDims, double tolerance = 1e-6) const

Compares two pixels for the first nDims dimensions, magnitudes are compared with a relative tolerance of tolerance

dip::FloatArray ToPixels( dip::PhysicalQuantityArray const& in) const

Converts physical units to pixels.

dip::PhysicalQuantityArray ToPhysical( dip::FloatArray const& in) const

Converts pixels to meters.

void swap( dip::PixelSize& other) noexcept

Swaps the values of this and other.

dip::PhysicalQuantity operator[]( dip::uint d) const

Returns the pixel size for the given dimension. Cannot be used to write to the array, see Set.

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

Compares two pixel sizes, magnitudes are compared with a 10^-6 relative tolerance

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