ImFusion SDK 4.3
ParametricImageRegistration Class Referenceabstract

#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< Optimizeroptimizer ()
 
virtual bool setReference (SharedImageSet *img)
 Specifies which of the two images will be used as a reference in the similarity measure.
 
SharedImageSetreference () const override
 Returns the image that will be iterated during the registration.
 
virtual SimilarityMeasureFactorysimilarityMeasureFactory ()
 Returns the factory that creates the SimilarityMeasureImpl instance during the registration.
 
virtual const SimilarityMeasureFactorysimilarityMeasureFactory () 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 SharedImageSetimage1 () const
 
virtual SharedImageSetimage2 () 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().
 
Progressprogress () 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 FactoryInfofactoryInfo () 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
 
Configurableoperator= (const Configurable &)
 
Configurableoperator= (Configurable &&) noexcept
 

Protected Member Functions

std::shared_ptr< OptimizercreateDefaultOptimizer (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< Optimizerm_opt
 NOTE: A default optimizer will be created by configure if no instance is already set.
 
SimilarityMeasureFactory m_smFactory
 
SimilarityMeasureImplm_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 SharedImagem_weights1
 
const SharedImagem_weights2
 
SharedImagem_resampled
 the moving image with pre-applied transformation, only set during compute and if m_preApplyTransformation is true
 
ImageTransformerm_transformer
 capsulates the transformation, only set during compute
 
PointCorrm_pointCorr
 Point correspondences instance if available.
 
ErrorFunctionm_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
SharedImageSetm_image1
 First image of the registration.
 
SharedImageSetm_image2
 Second image of the registration.
 
PointCorrAlgorithmm_pcAlg
 Optional point correspondences for evaluation.
 
- Protected Attributes inherited from Algorithm
std::string m_name
 Algorithm name.
 
Progressm_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< Actionm_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< Paramm_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
}
}
SharedImageSet * m_image2
Second image of the registration.
Definition AbstractImageRegistration.h:62
SimilarityMeasureImpl * m_sm
Actual similarity measure instance, only set during compute.
Definition ParametricImageRegistration.h:192
ImageTransformer * m_transformer
capsulates the transformation, only set during compute
Definition ParametricImageRegistration.h:202
double evaluate(int n, const double *x, double *dx=0) override=0
Assembles the parameters and returns similarity of images.
mat4 eulerToMat(const vec3 &trans, const vec3 &rot)
Convert a translation and Euler angles to a homogeneous transformation matrix. Angles are in degrees.

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:
Search Tab / S to search, Esc to close