The library infrastructure » Pixel data types module
#include "diplib.h"

Types used for image samples (pixels), and related support functionality

Contents

The following table lists all supported sample data types, together with dip::DataType constants and type groups (see dip::DataType::Classes) that they belong to.

C++ type Constant String Type groups Size (bytes)
dip::bin dip::DT_BIN "BIN" Binary, IntOrBin, FlexBin, Unsigned 1
dip::uint8 dip::DT_UINT8 "UINT8" UInt, Integer, IntOrBin, Real, Unsigned 1
dip::sint8 dip::DT_SINT8 "SINT8" SInt, Integer, IntOrBin, Real, Signed 1
dip::uint16 dip::DT_UINT16 "UINT16" UInt, Integer, IntOrBin, Real, Unsigned 2
dip::sint16 dip::DT_SINT16 "SINT16" SInt, Integer, IntOrBin, Real, Signed 2
dip::uint32 dip::DT_UINT32 "UINT32" UInt, Integer, IntOrBin, Real, Unsigned 4
dip::sint32 dip::DT_SINT32 "SINT32" SInt, Integer, IntOrBin, Real, Signed 4
dip::uint64 dip::DT_UINT64 "UINT64" UInt, Integer, IntOrBin, Real, Unsigned 8
dip::sint64 dip::DT_SINT64 "SINT64" SInt, Integer, IntOrBin, Real, Signed 8
dip::sfloat dip::DT_SFLOAT "SFLOAT" Float, Real, Flex, FlexBin, Signed 4
dip::dfloat dip::DT_DFLOAT "DFLOAT" Float, Real, Flex, FlexBin, Signed 8
dip::scomplex dip::DT_SCOMPLEX "SCOMPLEX" Complex, Flex, FlexBin, Signed 8 (4 x2)
dip::dcomplex dip::DT_DCOMPLEX "DCOMPLEX" Complex, Flex, FlexBin, Signed 16 (8 x2)

Note that some functions require specific data types for their input images, and will throw an exception if the data type doesn’t match. However, type restrictions typically are meaningful, in the sense that any data type that makes sense for the given operation should be accepted, and is rejected only when an operation is not possible on a given type. For example, it is not possible to find the maximum of a set of complex values, therefore dip::Maximum does not accept complex-valued images as input.

The output images are typically set to a suitable type, which is selected using functions such as dip::DataType::SuggestComplex and dip::DataType::SuggestFlex. The table below lists these functions and their output. See also dip::DataType::SuggestArithmetic and dip::DataType::SuggestDyadicOperation, which help select a suitable data type when combining two images. To manually select an output data type, see The “protect” flag.

Input data type SuggestInteger SuggestSigned SuggestAbs SuggestFloat SuggestDouble SuggestReal SuggestComplex SuggestFlex SuggestFlexBin
DT_BIN DT_UINT8 DT_SINT8 DT_BIN DT_SFLOAT DT_DFLOAT DT_UINT8 DT_SCOMPLEX DT_SFLOAT DT_BIN
DT_UINT8 DT_UINT8 DT_SINT16 DT_UINT8 DT_SFLOAT DT_DFLOAT DT_UINT8 DT_SCOMPLEX DT_SFLOAT DT_SFLOAT
DT_SINT8 DT_SINT8 DT_SINT8 DT_UINT8 DT_SFLOAT DT_DFLOAT DT_SINT8 DT_SCOMPLEX DT_SFLOAT DT_SFLOAT
DT_UINT16 DT_UINT16 DT_SINT32 DT_UINT16 DT_SFLOAT DT_DFLOAT DT_UINT16 DT_SCOMPLEX DT_SFLOAT DT_SFLOAT
DT_SINT16 DT_SINT16 DT_SINT16 DT_UINT16 DT_SFLOAT DT_DFLOAT DT_SINT16 DT_SCOMPLEX DT_SFLOAT DT_SFLOAT
DT_UINT32 DT_UINT32 DT_SINT64 DT_UINT32 DT_DFLOAT DT_DFLOAT DT_UINT32 DT_DCOMPLEX DT_DFLOAT DT_DFLOAT
DT_SINT32 DT_SINT32 DT_SINT32 DT_UINT32 DT_DFLOAT DT_DFLOAT DT_SINT32 DT_DCOMPLEX DT_DFLOAT DT_DFLOAT
DT_UINT64 DT_UINT64 DT_SINT64 DT_UINT64 DT_DFLOAT DT_DFLOAT DT_UINT64 DT_DCOMPLEX DT_DFLOAT DT_DFLOAT
DT_SINT64 DT_SINT64 DT_SINT64 DT_UINT64 DT_DFLOAT DT_DFLOAT DT_SINT64 DT_DCOMPLEX DT_DFLOAT DT_DFLOAT
DT_SFLOAT DT_SINT32 DT_SFLOAT DT_SFLOAT DT_SFLOAT DT_DFLOAT DT_SFLOAT DT_SCOMPLEX DT_SFLOAT DT_SFLOAT
DT_DFLOAT DT_SINT64 DT_DFLOAT DT_DFLOAT DT_DFLOAT DT_DFLOAT DT_DFLOAT DT_DCOMPLEX DT_DFLOAT DT_DFLOAT
DT_SCOMPLEX DT_SINT32 DT_SCOMPLEX DT_SFLOAT DT_SFLOAT DT_DCOMPLEX DT_SFLOAT DT_SCOMPLEX DT_SCOMPLEX DT_SCOMPLEX
DT_DCOMPLEX DT_SINT64 DT_DCOMPLEX DT_DFLOAT DT_DFLOAT DT_DCOMPLEX DT_DFLOAT DT_DCOMPLEX DT_DCOMPLEX DT_DCOMPLEX

Type casting

dip::clamp_cast is an operator that returns the input value cast to a different type, clamped to the range of values representable by that output type. This is also often referred to as saturated cast. Most DIPlib functions take care of properly clamping values when casting pixel values. This typically is more intuitive and useful when processing images than the default C/C++ overflow behavior, which corresponds to modular arithmetic for integer values.

When casting from complex to non-complex, the absolute value of the complex number is taken. When casting from a floating-point number to an integer, the decimals are truncated, as typically done in C++.

dip::clamp_cast is defined as a series of overloaded template functions with specializations. The input argument type is used in overload resolution, the output type is the template parameter, and should be specified between angled brackets after the function name, much like the standard static_cast and similar:

uint8 u = dip::clamp_cast< dip::uint8 >( -54.6 );

Saturated arithmetic

dip::saturated_XXX are templated functions for saturated arithmetic. Most DIPlib functions take care of properly clamping the result of operations on pixels by using these functions to perform arithmetic. For example,

10u - 20u == 4294967286u;
dip::saturated_sub(10u, 20u) == 0u;

Saturated arithmetic is made available by including diplib/saturated_arithmetic.h.

Classes

struct dip::DataType
DataType objects are used to indicate what the data type of an image is.
template<typename T>
struct dip::IsSampleType
For use with std::enable_if to enable templates only for types that are valid for image samples.
template<typename T>
struct dip::IsNumericType
For use with std::enable_if to enable templates only for types that are numeric types, similar to std::is_arithmetic but also true for complex types. See dip::IsSampleType for usage details.
template<typename T>
struct dip::IsIndexingType
For use with std::enable_if to enable templates only for types that are indexing types, true for signed and unsigned integers. See dip::IsSampleType for usage details.
class dip::bin
Type for samples in a binary image. Can store 0 or 1. Occupies 1 byte.

Aliases

using dip::DataTypeArray = dip::DimensionArray
An array to hold data types
using dip::uint8 = std::uint8_t
Type for samples in an 8-bit unsigned integer image; also to be used as single byte for pointer arithmetic
using dip::uint16 = std::uint16_t
Type for samples in a 16-bit unsigned integer image
using dip::uint32 = std::uint32_t
Type for samples in a 32-bit unsigned integer image
using dip::uint64 = std::uint64_t
Type for samples in a 64-bit unsigned integer image
using dip::sint8 = std::int8_t
Type for samples in an 8-bit signed integer image
using dip::sint16 = std::int16_t
Type for samples in a 16-bit signed integer image
using dip::sint32 = std::int32_t
Type for samples in a 32-bit signed integer image
using dip::sint64 = std::int64_t
Type for samples in a 64-bit signed integer image
using dip::sfloat = float
Type for samples in a 32-bit floating point (single-precision) image
using dip::dfloat = double
Type for samples in a 64-bit floating point (double-precision) image
using dip::scomplex = std::complex<sfloat>
Type for samples in a 64-bit complex-valued (single-precision) image
using dip::dcomplex = std::complex<dfloat>
Type for samples in a 128-bit complex-valued (double-precision) image
using dip::LabelType = dip::uint32
Type currently used for all labeled images, see dip::DT_LABEL.
template<typename T>
using dip::FloatType = dip::detail::FloatTypeCalculator
The type to use in calculations when a floating-point type is needed. Matches dip::DataType::SuggestFloat.
template<typename T>
using dip::DoubleType = dip::detail::DoubleTypeCalculator
The double precision floating point type (real or complex) to use when computing large sums of any input type. Matches dip::DataType::SuggestDouble.
template<typename T>
using dip::ComplexType = dip::detail::ComplexTypeCalculator
The type to use in calculations when a complex type is needed. Matches dip::DataType::SuggestComplex.
template<typename T>
using dip::FlexType = dip::detail::FlexTypeCalculator
The type to use in calculations. Matches dip::DataType::SuggestFlex.
template<typename T>
using dip::FlexBinType = dip::detail::FlexBinTypeCalculator
The type to use in calculations. Matches dip::DataType::SuggestFlexBin.
template<typename T>
using dip::AbsType = dip::detail::AbsTypeCalculator
The type to use for the output of abs operations. Matches dip::DataType::SuggestAbs.
template<typename T>
using dip::RealType = dip::detail::RealTypeCalculator
The type to use in calculations when a real-valued type is needed. Matches dip::DataType::SuggestReal.

Functions

template<typename TargetType, typename SourceType, <SFINAE> = 0>
auto dip::clamp_cast(SourceType v) -> TargetType constexpr
Casts a value of any pixel type to any other pixel type, clamping it to the destination range.
template<typename TPI, <SFINAE> = 0>
auto dip::CastLabelType(TPI label) -> dip::LabelType
Casting any unsigned integer type to dip::LabelType. Throws if value is too large.
template<typename TPI, <SFINAE> = 0>
auto dip::PixelIsInfinity(TPI ) -> bool
A templated function to check for positive infinity, which works also for integer types (always returning false)
template<typename TPI, <SFINAE> = 0>
auto dip::PixelIsMinusInfinity(TPI ) -> bool
A templated function to check for negative infinity, which works also for integer types (always returning false)
template<typename T, <SFINAE> = 0>
auto dip::saturated_add(T lhs, T rhs) -> T constexpr
Adds two values using saturated arithmetic.
template<typename T, <SFINAE> = 0>
auto dip::saturated_sub(T lhs, T rhs) -> T constexpr
Subtracts two values using saturated arithmetic.
template<typename T, <SFINAE> = 0>
auto dip::saturated_mul(T lhs, T rhs) -> T constexpr
Multiplies two values using saturated arithmetic.
template<typename T, <SFINAE> = 0>
auto dip::saturated_div(T lhs, T rhs) -> T constexpr
Divides two values using saturated arithmetic.
template<typename T>
auto dip::saturated_safediv(T lhs, T rhs) -> T constexpr
Divides two values using saturated arithmetic. Tests for division by zero, return 0 rather than infinity or NaN (or an exception).
template<typename T, <SFINAE> = 0>
auto dip::saturated_inv(T v) -> T constexpr
Inverts a value using saturated arithmetic. This is the same as negation, but not for unsigned values.

Operators

auto dip::operator<<(std::ostream& os, dip::DataType type) -> std::ostream&
You can output a dip::DataType to std::cout or any other stream. The result of type.Name() is written.
auto dip::operator<<(std::ostream& os, dip::bin const& v) -> std::ostream&
Writes the value as a bool to a stream.

Variables

dip::DataType const dip::DT_BIN constexpr
Constant representing the type dip::bin.
dip::DataType const dip::DT_UINT8 constexpr
Constant representing the type dip::uint8.
dip::DataType const dip::DT_SINT8 constexpr
Constant representing the type dip::sint8.
dip::DataType const dip::DT_UINT16 constexpr
Constant representing the type dip::uint16.
dip::DataType const dip::DT_SINT16 constexpr
Constant representing the type dip::sint16.
dip::DataType const dip::DT_UINT32 constexpr
Constant representing the type dip::uint32.
dip::DataType const dip::DT_SINT32 constexpr
Constant representing the type dip::sint32.
dip::DataType const dip::DT_UINT64 constexpr
Constant representing the type dip::uint64.
dip::DataType const dip::DT_SINT64 constexpr
Constant representing the type dip::sint64.
dip::DataType const dip::DT_SFLOAT constexpr
Constant representing the type dip::sfloat.
dip::DataType const dip::DT_DFLOAT constexpr
Constant representing the type dip::dfloat.
dip::DataType const dip::DT_SCOMPLEX constexpr
Constant representing the type dip::scomplex.
dip::DataType const dip::DT_DCOMPLEX constexpr
Constant representing the type dip::dcomplex.
dip::DataType const dip::DT_LABEL constexpr
Type currently used for all labeled images, see dip::LabelType.
dip::DataType const dip::DT_COUNT constexpr
Data type of histogram bins. See dip::Histogram::CountType.

Function documentation

#include "diplib/saturated_arithmetic.h"
template<typename T, <SFINAE> = 0>
T dip::saturated_add(T lhs, T rhs) constexpr

Adds two values using saturated arithmetic.

#include "diplib/saturated_arithmetic.h"
template<typename T, <SFINAE> = 0>
T dip::saturated_sub(T lhs, T rhs) constexpr

Subtracts two values using saturated arithmetic.

#include "diplib/saturated_arithmetic.h"
template<typename T, <SFINAE> = 0>
T dip::saturated_mul(T lhs, T rhs) constexpr

Multiplies two values using saturated arithmetic.

#include "diplib/saturated_arithmetic.h"
template<typename T, <SFINAE> = 0>
T dip::saturated_div(T lhs, T rhs) constexpr

Divides two values using saturated arithmetic.

#include "diplib/saturated_arithmetic.h"
template<typename T>
T dip::saturated_safediv(T lhs, T rhs) constexpr

Divides two values using saturated arithmetic. Tests for division by zero, return 0 rather than infinity or NaN (or an exception).

#include "diplib/saturated_arithmetic.h"
template<typename T, <SFINAE> = 0>
T dip::saturated_inv(T v) constexpr

Inverts a value using saturated arithmetic. This is the same as negation, but not for unsigned values.