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 Get(dip::uint d) const -> dip::PhysicalQuantity: 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.
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.
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.
auto Size() const -> dip::uint: Returns the number of dimensions stored.
void Resize(dip::uint d): Removes stored dimensions, keeping the first d dimensions only.
auto IsIsotropic() const -> bool: Tests the pixel size for isotropy (the pixel has the same size in all dimensions).
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.
auto IsDefined() const -> bool: Tests to see if the pixel size is defined.
auto IsPhysical() const -> bool: Tests to see if the pixel size is physical (i.e. has known physical units).
auto SameUnits() const -> bool: Tests to see if the units are the same (and physical) for all dimensions. Note that the prefix
auto Product(dip::uint d) const -> dip::PhysicalQuantity: Multiplies together the sizes for the first d dimensions.
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.
void ForcePhysical(): Any dimension that is not a physical dimension will be set to 1 px.
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 ToPixels(dip::PhysicalQuantityArray const& in) const -> dip::FloatArray: Converts physical units to pixels.
auto ToPhysical(dip::FloatArray const& in) const -> dip::PhysicalQuantityArray: Converts pixels to meters.
void swap(dip::PixelSize& other) noexcept: Swaps the values of this and other.

Operators

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

Function documentation

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.

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.

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

Contents