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

Inheritance diagram for CDPL.Shape.GaussianShapeFunctionAlignment:

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

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

None	__init__ (GaussianShapeFunction ref_func, int sym_class)
	Constructs the `GaussianShapeFunctionAlignment` instance with the given reference shape function. More...

int	getObjectID ()
	Returns the numeric identifier (ID) of the wrapped C++ class instance. More...

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

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

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

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

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

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

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

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

None	setColorMatchFunction (Pharm.BoolSizeType2Functor func)
	Specifies the function used to decide whether two color features match. More...

Pharm.BoolSizeType2Functor	getColorMatchFunction ()
	Returns the currently configured color-match function. More...

None	setColorFilterFunction (BoolSizeTypeFunctor func)
	Specifies the function used to filter color features by type. More...

BoolSizeTypeFunctor	getColorFilterFunction ()
	Returns the currently configured color-filter function. More...

None	performAlignment (bool perf_align)
	Specifies whether the actual alignment shall be performed (vs. More...

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

None	setMaxNumOptimizationIterations (int max_iter)
	Sets the maximum number of overlap-optimization iterations. More...

int	getMaxNumOptimizationIterations ()
	Returns the currently configured maximum number of overlap-optimization iterations. More...

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Result	getResult (int idx)
	Returns the alignment result at index idx. More...

int	__len__ ()

Result	__getitem__ (int idx)

Static Public Attributes
float	DEF_OPTIMIZATION_STOP_GRADIENT = 1.0
	Default gradient norm at which the overlap optimization is stopped.

int	DEF_MAX_OPTIMIZATION_ITERATIONS = 20
	Default maximum number of overlap-optimization iterations.

Properties
	objectID = property(getObjectID)

	numResults = property(getNumResults)

	overlapFunction = property(getOverlapFunction, setOverlapFunction)

	defaultOverlapFunction = property(getDefaultOverlapFunction)

	reference = property(getReference, setReference)

	startGenerator = property(getStartGenerator, setStartGenerator)

	defaultStartGenerator = property(getDefaultStartGenerator)

	colorMatchFunction = property(getColorMatchFunction, setColorMatchFunction)

	colorFilterFunction = property(getColorFilterFunction, setColorFilterFunction)

	perfAlignment = property(performAlignment, performAlignment)

	maxNumOptIterations = property(getMaxNumOptimizationIterations, setMaxNumOptimizationIterations)

	optStopGradient = property(getOptimizationStopGradient, setOptimizationStopGradient)

	optOverlap = property(optimizeOverlap, optimizeOverlap)

	greedyOpt = property(greedyOptimization, greedyOptimization)

	colorOverlaps = property(calcColorOverlaps, calcColorOverlaps)

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

Constructor & Destructor Documentation

◆ init()

None CDPL.Shape.GaussianShapeFunctionAlignment.__init__	(	GaussianShapeFunction	ref_func,
		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).

Member Function Documentation

◆ getObjectID()

int CDPL.Shape.GaussianShapeFunctionAlignment.getObjectID ( )

Returns the numeric identifier (ID) of the wrapped C++ class instance.

Different Python GaussianShapeFunctionAlignment instances may reference the same underlying C++ class instance. The commonly used Python expression a is not b thus cannot tell reliably whether the two GaussianShapeFunctionAlignment instances a and b reference different C++ objects. The numeric identifier returned by this method allows to correctly implement such an identity test via the simple expression a.getObjectID() != b.getObjectID().

Returns: The numeric ID of the internally referenced C++ class instance.

◆ setOverlapFunction()

None 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 ( )

Returns the currently configured overlap function.

Returns: A reference to the overlap function.

◆ getDefaultOverlapFunction()

FastGaussianShapeOverlapFunction CDPL.Shape.GaussianShapeFunctionAlignment.getDefaultOverlapFunction ( )

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

Returns: A reference to the default overlap function.

◆ setReference()

None CDPL.Shape.GaussianShapeFunctionAlignment.setReference	(	GaussianShapeFunction	func,
		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()

GaussianShapeFunction CDPL.Shape.GaussianShapeFunctionAlignment.getReference ( )

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

Returns: A reference to the reference shape function.

◆ setStartGenerator()

None 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 ( )

Returns the currently configured alignment-start generator.

Returns: A reference to the alignment-start generator.

◆ getDefaultStartGenerator()

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()

None CDPL.Shape.GaussianShapeFunctionAlignment.setColorMatchFunction ( Pharm.BoolSizeType2Functor func )

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

Parameters

func	The color-match function.

◆ getColorMatchFunction()

Pharm.BoolSizeType2Functor CDPL.Shape.GaussianShapeFunctionAlignment.getColorMatchFunction ( )

Returns the currently configured color-match function.

Returns: A reference to the color-match function.

◆ setColorFilterFunction()

None CDPL.Shape.GaussianShapeFunctionAlignment.setColorFilterFunction ( BoolSizeTypeFunctor func )

Specifies the function used to filter color features by type.

Parameters

func	The color-filter function.

◆ getColorFilterFunction()

BoolSizeTypeFunctor CDPL.Shape.GaussianShapeFunctionAlignment.getColorFilterFunction ( )

Returns the currently configured color-filter function.

Returns: A reference to the color-filter function.

◆ performAlignment() [1/2]

None 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 ( )

Tells whether the actual alignment is performed.

Returns: True if the alignment is performed, and False otherwise.

◆ setMaxNumOptimizationIterations()

None CDPL.Shape.GaussianShapeFunctionAlignment.setMaxNumOptimizationIterations ( int max_iter )

Sets the maximum number of overlap-optimization iterations.

Parameters

max_iter The new maximum number of iterations.

◆ getMaxNumOptimizationIterations()

int CDPL.Shape.GaussianShapeFunctionAlignment.getMaxNumOptimizationIterations ( )

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

Returns: The maximum number of iterations.

◆ setOptimizationStopGradient()

None CDPL.Shape.GaussianShapeFunctionAlignment.setOptimizationStopGradient ( float grad_norm )

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

Parameters

grad_norm The new stop gradient norm.

◆ getOptimizationStopGradient()

float CDPL.Shape.GaussianShapeFunctionAlignment.getOptimizationStopGradient ( )

Returns the currently configured overlap-optimization stop gradient.

Returns: The stop gradient norm.

◆ optimizeOverlap() [1/2]

None 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 ( )

Tells whether the overlap is optimized iteratively.

Returns: True if the overlap is optimized, and False otherwise.

◆ greedyOptimization() [1/2]

None 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 ( )

Tells whether the overlap optimization uses a greedy strategy.

Returns: True if the greedy strategy is used, and False otherwise.

◆ setupReference()

int CDPL.Shape.GaussianShapeFunctionAlignment.setupReference	(	GaussianShapeFunction	func,
		Math.Matrix4D	xform
	)

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()

int CDPL.Shape.GaussianShapeFunctionAlignment.setupAligned	(	GaussianShapeFunction	func,
		Math.Matrix4D	xform
	)

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).

◆ calcSelfOverlap()

float CDPL.Shape.GaussianShapeFunctionAlignment.calcSelfOverlap ( 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()

float CDPL.Shape.GaussianShapeFunctionAlignment.calcColorSelfOverlap ( 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]

None 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 ( )

Tells whether color overlaps are evaluated.

Returns: True if color overlaps are evaluated, and False otherwise.

◆ align()

bool CDPL.Shape.GaussianShapeFunctionAlignment.align	(	GaussianShapeFunction	func,
		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()

int CDPL.Shape.GaussianShapeFunctionAlignment.getNumResults ( )

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

Returns: The number of alignment results.

◆ getResult()

Result CDPL.Shape.GaussianShapeFunctionAlignment.getResult ( int idx )

Returns the alignment result at index idx.

Parameters

idx	The zero-based result index.

Returns: A reference to the result.

Exceptions

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

◆ len()

int CDPL.Shape.GaussianShapeFunctionAlignment.__len__ ( )

Returns

◆ getitem()

Result CDPL.Shape.GaussianShapeFunctionAlignment.__getitem__ ( int idx )

Parameters

idx

Returns

Classes

Public Member Functions

Static Public Attributes

Properties

Detailed Description

Constructor & Destructor Documentation

◆ __init__()

Member Function Documentation

◆ getObjectID()

◆ setOverlapFunction()

◆ getOverlapFunction()

◆ getDefaultOverlapFunction()

◆ setReference()

◆ getReference()

◆ setStartGenerator()

◆ getStartGenerator()

◆ getDefaultStartGenerator()

◆ setColorMatchFunction()

◆ getColorMatchFunction()

◆ setColorFilterFunction()

◆ getColorFilterFunction()

◆ performAlignment() [1/2]

◆ performAlignment() [2/2]

◆ setMaxNumOptimizationIterations()

◆ getMaxNumOptimizationIterations()

◆ setOptimizationStopGradient()

◆ getOptimizationStopGradient()

◆ optimizeOverlap() [1/2]

◆ optimizeOverlap() [2/2]

◆ greedyOptimization() [1/2]

◆ greedyOptimization() [2/2]

◆ setupReference()

◆ setupAligned()

◆ calcSelfOverlap()

◆ calcColorSelfOverlap()

◆ calcColorOverlaps() [1/2]

◆ calcColorOverlaps() [2/2]

◆ align()

◆ getNumResults()

◆ getResult()

◆ __len__()

◆ __getitem__()

◆ init()

◆ len()

◆ getitem()