#include <ImFusion/Reg/ParametricImageRegistration.h>

Base class for parametric image registration algorithms. More...

Inheritance diagram for ParametricImageRegistration:

Detailed Description

Base class for parametric image registration algorithms.

This class provides all the basics of a parametric optimization such as a similarity measure and an optimizer. The registration is always performed on two images. Derived classes need to specify the number of parameters to be optimizer and override the evaluate method.

Public Member Functions
	ParametricImageRegistration (SharedImageSet image1, SharedImageSet image2, int numberOfParameters)
	Creates a registration that keeps image1 fixed and moves image2.

void	compute () override
	Starts the registration.

double	evaluate (int n, const double x, double dx=0) override=0
	Assembles the parameters and returns similarity of images.

virtual void	setProgress (Progress *progress) override
	Sets a Progress interface the algorithm can use to notify observers about its computing progress.

virtual int	numberOfParameters () const =0
	Returns the number of parameters representing the transformation.

virtual void	setOptimizer (std::shared_ptr< Optimizer > opt)
	Sets an optimizer.

virtual std::shared_ptr< Optimizer >	optimizer ()

virtual bool	setReference (SharedImageSet *img)
	Specifies which of the two images will be used as a reference in the similarity measure.

SharedImageSet *	reference () const override
	Returns the image that will be iterated during the registration.

virtual SimilarityMeasureFactory &	similarityMeasureFactory ()
	Returns the factory that creates the SimilarityMeasureImpl instance during the registration.

virtual const SimilarityMeasureFactory &	similarityMeasureFactory () const

PreProcessingFilter	requiredPreprocessingFilter () const override
	Returns LC2_GradientMagnitude if the similarity measure is LC2 or None otherwise.

virtual void	setPreApplyTransformation (bool enable)
	If set the transformation will be pre-applied before computing the similarity.

virtual bool	preApplyTransformation () const

void	setSimilarityMeasure (SimilarityMeasureFactory::Mode mode)
	Convenient method to set the similarity measure.

SimilarityMeasureFactory::Mode	similarityMeasure () const

void	setPointCorrespondences (PointCorr *pc)
	Set a point correspondences class instance to use as error function or clear it (ownership not transferred)

void	setReInitialize (bool flag)
	Specify whether similarity measure and transformation shaders shall be re-initialized every time compute is called (on by default)

void	setRelativeToWorld (bool flag)
	Sets whether the relative transformation is applied in world or image coordinates.

bool	isRelativeToWorld () const
	Returns whether the relative transformation is applied in world (true) or image coordinates (false)

bool	isAffine () const
	Returns true if the optimizer uses affine parameters or false otherwise.

void	setAffine (bool affine)

void	setReferenceCoordinateSystem (const mat4 &mat)
	Set a reference coordinate system to use with the linear transformation.

void	setWeights (const SharedImage weights1, const SharedImage weights2)
	Set optional weight images which will be passed on to the similarity measure class.

void	setErrorFunction (ErrorFunction *ef)
	Set an optional error function that is also used to penalize the image similarity during registration.

int	numberOfLinearParameters () const
	Return the number of parameters for the linear transformation model.

double	overlap () const
	Return the last overlap computed by the similarity measure (0..1), i.e. the fraction of used pixels/voxels wrt. the fixed image.

virtual double	bestSimilarityValue () const override
	Returns the best value of the similarity measure after optimization (may return NaN if algorithm is not intialized)

void	configure (const Properties *p) override
	Configures the registration.

void	configuration (Properties *p) const override
	Gets the configuration of the registration.

void	setDefaultOptimizer ()
	Sets the optimizer to the optimizer created by `createDefaultOptimizer`

Public Member Functions inherited from AbstractImageRegistration
	AbstractImageRegistration (SharedImageSet image1, SharedImageSet image2)

virtual void	initializeTransformationModel ()=0

virtual SharedImageSet *	image1 () const

virtual SharedImageSet *	image2 () const

virtual void	setImage1 (SharedImageSet *img)

virtual void	setImage2 (SharedImageSet *img)

virtual void	reset ()=0
	Resets the registration of both images to the initial state.

virtual bool	isDeformable () const =0
	Returns if the registration is non-linear or not.

Public Member Functions inherited from Algorithm
	Algorithm ()
	Default constructor will registers a single "compute" action that calls compute() and returns status().

virtual OwningDataList	takeOutput ()
	Return any new Data that was created by the Algorithm during the last call to compute().

Progress *	progress () const
	Returns the progress interface if set.

virtual int	status () const
	Indicates the status of the last call to compute().

virtual bool	survivesDataDeletion (const Data *) const
	Indicates whether the algorithm can handle (partial) deletion of the specified data, by default this checks whether the data is in the input list.

const FactoryInfo &	factoryInfo () const
	Returns the record describing how this Algorithm was instantiated by the AlgorithmFactory.

void	setFactoryInfo (const FactoryInfo &value)
	Sets the record describing how this Algorithm was instantiated by the AlgorithmFactory.

Status	runAction (const std::string &id)
	Run the action with name `id` if it exists.

const std::vector< Action > &	actions ()
	Get a mapping from Action id to Action as registered in this algorithm.

Public Member Functions inherited from Configurable
virtual void	configureDefaults ()
	Retrieve the properties of this object, replaces values with their defaults and sets it again.

void	registerParameter (ParameterBase *param)
	Register the given Parameter or SubProperty, so that it will be configured during configure()/configuration().

void	unregisterParameter (const ParameterBase *param)
	Remove the given Parameter or SubProperty from the list of registered parameters.

	Configurable (const Configurable &rhs)

	Configurable (Configurable &&rhs) noexcept

Configurable &	operator= (const Configurable &)

Configurable &	operator= (Configurable &&) noexcept

Protected Member Functions
std::shared_ptr< Optimizer >	createDefaultOptimizer (int numParameters) const
	Returns a default optimizer with the given number if parameters.

mat4	updateLinearTransform (int n, const double *x)
	Compute the linear homogenous moving image transformation from optimization parameters.

Protected Member Functions inherited from AbstractImageRegistration
bool	complainAboutDeformationOnFixedImage ()

Protected Member Functions inherited from Algorithm
void	loadDefaults ()

void	registerAction (const std::string &id, const std::string &guiName, const std::function< Algorithm::Status(void)> &action)
	Register an action to be run via runAction.

template<typename D>
void	registerAction (const std::string &id, const std::string &guiName, Algorithm::Status(D::*action)(void))
	Template version of runAction that can be used with a pointer to a member function.

void	registerAction (const Action &action)
	Register an action.

Protected Attributes
std::shared_ptr< Optimizer >	m_opt
	NOTE: A default optimizer will be created by configure if no instance is already set.

SimilarityMeasureFactory	m_smFactory

SimilarityMeasureImpl *	m_sm
	Actual similarity measure instance, only set during compute.

bool	m_smIterate1

bool	m_preApplyTransformation

bool	m_reInit
	Re-initialize transformation and similarity measure every time compute is called.

double	m_overlap

const SharedImage *	m_weights1

const SharedImage *	m_weights2

SharedImage *	m_resampled
	the moving image with pre-applied transformation, only set during compute and if m_preApplyTransformation is true

ImageTransformer *	m_transformer
	capsulates the transformation, only set during compute

PointCorr *	m_pointCorr
	Point correspondences instance if available.

ErrorFunction *	m_errorFunc
	Optional error function also used to penalize similarity.

mat4	m_initMat
	Initial registration matrix for linear transformation model.

mat4	m_resetMat
	Unmodified matrix of the moving image for reseting.

mat4	m_refCoord
	Reference coordinate system to use with linear transformation.

bool	m_relWorld
	Apply relative transformation wrt. world coordinates for linear model.

int	m_affine
	0=rigid, 1=affine, 2=rigid then affine (2 only supported through configurable interface)

Protected Attributes inherited from AbstractImageRegistration
SharedImageSet *	m_image1
	First image of the registration.

SharedImageSet *	m_image2
	Second image of the registration.

PointCorrAlgorithm *	m_pcAlg
	Optional point correspondences for evaluation.

Protected Attributes inherited from Algorithm
std::string	m_name
	Algorithm name.

Progress *	m_progress = nullptr
	Non-owing pointer to a progress interface. May be a nullptr.

FactoryInfo	m_factoryInfo = {}
	Record describing how this algorithm was instantiated by the AlgorithmFactory.

int	m_status = Status::Unknown
	Algorithm status after last call to compute()

std::vector< Action >	m_actions
	Map of key given by the id of the action, of the available actions of this algorithm.

Protected Attributes inherited from Configurable
std::vector< Param >	m_params
	List of all registered Parameter and SubProperty instances.

Additional Inherited Members
Public Types inherited from AbstractImageRegistration
enum	PreProcessingFilter { None , LC2_GradientMagnitude }

Public Types inherited from Algorithm
enum	Status { Unknown = -1 , Success = 0 , Error = 1 , InvalidInput , IncompleteInput , OutOfMemoryHost , OutOfMemoryGPU , UnsupportedGPU , UnknownAction , AbortedByUser , User = 1000 }
	Status codes. More...

Static Public Member Functions inherited from Algorithm
static bool	createCompatible (const DataList &data, Algorithm **a=nullptr)
	Factory function to check algorithm compatibility with input data and optionally instantiate it.

Public Attributes inherited from Algorithm
Signal	signalOutputChanged
	Signal should be emitted by Algorithms when their output/result has changed.

Signal	signalParametersChanged
	Signal should be emitted by Algorithms when their parameter configuration has changed.

Public Attributes inherited from Configurable
Signal	signalParametersChanged
	Emitted whenever one of the registered Parameters' or SubPropertys' `signalValueChanged` signal was emitted.

Constructor & Destructor Documentation

◆ ParametricImageRegistration()

ParametricImageRegistration	(	SharedImageSet *	image1,
		SharedImageSet *	image2,
		int	numberOfParameters )

Creates a registration that keeps image1 fixed and moves image2.

The numberOfParameters is required to create a default optimizer.

Member Function Documentation

◆ compute()

void compute ( )

overridevirtual

Starts the registration.

Returns instantly if no optimizer is set.

Implements Algorithm.

Reimplemented in PolyRigidImageRegistration.

◆ evaluate()

double evaluate	(	int	n,
		const double *	x,
		double *	dx = 0 )

overridepure virtual

Assembles the parameters and returns similarity of images.

This method is mainly called during the optimization by the optimizer. n specifies the number of parameters in the arrays x and dx. x[i] contains the relative change to parameter i. Derived classes overriding this method must be able to apply these parameters to their transformation model. Since the parameters are only relative changes to the initial value, it is sometimes required to store the initial transformation in compute() before the optimization is started. The parameters will be optimized to maximize the return value of this method. If dx is not 0, derived classes can output the derivative of parameter i to each dx[i]. However, derived classes are not required to provide such a value.

Example:

double evaluate(int n, const double* x, out double* dx = 0) {
    if (n != 6)
        return 0.0;
    else {
        mat4 relativeMatrix = Pose::eulerToMat(x);
        m_image2->setMatrix(m_initialMatrix * relativeMatrix); // move image to new location
        return return m_sm->compute(m_transformer); // automatically picks up the new transformation of image2
    }
}

Implements CostFunction.

Implemented in FFDImageRegistration, GatedLinear4DImageRegistration, LinearGridRegistration, LinearImageRegistration, and ParametricDeformableRegistration.

◆ setProgress()

virtual void setProgress ( Progress * progress )

overridevirtual

Sets a Progress interface the algorithm can use to notify observers about its computing progress.

Reimplemented from Algorithm.

◆ numberOfParameters()

virtual int numberOfParameters ( ) const

pure virtual

Returns the number of parameters representing the transformation.

Implemented in GatedLinear4DImageRegistration, LinearGridRegistration, LinearImageRegistration, and ParametricDeformableRegistration.

◆ setReference()

virtual bool setReference ( SharedImageSet * img )

virtual

Specifies which of the two images will be used as a reference in the similarity measure.

The reference has no influence on which image will be moving (this is always image2!) but it specifies which image will be iterated in the similarity measure. The similarity measure is computed by iterating all pixels of the reference image and comparing them to the corresponding pixels in the other image. If the images differ in dimensions, the performance can sometimes be improved by iterating the smaller of both images. The default reference is image1.

◆ reference()

SharedImageSet * reference ( ) const

overridevirtual

Returns the image that will be iterated during the registration.

Implements AbstractImageRegistration.

◆ requiredPreprocessingFilter()

PreProcessingFilter requiredPreprocessingFilter ( ) const

overridevirtual

Returns LC2_GradientMagnitude if the similarity measure is LC2 or None otherwise.

Reimplemented from AbstractImageRegistration.

◆ setPreApplyTransformation()

virtual void setPreApplyTransformation ( bool enable )

virtual

If set the transformation will be pre-applied before computing the similarity.

Pre-applying the transformation creates a new image of the size of image1. image2 is then rendered into this image with the current transformation of each iteration. This avoids any multiple interpolations during the computation of the similarity measure and can lead to higher overall performance in some cases. Derived classes that support this, need to pass to call ImageTransformer::resampleMoving before calling the similarity measure without passing the ImageTransformer.

Example:
\code
double evaluate(int n, const double* x, double* dx = 0) {
    \\ ...
    if(m_resampled) {
        m_transformer->resampleMoving(m_resampled, 0);
        return m_sm->compute(0);
    } else {
        return m_sm->compute(m_transformer);
    }
}
\endcode

◆ bestSimilarityValue()

virtual double bestSimilarityValue ( ) const

overridevirtual

Returns the best value of the similarity measure after optimization (may return NaN if algorithm is not intialized)

Implements AbstractImageRegistration.

◆ configure()

void configure ( const Properties * p )

overridevirtual

Configures the registration.

A sub-property named "Optimizer" can be used to create and initialize an optimizer. If no optimizer is currently set, a default BOBYQA optimizer with a dimension of numberOfParameters. The dimension of an existing optimizer will be adjusted by numberOfParameters. The sub-property "SimilarityMeasure" can be used to set the configuration for the SimilarityMeasure

Reimplemented from AbstractImageRegistration.

Reimplemented in PolyRigidImageRegistration.

◆ configuration()

void configuration ( Properties * p ) const

overridevirtual

Gets the configuration of the registration.

If an optimizer is set, the sub-property "Optimizer" contains its configuration. The sub-property "SimilarityMeasure" contains the properties of the SimilarityMeasure

Reimplemented from AbstractImageRegistration.

Reimplemented in PolyRigidImageRegistration.

Member Data Documentation

◆ m_opt

std::shared_ptr<Optimizer> m_opt

protected

NOTE: A default optimizer will be created by configure if no instance is already set.

Subclasses can adjust the optimizer parameters in the constructor after calling configureDefaults(). Otherwise subclasses should expect that the instance of the optimizer will change frequently because it's re-created by the OptimizerDialog. Optimizer instance

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

ImFusion/Reg/ParametricImageRegistration.h

Detailed Description

Public Member Functions

Protected Member Functions

Protected Attributes

Additional Inherited Members

Constructor & Destructor Documentation

◆ ParametricImageRegistration()

Member Function Documentation

◆ compute()

◆ evaluate()

◆ setProgress()

◆ numberOfParameters()

◆ setReference()

◆ reference()

◆ requiredPreprocessingFilter()

◆ setPreApplyTransformation()

◆ bestSimilarityValue()

◆ configure()

◆ configuration()

Member Data Documentation

◆ m_opt