Labeled regions module
#include "diplib/label_map.h"
dip::LabelMap class

Represents a set of labels (object IDs), and maps them to new ones.

Contents

The object contains a set of known labels. Each of these known labels will be associated to a target label. If the target label is 0 (background), we refer to it as a zero mapping. If the taget is any other value, we refer to it as a non-zero mapping.

The function dip::LabelMap::Apply, when given a label image as input, will look up each pixel’s value in the set of known labels. If it is known, the corresponding pixel in the output image will be given the target label as value. If it is not known, it is left unchanged by default. After calling dip::LabelMap::DestroyUnknownLabels, the unknown labels will map to 0 instead.

Constructors, destructors, assignment and conversion operators

template<typename UnsignedIntegerType, <SFINAE> = 0>
LabelMap(std::vector<UnsignedIntegerType> const& labels) explicit
Construct a map that maps objectIDs to themselves.
LabelMap(dip::UnsignedArray const& labels) explicit
Construct a map that maps objectIDs to themselves.
template<typename IndexType_, typename ValueType_, typename UnionFunction_>
LabelMap(dip::UnionFind const& labels) explicit
Construct a map from the Union-Find data structure. Must call labels.Relabel() before converting to a LabelMap.
LabelMap(dip::LabelType maxLabel) explicit
Construct a map that maps objectIDs 1 to maxLabel (inclusive) to themselves.

Functions

void DestroyUnknownLabels()
Causes the map, when applied, to map unknown labels to 0 (background).
void PreserveUnknownLabels()
Causes the map, when applied, to keep unknown labels unchanged. This is the default.
auto Size() const -> dip::uint
Returns the number of labels known (i.e. explicitly listed in the mapping). See also dip::LabelMap::Count.
void Apply(dip::Image const& in, dip::Image& out) const
Applies the label map to a label image.
auto Apply(dip::Measurement const& in) const -> dip::Measurement
Applies the label map to measurement data.
void Negate()
Modifies the map such that labels mapped to 0 instead map to themselves, and those mapped to any non-zero label instead map to 0.
void Relabel()
Updates all target labels to be consecutive integers starting at 1. Zero mappings are not affected.
auto Contains(dip::LabelType label) const -> bool
Checks to see if label is known (i.e. explicitly listed with a mapping).
auto Count() const -> dip::uint
Counts how many labels have a non-zero mapping (i.e. how many objects are selected). See also dip::LabelMap::Size.

Operators

auto operator&=(dip::LabelMap const& rhs) -> dip::LabelMap&
Combines *this and other using logical AND.
auto operator|=(dip::LabelMap const& rhs) -> dip::LabelMap&
Combines *this and other using logical OR.
auto operator^=(dip::LabelMap const& rhs) -> dip::LabelMap&
Combines *this and other using logical XOR.
auto operator[](dip::LabelType label) -> dip::LabelType&
Looks up a label in the map and returns the target label by reference.
auto operator[](dip::LabelType label) const -> dip::LabelType
Looks up a label in the map and returns the target label. If the label is not present, instead returns the label (by default) or 0 (if dip::LabelMap::DestroyUnknownLabels was called previously).

Function documentation

void Apply(dip::Image const& in, dip::Image& out) const

Applies the label map to a label image.

in must be a label image (scalar, of an unsigned integer type). Out will be identical, but of type dip::DT_LABEL.

dip::Measurement Apply(dip::Measurement const& in) const

Applies the label map to measurement data.

Filters out objects (rows), and changes the object IDs for the remaining objects.

Note that the mapping can map multiple objects to the same ID. In this case, the output measurement data will contain only the measurements for the last object that mapped to any given ID.

dip::LabelMap& operator&=(dip::LabelMap const& rhs)

Combines *this and other using logical AND.

The resulting map will contain the union of all the labels in the two maps. Non-zero mappings that exist in both of the maps will be kept in the output map. The target value of *this is used. The remainder will map to 0.

dip::LabelMap& operator|=(dip::LabelMap const& rhs)

Combines *this and other using logical OR.

The resulting map will contain the union of all the labels in the two maps. Non-zero mappings that exist in either of the two maps will be kept in the output map. Those that map to a non-zero value in both maps will map to 0. If both label maps have a non-zero mapping for a given label, the one in *this is kept.

dip::LabelMap& operator^=(dip::LabelMap const& rhs)

Combines *this and other using logical XOR.

The resulting map will contain the union of all the labels in the two maps. Non-zero mappings that exist in only one of the two maps will be kept in the output map. The remainder will map to 0.

dip::LabelType& operator[](dip::LabelType label)

Looks up a label in the map and returns the target label by reference.

You can assign a new target label by updating the referenced label.

If the label is not present, it will be added. The newly added label will map to itself (by default) or to 0 (if dip::LabelMap::DestroyUnknownLabels was called previously).