Computes and stores extinction values for regional extrema. More...

#include <ExtinctionValues.hpp>

Public Types
using	value_type = Real
	Scalar type used for input attributes and extinction values.

Public Member Functions
	ExtinctionValues (const AltitudeView &view, const std::shared_ptr< Real[]> &attr)
	Computes extinction values from a valued-tree view and shared attribute buffer.

	ExtinctionValues (const AltitudeView &view, const std::vector< Real > &attr)
	Computes extinction values from a valued-tree view and vector attribute buffer.

	ExtinctionValues (const AltitudeView &view, const Real *attr)
	Computes extinction values from a valued-tree view and raw attribute buffer.

	ExtinctionValues (const ValuedMorphologicalTree< T > &valuedTree, const std::shared_ptr< Real[]> &attr)
	Computes extinction values from a valued tree and shared attribute buffer.

	ExtinctionValues (const ValuedMorphologicalTree< T > &valuedTree, const std::vector< Real > &attr)
	Computes extinction values from a valued tree and vector attribute buffer.

	ExtinctionValues (const ValuedMorphologicalTree< T > &valuedTree, const Real *attr)
	Computes extinction values from a valued tree and raw attribute buffer.

ImagePtr< Real >	contourMap (const ExtinctionSelectionPolicy< Real > &selection, ExtinctionContourScorePolicy scorePolicy) const
	Builds a contour-valued image from selected extinction events.

const std::vector< Real > &	getExtinctionValueAttribute () const
	Returns extinction values extended from extrema to every hierarchy node.

std::vector< int >	computeRankedExtinctionValueAttribute () const
	Builds a dense integer extinction attribute from extinction levels.

EdgeSaliencyMap< Real >	computeFormalSaliencyEdgeMap (const RegularGridAdjacency2D &adjacency) const
	Computes the formal hierarchical-watershed extinction saliency map.

EdgeSaliencyMap< Real >	computeFormalSaliencyEdgeMap () const
	Computes the formal extinction saliency edge map using stored adjacency.

EdgeSaliencyMap< int >	computeRankedFormalSaliencyEdgeMap (const RegularGridAdjacency2D &adjacency) const
	Computes a ranked formal extinction saliency edge map.

EdgeSaliencyMap< int >	computeRankedFormalSaliencyEdgeMap () const
	Computes a ranked formal extinction saliency edge map using stored adjacency.

EdgeSaliencyMap< Real >	computeMonotoneExtinctionProjection (const RegularGridAdjacency2D &adjacency) const
	Projects the max-descendant extinction attribute directly by LCA.

EdgeSaliencyMap< Real >	computeMonotoneExtinctionProjection () const
	Stored-adjacency overload of `computeMonotoneExtinctionProjection`.

EdgeSaliencyMap< int >	computeRankedMonotoneExtinctionProjection (const RegularGridAdjacency2D &adjacency) const
	Computes canonical effective-edge ranks for the monotone projection.

EdgeSaliencyMap< int >	computeRankedMonotoneExtinctionProjection () const
	Stored-adjacency overload of `computeRankedMonotoneExtinctionProjection`.

ImagePtr< T >	filtering (const ExtinctionSelectionPolicy< Real > &selection) const
	Reconstructs an image from selected regional extrema.

const std::vector< RegionalExtremaNode< Real > > &	getRegionalExtrema () const
	Returns regional-extremum records sorted by decreasing extinction.

Detailed Description

template<AltitudeValue T, std::floating_point Real = float>
class mmcfilters::ExtinctionValues< T, Real >

Computes and stores extinction values for regional extrema.

ExtinctionValues implements the classical leaf-extrema extinction ranking for hierarchies that declare a globally monotone altitude order. Standard max-tree and min-tree producers provide this capability. In this setting, the regional extrema processed by the algorithm are the tree leaves. The supplied scalar attribute is indexed by dense internal NodeId, must have one value for every internal node slot, and is interpreted so that larger values represent stronger extrema. Results are sorted in decreasing extinction order and can be consumed either as records, a filtered reconstruction, or a contour saliency map.

The strongest extremum has no stronger merge point. Its extinction value is represented by the explicit finite sentinel numeric_limits<Real>::max().

Standard tree-of-shapes and self-dual residual-tree producers declare NodeAltitudeOrder::Unconstrained and are rejected because their complete regional-extrema set is not generally equivalent to tree.leaves(). Acceptance is based on the altitude-order capability, not the descriptive tree kind.

The object records the tree mutation version at construction time. Public operations reject use after the underlying topology changes.

Primary algorithmic reference: Alexandre Gonçalves Silva and Roberto de Alencar Lotufo, "Efficient computation of new extinction values from extended component tree," Pattern Recognition Letters, 32(1):79-90, 2011. DOI 10.1016/j.patrec.2010.07.019. The component-tree branch traversal follows Algorithm 1; this class receives an already constructed tree and attribute buffer instead of incrementally computing them during tree construction.

Template Parameters

T	Altitude type used by the valued tree or valued-tree view.
Real	Attribute-buffer floating-point type.

Definition at line 173 of file ExtinctionValues.hpp.

Member Typedef Documentation

◆ value_type

template<AltitudeValue T, std::floating_point Real = float>

using mmcfilters::ExtinctionValues< T, Real >::value_type = Real

Scalar type used for input attributes and extinction values.

Definition at line 582 of file ExtinctionValues.hpp.

Constructor & Destructor Documentation

◆ ExtinctionValues() [1/6]

template<AltitudeValue T, std::floating_point Real = float>

mmcfilters::ExtinctionValues< T, Real >::ExtinctionValues	(	const AltitudeView &	view,
		const std::shared_ptr< Real[]> &	attr
	)

inline

Computes extinction values from a valued-tree view and shared attribute buffer.

Parameters

view	Valued tree view whose topology and altitude define the reconstruction domain.
attr	Shared buffer with one scalar attribute value per internal node slot.

Exceptions

std::invalid_argument	If `attr` is null.
std::logic_error	If `view` is stale.

Definition at line 594 of file ExtinctionValues.hpp.

◆ ExtinctionValues() [2/6]

template<AltitudeValue T, std::floating_point Real = float>

mmcfilters::ExtinctionValues< T, Real >::ExtinctionValues	(	const AltitudeView &	view,
		const std::vector< Real > &	attr
	)

inline

Computes extinction values from a valued-tree view and vector attribute buffer.

Parameters

view	Valued tree view whose topology and altitude define the reconstruction domain.
attr	Vector with one scalar attribute value per internal node slot.

Exceptions

std::invalid_argument	If `attr` does not match the internal node slot count of `view.topology()`.
std::logic_error	If `view` is stale.

Definition at line 606 of file ExtinctionValues.hpp.

◆ ExtinctionValues() [3/6]

template<AltitudeValue T, std::floating_point Real = float>

mmcfilters::ExtinctionValues< T, Real >::ExtinctionValues	(	const AltitudeView &	view,
		const Real *	attr
	)

inline

Computes extinction values from a valued-tree view and raw attribute buffer.

Parameters

view	Valued tree view whose topology and altitude define the reconstruction domain.
attr	Non-null buffer indexed by dense internal `NodeId`.

Exceptions

std::invalid_argument	If `attr` is null.
std::logic_error	If `view` is stale.

Definition at line 618 of file ExtinctionValues.hpp.

◆ ExtinctionValues() [4/6]

template<AltitudeValue T, std::floating_point Real = float>

mmcfilters::ExtinctionValues< T, Real >::ExtinctionValues	(	const ValuedMorphologicalTree< T > &	valuedTree,
		const std::shared_ptr< Real[]> &	attr
	)

inline

Computes extinction values from a valued tree and shared attribute buffer.

The valued tree is borrowed; it must outlive this object.

Parameters

valuedTree	Valued tree whose topology and altitude define the reconstruction domain.
attr	Shared buffer with one scalar attribute value per internal node slot.

Exceptions

std::invalid_argument If attr is null.

Definition at line 635 of file ExtinctionValues.hpp.

◆ ExtinctionValues() [5/6]

template<AltitudeValue T, std::floating_point Real = float>

mmcfilters::ExtinctionValues< T, Real >::ExtinctionValues	(	const ValuedMorphologicalTree< T > &	valuedTree,
		const std::vector< Real > &	attr
	)

inline

Computes extinction values from a valued tree and vector attribute buffer.

The valued tree is borrowed; it must outlive this object.

Parameters

valuedTree	Valued tree whose topology and altitude define the reconstruction domain.
attr	Vector with one scalar attribute value per internal node slot.

Exceptions

std::invalid_argument If attr does not match the internal node slot count of the tree.

Definition at line 650 of file ExtinctionValues.hpp.

◆ ExtinctionValues() [6/6]

template<AltitudeValue T, std::floating_point Real = float>

mmcfilters::ExtinctionValues< T, Real >::ExtinctionValues	(	const ValuedMorphologicalTree< T > &	valuedTree,
		const Real *	attr
	)

inline

Computes extinction values from a valued tree and raw attribute buffer.

The valued tree is borrowed; it must outlive this object.

Parameters

valuedTree	Valued tree whose topology and altitude define the reconstruction domain.
attr	Non-null buffer indexed by dense internal `NodeId`.

Exceptions

std::invalid_argument If attr is null.

Definition at line 664 of file ExtinctionValues.hpp.

Member Function Documentation

◆ computeFormalSaliencyEdgeMap() [1/2]

template<AltitudeValue T, std::floating_point Real = float>

EdgeSaliencyMap< Real > mmcfilters::ExtinctionValues< T, Real >::computeFormalSaliencyEdgeMap ( ) const

inline

Computes the formal extinction saliency edge map using stored adjacency.

The valued tree must carry a construction adjacency relation. Use the overload receiving RegularGridAdjacency2D when the tree was imported without stored adjacency metadata.

Returns: Edge-indexed saliency map with raw extinction values.

Exceptions

std::logic_error	If the tree topology changed after construction or no stored adjacency is available.
std::invalid_argument	If the raw extinction valuation is invalid.

Definition at line 831 of file ExtinctionValues.hpp.

◆ computeFormalSaliencyEdgeMap() [2/2]

template<AltitudeValue T, std::floating_point Real = float>

EdgeSaliencyMap< Real > mmcfilters::ExtinctionValues< T, Real >::computeFormalSaliencyEdgeMap ( const RegularGridAdjacency2D & adjacency ) const

inline

Computes the formal hierarchical-watershed extinction saliency map.

This is the Section 8.1 persistence path of Cousty et al.: a Kruskal BPTAO is represented by an MST, each binary merge receives the minimum of the maximum descendant extinctions of its two children, and the resulting persistence-valuedTree MST is converted to its full-graph QFZ saliency map. The return type is an edge map, not the image-domain contour visualization returned by contourMap.

Primary reference: Jean Cousty, Laurent Najman, Yukiko Kenmochi, and Silvio Guimarães, "Hierarchical segmentations with graphs: quasi-flat zones, minimum spanning trees, and saliency maps," Journal of Mathematical Imaging and Vision, 60(4):479-502, 2018, DOI 10.1007/s10851-017-0768-7, Section 8.1.

Parameters

adjacency Explicit adjacency relation used to enumerate image-domain graph edges.

Returns: Edge-indexed saliency map with raw extinction values.

Exceptions

std::logic_error	If the tree topology changed after construction.
std::invalid_argument	If the raw extinction valuation is invalid.

Definition at line 814 of file ExtinctionValues.hpp.

◆ computeMonotoneExtinctionProjection() [1/2]

template<AltitudeValue T, std::floating_point Real = float>

EdgeSaliencyMap< Real > mmcfilters::ExtinctionValues< T, Real >::computeMonotoneExtinctionProjection ( ) const

inline

Stored-adjacency overload of computeMonotoneExtinctionProjection.

Returns: Edge-indexed map obtained by monotone LCA projection.

Exceptions

std::logic_error	If the topology changed or no unambiguous stored adjacency is available.
std::invalid_argument	If the valuation or projection graph is invalid.

Definition at line 897 of file ExtinctionValues.hpp.

◆ computeMonotoneExtinctionProjection() [2/2]

template<AltitudeValue T, std::floating_point Real = float>

EdgeSaliencyMap< Real > mmcfilters::ExtinctionValues< T, Real >::computeMonotoneExtinctionProjection ( const RegularGridAdjacency2D & adjacency ) const

inline

Projects the max-descendant extinction attribute directly by LCA.

This method preserves the pre-correction behavior of computeFormalSaliencyEdgeMap. It induces a valid monotone hierarchy, but it is not the hierarchical-watershed persistence construction.

Parameters

adjacency Explicit adjacency relation used to enumerate image-domain graph edges.

Returns: Edge-indexed map obtained by LCA projection of the max-descendant extinction valuation.

Exceptions

std::logic_error	If the tree topology changed after construction.
std::invalid_argument	If the valuation or projection graph is invalid.

Definition at line 884 of file ExtinctionValues.hpp.

◆ computeRankedExtinctionValueAttribute()

template<AltitudeValue T, std::floating_point Real = float>

std::vector< int > mmcfilters::ExtinctionValues< T, Real >::computeRankedExtinctionValueAttribute ( ) const

inline

Builds a dense integer extinction attribute from extinction levels.

Raw extinction values can include the dominant-extremum sentinel numeric_limits<Real>::max(), which is useful for ordering records but awkward as a display scale. This helper preserves the induced hierarchy order while replacing distinct live-node values by dense ranks 0..k-1. Equal extinction levels remain equal, so intentional level collapse is preserved.

Returns: Dense integer hierarchy valuation indexed by internal NodeId.

Exceptions

std::logic_error	If the tree topology changed after construction.
std::invalid_argument	If the raw extinction valuation is invalid.

Definition at line 785 of file ExtinctionValues.hpp.

◆ computeRankedFormalSaliencyEdgeMap() [1/2]

template<AltitudeValue T, std::floating_point Real = float>

EdgeSaliencyMap< int > mmcfilters::ExtinctionValues< T, Real >::computeRankedFormalSaliencyEdgeMap ( ) const

inline

Computes a ranked formal extinction saliency edge map using stored adjacency.

The valued tree must carry a construction adjacency relation. Use the overload receiving RegularGridAdjacency2D when the tree was imported without stored adjacency metadata.

Returns: Edge-indexed saliency map with dense integer extinction ranks.

Exceptions

std::logic_error	If the tree topology changed after construction or no stored adjacency is available.
std::invalid_argument	If the raw extinction valuation is invalid.

Definition at line 865 of file ExtinctionValues.hpp.

◆ computeRankedFormalSaliencyEdgeMap() [2/2]

template<AltitudeValue T, std::floating_point Real = float>

EdgeSaliencyMap< int > mmcfilters::ExtinctionValues< T, Real >::computeRankedFormalSaliencyEdgeMap ( const RegularGridAdjacency2D & adjacency ) const

inline

Computes a ranked formal extinction saliency edge map.

This variant first computes the persistence-based hierarchical watershed, then ranks only distinct values that occur on its final graph edges. The dominant-extremum sentinel therefore cannot create an unused rank.

Parameters

adjacency Explicit adjacency relation used to enumerate image-domain graph edges.

Returns: Edge-indexed saliency map with dense integer extinction ranks.

Exceptions

std::logic_error	If the tree topology changed after construction.
std::invalid_argument	If the raw extinction valuation is invalid.

Definition at line 848 of file ExtinctionValues.hpp.

◆ computeRankedMonotoneExtinctionProjection() [1/2]

template<AltitudeValue T, std::floating_point Real = float>

EdgeSaliencyMap< int > mmcfilters::ExtinctionValues< T, Real >::computeRankedMonotoneExtinctionProjection ( ) const

inline

Stored-adjacency overload of computeRankedMonotoneExtinctionProjection.

Returns: Edge-indexed monotone projection with dense effective-edge ranks.

Exceptions

std::logic_error	If the topology changed or no unambiguous stored adjacency is available.
std::invalid_argument	If the valuation or projection graph is invalid.

Definition at line 925 of file ExtinctionValues.hpp.

◆ computeRankedMonotoneExtinctionProjection() [2/2]

template<AltitudeValue T, std::floating_point Real = float>

EdgeSaliencyMap< int > mmcfilters::ExtinctionValues< T, Real >::computeRankedMonotoneExtinctionProjection ( const RegularGridAdjacency2D & adjacency ) const

inline

Computes canonical effective-edge ranks for the monotone projection.

Parameters

adjacency Explicit adjacency relation used to enumerate image-domain graph edges.

Returns: Edge-indexed monotone projection with dense effective-edge ranks.

Exceptions

std::logic_error	If the tree topology changed after construction.
std::invalid_argument	If the valuation or projection graph is invalid.

Definition at line 911 of file ExtinctionValues.hpp.

◆ contourMap()

template<AltitudeValue T, std::floating_point Real = float>

ImagePtr< Real > mmcfilters::ExtinctionValues< T, Real >::contourMap	(	const ExtinctionSelectionPolicy< Real > &	selection,
		ExtinctionContourScorePolicy	scorePolicy
	)		const

inline

Builds a contour-valued image from selected extinction events.

contourMap is an image-domain visualization, not the formal edge-indexed saliency map of a hierarchy. The selection policy chooses which regional extrema are kept, and the score policy chooses the value written on each retained cutoff-node contour. If several selected extrema share the same cutoff node, the strongest score for that node is kept.

Parameters

selection	Selection policy shared with `filtering`.
scorePolicy	Value convention for retained contours.

Returns: Floating-point image on the original image domain.

Exceptions

std::invalid_argument	If `selection` is invalid.
std::logic_error	If the tree topology changed after construction.

Definition at line 681 of file ExtinctionValues.hpp.

◆ filtering()

template<AltitudeValue T, std::floating_point Real = float>

ImagePtr< T > mmcfilters::ExtinctionValues< T, Real >::filtering ( const ExtinctionSelectionPolicy< Real > & selection ) const

inline

Reconstructs an image from selected regional extrema.

Parameters

selection Selection policy used to retain extrema by rank or by extinction threshold.

Returns: Image on the original image domain using altitude type T.

Exceptions

std::invalid_argument	If `selection` is invalid.
std::logic_error	If the tree topology changed after construction.

Definition at line 939 of file ExtinctionValues.hpp.

◆ getExtinctionValueAttribute()

template<AltitudeValue T, std::floating_point Real = float>

const std::vector< Real > & mmcfilters::ExtinctionValues< T, Real >::getExtinctionValueAttribute ( ) const

inline

Returns extinction values extended from extrema to every hierarchy node.

The extinction records associate one value with each leaf extremum and store the cutoff node where that extremum stops being dominant. This method follows the standard extinction-attribute extension used for hierarchy saliency: each extremum leaf receives its extinction value, and every non-leaf node receives the maximum extinction value among the extrema contained in its subtree.

The resulting dense node attribute is computed during initialization, non-decreasing toward the root. It can be passed to HierarchySaliencyMap::computeSaliencyEdgeMap when the monotone node projection is explicitly desired. The Cousty hierarchical-watershed path is computeFormalSaliencyEdgeMap, which additionally computes merge persistences. Raw extinction values are required to be finite and non-negative; use computeRankedExtinctionValueAttribute when a compact integer level scale is preferable to the raw values and the dominant-extremum sentinel.

Returns: Cached dense node extinction attribute.

Exceptions

std::logic_error	If the tree topology changed after construction.
std::invalid_argument	If cached values are not a valid non-negative hierarchy valuation.

Definition at line 764 of file ExtinctionValues.hpp.

◆ getRegionalExtrema()

template<AltitudeValue T, std::floating_point Real = float>

const std::vector< RegionalExtremaNode< Real > > & mmcfilters::ExtinctionValues< T, Real >::getRegionalExtrema ( ) const

inline

Returns regional-extremum records sorted by decreasing extinction.

Returns: Immutable record vector kept by this object.

Exceptions

std::logic_error If the tree topology changed after construction.

Definition at line 951 of file ExtinctionValues.hpp.

The documentation for this class was generated from the following file:

mmcfilters/filters/ExtinctionValues.hpp

Public Types

Public Member Functions

Detailed Description

Member Typedef Documentation

◆ value_type

Constructor & Destructor Documentation

◆ ExtinctionValues() [1/6]

◆ ExtinctionValues() [2/6]

◆ ExtinctionValues() [3/6]

◆ ExtinctionValues() [4/6]

◆ ExtinctionValues() [5/6]

◆ ExtinctionValues() [6/6]

Member Function Documentation

◆ computeFormalSaliencyEdgeMap() [1/2]

◆ computeFormalSaliencyEdgeMap() [2/2]

◆ computeMonotoneExtinctionProjection() [1/2]

◆ computeMonotoneExtinctionProjection() [2/2]

◆ computeRankedExtinctionValueAttribute()

◆ computeRankedFormalSaliencyEdgeMap() [1/2]

◆ computeRankedFormalSaliencyEdgeMap() [2/2]

◆ computeRankedMonotoneExtinctionProjection() [1/2]

◆ computeRankedMonotoneExtinctionProjection() [2/2]

◆ contourMap()

◆ filtering()

◆ getExtinctionValueAttribute()

◆ getRegionalExtrema()