UltrasoundCalibration Class Reference

#include <ImFusion/US/UltrasoundCalibration.h>

Freehand ultrasound calibration with overlapping sweeps. More...

Inheritance diagram for UltrasoundCalibration:

Detailed Description

Freehand ultrasound calibration with overlapping sweeps.

Requires pairs of ultrasound sweeps, which are reconstructed into the respective others' frames to compute 2D image similarities. The calibration matrix and optionally the temporal calibration offset are optimized using the optimization framework and BOBYQA as default derivative-free optimizer.

The algorithm is described in detail in this paper:

‍Wolfgang Wein and Ali Khamene. "Image-based method for in-vivo freehand ultrasound calibration." Medical Imaging 2008: Ultrasonic Imaging and Signal Processing. Vol. 6920. SPIE, 2008. DOI, PDF

Since this algorithm utilizes image similarities, its capture range is similarly limited as with intensity-based image registration. Call this algorithm with pre-aligned sweeps.

To determine whether the provided sweeps are suited to estimated the calibration, call solvability for an estimation how numerically stable the calibration is. A typical issue is insufficient rotation of the two input sweeps, yielding infinite solutions as only 5 out of 6 degrees of freedom are can be estimated.

Note

Use the VolumeCalibration for pairs of 3D volumes instead.

Public Types
enum	Solvability { Exact = 0 , UpToAFlip , InfiniteSolutions }
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
	UltrasoundCalibration (UltrasoundSweep *us1, UltrasoundSweep *us2)
	Constructor with the two sweeps to use for calibration.
	UltrasoundCalibration (const std::vector< UltrasoundSweep * > &sweeps)
	Constructor with even number of sweeps used in pairs.
void	configure (const Properties *p) override
	Configures the algorithm. Sub-properties SimilarityMeasure and Optimizer are forwarded.
void	configuration (Properties *p) const override
	Returns the algorithm's configuration.
void	defineOriginalState ()
	Define the original state.
void	resetToOriginalState ()
	Reset the calibration the original state. Unless defineOriginalState() has been called, the sweep calibrations will be reset to their state at construction of this algorithm.
double	evaluate (int n, const double *x, double *dx=0) override
	Cost function evaluation.
void	compute () override
	Execute the calibration using the provided optimizer.
void	centerSweeps ()
	Shift the registration matrices to center the sweeps in 3D world coordinates.
void	setOptimizer (std::shared_ptr< Optimizer > opt)
	Override the default optimizer.
void	setSimilarityMeasure (int mode, int patchSize=0)
	Set the mode of the existing similarity measure, including patch size if non-zero.
void	setMultiMode (int mode)
	Set mode of handling multiple sweeps (0 = concatenate, 1 = successive pairs).
void	setZeroMask (bool flag)
	Set whether an internal mask is used for the compounded slices to ignore zero intensities.
void	setMode (int which)
	Specify which sweeps are iterated over during computation.
void	setMaxFrames (int num)
	Specify the maximum number of frames to use per sweep.
void	setMinOverlap (int percent)
	Set the minimum overlap percentage (how much the two input sweeps overlap under the current calibration estimate in world space).
void	setMotion2 (SweepMotion *motion)
	Set motion instance of the second ultrasound sweep from outside.
void	setUseBackwardCompounding (bool value)
	Set flag whether to use backward compounding instead of direct compounding.
SharedImage *	previewImage (int sweep)
	Reconstructs that frame of the respective other sweep that corresponds to the focus frame of the sweep-th sweep.
int	numSweeps () const
	Return the number of sweeps used.
UltrasoundSweep *	sweep (int which)
	Access one of the sweeps.
int	frameCount () const
	Returns how many frames were considered during the last calibration optimization in total, which equals the number of times the similarity metric was evaluated in each iteration.
int	numMotionPars (int sweep) const
	Return the number of motion parameters per sweep available for optimization.
double	overlap () const
	Return the average image overlap from the last computation.
std::shared_ptr< Optimizer >	createDefaultOptimizer () const
	Returns a default optimizer suited for this algorithm.
Solvability	solvability (double threshold=0.12, int numFrames=20) const
	Returns the solvability of the calibration problem given the input sweeps.
void	flip (int numFrames=20)
	Flips the current calibration, should be called only when solvability() returns UpToAFlip.
void	transferCalibrationToOtherSweeps (const int srcSweepId, const bool transferSize=true, const bool transferTemporalOffset=true)
	Transfer the calibration matrix from the sweep specified by srcSweepId to all other sweeps.
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
Public Member Functions inherited from 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 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 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
Eigen::Matrix< double, 9, 2 >	computeFlipVector (int numFrames) const
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.

Additional Inherited Members
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 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.
Protected Attributes inherited from 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.

Member Function Documentation

configure()

void configure ( const Properties * p )

overridevirtual

Configures the algorithm. Sub-properties SimilarityMeasure and Optimizer are forwarded.

Reimplemented from Configurable.

configuration()

void configuration ( Properties * p ) const

overridevirtual

Returns the algorithm's configuration.

Adds the similarity metric's and optimizer's configuration in sub-properties SimilarityMeasure and Optimizer, respectively.

Reimplemented from Configurable.

evaluate()

double evaluate ( int n, const double * x, double * dx = 0 )

overridevirtual

Cost function evaluation.

Implements CostFunction.

compute()

void compute ( )

overridevirtual

Execute the calibration using the provided optimizer.

Implements Algorithm.

setSimilarityMeasure()

void setSimilarityMeasure	(	int	mode,
		int	patchSize = 0 )

Set the mode of the existing similarity measure, including patch size if non-zero.

Only required for advanced uses of the calibration algorithm.

setMultiMode()

void setMultiMode

(

int

mode

)

Set mode of handling multiple sweeps (0 = concatenate, 1 = successive pairs).

Mode 0 means that the first half of all sweeps are always used when reconstructing frames from a sweep of the second half, respectively - and vice versa. It may be used for example to expand the lateral field of view for a linear probe by doing two shifted acquisitions for each orientation. Mode 1 means that all two successive sweeps in the vector are calibrated as pair, but put in the same cost function together. This may be used when imaging different calibration objects each with a pair of sweeps, gaining stability by optimizing over all of them. Default is 0.

setMode()

void setMode

(

int

which

)

Specify which sweeps are iterated over during computation.

0..n-1 is a specific sweep. This one sweep is iterated over, and the respective other sweep(s) reconstructed into the location of its frames to compute the 2D image similarity. -1 are all sweeps, for for two sweeps, both of their frames are reconstructed into each others. This is the default as it tends to average out the anisotropic point spread function in ultrasound. -2 is a heuristic initialization both on the two sweeps assumed geometry.

setMaxFrames()

void setMaxFrames

(

int

num

)

Specify the maximum number of frames to use per sweep.

The algorithm adjusts the sweeps' skip parameter accordingly.

setMinOverlap()

void setMinOverlap

(

int

percent

)

Set the minimum overlap percentage (how much the two input sweeps overlap under the current calibration estimate in world space).

If set to a value above zero, the final sum of all frame similarities during optimization is multiplied with an additional penalty function (10% fade-off margin) to nudge the optimization into the right direction.

setMotion2()

void setMotion2 ( SweepMotion * motion )

inline

Set motion instance of the second ultrasound sweep from outside.

nullptr switches the motion optimization off. For the first sweep, call setMotion(). Must only be used if there are exactly two input sweeps.

setUseBackwardCompounding()

void setUseBackwardCompounding ( bool value )

inline

Set flag whether to use backward compounding instead of direct compounding.

Backward compounding provides superior performance, but the user must ensure that the number of frames in all input sweeps is not modified while this algorithm exists.

previewImage()

SharedImage * previewImage

(

int

sweep

)

Reconstructs that frame of the respective other sweep that corresponds to the focus frame of the sweep-th sweep.

The returned image is owned by the algorithm in m_outImgs. The controller uses this method to preview how accurate the current calibration is, by showing both sweep(selectedSweep)->get() and previewImage(selectedSweep) in a 2D view.

solvability()

Solvability solvability	(	double	threshold = 0.12,
		int	numFrames = 20 ) const

Returns the solvability of the calibration problem given the input sweeps.

Under the assumption that there are points in world coordinate system that are contained by pairs of frames of both sweeps, it is possible to construct a linear system to solve for the calibration parameters. Not knowing these correspondences, it is a least possible to decompose the linear system matrix into three parts that only depend on the unknown points, the sweeps' tracking poses, and the also unknown calibration matrix. This method constructs the second of these matrices (the one depending only on the tracking poses) using numFrames of each sweep, and determines its singular values. If there are two singular values close to zero (below threshold), the system doesn't have a unique solution, If there is one such singular values, there are two solutions (UpToAFlip). Otherwise, there is one unique solution.

flip()

void flip

(

int

numFrames = 20

)

Flips the current calibration, should be called only when solvability() returns UpToAFlip.

Tries to construct a similar linear system as solvability() using numFrames of both sweeps, determines which of the two solutions is in the vicinity of the current calibration estimate of the sweeps, estimates the respective other solution and applies it.

transferCalibrationToOtherSweeps()

void transferCalibrationToOtherSweeps	(	const int	srcSweepId,
		const bool	transferSize = true,
		const bool	transferTemporalOffset = true )

Transfer the calibration matrix from the sweep specified by srcSweepId to all other sweeps.

transferSize and transferTemporalOffset define whether the image size and the temporal offset should be transferred as well. The transfer is performed so that for all sweeps, the tip of the probe lies at the same position in the world coordinate system.

---

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

• ImFusion/US/UltrasoundCalibration.h