PiecewiseMotionModel Class Reference

#include <ImFusion/US/MotionTrajectoryModel.h>

Motion model enabling piecewise segment-based registration using frame selection. More...

Inheritance diagram for PiecewiseMotionModel:

Detailed Description

Motion model enabling piecewise segment-based registration using frame selection.

This motion model optimizes the input motion within user-defined frame selections. The output motion is interpolated across the selected segments (frame ranges). To initialize the model, call fitMatrices(const std::vector<mat4>&) to provide the original tracking matrices and define the initial control segments. The first and last selected frames will be automatically chosen as control points.

Additional motion segments can later be appended using addPiece(const Selection& totalSelection, int newPieceSize).

Example usage:

UltrasoundSweep us = getUltrasoundSweepOfSize1000();
PiecewiseMotionModel model(1000);
 
us.selection().setNone();   // explicitly defined empty selection as default
us.selection().setSelected(250, true);
us.selection().setSelected(750, true);
model.setSelection(us.selection());
 
std::vector<mat4> mat(1000);
for (int i = 0; i < 1000; i++)
    mat[i] = us.tracking()->matrix(i);
 
mat4 registration = model.fitMatrices(mat);
 
Selection totalSelection = us.selection();
totalSelection.setSelected(800, true);
model.addPiece(totalSelection, 50);
 
auto selectedMotion = model.defineMotion();

Public Member Functions
	PiecewiseMotionModel (int size)
std::string	name () const override
	Returns the name of the current motion model.
int	numberOfParameters () const override
	Returns the number of parameters currently active in the model.
std::vector< double >	parameters () const override
	Returns the current transformation parameters of the model.
void	setParameters (const std::vector< double > &pars) override
	Sets the transformation parameters for the currently optimized piece(s).
bool	addPiece (const Selection &totalSelection, int newPieceSize)
	Adds a new motion segment to the model based on updated frame selection.
void	setExposeAllParameters (bool b)
	Sets whether all transformation parameters should be exposed for optimization.
bool	exposeAllParameters () const
	Checks whether all transformation parameters are exposed.
std::vector< mat4 >	defineMotion () const override
	Generates the complete interpolated motion trajectory over the model's frame range.
mat4	fitMatrices (const std::vector< mat4 > &mat) override
	Initializes the piecewise motion model from the input transformation matrices.
void	setSelection (Selection s)
const Selection &	selection ()
Public Member Functions inherited from MotionTrajectoryModel
	MotionTrajectoryModel (int size)
void	setRelativeShiftMatrix (const mat4 &relShiftBefore)
	Sets the relative shift matrix applied before the motion.
void	configure (const Properties *p) override
	Sets one or multiple properties.
void	configuration (Properties *p) const override
	Retrieve the properties of this object.
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

Protected Attributes
Selection	m_selection
	Current selection.
bool	m_exposeAllParams
	Flag if all parameters or just the ones of the current piece are exposed.
std::vector< std::pair< int, mat4 > >	m_piecewiseFrameMat
	Control points at frame indices for piecewise optimization.
int	m_currentOptimPiece
	Index of the piece between control points currently being optimized.
std::vector< mat4 >	referenceMatrices
	The motion initially provided in the fitMatrices(const std::vector<mat4>& mat)
Protected Attributes inherited from MotionTrajectoryModel
const int	m_size
	Size of the model, regularly the number of frames.
std::vector< double >	m_pars
	Full motion parameter vector - not necessarily the exposed ones.
mat4	m_relShift
	Generic helper matrix to incorporate optional shifts. Considered by rigidMotion().
Protected Attributes inherited from Configurable
std::vector< Param >	m_params
	List of all registered Parameter and SubProperty instances.

Additional Inherited Members
Public Types inherited from MotionTrajectoryModel
typedef std::function< MotionTrajectoryModel *(int)>	createModelFunc
	Function signature for creating a motion model with a given size.
Static Public Member Functions inherited from MotionTrajectoryModel
static std::vector< std::pair< std::string, createModelFunc > > &	supportedModels ()
	Returns a list of supported motion models.
Public Attributes inherited from Configurable
Signal	signalParametersChanged
	Emitted whenever one of the registered Parameters' or SubPropertys' signalValueChanged signal was emitted.
Protected Member Functions inherited from MotionTrajectoryModel
std::vector< mat4 >	rigidMotion (const mat4 &m0, const mat4 &m1, int startFrame=0, int endFrame=-1) const
	Helper method to interpolate a rigid motion between m0 and m1.

Constructor & Destructor Documentation

PiecewiseMotionModel()

PiecewiseMotionModel ( int size )

explicit

Parameters

size	The number of frames in the motion sequence.

Member Function Documentation

name()

std::string name ( ) const

inlineoverridevirtual

Returns the name of the current motion model.

Implements MotionTrajectoryModel.

numberOfParameters()

int numberOfParameters ( ) const

overridevirtual

Returns the number of parameters currently active in the model.

• If exposeAllParameters() is true, returns the total number of transformation parameters across all pieces (6 per piece).
• If exposeAllParameters() is false and fitMatrices(const std::vector<mat4>&) has been called, returns 12 (6 per segment for two segments).
• If fitMatrices(const std::vector<mat4>&) has not been called, returns 0.

  Returns

  The number of transformation parameters.

Reimplemented from MotionTrajectoryModel.

parameters()

std::vector< double > parameters ( ) const

overridevirtual

Returns the current transformation parameters of the model.

The number and meaning of parameters depend on the model state and exposure mode:

• If exposeAllParameters() is true, returns all transformation parameters for every piece (typically 6 parameters per piece).
• If exposeAllParameters() is false and fitMatrices(const std::vector<mat4>&) has been called, returns 12 parameters representing the affine transform of either the first or last segment, depending on where the last piece was added (at the front or back of the current selection).
• If fitMatrices(const std::vector<mat4>&) has not been called, returns an empty vector.

  Returns

  A vector containing the current transformation parameters.

Reimplemented from MotionTrajectoryModel.

setParameters()

void setParameters ( const std::vector< double > & pars )

overridevirtual

Sets the transformation parameters for the currently optimized piece(s).

Parameters

pars	A vector of transformation parameters. Its length must match numberOfParameters().

• When exposeAllParameters() is false, expects a 6-element vector for the current piece.
• When exposeAllParameters() is true, expects the full parameter set for all pieces.

  Note

  Does nothing if fitMatrices(const std::vector<mat4>&) has not been called.

  Warning

  If the parameter vector is longer than 6 and exposeAllParameters() is false, behavior is undefined.

Reimplemented from MotionTrajectoryModel.

addPiece()

bool addPiece	(	const Selection &	totalSelection,
		int	newPieceSize )

Adds a new motion segment to the model based on updated frame selection.

Parameters

totalSelection	The full selection, including the newly selected control point.
newPieceSize	Number of frames to extend the piecewise model by: Positive values append a new piece after the current selection. Negative values prepend a new piece before the current selection.

This method allows incrementally building a piecewise model by appending new control points and segments.

Note

Requires fitMatrices(const std::vector<mat4>&) to have been called first.

Returns

True if the piece was successfully added; false otherwise.

setExposeAllParameters()

void setExposeAllParameters

(

bool

b

)

Sets whether all transformation parameters should be exposed for optimization.

Parameters

b	If true, all parameters for all segments are exposed; if false, only those of the current segment are used.

exposeAllParameters()

bool exposeAllParameters

(

)

const

Checks whether all transformation parameters are exposed.

Returns

True if all parameters are exposed for optimization; false if only a subset (e.g., current segment) is.

defineMotion()

std::vector< mat4 > defineMotion ( ) const

overridevirtual

Generates the complete interpolated motion trajectory over the model's frame range.

Returns a vector of transformation matrices, one per frame, with total size equal to the model's configured size.

The output motion is defined as follows:

• Frames before the first selected frame are assigned the motion of the first selected frame.
• Frames after the last selected frame are assigned the motion of the last selected frame.
• Frames between selected control points (as defined via fitMatrices(const std::vector<mat4>&) and extended via addPiece(const Selection&, int)) are interpolated using rigid (linear) interpolation.

This results in a piecewise-rigid motion profile with constant motion outside the selected regions.

Note

Be aware that fitMatrices(const std::vector<mat4>&) chooses the first selected frame as the reference registration frame.

Implements MotionTrajectoryModel.

fitMatrices()

mat4 fitMatrices ( const std::vector< mat4 > & mat )

overridevirtual

Initializes the piecewise motion model from the input transformation matrices.

Uses the first and last selected frames (as defined via setSelection(Selection)) as initial control points, and computes the rigid motion between them. These control frames define the initial segment.

Note

The registration frame is set to the first selected frame.

Warning

mat must contain at least as many entries as the index of the last selected frame.

Note

For meaningful interpolation, mat should ideally match the model size provided at construction.

Implements MotionTrajectoryModel.

---

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

• ImFusion/US/MotionTrajectoryModel.h