Driver for the alignment of one Shape::GaussianShapeFunction (the aligned shape) against a fixed reference Shape::GaussianShapeFunction. More...

#include <GaussianShapeFunctionAlignment.hpp>

Classes
class	Result
	A single alignment result: rigid-body transformation plus shape and color overlap values. More...

Public Types
typedef std::shared_ptr< GaussianShapeFunctionAlignment >	SharedPointer
	A reference-counted smart pointer [SHPTR] for dynamically allocated `GaussianShapeFunctionAlignment` instances. More...

typedef ResultList::const_iterator	ConstResultIterator
	A constant iterator over the alignment results. More...

typedef GaussianShapeOverlapFunction::ColorFilterFunction	ColorFilterFunction
	Type of the function used to filter color (pharmacophore) features by type. More...

typedef GaussianShapeOverlapFunction::ColorMatchFunction	ColorMatchFunction
	Type of the function used to decide whether two color features match. More...

Public Member Functions
	GaussianShapeFunctionAlignment ()
	Constructs the `GaussianShapeFunctionAlignment` instance without a reference shape. More...

	GaussianShapeFunctionAlignment (const GaussianShapeFunction &ref_func, unsigned int sym_class)
	Constructs the `GaussianShapeFunctionAlignment` instance with the given reference shape function. More...

	GaussianShapeFunctionAlignment (const GaussianShapeFunctionAlignment &alignment)=delete

	~GaussianShapeFunctionAlignment ()
	Destructor. More...

GaussianShapeFunctionAlignment &	operator= (const GaussianShapeFunctionAlignment &alignment)=delete

void	setOverlapFunction (GaussianShapeOverlapFunction &func)
	Specifies the Gaussian-shape overlap function used during alignment. More...

GaussianShapeOverlapFunction &	getOverlapFunction () const
	Returns the currently configured overlap function. More...

const FastGaussianShapeOverlapFunction &	getDefaultOverlapFunction () const
	Returns the built-in default overlap function (Shape::FastGaussianShapeOverlapFunction). More...

FastGaussianShapeOverlapFunction &	getDefaultOverlapFunction ()
	Returns the built-in default overlap function (Shape::FastGaussianShapeOverlapFunction). More...

void	setStartGenerator (GaussianShapeAlignmentStartGenerator &gen)
	Specifies the alignment-start generator used to seed the overlap optimization. More...

GaussianShapeAlignmentStartGenerator &	getStartGenerator () const
	Returns the currently configured alignment-start generator. More...

const PrincipalAxesAlignmentStartGenerator &	getDefaultStartGenerator () const
	Returns the built-in default principal-axes alignment-start generator. More...

PrincipalAxesAlignmentStartGenerator &	getDefaultStartGenerator ()
	Returns the built-in default principal-axes alignment-start generator. More...

void	setColorMatchFunction (const ColorMatchFunction &func)
	Specifies the function used to decide whether two color features match. More...

const ColorMatchFunction &	getColorMatchFunction () const
	Returns the currently configured color-match function. More...

void	setColorFilterFunction (const ColorFilterFunction &func)
	Specifies the function used to filter color features by type. More...

const ColorFilterFunction &	getColorFilterFunction () const
	Returns the currently configured color-filter function. More...

void	performAlignment (bool perf_align)
	Specifies whether the actual alignment shall be performed (vs. only evaluating overlaps in the initial pose). More...

bool	performAlignment () const
	Tells whether the actual alignment is performed. More...

void	optimizeOverlap (bool optimize)
	Specifies whether the overlap shall be optimized iteratively after the initial alignment. More...

bool	optimizeOverlap () const
	Tells whether the overlap is optimized iteratively. More...

void	greedyOptimization (bool greedy)
	Specifies whether the overlap optimization shall use a greedy strategy that stops at the first local maximum. More...

bool	greedyOptimization () const
	Tells whether the overlap optimization uses a greedy strategy. More...

void	setMaxNumOptimizationIterations (std::size_t max_iter)
	Sets the maximum number of overlap-optimization iterations. More...

std::size_t	getMaxNumOptimizationIterations () const
	Returns the currently configured maximum number of overlap-optimization iterations. More...

void	setOptimizationStopGradient (double grad_norm)
	Sets the gradient norm at which the overlap optimization is stopped. More...

double	getOptimizationStopGradient () const
	Returns the currently configured overlap-optimization stop gradient. More...

unsigned int	setupReference (GaussianShapeFunction &func, Math::Matrix4D &xform) const
	Delegates the reference-shape preparation to the configured start generator. More...

unsigned int	setupAligned (GaussianShapeFunction &func, Math::Matrix4D &xform) const
	Delegates the aligned-shape preparation to the configured start generator. More...

void	setReference (const GaussianShapeFunction &func, unsigned int sym_class)
	Sets the reference shape function used by subsequent align() calls. More...

const GaussianShapeFunction *	getReference () const
	Returns the current reference shape function (or `nullptr` if none is set). More...

double	calcSelfOverlap (const GaussianShapeFunction &func)
	Calculates the shape-only self-overlap of func using the configured overlap function. More...

double	calcColorSelfOverlap (const GaussianShapeFunction &func)
	Calculates the color self-overlap of func using the configured overlap function. More...

void	calcColorOverlaps (bool calc)
	Specifies whether color overlaps shall be evaluated in addition to shape overlaps. More...

bool	calcColorOverlaps () const
	Tells whether color overlaps are evaluated. More...

bool	align (const GaussianShapeFunction &func, unsigned int sym_class)
	Aligns the shape function func against the configured reference shape. More...

std::size_t	getNumResults () const
	Returns the number of alignment results produced by the last align() call. More...

const Result &	getResult (std::size_t idx) const
	Returns the alignment result at index idx. More...

ConstResultIterator	getResultsBegin () const
	Returns a constant iterator pointing to the first alignment result. More...

ConstResultIterator	getResultsEnd () const
	Returns a constant iterator pointing one past the last alignment result. More...

ConstResultIterator	begin () const
	Returns a constant iterator pointing to the first alignment result (range-based for support). More...

ConstResultIterator	end () const
	Returns a constant iterator pointing one past the last alignment result (range-based for support). More...

Static Public Attributes
static constexpr double	DEF_OPTIMIZATION_STOP_GRADIENT = 1.0
	Default gradient norm at which the overlap optimization is stopped. More...

static constexpr std::size_t	DEF_MAX_OPTIMIZATION_ITERATIONS = 20
	Default maximum number of overlap-optimization iterations. More...

Detailed Description

Driver for the alignment of one Shape::GaussianShapeFunction (the aligned shape) against a fixed reference Shape::GaussianShapeFunction.

The alignment iterates over starting transformations produced by a configurable Shape::GaussianShapeAlignmentStartGenerator, optionally refines each start via BFGS minimization (Math::BFGSMinimizer) of the overlap function, and collects the resulting transformations and overlap values in Result instances.

See also: Math::BFGSMinimizer

Member Typedef Documentation

◆ SharedPointer

typedef std::shared_ptr<GaussianShapeFunctionAlignment> CDPL::Shape::GaussianShapeFunctionAlignment::SharedPointer

A reference-counted smart pointer [SHPTR] for dynamically allocated GaussianShapeFunctionAlignment instances.

◆ ConstResultIterator

typedef ResultList::const_iterator CDPL::Shape::GaussianShapeFunctionAlignment::ConstResultIterator

A constant iterator over the alignment results.

◆ ColorFilterFunction

typedef GaussianShapeOverlapFunction::ColorFilterFunction CDPL::Shape::GaussianShapeFunctionAlignment::ColorFilterFunction

Type of the function used to filter color (pharmacophore) features by type.

◆ ColorMatchFunction

typedef GaussianShapeOverlapFunction::ColorMatchFunction CDPL::Shape::GaussianShapeFunctionAlignment::ColorMatchFunction

Type of the function used to decide whether two color features match.

Constructor & Destructor Documentation

◆ GaussianShapeFunctionAlignment() [1/3]

CDPL::Shape::GaussianShapeFunctionAlignment::GaussianShapeFunctionAlignment ( )

Constructs the GaussianShapeFunctionAlignment instance without a reference shape.

◆ GaussianShapeFunctionAlignment() [2/3]

CDPL::Shape::GaussianShapeFunctionAlignment::GaussianShapeFunctionAlignment	(	const GaussianShapeFunction &	ref_func,
		unsigned int	sym_class
	)

Constructs the GaussianShapeFunctionAlignment instance with the given reference shape function.

Parameters

ref_func	The reference shape function.
sym_class	The symmetry class of the reference shape (see namespace Shape::SymmetryClass).

◆ GaussianShapeFunctionAlignment() [3/3]

CDPL::Shape::GaussianShapeFunctionAlignment::GaussianShapeFunctionAlignment ( const GaussianShapeFunctionAlignment & alignment )

delete

◆ ~GaussianShapeFunctionAlignment()

CDPL::Shape::GaussianShapeFunctionAlignment::~GaussianShapeFunctionAlignment ( )

Destructor.

Member Function Documentation

◆ operator=()

GaussianShapeFunctionAlignment& CDPL::Shape::GaussianShapeFunctionAlignment::operator= ( const GaussianShapeFunctionAlignment & alignment )

delete

◆ setOverlapFunction()

void CDPL::Shape::GaussianShapeFunctionAlignment::setOverlapFunction ( GaussianShapeOverlapFunction & func )

Specifies the Gaussian-shape overlap function used during alignment.

Parameters

func	The overlap function.

◆ getOverlapFunction()

GaussianShapeOverlapFunction& CDPL::Shape::GaussianShapeFunctionAlignment::getOverlapFunction ( ) const

Returns the currently configured overlap function.

Returns: A reference to the overlap function.

◆ getDefaultOverlapFunction() [1/2]

const FastGaussianShapeOverlapFunction& CDPL::Shape::GaussianShapeFunctionAlignment::getDefaultOverlapFunction ( ) const

Returns the built-in default overlap function (Shape::FastGaussianShapeOverlapFunction).

Returns: A const reference to the default overlap function.

◆ getDefaultOverlapFunction() [2/2]

FastGaussianShapeOverlapFunction& CDPL::Shape::GaussianShapeFunctionAlignment::getDefaultOverlapFunction ( )

Returns the built-in default overlap function (Shape::FastGaussianShapeOverlapFunction).

Returns: A reference to the default overlap function.

◆ setStartGenerator()

void CDPL::Shape::GaussianShapeFunctionAlignment::setStartGenerator ( GaussianShapeAlignmentStartGenerator & gen )

Specifies the alignment-start generator used to seed the overlap optimization.

Parameters

gen	The alignment-start generator.

◆ getStartGenerator()

GaussianShapeAlignmentStartGenerator& CDPL::Shape::GaussianShapeFunctionAlignment::getStartGenerator ( ) const

Returns the currently configured alignment-start generator.

Returns: A reference to the alignment-start generator.

◆ getDefaultStartGenerator() [1/2]

const PrincipalAxesAlignmentStartGenerator& CDPL::Shape::GaussianShapeFunctionAlignment::getDefaultStartGenerator ( ) const

Returns the built-in default principal-axes alignment-start generator.

Returns: A const reference to the default alignment-start generator.

◆ getDefaultStartGenerator() [2/2]

PrincipalAxesAlignmentStartGenerator& CDPL::Shape::GaussianShapeFunctionAlignment::getDefaultStartGenerator ( )

Returns the built-in default principal-axes alignment-start generator.

Returns: A reference to the default alignment-start generator.

◆ setColorMatchFunction()

void CDPL::Shape::GaussianShapeFunctionAlignment::setColorMatchFunction ( const ColorMatchFunction & func )

Specifies the function used to decide whether two color features match.

Parameters

func	The color-match function.

◆ getColorMatchFunction()

const ColorMatchFunction& CDPL::Shape::GaussianShapeFunctionAlignment::getColorMatchFunction ( ) const

Returns the currently configured color-match function.

Returns: A const reference to the color-match function.

◆ setColorFilterFunction()

void CDPL::Shape::GaussianShapeFunctionAlignment::setColorFilterFunction ( const ColorFilterFunction & func )

Specifies the function used to filter color features by type.

Parameters

func	The color-filter function.

◆ getColorFilterFunction()

const ColorFilterFunction& CDPL::Shape::GaussianShapeFunctionAlignment::getColorFilterFunction ( ) const

Returns the currently configured color-filter function.

Returns: A const reference to the color-filter function.

◆ performAlignment() [1/2]

void CDPL::Shape::GaussianShapeFunctionAlignment::performAlignment ( bool perf_align )

Specifies whether the actual alignment shall be performed (vs. only evaluating overlaps in the initial pose).

Parameters

perf_align true to perform the alignment, and false to only evaluate the initial pose.

◆ performAlignment() [2/2]

bool CDPL::Shape::GaussianShapeFunctionAlignment::performAlignment ( ) const

Tells whether the actual alignment is performed.

Returns: true if the alignment is performed, and false otherwise.

◆ optimizeOverlap() [1/2]

void CDPL::Shape::GaussianShapeFunctionAlignment::optimizeOverlap ( bool optimize )

Specifies whether the overlap shall be optimized iteratively after the initial alignment.

Parameters

optimize true to optimize the overlap, and false to skip optimization.

◆ optimizeOverlap() [2/2]

bool CDPL::Shape::GaussianShapeFunctionAlignment::optimizeOverlap ( ) const

Tells whether the overlap is optimized iteratively.

Returns: true if the overlap is optimized, and false otherwise.

◆ greedyOptimization() [1/2]

void CDPL::Shape::GaussianShapeFunctionAlignment::greedyOptimization ( bool greedy )

Specifies whether the overlap optimization shall use a greedy strategy that stops at the first local maximum.

Parameters

greedy true to use the greedy strategy, and false to use the full optimization.

◆ greedyOptimization() [2/2]

bool CDPL::Shape::GaussianShapeFunctionAlignment::greedyOptimization ( ) const

Tells whether the overlap optimization uses a greedy strategy.

Returns: true if the greedy strategy is used, and false otherwise.

◆ setMaxNumOptimizationIterations()

void CDPL::Shape::GaussianShapeFunctionAlignment::setMaxNumOptimizationIterations ( std::size_t max_iter )

Sets the maximum number of overlap-optimization iterations.

Parameters

max_iter The new maximum number of iterations.

◆ getMaxNumOptimizationIterations()

std::size_t CDPL::Shape::GaussianShapeFunctionAlignment::getMaxNumOptimizationIterations ( ) const

Returns the currently configured maximum number of overlap-optimization iterations.

Returns: The maximum number of iterations.

◆ setOptimizationStopGradient()

void CDPL::Shape::GaussianShapeFunctionAlignment::setOptimizationStopGradient ( double grad_norm )

Sets the gradient norm at which the overlap optimization is stopped.

Parameters

grad_norm The new stop gradient norm.

◆ getOptimizationStopGradient()

double CDPL::Shape::GaussianShapeFunctionAlignment::getOptimizationStopGradient ( ) const

Returns the currently configured overlap-optimization stop gradient.

Returns: The stop gradient norm.

◆ setupReference()

unsigned int CDPL::Shape::GaussianShapeFunctionAlignment::setupReference	(	GaussianShapeFunction &	func,
		Math::Matrix4D &	xform
	)		const

Delegates the reference-shape preparation to the configured start generator.

Parameters

func	The reference shape function (may be modified).
xform	The output transformation that maps the prepared frame back to the original frame.

Returns: The perceived symmetry class of the reference shape (see namespace Shape::SymmetryClass).

◆ setupAligned()

unsigned int CDPL::Shape::GaussianShapeFunctionAlignment::setupAligned	(	GaussianShapeFunction &	func,
		Math::Matrix4D &	xform
	)		const

Delegates the aligned-shape preparation to the configured start generator.

Parameters

func	The aligned shape function (may be modified).
xform	The output transformation that maps the prepared frame back to the original frame.

Returns: The perceived symmetry class of the aligned shape (see namespace Shape::SymmetryClass).

◆ setReference()

void CDPL::Shape::GaussianShapeFunctionAlignment::setReference	(	const GaussianShapeFunction &	func,
		unsigned int	sym_class
	)

Sets the reference shape function used by subsequent align() calls.

Parameters

func	The reference shape function.
sym_class	The symmetry class of the reference shape (see namespace Shape::SymmetryClass).

◆ getReference()

const GaussianShapeFunction* CDPL::Shape::GaussianShapeFunctionAlignment::getReference ( ) const

Returns the current reference shape function (or nullptr if none is set).

Returns: A pointer to the reference shape function.

◆ calcSelfOverlap()

double CDPL::Shape::GaussianShapeFunctionAlignment::calcSelfOverlap ( const GaussianShapeFunction & func )

Calculates the shape-only self-overlap of func using the configured overlap function.

Parameters

func	The shape function.

Returns: The self-overlap value.

◆ calcColorSelfOverlap()

double CDPL::Shape::GaussianShapeFunctionAlignment::calcColorSelfOverlap ( const GaussianShapeFunction & func )

Calculates the color self-overlap of func using the configured overlap function.

Parameters

func	The shape function.

Returns: The color self-overlap value.

◆ calcColorOverlaps() [1/2]

void CDPL::Shape::GaussianShapeFunctionAlignment::calcColorOverlaps ( bool calc )

Specifies whether color overlaps shall be evaluated in addition to shape overlaps.

Parameters

calc	`true` to evaluate color overlaps, and `false` to skip them.

◆ calcColorOverlaps() [2/2]

bool CDPL::Shape::GaussianShapeFunctionAlignment::calcColorOverlaps ( ) const

Tells whether color overlaps are evaluated.

Returns: true if color overlaps are evaluated, and false otherwise.

◆ align()

bool CDPL::Shape::GaussianShapeFunctionAlignment::align	(	const GaussianShapeFunction &	func,
		unsigned int	sym_class
	)

Aligns the shape function func against the configured reference shape.

Parameters

func	The aligned shape function.
sym_class	The symmetry class of the aligned shape (see namespace Shape::SymmetryClass).

Returns: true if at least one alignment result was produced, and false otherwise.

◆ getNumResults()

std::size_t CDPL::Shape::GaussianShapeFunctionAlignment::getNumResults ( ) const

Returns the number of alignment results produced by the last align() call.

Returns: The number of alignment results.

◆ getResult()

const Result& CDPL::Shape::GaussianShapeFunctionAlignment::getResult ( std::size_t idx ) const

Returns the alignment result at index idx.

Parameters

idx	The zero-based result index.

Returns: A const reference to the result.

Exceptions

Base::IndexError if the number of results is zero or idx is not in the range [0, getNumResults() - 1].

◆ getResultsBegin()

ConstResultIterator CDPL::Shape::GaussianShapeFunctionAlignment::getResultsBegin ( ) const

Returns a constant iterator pointing to the first alignment result.

Returns: A constant iterator pointing to the first alignment result.

◆ getResultsEnd()

ConstResultIterator CDPL::Shape::GaussianShapeFunctionAlignment::getResultsEnd ( ) const

Returns a constant iterator pointing one past the last alignment result.

Returns: A constant iterator pointing one past the last alignment result.

◆ begin()

ConstResultIterator CDPL::Shape::GaussianShapeFunctionAlignment::begin ( ) const

Returns a constant iterator pointing to the first alignment result (range-based for support).

Returns: A constant iterator pointing to the first alignment result.

◆ end()

ConstResultIterator CDPL::Shape::GaussianShapeFunctionAlignment::end ( ) const

Returns a constant iterator pointing one past the last alignment result (range-based for support).

Returns: A constant iterator pointing one past the last alignment result.

Member Data Documentation

◆ DEF_OPTIMIZATION_STOP_GRADIENT

constexpr double CDPL::Shape::GaussianShapeFunctionAlignment::DEF_OPTIMIZATION_STOP_GRADIENT = 1.0

staticconstexpr

Default gradient norm at which the overlap optimization is stopped.

◆ DEF_MAX_OPTIMIZATION_ITERATIONS

constexpr std::size_t CDPL::Shape::GaussianShapeFunctionAlignment::DEF_MAX_OPTIMIZATION_ITERATIONS = 20

staticconstexpr

Default maximum number of overlap-optimization iterations.

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

GaussianShapeFunctionAlignment.hpp

Classes

Public Types

Public Member Functions

Static Public Attributes

Detailed Description

Member Typedef Documentation

◆ SharedPointer

◆ ConstResultIterator

◆ ColorFilterFunction

◆ ColorMatchFunction

Constructor & Destructor Documentation

◆ GaussianShapeFunctionAlignment() [1/3]

◆ GaussianShapeFunctionAlignment() [2/3]

◆ GaussianShapeFunctionAlignment() [3/3]

◆ ~GaussianShapeFunctionAlignment()

Member Function Documentation

◆ operator=()

◆ setOverlapFunction()

◆ getOverlapFunction()

◆ getDefaultOverlapFunction() [1/2]

◆ getDefaultOverlapFunction() [2/2]

◆ setStartGenerator()

◆ getStartGenerator()

◆ getDefaultStartGenerator() [1/2]

◆ getDefaultStartGenerator() [2/2]

◆ setColorMatchFunction()

◆ getColorMatchFunction()

◆ setColorFilterFunction()

◆ getColorFilterFunction()

◆ performAlignment() [1/2]

◆ performAlignment() [2/2]

◆ optimizeOverlap() [1/2]

◆ optimizeOverlap() [2/2]

◆ greedyOptimization() [1/2]

◆ greedyOptimization() [2/2]

◆ setMaxNumOptimizationIterations()

◆ getMaxNumOptimizationIterations()

◆ setOptimizationStopGradient()

◆ getOptimizationStopGradient()

◆ setupReference()

◆ setupAligned()

◆ setReference()

◆ getReference()

◆ calcSelfOverlap()

◆ calcColorSelfOverlap()

◆ calcColorOverlaps() [1/2]

◆ calcColorOverlaps() [2/2]

◆ align()

◆ getNumResults()

◆ getResult()

◆ getResultsBegin()

◆ getResultsEnd()

◆ begin()

◆ end()

Member Data Documentation

◆ DEF_OPTIMIZATION_STOP_GRADIENT

◆ DEF_MAX_OPTIMIZATION_ITERATIONS