#include <ImFusion/US/SweepGlobalInitAlgorithm.h>

Algorithm for initializing the 3D pose of an ultrasound sweep relative to a reference volume. More...

Inheritance diagram for ImFusion::US::SweepGlobalInitAlgorithm:

Detailed Description

Algorithm for initializing the 3D pose of an ultrasound sweep relative to a reference volume.

This algorithm estimates the initial rigid transformation between a freehand ultrasound sweep and a reference 3D volume. It is typically used as a global initialization step for subsequent fine registration.

Inputs:

An UltrasoundSweep.
A reference volume.
Optionally, a segmentation volume (label map or distance volume) for anatomical constraints. If the volume has floating point type (Image::Type::FLOAT), it is treated as a distance volume. If it has Data::LABEL modality and Image::Type::UBYTE type, it is treated as a label map. Otherwise it is ignored.

Effects on input data:

Updates the transformation of the ultrasound sweep (if p_usIsMoving is true) or of the volume (if p_usIsMoving is false).

Outputs:

If a labelmap is provided, the first output is the distance volume computed from the labelmap.
If a ProbeDeformationAlgorithm is set, the second output is the output of that algorithm.
If a RegistrationFromPredictionMapAlgorithm is set, the third output of that algorithm.

This algorithm uses a combination of different penalties to guide the initialization:

Landmark correspondence distance or distance of ultrasound landmarks to segmentation
Angle between ultrasound beam axis and patient's anterior-posterior direction
Distance of points on the ultrasound transducer to the patient's skin surface
Angle of the ultrasound transducer with respect to the patient's skin surface.
Residual error of the registration-from-prediction-map algorithm.

The behavior is controlled by a set of parameters and penalty functions, which can be enabled or disabled as needed.

Parameters:

p_usIsMoving : If true, the ultrasound sweep is treated as the moving data; otherwise, the reference volume is moved.
p_useSkinSurface : If enabled, the skin surface is segmented and used as a penalty function.
p_usePredMap : If enabled, uses the registration-from-prediction-maps algorithm for initialization.
p_useKeypoints : If enabled, uses keypoint-based registration for initialization.
p_usePredMapTranslationOnly : If enabled, restricts prediction map registration to translation only.
p_useSliceOrientation : If enabled, uses slice orientation estimation for initialization.

Public Types
enum class	Penalty { Distance = 0 , BeamAngle = 1 , SkinDist = 2 , SkinAngle = 3 , PredMap = 4 }
	Supported penalty functions, which can be combined to guide the initialization. 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
	SweepGlobalInitAlgorithm (UltrasoundSweep &sweep, SharedImageSet &volume, SharedImageSet *segVol=nullptr)
void	setRegistrationAlgorithm (Algorithm *regAlg)
	Set an image-based registration algorithm instance from outside, applying the error/penalty function from here.
void	setPointCorrAlgorithm (SweepPointCorrAlgorithm *pca)
	Set the point correspondences algorithm from outside if available, using its distance penalty.
void	evaluateError (std::vector< double > &out) override
	Implements the ErrorFunction interface.
std::vector< double >	computeErrors ()
	Compute errors for all enabled penalties and return the results.
std::vector< double >	lastErrors () const
	Return the last computed penalty errors.
double	penalize (double cost, const std::vector< double > &error) override
	Compute the penalized cost based on the provided error vector and penalty configuration.
void	compute () override
	Execute the algorithm.
OwningDataList	takeOutput () override
void	configure (const Properties *p) override
	Configure this object instance by de-serializing the given Properties.
void	configuration (Properties *p) const override
	Serialize the current object configuration into the given Properties object.
UltrasoundSweep &	sweep ()
	Access to the ultrasound sweep.
SharedImageSet &	volume ()
	Access to the reference volume.
PointsOnImage *	sweepPoints ()
	Access to the sweep points instance, which exists if a segmentation volume is used.
SweepPointCorrAlgorithm *	pointCorrAlgorithm ()
	Access the point correspondences algorithm instance if available.
bool	isAbdominalFusion () const
	Return true if the data is presumably an abdominal ultrasound fusion with CT or MRI.
void	setProbeDeformationAlgorithm (ProbeDeformationAlgorithm *alg)
	Set the probe deformation algorithm instance from outside. No ownership is transferred.
Algorithm *	transferProbeDeformationAlgorithm ()
	Transfer and release probe deformation algorithm if created internally.
bool	computePredictionMapsAlgorithm (SharedImageSet *usVolume)
	Initialize and compute registration from prediction maps with provided ultrasound volume.
bool	hasSliceOrientationEstimation () const
	Check if the SliceOrientationEstimation algorithm is available.
bool	computeSliceOrientationEstimation ()
	Initialize and compute registration using slice orientation estimation with provided ultrasound sweep.
bool	hasKeypointsRegistration () const
	Check if the Keypoint algorithm is available.
bool	computeKeypointsRegistration ()
	Initialize and compute registration using the keypoint networks.
Public Member Functions inherited from ImFusion::Algorithm
	Algorithm ()
	Default constructor will registers a single "compute" action that calls compute() and returns status().
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::SignalReceiver
	SignalReceiver ()=default
	Default constructor.
	SignalReceiver (const SignalReceiver &other)
	Copy constructor, does not copy any existing signal connections from other.
SignalReceiver &	operator= (SignalReceiver rhs)
	Assignment operator, disconnects all existing connections, does not copy any existing signal connections from rhs.
virtual	~SignalReceiver ()
	Virtual destructor disconnects from all connected signals.

Static Public Member Functions
static bool	createCompatible (const DataList &data, Algorithm **a)
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 double	errorToMultPenalty (double value, double range)
	There is a margin of half the range within which the returned penalty value fades from 1 to 0 with a polynomial function, and extents below zero after 1.5x range, and is continuous in the derivative.
static double	errorsToMultPenalty (const std::vector< double > &error, const std::vector< double > &range)
	Return a number of error values to a combined penalty function, while properly housekeeping values < 0.

Protected Attributes
UltrasoundSweep &	m_sweep
	The ultrasound sweep to be modified.
SharedImageSet &	m_volume
	The CT or MRI volume to register against.
SharedImageSet *	m_segVol = nullptr
	Optional segmentation as label or distance volume.
std::unique_ptr< SharedImageSet >	m_distVol
	Distance volume if computed here.
std::unique_ptr< PointDistanceReg >	m_pointReg
	Point-surface registration instance.
SharedImageSet *	m_usVolumeFromSweep = nullptr
	Compounded ultrasound volume required for prediction map algorithm.
std::unique_ptr< SharedImageSet >	m_ownUsVolume
	Denotes whether the above has been computed internally.
std::unique_ptr< LinkPose >	m_linkPoseUs
	Links transformation of the sweep and compounded volume.
std::unique_ptr< RegistrationFromPredictionMapAlgorithm >	m_predMapAlg
	Prediction map algorithm instance.
std::unique_ptr< Algorithm >	m_sliceOrientationAlg
	Slice orientation algorithm instance.
std::unique_ptr< Algorithm >	m_keypointAlg
	Keypoint algorithm instance.
std::shared_ptr< PointsOnImage >	m_sweepPoints
	Sweep points for segmentation distance mode.
std::unique_ptr< ProbeDeformationAlgorithm >	m_ownProbeDefAlg
	Probe deformation algorithm instance created here.
ProbeDeformationAlgorithm *	m_probeDefAlg = nullptr
	Probe deformation algorithm for skin surface constraint.
Algorithm *	m_regAlg = nullptr
	Optional registration algorithm set from outside.
SweepPointCorrAlgorithm *	m_pointCorrAlg = nullptr
	Optional point correspondence alg. set from outside.
bool	m_predMapAlgComputing = false
	Preventing recursive penalty computation while prediction map algorithm is running.
std::vector< double >	m_cachedError
	Errors cached to avoid redundant computations.
std::vector< double >	m_lastError
	Last computed landmark, surface or angle errors.
std::vector< double >	m_penaltyRange = {10.0, 45.0, 30.0, 50.0, 10.0}
	Configured penalty range values.
std::vector< bool >	m_penaltyEnabled
	Enabled flag for all penalties.
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.

Parameters of the algorithm
Parameter< bool >	p_usIsMoving = {"usIsMoving", true, this}
	Specifies if the ultrasound sweep shall be moved as opposed to the volume.
Parameter< bool >	p_useSkinSurface = {"useSkinSurface", false, this}
	If enabled, the skin surface is segmented from the volume and used as penalty function.
Parameter< bool >	p_usePredMap = {"usePredMap", false, this}
	Specify whether the registration from prediction maps algorithm shall be used for initialization.
Parameter< bool >	p_useKeypoints = {"useKeypoints", false, this}
	Specify whether the registration from keypoints algorithm shall be used.
Parameter< bool >	p_usePredMapTranslationOnly = {"usePredMapTranslationOnly", false, this}
	Specify whether the registration from prediction maps algorithm shall be used in translation only mode.
Parameter< bool >	p_useSliceOrientation = {"useSliceOrientation", false, this}
	Specify whether the slice orientation algorithm shall be used for initialization.

Dealing with the penalty functions
void	setPenaltyRange (Penalty which, double range)
void	setPenaltyEnabled (Penalty which, bool flag)
	Enable or disable a particular penalty function.
double	penaltyRange (Penalty which) const
	Return the current allowed range of a penalty function.
bool	penaltyEnabled (Penalty which) const
	Return whether the chosen penalty function is enabled.
bool	penaltyAvailable (Penalty which) const
	Return whether a penalty function is available in the current configuration.

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.
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 Member Functions inherited from ImFusion::SignalReceiver
void	disconnectAll ()
	Disconnects all existing connections.

Member Enumeration Documentation

◆ Penalty

enum class ImFusion::US::SweepGlobalInitAlgorithm::Penalty

strong

Supported penalty functions, which can be combined to guide the initialization.

Enumerator
Distance	Landmark correspondence distance or distance of ultrasound landmarks to segmentation if provided.
BeamAngle	Angle between ultrasound beam axis and patient's anterior-posterior direction.
SkinDist	Distance of points on the ultrasound transducer to the patient's skin surface.
SkinAngle	Angle of the ultrasound transducer with respect to the patient's skin surface.
PredMap	Residual error of the registration-from-prediction-map algorithm.

Member Function Documentation

◆ setRegistrationAlgorithm()

void ImFusion::US::SweepGlobalInitAlgorithm::setRegistrationAlgorithm ( Algorithm * regAlg )

Set an image-based registration algorithm instance from outside, applying the error/penalty function from here.

Parameters

regAlg Pointer to the registration algorithm to use for error evaluation.

◆ setPointCorrAlgorithm()

void ImFusion::US::SweepGlobalInitAlgorithm::setPointCorrAlgorithm ( SweepPointCorrAlgorithm * pca )

inline

Set the point correspondences algorithm from outside if available, using its distance penalty.

Parameters

pca	Pointer to the SweepPointCorrAlgorithm instance.

◆ evaluateError()

void ImFusion::US::SweepGlobalInitAlgorithm::evaluateError ( std::vector< double > & out )

overridevirtual

Implements the ErrorFunction interface.

Evaluates all enabled penalties and stores the results.

Parameters

out	Output vector, will have size equal to the number of enabled penalties and contain the computed penalties.

Implements ImFusion::ErrorFunction.

◆ computeErrors()

std::vector< double > ImFusion::US::SweepGlobalInitAlgorithm::computeErrors ( )

Compute errors for all enabled penalties and return the results.

Returns: Vector of penalty values in the order defined by Penalty.

◆ lastErrors()

std::vector< double > ImFusion::US::SweepGlobalInitAlgorithm::lastErrors ( ) const

Return the last computed penalty errors.

Returns: Vector of penalty values from the last evaluation.

◆ penalize()

double ImFusion::US::SweepGlobalInitAlgorithm::penalize	(	double	cost,
		const std::vector< double > &	error )

overridevirtual

Compute the penalized cost based on the provided error vector and penalty configuration.

Parameters

cost	The original cost value.
error	The vector of penalty values, if empty it will be computed.

Returns: Penalized cost.

See also: ErrorFunction::errorToMultPenalty

Reimplemented from ImFusion::ErrorFunction.

◆ setPenaltyRange()

void ImFusion::US::SweepGlobalInitAlgorithm::setPenaltyRange	(	Penalty	which,
		double	range )

Set allowed range for a particular penalty function

Parameters

which	The penalty function to configure.
range	Acceptable range value, for the penalty function. Negative values are discarded and a warning message is emitted.

See also: ErrorFunction::errorToMultPenalty

◆ setPenaltyEnabled()

void ImFusion::US::SweepGlobalInitAlgorithm::setPenaltyEnabled	(	Penalty	which,
		bool	flag )

Enable or disable a particular penalty function.

Parameters

which	The penalty function to configure.
flag	True to enable, false to disable.

◆ penaltyRange()

double ImFusion::US::SweepGlobalInitAlgorithm::penaltyRange ( Penalty which ) const

Return the current allowed range of a penalty function.

Parameters

which The penalty function to query.

Returns: The allowed range value.

See also: ErrorFunction::errorToMultPenalty

◆ penaltyEnabled()

bool ImFusion::US::SweepGlobalInitAlgorithm::penaltyEnabled ( Penalty which ) const

Return whether the chosen penalty function is enabled.

Parameters

which The penalty function to query.

◆ penaltyAvailable()

bool ImFusion::US::SweepGlobalInitAlgorithm::penaltyAvailable ( Penalty which ) const

Return whether a penalty function is available in the current configuration.

Parameters

which The penalty function to query.

Returns: True if available, false otherwise.

◆ compute()

void ImFusion::US::SweepGlobalInitAlgorithm::compute ( )

overridevirtual

Execute the algorithm.

Implements ImFusion::Algorithm.

◆ takeOutput()

OwningDataList ImFusion::US::SweepGlobalInitAlgorithm::takeOutput ( )

overridevirtual

Note: Also sets m_pointReg = nullptr

Reimplemented from ImFusion::Algorithm.

◆ configure()

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

overridevirtual

Configure this object instance by de-serializing the given Properties.

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

See also: configuration() for the inverse functionality

Reimplemented from ImFusion::Configurable.

◆ configuration()

void ImFusion::US::SweepGlobalInitAlgorithm::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 ImFusion::Configurable.

◆ transferProbeDeformationAlgorithm()

Algorithm * ImFusion::US::SweepGlobalInitAlgorithm::transferProbeDeformationAlgorithm ( )

Transfer and release probe deformation algorithm if created internally.

Returns: Pointer to the released ProbeDeformationAlgorithm instance, or nullptr if not owned.

◆ computePredictionMapsAlgorithm()

bool ImFusion::US::SweepGlobalInitAlgorithm::computePredictionMapsAlgorithm ( SharedImageSet * usVolume )

Initialize and compute registration from prediction maps with provided ultrasound volume.

Parameters

usVolume Pointer to the ultrasound volume.

Returns: True if computation was successful, false otherwise.

◆ computeSliceOrientationEstimation()

bool ImFusion::US::SweepGlobalInitAlgorithm::computeSliceOrientationEstimation ( )

Initialize and compute registration using slice orientation estimation with provided ultrasound sweep.

Returns: True if computation was successful, false otherwise.

◆ computeKeypointsRegistration()

bool ImFusion::US::SweepGlobalInitAlgorithm::computeKeypointsRegistration ( )

Initialize and compute registration using the keypoint networks.

Returns: True if computation was successful, false otherwise.

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

ImFusion/US/SweepGlobalInitAlgorithm.h

Detailed Description

Public Types

Public Member Functions

Static Public Member Functions

Protected Attributes

Parameters of the algorithm

Dealing with the penalty functions

Additional Inherited Members

Member Enumeration Documentation

◆ Penalty

Member Function Documentation

◆ setRegistrationAlgorithm()

◆ setPointCorrAlgorithm()

◆ evaluateError()

◆ computeErrors()

◆ lastErrors()

◆ penalize()

◆ setPenaltyRange()

◆ setPenaltyEnabled()

◆ penaltyRange()

◆ penaltyEnabled()

◆ penaltyAvailable()

◆ compute()

◆ takeOutput()

◆ configure()

◆ configuration()

◆ transferProbeDeformationAlgorithm()

◆ computePredictionMapsAlgorithm()

◆ computeSliceOrientationEstimation()

◆ computeKeypointsRegistration()