ImFusion::US::SliceToVolumeRegistrationAlgorithm Class Reference

#include <ImFusion/US/SliceToVolumeRegistrationAlgorithm.h>

Intensity-based registration of an ultrasound sweep to a volume. More...

Inheritance diagram for ImFusion::US::SliceToVolumeRegistrationAlgorithm:

Detailed Description

Intensity-based registration of an ultrasound sweep to a volume.

This algorithm registers a tracked ultrasound sweep (composed of 2D slices) with a 3D reference volume (such as CT or MRI) by optimizing the registration parameters to maximize a similarity measure computed by reslicing the tomographic volume using the ultrasound frames.

Key features:

• Fine-grained control over which parameters are optimized (rigid, affine, deformation, etc.).
• Supports both CPU and GPU computation for similarity measures.
• Configurable for advanced workflows, including machine learning-based similarity, probe deformation, gating, and more.
• Accepts optional distance volumes to enable deformation models.
• Provides detailed configuration options for similarity measures, patch sizes, downsampling, and more.

Inputs:

• A 3D reference volume (typically CT or MRI, but can be any volume).
• An UltrasoundSweep.
• (Optional) A distance volume to enable deformation models. See GlUltrasoundSimulation::setDistTex.

The class provides fine-grained control over which parameters are optimized, supports both CPU and GPU computation, and can be configured for advanced workflows (e.g., machine learning-based similarity, probe deformation, gating, etc.).

See also

GlUltrasoundSimulation

Public Types
enum class	OptimizationMode { OnlyRigidRegistration = 1 , OnlyMotion = 32 , All = 127 }
	Mode defining which parameters to optimize. More...
Public Types inherited from ImFusion::Algorithm
enum	Status {   Unknown = -1 , Success = 0 , Error = 1 , InvalidInput ,   IncompleteInput , OutOfMemoryHost , OutOfMemoryGPU , UnsupportedGPU ,   UnknownAction , AbortedByUser , User = 1000 }
	Status codes. More...

Public Member Functions
	SliceToVolumeRegistrationAlgorithm (SharedImageSet *vol, UltrasoundSweep *sweep, SharedImageSet *distVol=nullptr)
double	evaluate (int n, const double *x, double *dx=0) override
	Cost function evaluation.
std::shared_ptr< Optimizer >	createDefaultOptimizer () const override
	Creates and configures the BOBYQA optimizer.
void	compute () override
	Execute the registration.
SharedImage *	resultImage ()
	Image containing per pixel similarity.
void	setSimilarityMeasure (int val)
	Set the similarity measure type. See SimilarityMeasureFactory::Mode for options. By default, it is set to LC2.
int	similarityMeasure () const
	Get the current similarity measure type. See SimilarityMeasureFactory::Mode for options.
void	setSimGPU (bool enable)
	Enable or disable GPU-based similarity computation.
bool	simGPU () const
	Whether GPU-based similarity computation is enabled.
void	setLC2PatchSize (int val)
	Set the patch size for LC2 similarity.
int	LC2PatchSize () const
	Patch size for LC2 similarity.
void	setDownsampling (int val)
	Set the downsampling factor.
int	downsampling () const
	Get the downsampling factor.
void	setLC2DebugOut (bool enable)
	Enable or disable LC2 debug output.
bool	LC2DebugOut () const
	Whether LC2 debug output is enabled.
void	setSingleFrame (bool enable)
	Enable or disable single frame mode.
bool	singleFrame () const
	Whether the algorithm is in single frame mode.
void	setAttenuation (int val)
	Set the attenuation parameter. Range is typically 0 to 100.
int	attenuation () const
	Get the attenuation parameter.
void	setGain (int val)
	Set the gain parameter. Range is typically 0 to 100.
int	gain () const
	Get the gain parameter.
void	setDeformation (int val)
	Set the deformation parameter. Range is typically 0 to 100.
int	deformation () const
	Get the deformation parameter. Range is typically 0 to 100.
void	setCompression (int val)
	Set the compression parameter. Range is typically 0 to 100.
int	compression () const
	Get the compression parameter.
void	setMLModelFilePath (const std::string &path)
	Set the file path for the machine learning model.
std::string	mLModelFilePath () const
	Get the file path for the machine learning model.
void	setMaxFrames (int val)
	Set the maximum number of frames that are considered the similarity measure computation.
int	maxFrames () const
	Get the maximum number of frames that are considered the similarity measure computation.
void	setDeformable (bool enable)
	Enable or disable deformable registration. If enabled and the volumes and the sweep don't have a deformation, it will add GlProbeDeformation to the volume.
bool	isDeformable () const
	Return whether the registration is deformable.
void	setMoveVolume (bool flag)
	Set whether to move the volume instead of the sweep.
void	setErrorFunction (ErrorFunction *ef)
	Set an optional error function from outside that is also used to penalize the similarity.
void	setSimulationMode (bool flag)
	Enable or disable simulation mode.
void	setOptimizationMode (OptimizationMode mode)
	Set the optimization mode.
OptimizationMode	optimizationMode () const
	Get the current optimization mode.
void	evaluate ()
	Single computation of the similarity measure at current pose.
double	lastResult () const
	Return the result of the last cost function evaluation.
GlUltrasoundSimulation *	simulation ()
	Direct access to the inner simulation instance for providing details to the GUI.
void	printSpacing () const
	Print the effective slice spacing based on the current skip.
UltrasoundSweep *	sweep ()
	Access to the ultrasound sweep.
bool	volMatChanged () const
	Return if the volume matrix has changed since the last computation.
void	configure (const Properties *p) override
	Configures the optimizer from a sub-property if available.
void	configuration (Properties *p) const override
	Stores the optimizer configuration into a sub-property.
ParametricDeformation *	defInstance () const
	Return pointer to the currently active deformation if available.
Public Member Functions inherited from ImFusion::OptimizingAlgorithm
void	setOptimizer (std::shared_ptr< Optimizer > opt)
	Set an optimizer from outside.
std::shared_ptr< Optimizer >	optimizer ()
	Returns the current optimizer.
Public Member Functions inherited from ImFusion::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 ImFusion::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
Public Member Functions inherited from ImFusion::US::SweepOptimization
	SweepOptimization (UltrasoundSweep *us)
	Constructor, stores the current sweep setting as reference state.
void	defineReferenceState ()
	Define the current sweep settings as reference for relative optimization.
void	setOptRelativeToProbeTip (bool flag)
	Set whether to optimize the calibration and the size w.r.t. the tip of the probe instead of the image center.
bool	optRelativeToProbeTip () const
	Returns whether to optimize the calibration and the size w.r.t. the tip of the probe instead of the image center.
void	setUseReferenceCoordinateSystem (bool flag)
	Specify if the sweep's reference coordinate system shall be used.
void	setMovingVolume (SharedImageSet *vol)
	Set pointer to a volume to be used instead of the ultrasound sweep to apply the registration to.
void	setMotion (SweepMotion *sm)
	Set pointer to a sweep trajectory motion instance to also optimize.
SweepMotion *	motion () const
	Return pointer to sweep trajectory motion instance.
double	motionPenalty () const
	Computes a penalty to be used within sweep optimization taking into account geometry constraints.
bool	applyRegistrationPars (const double *sixParsRigid, const double *sixParsAffine=nullptr)
	Applies relative registration parameters to the ultrasound sweep or moving volume.
bool	applyCalibrationPars (const double *sixPars)
	Applies relative calibration parameters to the ultrasound sweep.
bool	applyTemporalOffsetPar (const double *onePar, double scaleFactor=0.1)
	Applies a relative temporal offset parameter to the ultrasound sweep.
bool	applyImageSizePars (const double *twoPars, double scaleFactor=1.)
	Applies relative image size parameters to the ultrasound sweep.
bool	applyMotionPars (int nPars, const double *pars)
	Applies motion parameters to the ultrasound sweep.
bool	applyDeformationPars (int nPars, const double *pars)
	Applies deformation parameters to the ultrasound sweep.
UltrasoundSweep *	sweep ()
	Returns the ultrasound sweep.

Static Public Member Functions
static bool	createCompatible (const DataList &data, Algorithm **a=0)
Static Public Member Functions inherited from ImFusion::Algorithm
static bool	createCompatible (const DataList &data, Algorithm **a=nullptr)
	Factory function to check algorithm compatibility with input data and optionally instantiate it.
Static Public Member Functions inherited from ImFusion::US::SweepOptimization
static void	restorePositionOfProbeTipAfterSizeChange (UltrasoundSweep *sweep, vec2 prevSize)
	After the image size of sweep has been changed, this function can be used to adjust its calibration matrix, so that the tip of the probe is at the same position in the world coordinate system as before the size change (assuming that the image size before the size change was prevSize).

Protected Member Functions
double	penalty () const
	Compute multiplicative penalty based on if the sweep is outside the volume.
void	updateDeformation ()
	Update the deformation on the volume.
Protected Member Functions inherited from ImFusion::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
double	m_lastVal
ErrorFunction *	m_errorFunc
	Optional error function also used to penalize similarity.
mat4	m_lastVolMat
	Volume matrix during last compute.
vec3	m_initVolSpacing
	Original volume scaling used when optimizing.
double	m_initGatingPhaseOffset = 0
	Original gating offset, used when optimizing.
OptimizationMode	m_optimizationMode = OptimizationMode::All
	Defines which parameters to optimize.
Protected Attributes inherited from ImFusion::OptimizingAlgorithm
std::shared_ptr< Optimizer >	m_opt
	The optimizer instance.
Protected Attributes inherited from ImFusion::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 ImFusion::Configurable
std::vector< Param >	m_params
	List of all registered Parameter and SubProperty instances.
Protected Attributes inherited from ImFusion::US::SweepOptimization
UltrasoundSweep *	m_us
	Pointer to the ultrasound sweep.
SharedImageSet *	m_movingVol = nullptr
	Pointer to the moving volume to be used instead of the sweep to apply the registration to.
mat4	m_initReg
	Initial registration at start of optimization.
mat4	m_initCal
	Initial calibration at start of optimization.
double	m_initTemporal
	Initial temporal calibration.
vec2	m_initSize
	Initial size of the ultrasound frames.
std::vector< double >	m_initMot
	Initial motion parameters if applicable.
std::vector< double >	m_initDef
	Initial deformation parameters if applicable.
mat4	m_refMat
	Reference coordinate system for registration.
bool	m_useRefCoord = false
	Use reference coordinate system, if available.
SweepMotion *	m_motion = nullptr
	Optional instance for sweep trajectory motion.
bool	m_optRelativeToProbeTip = false
	Whether to optimize the calibration and the size w.r.t the tip of the probe instead of the image center.

Additional Inherited Members
Public Attributes inherited from ImFusion::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 ImFusion::Configurable
Signal	signalParametersChanged
	Emitted whenever one of the registered Parameters' or SubPropertys' signalValueChanged signal was emitted.

Member Enumeration Documentation

OptimizationMode

enum class ImFusion::US::SliceToVolumeRegistrationAlgorithm::OptimizationMode

strong

Mode defining which parameters to optimize.

Integer values result from converting the following sequence of bits to decimal: Deformation Motion ImageSize TemporalOffset Calibration AffineRegistration RigidRegistration 64 32 16 8 4 2 1

Enumerator
OnlyRigidRegistration	Optimize only rigid registration parameters.
OnlyMotion	Optimize only motion parameters.
All	Optimize all supported parameters.

Member Function Documentation

evaluate()

double ImFusion::US::SliceToVolumeRegistrationAlgorithm::evaluate ( int n, const double * x, double * dx = 0 )

overridevirtual

Cost function evaluation.

Implements ImFusion::CostFunction.

createDefaultOptimizer()

std::shared_ptr< Optimizer > ImFusion::US::SliceToVolumeRegistrationAlgorithm::createDefaultOptimizer ( ) const

overridevirtual

Creates and configures the BOBYQA optimizer.

Implements ImFusion::OptimizingAlgorithm.

compute()

void ImFusion::US::SliceToVolumeRegistrationAlgorithm::compute ( )

overridevirtual

Execute the registration.

Implements ImFusion::Algorithm.

setErrorFunction()

void ImFusion::US::SliceToVolumeRegistrationAlgorithm::setErrorFunction ( ErrorFunction * ef )

inline

Set an optional error function from outside that is also used to penalize the similarity.

If the penalty evaluates to zero or lower, the similarity is not computed at all.

configure()

void ImFusion::US::SliceToVolumeRegistrationAlgorithm::configure ( const Properties * p )

overridevirtual

Configures the optimizer from a sub-property if available.

Reimplemented from ImFusion::OptimizingAlgorithm.

configuration()

void ImFusion::US::SliceToVolumeRegistrationAlgorithm::configuration ( Properties * p ) const

overridevirtual

Stores the optimizer configuration into a sub-property.

Reimplemented from ImFusion::OptimizingAlgorithm.

---

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

• ImFusion/US/SliceToVolumeRegistrationAlgorithm.h