#include <ImFusion/US/SweepPointCorrAlgorithm.h>

Handles point correspondences between an ultrasound sweep and a 3D volume for registration. More...

Inheritance diagram for ImFusion::US::SweepPointCorrAlgorithm:

Detailed Description

Handles point correspondences between an ultrasound sweep and a 3D volume for registration.

This algorithm computes the rigid registration between an ultrasound sweep and a reference volume using point correspondences. It evaluates errors, applies penalties, and supports landmark-based registration.

The algorithm can also use a predefined view matrix for orientation alignment.

Inputs:

Ultrasound sweep (UltrasoundSweep)
Reference volume (SharedImageSet)

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

Parameters:

p_usIsMoving: Specifies if the ultrasound sweep is moved instead of the volume
m_penaltyRange: Global penalty range for error evaluation
m_perLandmarkRange: Individual error ranges for landmarks

Public Member Functions
	SweepPointCorrAlgorithm (UltrasoundSweep &sweep, SharedImageSet &volume, std::string pointSetName="")
	Constructor with an ultrasound sweep and 3D volume. If pointSetName is empty, it will use the first available name from "SweepInit3D" and "SweepPointCorr".
void	setViewMatrix (bool useViewMatrix, mat4 m=mat4::Identity())
	Defines if and which view matrix should be used.
void	setRegistrationAlgorithm (Algorithm *regAlg)
	Add this class as an ErrorFunction to a registration algorithm.
bool	computeSweepMotion (SweepMotion *sm)
	If the sweep has empty matrices, try to compute motion parameters from the landmarks.
void	evaluateError (std::vector< double > &out) override
	Implements the error function interface to evaluate errors.
std::vector< double >	computeErrors ()
	Compute the error and returns it.
std::vector< double >	lastErrors () const
double	penalize (double cost, const std::vector< double > &error) override
	Applies a penalty to the given cost based on the provided errors.
void	setPenaltyRange (double val)
	Sets the allowed range for the penalty function.
double	penaltyRange () const
	Returns the current allowed range of the penalty function.
void	setPerLandmarkRange (int landmark, double range)
	Sets an individual allowed error range in mm for a landmark pair.
double	perLandmarkRange (int landmark) const
	Returns the individual landmark range (zero if not set).
double	landmarkError (int landmark, bool *exceededOut=nullptr) const
	Returns the current error of an individual landmark or all of them if landmark=-1.
void	clearPerLandmarkRanges ()
	Clears all individual landmark range values.
void	compute () override
	Execute the algorithm.
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, it always exists.
PointsOnImage *	volumePoints ()
	Access to the volume points instance, it always exists.
PointCorrespondences *	correspondences ()
	Access to the point correspondences instance, it always exists.
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::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 void	pointCorrResidual (const PointCorrespondences &corr, double &regErrorOut, int &notOnLineOut)
	Computes the average error across the point correspondences.
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.

Public Attributes
Parameter< bool >	p_usIsMoving = {"usIsMoving", true, this}
	Specifies if the ultrasound sweep shall be moved as opposed to the volume.
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 Attributes
UltrasoundSweep &	m_sweep
	The ultrasound sweep to be modified.
SharedImageSet &	m_volume
	The CT or MRI volume to register against.
std::shared_ptr< PointsOnImage >	m_sweepPoints
	Sweep points instance.
std::shared_ptr< PointsOnImage >	m_volumePoints
	Volume points instance.
std::unique_ptr< PointCorrespondences >	m_correspondences
	Point correspondences instance.
Algorithm *	m_regAlg = nullptr
	Optional registration algorithm set from outside.
std::vector< double >	m_cachedError
	Errors cached to avoid redundant computations.
std::vector< double >	m_lastError
	Last computed landmark, surface or angle errors.
double	m_penaltyRange = 10.0
	Configured global penalty range.
std::vector< double >	m_perLandmarkRange
	Optional individual error ranges per landmark.
mat4	m_viewMatrix = mat4::Identity()
	Matrix of the axial (red) MPR.
bool	m_useViewRotation = false
	Flag if axial MPR matrix should be used as rotation.
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.

Additional Inherited Members
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...
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 Function Documentation

◆ setViewMatrix()

void ImFusion::US::SweepPointCorrAlgorithm::setViewMatrix	(	bool	useViewMatrix,
		mat4	m = mat4::Identity() )

Defines if and which view matrix should be used.

Parameters

useViewMatrix	Whether to use the view matrix for alignment
m	The view matrix to be applied

◆ setRegistrationAlgorithm()

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

Add this class as an ErrorFunction to a registration algorithm.

Will remove itself from the algorithm on destruction.

Parameters

regAlg The external registration algorithm

◆ computeSweepMotion()

bool ImFusion::US::SweepPointCorrAlgorithm::computeSweepMotion ( SweepMotion * sm )

If the sweep has empty matrices, try to compute motion parameters from the landmarks.

Returns false if the computation fails

◆ evaluateError()

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

overridevirtual

Implements the error function interface to evaluate errors.

Parameters

out	Output vector, will have size 1 and contain the computed penalty.

Implements ImFusion::ErrorFunction.

◆ computeErrors()

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

Compute the error and returns it.

Returns: A vector of size 1 containing the penalty

◆ lastErrors()

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

Returns: the last computed penalty errors

◆ penalize()

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

overridevirtual

Applies a penalty to the given cost based on the provided errors.

Parameters

cost	The initial cost value
error	The vector of errors to evaluate

Returns: The penalized cost

See also: ErrorFunction::errorToMultPenalty

Reimplemented from ImFusion::ErrorFunction.

◆ pointCorrResidual()

void ImFusion::US::SweepPointCorrAlgorithm::pointCorrResidual	(	const PointCorrespondences &	corr,
		double &	regErrorOut,
		int &	notOnLineOut )

static

Computes the average error across the point correspondences.

Parameters

corr	The point correspondences
regErrorOut	Output for the registration error
notOnLineOut	Output for the not-on-line metric in percent

◆ setPenaltyRange()

void ImFusion::US::SweepPointCorrAlgorithm::setPenaltyRange ( double val )

inline

Sets the allowed range for the penalty function.

Parameters

val	The new penalty range

See also: ErrorFunction::errorToMultPenalty

◆ penaltyRange()

double ImFusion::US::SweepPointCorrAlgorithm::penaltyRange ( ) const

inline

Returns the current allowed range of the penalty function.

Returns: The penalty range

See also: ErrorFunction::errorToMultPenalty

◆ setPerLandmarkRange()

void ImFusion::US::SweepPointCorrAlgorithm::setPerLandmarkRange	(	int	landmark,
		double	range )

Sets an individual allowed error range in mm for a landmark pair.

Parameters

landmark	The index of the landmark
range	The allowed error range in mm

See also: ErrorFunction::errorToMultPenalty

◆ perLandmarkRange()

double ImFusion::US::SweepPointCorrAlgorithm::perLandmarkRange ( int landmark ) const

Returns the individual landmark range (zero if not set).

Parameters

landmark The index of the landmark

Returns: The allowed error range in mm

◆ landmarkError()

double ImFusion::US::SweepPointCorrAlgorithm::landmarkError	(	int	landmark,
		bool *	exceededOut = nullptr ) const

Returns the current error of an individual landmark or all of them if landmark=-1.

Parameters

landmark	The index of the landmark (-1 for all landmarks)
exceededOut	Optional output to indicate if the error exceeds the range

Returns: The computed error

◆ compute()

void ImFusion::US::SweepPointCorrAlgorithm::compute ( )

overridevirtual

Execute the algorithm.

Implements ImFusion::Algorithm.

◆ configure()

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

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

ImFusion/US/SweepPointCorrAlgorithm.h

Detailed Description

Public Member Functions

Static Public Member Functions

Public Attributes

Protected Attributes

Additional Inherited Members

Member Function Documentation

◆ setViewMatrix()

◆ setRegistrationAlgorithm()

◆ computeSweepMotion()

◆ evaluateError()

◆ computeErrors()

◆ lastErrors()

◆ penalize()

◆ pointCorrResidual()

◆ setPenaltyRange()

◆ penaltyRange()

◆ setPerLandmarkRange()

◆ perLandmarkRange()

◆ landmarkError()

◆ compute()

◆ configure()

◆ configuration()