Computes a spatial alignment between two sets of entities (with 3D coordinates) by composing topological entity matching with Kabsch-style 3D superposition. More...

#include <SpatialEntityAlignment.hpp>

Inheritance diagram for CDPL::Chem::SpatialEntityAlignment< T >:

Public Types
typedef T	EntityType
	The actual entity type. More...

typedef TopologicalAlignment::ConstEntityIterator	ConstEntityIterator
	A constant iterator over the stored entities. More...

typedef std::function< bool(const Util::STPairArray &)>	TopologicalAlignmentConstraintFunction
	Generic wrapper class used to store a user-defined predicate to restrict allowed topological entity alignments. More...

typedef std::function< const Math::Vector3D &(const EntityType &)>	Entity3DCoordinatesFunction
	Generic wrapper class used to store a user-defined entity 3D-coordinates function. More...

typedef std::function< double(const EntityType &)>	EntityWeightFunction
	Generic wrapper class used to store a user-defined entity alignment weight function. More...

typedef TopologicalAlignment::EntityMatchFunction	EntityMatchFunction
	Generic wrapper class used to store a user-defined topological entity match constraint function. More...

typedef TopologicalAlignment::EntityPairMatchFunction	EntityPairMatchFunction
	Generic wrapper class used to store a user-defined entity-pair match constraint function. More...

Public Member Functions
	SpatialEntityAlignment ()
	Constructs the `SpatialEntityAlignment` instance. More...

virtual	~SpatialEntityAlignment ()
	Virtual destructor. More...

void	setMinTopologicalMappingSize (std::size_t min_size)
	Specifies the minimum number of topologically mapped entities that is required to enable a subsequent spatial alignment. More...

std::size_t	getMinTopologicalMappingSize ()
	Returns the minimum number of topologically mapped entities that is required to enable a subsequent spatial alignment. More...

void	setEntity3DCoordinatesFunction (const Entity3DCoordinatesFunction &func)
	Specifies a function for the retrieval of entity 3D-coordinates. More...

const Entity3DCoordinatesFunction &	getEntity3DCoordinatesFunction () const
	Returns the function that was registered for the retrieval of entity 3D-coordinates. More...

void	setEntityWeightFunction (const EntityWeightFunction &func)
	Specifies a function for the retrieval of entity weights for spatial alignment. More...

const EntityWeightFunction &	getEntityWeightFunction () const
	Returns the function that was registered for the retrieval of entity weights for spatial alignment. More...

void	setTopAlignmentConstraintFunction (const TopologicalAlignmentConstraintFunction &func)
	Specifies a function for restricting allowed topological entity alignments. More...

const TopologicalAlignmentConstraintFunction &	getTopAlignmentConstraintFunction () const
	Returns the function that was registered for restricting allowed topological entity alignments. More...

void	setEntityMatchFunction (const EntityMatchFunction &func)
	Specifies a function for restricting allowed topological entity mappings in the search for alignment solutions. More...

const EntityMatchFunction &	getEntityMatchFunction () const
	Returns the function that was registered for restricting allowed topological entity mappings. More...

void	setEntityPairMatchFunction (const EntityPairMatchFunction &func)
	Specifies a function for checking the compatibility of entity-pairs in the search for alignment solutions. More...

const EntityPairMatchFunction &	getEntityPairMatchFunction () const
	Returns the function that was registered for checking the compatibility of entity-pairs. More...

void	performExhaustiveSearch (bool exhaustive)
	Specifies whether topological mappings shall be enumerated exhaustively before spatial alignment, or one-by-one as nextAlignment() is called. More...

bool	exhaustiveSearchPerformed () const
	Tells whether topological mappings are enumerated exhaustively before spatial alignment. More...

void	addEntity (const EntityType &entity, bool first_set)
	Adds an entity to the specified alignment entity set. More...

void	clearEntities (bool first_set)
	Removes all entities in the specified alignment entity set. More...

std::size_t	getNumEntities (bool first_set) const
	Returns the number of entities in the specified alignment entity set. More...

ConstEntityIterator	getEntitiesBegin (bool first_set) const
	Returns a constant iterator pointing to the beginning of the entities stored in the specified set. More...

ConstEntityIterator	getEntitiesEnd (bool first_set) const
	Returns a constant iterator pointing to the end of the entities stored in the specified set. More...

const EntityType &	getEntity (std::size_t idx, bool first_set) const
	Returns a non-`const` reference to the stored entity at index idx in the specified set. More...

bool	nextAlignment ()
	Searches for the next alignment solution. More...

void	reset ()
	Discards the current alignment-search state so that the next call to nextAlignment() restarts the topological-mapping enumeration from scratch. More...

const Math::Matrix4D &	getTransform () const
	Returns the alignment transformation matrix that was calculated in the last successful call to nextAlignment(). More...

const Util::STPairArray &	getTopologicalMapping () const
	Returns the topological entity mapping resulting from the last successful call to nextAlignment(). More...

Detailed Description

template<typename T>
class CDPL::Chem::SpatialEntityAlignment< T >

Computes a spatial alignment between two sets of entities (with 3D coordinates) by composing topological entity matching with Kabsch-style 3D superposition.

The class drives an internal Chem::TopologicalEntityAlignment over the two entity sets to enumerate candidate index mappings (subject to setMinTopologicalMappingSize() and the optional setTopAlignmentConstraintFunction()), then computes the optimal rigid-body transformation for each accepted mapping using Math::KabschAlgorithm with the entity 3D coordinates supplied by setEntity3DCoordinatesFunction() and (optionally) the per-entity weights supplied by setEntityWeightFunction(). Calls to nextAlignment() advance the search; the resulting transformation and the corresponding topological mapping are retrieved with getTransform() and getTopologicalMapping().

Template Parameters

T	The entity type to align.

Member Typedef Documentation

◆ EntityType

template<typename T >

typedef T CDPL::Chem::SpatialEntityAlignment< T >::EntityType

The actual entity type.

◆ ConstEntityIterator

template<typename T >

typedef TopologicalAlignment::ConstEntityIterator CDPL::Chem::SpatialEntityAlignment< T >::ConstEntityIterator

A constant iterator over the stored entities.

◆ TopologicalAlignmentConstraintFunction

template<typename T >

typedef std::function<bool(const Util::STPairArray&)> CDPL::Chem::SpatialEntityAlignment< T >::TopologicalAlignmentConstraintFunction

Generic wrapper class used to store a user-defined predicate to restrict allowed topological entity alignments.

◆ Entity3DCoordinatesFunction

template<typename T >

typedef std::function<const Math::Vector3D&(const EntityType&)> CDPL::Chem::SpatialEntityAlignment< T >::Entity3DCoordinatesFunction

Generic wrapper class used to store a user-defined entity 3D-coordinates function.

◆ EntityWeightFunction

template<typename T >

typedef std::function<double(const EntityType&)> CDPL::Chem::SpatialEntityAlignment< T >::EntityWeightFunction

Generic wrapper class used to store a user-defined entity alignment weight function.

◆ EntityMatchFunction

template<typename T >

typedef TopologicalAlignment::EntityMatchFunction CDPL::Chem::SpatialEntityAlignment< T >::EntityMatchFunction

Generic wrapper class used to store a user-defined topological entity match constraint function.

◆ EntityPairMatchFunction

template<typename T >

typedef TopologicalAlignment::EntityPairMatchFunction CDPL::Chem::SpatialEntityAlignment< T >::EntityPairMatchFunction

Generic wrapper class used to store a user-defined entity-pair match constraint function.

Constructor & Destructor Documentation

◆ SpatialEntityAlignment()

template<typename T >

CDPL::Chem::SpatialEntityAlignment< T >::SpatialEntityAlignment

Constructs the SpatialEntityAlignment instance.

◆ ~SpatialEntityAlignment()

template<typename T >

virtual CDPL::Chem::SpatialEntityAlignment< T >::~SpatialEntityAlignment ( )

inlinevirtual

Virtual destructor.

Member Function Documentation

◆ setMinTopologicalMappingSize()

template<typename T >

void CDPL::Chem::SpatialEntityAlignment< T >::setMinTopologicalMappingSize ( std::size_t min_size )

Specifies the minimum number of topologically mapped entities that is required to enable a subsequent spatial alignment.

Parameters

min_size The minimum required number of topologically mapped entities.

◆ getMinTopologicalMappingSize()

template<typename T >

std::size_t CDPL::Chem::SpatialEntityAlignment< T >::getMinTopologicalMappingSize

Returns the minimum number of topologically mapped entities that is required to enable a subsequent spatial alignment.

Returns: The minimum required number of topologically mapped entities.

◆ setEntity3DCoordinatesFunction()

template<typename T >

void CDPL::Chem::SpatialEntityAlignment< T >::setEntity3DCoordinatesFunction ( const Entity3DCoordinatesFunction & func )

Specifies a function for the retrieval of entity 3D-coordinates.

Parameters

func	The entity 3D-coordinates function.

◆ getEntity3DCoordinatesFunction()

template<typename T >

const CDPL::Chem::SpatialEntityAlignment< T >::Entity3DCoordinatesFunction & CDPL::Chem::SpatialEntityAlignment< T >::getEntity3DCoordinatesFunction

Returns the function that was registered for the retrieval of entity 3D-coordinates.

Returns: The registered entity 3D-coordinates function.

◆ setEntityWeightFunction()

template<typename T >

void CDPL::Chem::SpatialEntityAlignment< T >::setEntityWeightFunction ( const EntityWeightFunction & func )

Specifies a function for the retrieval of entity weights for spatial alignment.

Parameters

func	The entity weight function.

◆ getEntityWeightFunction()

template<typename T >

const CDPL::Chem::SpatialEntityAlignment< T >::EntityWeightFunction & CDPL::Chem::SpatialEntityAlignment< T >::getEntityWeightFunction

Returns the function that was registered for the retrieval of entity weights for spatial alignment.

Returns: The registered entity weight function.

◆ setTopAlignmentConstraintFunction()

template<typename T >

void CDPL::Chem::SpatialEntityAlignment< T >::setTopAlignmentConstraintFunction ( const TopologicalAlignmentConstraintFunction & func )

Specifies a function for restricting allowed topological entity alignments.

Parameters

func	The constraint check function.

◆ getTopAlignmentConstraintFunction()

template<typename T >

const CDPL::Chem::SpatialEntityAlignment< T >::TopologicalAlignmentConstraintFunction & CDPL::Chem::SpatialEntityAlignment< T >::getTopAlignmentConstraintFunction

Returns the function that was registered for restricting allowed topological entity alignments.

Returns: The registered constraint check function.

◆ setEntityMatchFunction()

template<typename T >

void CDPL::Chem::SpatialEntityAlignment< T >::setEntityMatchFunction ( const EntityMatchFunction & func )

Specifies a function for restricting allowed topological entity mappings in the search for alignment solutions.

Parameters

func	The constraint check function.

◆ getEntityMatchFunction()

template<typename T >

const CDPL::Chem::SpatialEntityAlignment< T >::EntityMatchFunction & CDPL::Chem::SpatialEntityAlignment< T >::getEntityMatchFunction

Returns the function that was registered for restricting allowed topological entity mappings.

Returns: The registered constraint check function.

◆ setEntityPairMatchFunction()

template<typename T >

void CDPL::Chem::SpatialEntityAlignment< T >::setEntityPairMatchFunction ( const EntityPairMatchFunction & func )

Specifies a function for checking the compatibility of entity-pairs in the search for alignment solutions.

Parameters

func	The constraint check function.

Note: This function gets only called for pairs with already matching first and second entities.

◆ getEntityPairMatchFunction()

template<typename T >

const CDPL::Chem::SpatialEntityAlignment< T >::EntityPairMatchFunction & CDPL::Chem::SpatialEntityAlignment< T >::getEntityPairMatchFunction

Returns the function that was registered for checking the compatibility of entity-pairs.

Returns: The registered constraint check function.

◆ performExhaustiveSearch()

template<typename T >

void CDPL::Chem::SpatialEntityAlignment< T >::performExhaustiveSearch ( bool exhaustive )

Specifies whether topological mappings shall be enumerated exhaustively before spatial alignment, or one-by-one as nextAlignment() is called.

Parameters

exhaustive true to enumerate all topological mappings up front, and false to enumerate them lazily.

◆ exhaustiveSearchPerformed()

template<typename T >

bool CDPL::Chem::SpatialEntityAlignment< T >::exhaustiveSearchPerformed

Tells whether topological mappings are enumerated exhaustively before spatial alignment.

Returns: true if exhaustive enumeration is enabled, and false otherwise.

See also: performExhaustiveSearch()

◆ addEntity()

template<typename T >

void CDPL::Chem::SpatialEntityAlignment< T >::addEntity	(	const EntityType &	entity,
		bool	first_set
	)

Adds an entity to the specified alignment entity set.

Parameters

entity	The entity object to add.
first_set	If `true`, the entity is added to the first entity set, if `false` to the second one.

◆ clearEntities()

template<typename T >

void CDPL::Chem::SpatialEntityAlignment< T >::clearEntities ( bool first_set )

Removes all entities in the specified alignment entity set.

Parameters

first_set If true, the first entity set is cleared, if false the second one.

◆ getNumEntities()

template<typename T >

std::size_t CDPL::Chem::SpatialEntityAlignment< T >::getNumEntities ( bool first_set ) const

Returns the number of entities in the specified alignment entity set.

Parameters

first_set If true, the size of first entity set is returned, if false the size of the second one.

◆ getEntitiesBegin()

template<typename T >

CDPL::Chem::SpatialEntityAlignment< T >::ConstEntityIterator CDPL::Chem::SpatialEntityAlignment< T >::getEntitiesBegin ( bool first_set ) const

Returns a constant iterator pointing to the beginning of the entities stored in the specified set.

Parameters

first_set If true, an iterator for first entity set is returned, if false for the second one.

Returns: A constant iterator pointing to the beginning of the entities stored in the specified set.

◆ getEntitiesEnd()

template<typename T >

CDPL::Chem::SpatialEntityAlignment< T >::ConstEntityIterator CDPL::Chem::SpatialEntityAlignment< T >::getEntitiesEnd ( bool first_set ) const

Returns a constant iterator pointing to the end of the entities stored in the specified set.

Parameters

first_set If true, an iterator for first entity set is returned, if false for the second one.

Returns: A constant iterator pointing to the end of the entities stored in the specified set.

◆ getEntity()

template<typename T >

const CDPL::Chem::SpatialEntityAlignment< T >::EntityType & CDPL::Chem::SpatialEntityAlignment< T >::getEntity	(	std::size_t	idx,
		bool	first_set
	)		const

Returns a non-const reference to the stored entity at index idx in the specified set.

Parameters

idx	The zero-based index of the entity instance to return.
first_set	`true`, if the entity to return is stored in the first set. `false`, if stored in the second set.

Returns: A non-const reference to the entity stored at index idx in the specified set.

Exceptions

Base::IndexError if the number of entities in the specified set is zero or idx is not in the range [0, getNumEntities() - 1].

◆ nextAlignment()

template<typename T >

bool CDPL::Chem::SpatialEntityAlignment< T >::nextAlignment

Searches for the next alignment solution.

Returns: true if a new alignment solution could be found, and false otherwise.

◆ reset()

template<typename T >

void CDPL::Chem::SpatialEntityAlignment< T >::reset

Discards the current alignment-search state so that the next call to nextAlignment() restarts the topological-mapping enumeration from scratch.

◆ getTransform()

template<typename T >

const CDPL::Math::Matrix4D & CDPL::Chem::SpatialEntityAlignment< T >::getTransform

Returns the alignment transformation matrix that was calculated in the last successful call to nextAlignment().

A transformation of the positions of the entities in the second set aligns them spatially to the topologically mapped entities in the first set.

Returns: The alignment transformation matrix.

◆ getTopologicalMapping()

template<typename T >

const CDPL::Util::STPairArray & CDPL::Chem::SpatialEntityAlignment< T >::getTopologicalMapping

Returns the topological entity mapping resulting from the last successful call to nextAlignment().

Returns: The topological entity mapping as an array of pairs of entity indices.

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

SpatialEntityAlignment.hpp

Public Types

Public Member Functions

Detailed Description

template<typename T> class CDPL::Chem::SpatialEntityAlignment< T >

Member Typedef Documentation

◆ EntityType

◆ ConstEntityIterator

◆ TopologicalAlignmentConstraintFunction

◆ Entity3DCoordinatesFunction

◆ EntityWeightFunction

◆ EntityMatchFunction

◆ EntityPairMatchFunction

Constructor & Destructor Documentation

◆ SpatialEntityAlignment()

◆ ~SpatialEntityAlignment()

Member Function Documentation

◆ setMinTopologicalMappingSize()

◆ getMinTopologicalMappingSize()

◆ setEntity3DCoordinatesFunction()

◆ getEntity3DCoordinatesFunction()

◆ setEntityWeightFunction()

◆ getEntityWeightFunction()

◆ setTopAlignmentConstraintFunction()

◆ getTopAlignmentConstraintFunction()

◆ setEntityMatchFunction()

◆ getEntityMatchFunction()

◆ setEntityPairMatchFunction()

◆ getEntityPairMatchFunction()

◆ performExhaustiveSearch()

◆ exhaustiveSearchPerformed()

◆ addEntity()

◆ clearEntities()

◆ getNumEntities()

◆ getEntitiesBegin()

◆ getEntitiesEnd()

◆ getEntity()

◆ nextAlignment()

◆ reset()

◆ getTransform()

◆ getTopologicalMapping()

template<typename T>
class CDPL::Chem::SpatialEntityAlignment< T >