#include <ImFusion/Reg/DemonsImageRegistration.h>

Registers two images with the Demons algorithm The algorithm modifies the GlDenseDeformation object attached to the moving image A number of variants of the standard demons algorithm (diffeomorphic vs additive, various gradient modes) are supported (cf. More...

Inheritance diagram for DemonsImageRegistration:

Detailed Description

Registers two images with the Demons algorithm The algorithm modifies the GlDenseDeformation object attached to the moving image A number of variants of the standard demons algorithm (diffeomorphic vs additive, various gradient modes) are supported (cf.

T. Vercauteren et al, " Diffeomorphic demons: efficient non-parametric image registration", Neuroimage (2009)).

Masking:

If m_constrainDeformationByFixedImageMask is true:
- If a mask is defined on fixed m_image1, it will be converted to an explicit mask and applied to the deformation field. This ensures that the moving m_image2 retains its original values wherever the mask is active.
- If a mask is defined on the moving image (m_image2), this mask is only used during the demons force calculation.
- During force calculation, the force at a pixel is set to zero if either the moving or fixed image is masked at that pixel.
- In case of using an image set with multiple images as fixed (or moving), all images must have the same mask (respectively).
If m_constrainDeformationByFixedImageMask is false:
- Masks on fixed m_image1 and moving m_image2 are only used to constrain the forces calculated by computeDemonsForces to non-masked locations.
- Masks are not considered during vector field flow (diffeomorphic demons) or pyramid upsampling.

Public Types
enum class	Adjustment { DIFFEOMORPHIC = 0 , ADDITIVE = 1 , AFFINE = 2 }
	How to do the update step.

enum class	GradientType { REFERENCE = 0 , MOVING = 1 , SYMMETRIC = 2 }
	The Demons image algorithm requires the approximation of a gradient. More...

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

Public Member Functions
	DemonsImageRegistration (SharedImageSet image1, SharedImageSet image2, bool alreadySplitChannels=false)
	Constructor.

void	initializeTransformationModel () override

void	compute () override
	Execute the algorithm.

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

void	setFixedWeight (SharedImage *weight)
	Set a fixed weight image. This image is used across all channels if multiple channels are present. This is used in the smoothing of the forces to prioritize forces coming from the weighted area.

void	setImage2 (SharedImageSet *img) override

std::shared_ptr< GlDenseDeformation >	deformation () const
	Returns the deformation object that is currently modified This is a convenience method that casts moving to a SharedImageSet, retrieves its deformation and cast that to a GlDenseDeformation.

void	reset () override
	Calls `setIdentity()` on the deformation of the moving image.

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

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

void	setConstrainDeformationByFixedImageMask (bool doConstrain)
	If set, the deformation field will be computed only for the region specified by the mask of the fixed image.

void	configure (const Properties *p) override
	Configurable interface.

void	configuration (Properties *p) const override
	Serialize the current object configuration into the given Properties object.

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

virtual PreProcessingFilter	requiredPreprocessingFilter () const
	Returns which pre-processing is required for the current registration settings.

virtual SharedImageSet *	image1 () const

virtual SharedImageSet *	image2 () const

virtual void	setImage1 (SharedImageSet *img)

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

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

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

Static Public Member Functions
static bool	createCompatible (const DataList &data, Algorithm **a=0)
	Expects two Volumes/Images.

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
Parameter< int >	p_minLevel

Parameter< int >	p_maxLevel = {"maxLevel", 0, this}
	Highest level of the resolution pyramid. Is initialized in the constructor.

Parameter< int >	p_halfKernelSize = {"halfKernelSize", 2, this}
	Half kernel size for force smoothing.

Parameter< double >	p_alpha = {"alpha", 2.0, this}
	The weighting of the difference squared term in denominator of demons algorithm.

Parameter< Adjustment >	p_adjustment = {"adjustment", Adjustment::DIFFEOMORPHIC, this}

Parameter< GradientType >	p_gradientType = {"gradientType", GradientType::SYMMETRIC, this}

Parameter< int >	p_maxIterations = {"maxIterations", 100, this}
	Maximum number of iterations per level.

Parameter< bool >	p_restrictToInputs
	If true, gradient estimate is set to zero outside the input images.

Parameter< double >	p_damping = {"damping", 1.0, this}
	Scaling of update step.

Parameter< double >	p_tolAbs
	Stop iterating once the similarity measure difference per iteration reaches this threshold.

Parameter< bool >	p_verbose = {"verbose", true, this}
	Print info messages.

Parameter< bool >	p_noSmoothingFinalStep = {"noSmoothingFinalStep", false, this}
	If true, do not smooth after the final iteration.

Parameter< int >	p_affineSkip = {"affineSkip", 1, this}
	Number of iterations to skip between affine smoothing for Adjustment::AFFINE.

Parameter< std::vector< double > >	p_channelWeights
	Weights for each channel. Forces are scaled by this amount (normalized by the total weight) in the update step. Only relevant for the multi-channel case.

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.

Protected Member Functions
virtual void	runRegistration (SharedImage imageRef, SharedImage imageMoving, Progress *progress, bool isLastLevel)
	Execute a single resolution pyramid level of the image registration.

void	runMultiChannelRegistration (std::vector< SharedImage * > imageRef, std::vector< SharedImage * > imageMoving, Progress *progress, bool isLastLevel)

bool	createProgram ()

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
GL::ImageProgram *	m_progDemons = nullptr
	Shader program for demons force update.

bool	m_exportDeformationFields = false

bool	m_logData = false
	Whether to write intermediate values to DataLogger.

VectorFieldFlowAlgorithm	m_vff
	Adjustment used for updating displacement field, cf. the Diffeomorphic Demons paper.

double	m_bestSimilarity = std::numeric_limits<double>::quiet_NaN()

SharedImage *	m_fixedWeight = nullptr
	Best similarity value obtained after registration.

double	m_minWeight = 0.01

bool	m_alreadySplitChannels = false

bool	m_constrainDeformationByFixedImageMask = true
	Mask of fixed image will be applied to deformation field as explicit mask.

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.

Member Enumeration Documentation

◆ GradientType

enum class GradientType

strong

The Demons image algorithm requires the approximation of a gradient.

We support a number of options here. cf. T. Vercauteren et al, " Diffeomorphic demons: efficient non-parametric image registration", Neuroimage (2009)

Enumerator
REFERENCE	Use the gradient of the (fixed) reference image. Efficient, as can be computed once per image level.
MOVING	Use finite difference gradient of the moving image, including the deformation. Must be computed per iteration.
SYMMETRIC	Symmetric combination of the above options.

Constructor & Destructor Documentation

◆ DemonsImageRegistration()

DemonsImageRegistration	(	SharedImageSet *	image1,
		SharedImageSet *	image2,
		bool	alreadySplitChannels = false )

Constructor.

If alreadySplitChannels is true, the input images are assumed to be already split into channels. Otherwise the focus image is used for registration, and (in the multi-channel case) the image is split into single channel images internally for registration.

Member Function Documentation

◆ initializeTransformationModel()

void initializeTransformationModel ( )

overridevirtual

Implements AbstractImageRegistration.

◆ compute()

void compute ( )

overridevirtual

Execute the algorithm.

Implements Algorithm.

◆ reference()

SharedImageSet * reference ( ) const

overridevirtual

Returns the image that will be iterated during the registration.

Implements AbstractImageRegistration.

◆ setImage2()

void setImage2 ( SharedImageSet * img )

overridevirtual

Reimplemented from AbstractImageRegistration.

◆ deformation()

std::shared_ptr< GlDenseDeformation > deformation ( ) const

Returns the deformation object that is currently modified This is a convenience method that casts moving to a SharedImageSet, retrieves its deformation and cast that to a GlDenseDeformation.

Returns nullptr, if any of the casts fail.

◆ reset()

void reset ( )

overridevirtual

Calls setIdentity() on the deformation of the moving image.

Implements AbstractImageRegistration.

◆ isDeformable()

bool isDeformable ( ) const

overridevirtual

Returns if the registration is non-linear or not.

Implements AbstractImageRegistration.

◆ bestSimilarityValue()

virtual double bestSimilarityValue ( ) const

inlineoverridevirtual

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

Implements AbstractImageRegistration.

◆ configure()

void configure ( const Properties * p )

overridevirtual

Configurable interface.

Reimplemented from AbstractImageRegistration.

◆ configuration()

void configuration ( Properties * p ) const

overridevirtual

Serialize the current object configuration into the given Properties object.

The default implementation will do so automatically for all registered Parameter and SubProperty instances.

See also: configure() for the inverse functionality

Reimplemented from AbstractImageRegistration.

Member Data Documentation

◆ p_minLevel

Parameter<int> p_minLevel

Initial value:

= {"minLevel",
                                     1,
                                     this}

◆ p_restrictToInputs

Parameter<bool> p_restrictToInputs

Initial value:

= {"restrictToInputs",
                                              true,
                                              this}

If true, gradient estimate is set to zero outside the input images.

◆ p_tolAbs

Parameter<double> p_tolAbs

Initial value:

= {"tolAbs",
                                      1e-6,
                                      this}

Stop iterating once the similarity measure difference per iteration reaches this threshold.

◆ p_channelWeights

Parameter<std::vector<double> > p_channelWeights

Initial value:

= {
            "channelWeights",
            std::vector<double>{},
            this}

Weights for each channel. Forces are scaled by this amount (normalized by the total weight) in the update step. Only relevant for the multi-channel case.

◆ m_vff

VectorFieldFlowAlgorithm m_vff

protected

Adjustment used for updating displacement field, cf. the Diffeomorphic Demons paper.

Helper object used for computing flows of vector fields.

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

ImFusion/Reg/DemonsImageRegistration.h

Detailed Description

Public Types

Public Member Functions

Static Public Member Functions

Public Attributes

Protected Member Functions

Protected Attributes

Member Enumeration Documentation

◆ GradientType

Constructor & Destructor Documentation

◆ DemonsImageRegistration()

Member Function Documentation

◆ initializeTransformationModel()

◆ compute()

◆ reference()

◆ setImage2()

◆ deformation()

◆ reset()

◆ isDeformable()

◆ bestSimilarityValue()

◆ configure()

◆ configuration()

Member Data Documentation

◆ p_minLevel

◆ p_restrictToInputs

◆ p_tolAbs

◆ p_channelWeights

◆ m_vff