GatingMotionModel Class Reference

#include <ImFusion/US/MotionTrajectoryModel.h>

Specialized motion model that incorporates gating metadata for respiratory-aware motion. More...

Inheritance diagram for GatingMotionModel:

Detailed Description

Specialized motion model that incorporates gating metadata for respiratory-aware motion.

This model extends SimpleMotionModel by applying respiratory gating, allowing the motion to be modulated according to a provided phase signal.

Unlike basic rigid models with only 6 pose parameters (translation + Euler angles), this model optionally supports up to 9 parameters:

• The first 6 are standard pose parameters (3 translation + 3 rotation).
• The last 3 are gating parameters, each in the [0, 1] range:
  1. Hold after peak — how long to retain full motion after the phase peak.
  2. Hold before peak — how long to retain full motion before the peak.
  3. Phase shift — phase offset applied to the signal.

These gating parameters allow the motion to "linger" around the breathing phase peak, simulating held or dampened motion in sync with the respiratory signal.

Note

This model is specifically designed for applications involving periodic physiological motion, such as breathing, and assumes that gating metadata (e.g., a phase signal) is available.

Public Member Functions
	GatingMotionModel (int size, const GatingMetadata *gatingData=nullptr)
	Constructs the model with a given number of frames and optional gating metadata.
std::string	name () const override
	Returns the name of the current motion model.
void	configure (const Properties *p) override
	Configures the model from a Properties object.
void	configuration (Properties *p) const override
	Stores the model's configuration in a Properties object.
std::vector< mat4 >	defineMotion () const override
	Generates the motion trajectory modulated by gating parameters and phase signal.
mat4	fitMatrices (const std::vector< mat4 > &mat) override
	Not implemented for this model.
void	setGatingData (const GatingMetadata *gatingData)
	Sets or updates the gating metadata used by the model.
Public Member Functions inherited from SimpleMotionModel
	SimpleMotionModel (int size)
std::string	name () const override
	Returns the name of the current motion model.
void	configure (const Properties *p) override
	Extends MotionTrajectoryModel::configure(const Properties *)
void	configuration (Properties *p) const override
	Saves the current model settings into the provided Properties object, including the "distributeSymmetrically" property if set.
void	setParameters (const std::vector< double > &pars) override
	Sets the motion parameters in Euler representation.
std::vector< mat4 >	defineMotion () const override
	Computes a set of m_size matrices describing the intended motion trajectory.
mat4	fitMatrices (const std::vector< mat4 > &mat) override
	Sets the parameters based on the given motion sequence.
double	shift () const
	Returns the translation along the Z-axis.
double	rotation () const
	Returns the rotation around the Z-axis.
void	setMotionType (SimpleMotionType t)
SimpleMotionType	motionType () const
void	setDistributeSymmetrically (bool b)
bool	distributeSymmetrically () const
Public Member Functions inherited from MotionTrajectoryModel
	MotionTrajectoryModel (int size)
void	setRelativeShiftMatrix (const mat4 &relShiftBefore)
	Sets the relative shift matrix applied before the motion.
virtual int	numberOfParameters () const
virtual std::vector< double >	parameters () const
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
const GatingMetadata *	m_gatingData
	Metadata containing the phase signal used for gating.
vec3	m_gatingPars
	Custom gating parameters: hold-after, hold-before, and phase shift.
Protected Attributes inherited from SimpleMotionModel
SimpleMotionType	m_type
bool	m_distributeSymmetrically
	If true, will distribute symmetrically around the central frame.
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 SimpleMotionModel
enum class	SimpleMotionType { ShiftAndRotation , RigidPose }
	The modes of the SimpleMotionModel.
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

GatingMotionModel()

GatingMotionModel	(	int	size,
		const GatingMetadata *	gatingData = nullptr )

Constructs the model with a given number of frames and optional gating metadata.

Parameters

size	The number of frames in the motion trajectory.
gatingData	Optional pointer to gating metadata used for modulating motion by phase.

Member Function Documentation

name()

std::string name ( ) const

inlineoverridevirtual

Returns the name of the current motion model.

Implements MotionTrajectoryModel.

configure()

void configure ( const Properties * p )

overridevirtual

Configures the model from a Properties object.

Extends the SimpleMotionModel by supporting an additional "gatingConfig" property, which specifies custom gating parameters.

Reimplemented from Configurable.

configuration()

void configuration ( Properties * p ) const

overridevirtual

Stores the model's configuration in a Properties object.

Reimplemented from Configurable.

defineMotion()

std::vector< mat4 > defineMotion ( ) const

overridevirtual

Generates the motion trajectory modulated by gating parameters and phase signal.

Applies the base rigid motion, then redistributes it over time based on the phase signal and the custom gating parameters.

Returns

A vector of transformation matrices defining the gated motion.

Warning

If gating metadata is not provided or the metadata does not contain the phase signal of the model size then empty motion of the model size will be return.

Implements MotionTrajectoryModel.

fitMatrices()

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

overridevirtual

Not implemented for this model.

Returns

Always returns mat4::Identity().

Implements MotionTrajectoryModel.

setGatingData()

void setGatingData

(

const GatingMetadata *

gatingData

)

Sets or updates the gating metadata used by the model.

Parameters

gatingData

Pointer to a GatingMetadata object providing a phase signal per frame.

---

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

• ImFusion/US/MotionTrajectoryModel.h