dip::PixelSize class

Specifies an image’s pixel size as physical quantities.

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 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 Product(dip::uint d) const -> dip::PhysicalQuantity
Multiplies together the sizes for the first d dimensions.
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)
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 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.