#include <RegistrationEnergy.h>

Inheritance diagram for mirtk::RegistrationEnergy:

Collaboration diagram for mirtk::RegistrationEnergy:

Public Types
typedef FastDelegate1< bool >	PreUpdateFunctionType
	Type of pre-update function delegate.

Public Member Functions
void	Add (EnergyTerm *)
	Add energy term and take over ownership of the object.

virtual void	AddConstraintGradient (double dx, double step=.0, bool sgn_chg=nullptr)

void	Clear ()
	Delete previously added energy terms.

virtual void	DataFidelityGradient (double dx, double step=.0, bool sgn_chg=nullptr)

bool	Empty () const
	Whether energy function has no terms.

virtual double	Evaluate (double dx=NULL, double step=.0, bool sgn_chg=NULL)

virtual void	Get (double *x) const

virtual double	Get (int) const

void	Gradient (double dx, double step=.0, bool sgn_chg=nullptr)

double	GradientNorm (const double *) const

void	GradientStep (const double *dx, double &min, double &max) const

virtual void	Initialize ()
	Initialize energy terms once input and parameters have been set.

double	InitialValue ()
	Query/evaluate initial value of registration energy.

double	InitialValue (int)
	Get initial value of n-th energy term.

bool	IsActive (int) const
	Whether the n-th energy term has non-zero weight.

bool	IsConstraint (int) const
	Whether the n-th energy term is a penalty term.

bool	IsDataTerm (int) const
	Whether the n-th energy term is a data term.

bool	IsSparsityConstraint (int) const
	Whether the n-th energy term is a sparsity term.

void	NormalizeGradient (double *dx)

int	NumberOfActiveTerms () const
	Number of energy terms with non-zero weight.

int	NumberOfConstraints () const
	Number of penalty terms, i.e., with base type TransformationConstraint.

int	NumberOfDataTerms () const
	Number of data terms, i.e., with base type DataFidelity.

virtual int	NumberOfDOFs () const

int	NumberOfTerms () const
	Number of energy terms.

virtual ParameterList	Parameter () const
	Get parameter as key/value as string map.

virtual void	Put (const double *x)

double	RawValue (int)

	RegistrationEnergy ()
	Constructor.

virtual bool	Set (const char , const char )
	Set parameter value from string.

virtual double	Step (double *dx)

void	Sub (EnergyTerm *)
	Remove energy term and revoke ownership of the object.

EnergyTerm *	Term (int)
	Get the n-th energy term.

virtual void	Update (bool=true)
	Update internal state after change of parameters.

virtual bool	Upgrade ()

double	Value ()
	Evaluate registration energy.

double	Value (int)
	Get value of n-th energy term computed upon last evaluation.

virtual void	WriteDataSets (const char , const char , bool=true) const
	Write input of data fidelity terms.

virtual void	WriteGradient (const char , const char ) const
	Write gradient of data fidelity terms w.r.t each transformed input.

virtual	~RegistrationEnergy ()
	Destructor.

Public Member Functions inherited from mirtk::ObjectiveFunction
virtual	~ObjectiveFunction ()=0
	Destructor.

Public Member Functions inherited from mirtk::Observable
void	AddObserver (Observer &)
	Add observer.

void	Broadcast (Event, const void *=NULL)
	Broadcast event to observers.

void	ClearObservers ()
	Delete all observers.

void	DeleteObserver (Observer &)
	Delete observer.

void	NotifyObservers (Event, const void *=NULL)
	Notify all observers about given event if this object has changed.

int	NumberOfObservers () const
	Number of current observers.

virtual	~Observable ()
	Destructor.

Public Member Functions inherited from mirtk::Object
virtual const char *	NameOfClass () const =0
	Get name of class, which this object is an instance of.

bool	Parameter (const ParameterList &)
	Set parameters from name/value pairs.

virtual	~Object ()
	Destructor.

Additional Inherited Members
Static Public Member Functions inherited from mirtk::Object
static const char *	NameOfType ()
	Get name of this class type.

Protected Member Functions inherited from mirtk::ObjectiveFunction
	mirtkAttributeMacro (double, StepLength)
	Default step length used for gradient approximation.

Protected Member Functions inherited from mirtk::Observable
	Observable ()
	Default constructor.

	Observable (const Observable &)
	Copy constructor.

Observable &	operator= (const Observable &)
	Assignment operator.

Protected Member Functions inherited from mirtk::Object
template<typename... Args>
void	Throw (ErrorType err, const char *func, Args... args) const

Static Protected Member Functions inherited from mirtk::Object
template<typename... Args>
static void	ThrowStatic (ErrorType err, const char cls, const char func, Args... args)

Detailed Description

Registration energy term which sums up the individual composite terms

Definition at line 38 of file RegistrationEnergy.h.

Member Function Documentation

§ AddConstraintGradient()

virtual void mirtk::RegistrationEnergy::AddConstraintGradient	(	double *	dx,
		double	step = `.0`,
		bool *	sgn_chg = `nullptr`
	)

virtual

Add model constraint gradient of objective function w.r.t its DoFs

Parameters

[in]	step	Step length for finite differences.
[out]	dx	Gradient of objective function, e.g., either initialised to zero or the data fidelity gradient computed beforehand using DataFidelityGradient.
[out]	sgn_chg	Whether function parameter value is allowed to change sign when stepping along the computed gradient.

Reimplemented from mirtk::ObjectiveFunction.

§ DataFidelityGradient()

virtual void mirtk::RegistrationEnergy::DataFidelityGradient	(	double *	dx,
		double	step = `.0`,
		bool *	sgn_chg = `nullptr`
	)

virtual

Evaluate data fidelity gradient of objective function w.r.t its DoFs

Parameters

[in]	step	Step length for finite differences.
[out]	dx	Data fidelity gradient of objective function.
[out]	sgn_chg	Whether function parameter value is allowed to change sign when stepping along the computed gradient.

Reimplemented from mirtk::ObjectiveFunction.

§ Evaluate()

virtual double mirtk::RegistrationEnergy::Evaluate	(	double *	dx = `NULL`,
		double	step = `.0`,
		bool *	sgn_chg = `NULL`
	)

virtual

Evaluate registration energy

This function first updates the internal state of the function object if required due to a previous change of the function parameters and then evaluates the current registration energy.

Parameters

[in]	step	Step length for finite differences.
[out]	dx	Gradient of objective function. If `NULL`, only the function value is computed.
[out]	sgn_chg	Whether function parameter value is allowed to change sign when stepping along the computed gradient. Ignord if `dx` is `NULL`.

Reimplemented from mirtk::ObjectiveFunction.

§ Get() [1/2]

virtual void mirtk::RegistrationEnergy::Get ( double * x ) const

virtual

Get transformation parameters

This function can be used to store a backup of the current transformation parameters before an update such that these can be restored using the Put member function if the update did not result in the desired change of the overall registration energy.

Parameters

[in] x Current values of transformation parameters (DoFs).

Implements mirtk::ObjectiveFunction.

§ Get() [2/2]

virtual double mirtk::RegistrationEnergy::Get ( int ) const

virtual

Get function parameter value

Returns: Value of specified function parameter (DoF).

Implements mirtk::ObjectiveFunction.

§ Gradient()

void mirtk::RegistrationEnergy::Gradient	(	double *	dx,
		double	step = `.0`,
		bool *	sgn_chg = `nullptr`
	)

virtual

Evaluate gradient of registration energy

Note that this gradient need not necessarily correspond to the analytic gradient of the energy function. It can also be a desired change of each function parameter computed otherwise such as through a local patch match. The only requirement is that the change will increase the energy function value such that successively walking in the direction of the computed "gradient", a (local) maximum of the registration energy will be be reached.

Parameters

[in]	dx	Gradient of registration energy function.
[in]	step	Step length for finite differences.
[out]	sgn_chg	Whether function parameter value is allowed to change sign when stepping along the computed gradient.

Implements mirtk::ObjectiveFunction.

§ GradientNorm()

double mirtk::RegistrationEnergy::GradientNorm ( const double * ) const

virtual

Compute norm of gradient of registration energy

This norm can, for example, be the maximum absolute parameter change or the maximum control point displacement in case of a FFD transformation model.

Implements mirtk::ObjectiveFunction.

§ GradientStep()

void mirtk::RegistrationEnergy::GradientStep	(	const double *	dx,
		double &	min,
		double &	max
	)		const

virtual

Adjust step length range

Parameters

[in]	dx	Gradient of objective function.
[in,out]	min	Minimum step length.
[in,out]	max	Maximum step length.

Reimplemented from mirtk::ObjectiveFunction.

§ NormalizeGradient()

void mirtk::RegistrationEnergy::NormalizeGradient ( double * dx )

Normalize energy gradient

Zikic, D., Baust, M., Kamen, A., & Navab, N. A General Preconditioning Scheme for Difference Measures in Deformable Registration. In ICCV 2011.

§ NumberOfDOFs()

virtual int mirtk::RegistrationEnergy::NumberOfDOFs ( ) const

virtual

Get number of transformation parameters

Returns: Number of transformation parameters (DoFs).

Implements mirtk::ObjectiveFunction.

§ Put()

virtual void mirtk::RegistrationEnergy::Put ( const double * x )

virtual

Set transformation parameters

This function can be used to restore the transformation parameters after a failed update which did not result in the desired improvement.

Parameters

[in] x Value of transformation parameters (DoFs).

Implements mirtk::ObjectiveFunction.

§ RawValue()

double mirtk::RegistrationEnergy::RawValue ( int )

Get unweighted and unnormalized value of n-th energy term

Remarks: Use for progress reporting only.

§ Step()

virtual double mirtk::RegistrationEnergy::Step ( double * dx )

virtual

Add change (i.e., scaled gradient) to each transformation parameter

This function updates each parameter of the registration energy function given a vector of desired changes, i.e., the computed gradient of the energy function w.r.t. these parameters or a desired change computed otherwise such as through matching patches (in a very loose sense an approximate "gradient") or a discrete assignment (c.f. MRF registration). It moreover triggers an update of the internal state of each energy term which depends on the current transformation. A data similarity term, for example, will update its moving (transformed) input data.

Note: How this change is applied to the transformation parameters depends on the particular underlying transformation model. Often dx is simply added to x, the current transformation parameters. Some transformations may compute a slightly different update from dx, however, such as converting displacements into velocities first.

Parameters

[in] dx Change of each function parameter (DoF) as computed by the Gradient member function and scaled by a chosen step length.

Returns: Maximum change of transformation parameter.

Implements mirtk::ObjectiveFunction.

§ Upgrade()

virtual bool mirtk::RegistrationEnergy::Upgrade ( )

virtual

Update energy function after convergence

For example, fiducial registration error (FRE) terms may update the point correspondences before another gradient-based optimization of the new FRE term.

Returns: Whether the energy function has changed.

Reimplemented from mirtk::ObjectiveFunction.

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

RegistrationEnergy.h

Public Types

Public Member Functions

Additional Inherited Members

Detailed Description

Member Function Documentation

§ AddConstraintGradient()

§ DataFidelityGradient()

§ Evaluate()

§ Get() [1/2]

§ Get() [2/2]

§ Gradient()

§ GradientNorm()

§ GradientStep()

§ NormalizeGradient()

§ NumberOfDOFs()

§ Put()

§ RawValue()

§ Step()

§ Upgrade()