#include <ImFusion/US/GlProbeDeformation.h>

Deformation model simulating radial compression from an ultrasound probe. More...

Inheritance diagram for GlProbeDeformation:

Detailed Description

Deformation model simulating radial compression from an ultrasound probe.

This class models a radial tissue deformation pattern typically caused by pressure from an ultrasound probe.

The model supports configuration of geometric parameters such as the probe position and compression radii, as well as deformation characteristics like amplitude and non-linearity.

The parameters can be set directly or derived from an ultrasound sweep or a compounded volume.

Note: If the probe parameters are set using an UltrasoundSweep object via setProbeParameters(UltrasoundSweep* sweep), all relevant parameters will then be retrieved from the sweep. In this case, the m_probeMatrix member is no longer taken into account, as the sweep becomes the authoritative source for the probe parameters.

Public Member Functions
	GlProbeDeformation (std::shared_ptr< SharedImageSet > distImg)
	Constructor taking a distance image, for example, computed by ProbeDeformationAlgorithm.

	GlProbeDeformation (const GlProbeDeformation &other)

GlProbeDeformation &	operator= (const GlProbeDeformation &)=delete

void	setProbeParameters (const vec3 &position, double radiusMin, double radiusMax)
	Set the geometric parameters of the compression model.

void	setProbeParameters (SharedImageSet *sweepOrVolume)
	Set the geometric parameters from an ultrasound sweep instance or a compounded sweep.

void	setDeformationParameters (double amplitude, double nonLinearity)
	Set the variable deformation parameters amplitude and non-linearity.

double	parameter (const std::string &name) const
	Get the value of the known optimizable parameter with given name.

void	setMode (int mode)
	Set internal deformation mode.

int	mode () const

void	setModifyProbeParameters (bool flag)
	Sets whether probe parameters should be included in the parameter list.

std::vector< std::string >	availableParameters () const
	Get the list of all known optimization parameters.

std::vector< std::string >	usedParameters () const
	Get the names of currently used optimization parameters.

bool	setUsedParameters (const std::vector< std::string > &names)
	Set the currently used optimization parameters and the order in which values are expected by setParameters(const std::vector<double>& pars).

void	setDistanceVolume (std::shared_ptr< SharedImageSet > dist)
	Set the distance volume of the skin surface segmentation.

SharedImageSet *	distanceVolume () const
	Return the skin surface distance volume.

Deformation *	clone () const override
	Returns a copy of the deformation.

vec3	displacement (const vec3 &pos) const override
	Returns the displacement for pos (in world coordinates).

bool	isIdentity () const override
	Returns if the current state of the deformation transformations the image or not.

void	setIdentity () override
	Sets all displacements to 0.

int	setIncludeArguments (GL::Program &p, const SharedImage *img, const std::string &prefix) const override
	Override default arguments for GlMask includes.

int	dimension () const override
	Returns the dimension of the deformation.

int	setIncludeArguments (GL::Program &p, const SharedImage *img) const
	Equivalent to setIncludeArguments(p, img, "deform")

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.

void	onDataDeleted (const Data *data)
	If `data` is the same as the internally stored sweep (set by `setProbeParameters(UltrasoundSweep* sweep)`) then reset the stored sweep.

std::string	id () const override
	Returns a unique string identifier for this type of deformation.

Public Member Functions inherited from ParametricDeformation
	ParametricDeformation (const std::string &shaderPath)
	Initializes the parametric deformation with path to the GlInclude file.

	~ParametricDeformation () override
	Destructor.

virtual void	setDisplacement (const std::vector< vec3f > &d)
	Set displacement in mm for all control points if applicable For 2D images the z-coordinate of the displacement is ignored.

virtual std::vector< vec3f >	displacements () const
	Get displacement in mm of all control points if applicable.

virtual std::vector< vec3 >	controlPoints () const
	Returns a list of all control points in world coordinates (might be empty for certain models)

virtual int	numberOfControlPoints () const
	Returns the number of control points (may be zero for certain deformations)

Public Member Functions inherited from Deformation
	Deformation (const std::string &shaderPath)
	Initializes the Deformation with path to the GlInclude file.

virtual vec3	displacement (const vec2 &pos) const
	Returns the displacement at the world position pos.

virtual vec3	displacePoint (const vec3 &point) const
	Returns the displaced position of the given point in world-coordinates.

void	setDisabled (bool flag)
	Set a disabled flag in order to hide the visualization of this deformation.

bool	disabled () const
	Return whether the deformation was set to disabled.

virtual std::unique_ptr< SharedImageSet >	supportingImages () const
	Returns the images that, together with the configuration, defines the deformation.

Public Member Functions inherited from AbstractInclude
	AbstractInclude (const std::string &defineName, const std::string &includePath)
	Creates a AbstractInclude for the given define and with the corresponding GLSL file at includePath.

const std::string &	defineName () const
	Returns the name of define used by this include.

const std::string &	includePath () const
	Returns the path to the included shader file.

virtual std::function< std::string(const std::string &)>	includeCodeSubstitution () const
	Optionally the abstract include can provide a function to change the shader code.

virtual std::vector< AbstractInclude * >	dependentIncludes () const
	Returns a list of dependent abstract includes that need to be included as well.

virtual Fingerprint	fingerprint () const
	Provides a finger print of the include.

Public Member Functions inherited from MultiIncludable< Deformation, const SharedImage * >
std::shared_ptr< MultiIncludeType >	createMultiInclude (const std::string &replacementToken)
	Instantiates a new AbstractInclude instance where all occurrences of baseToken provided during construction are replaces with replacementToken according to the specified replacementScheme.

virtual int	setIncludeArguments (Program &prog, IncludeArgumentsTypes... includeArgs, const std::string &token) const=0
	Interface that multi includes should use to configure the shader include (such as setting uniforms, binding textures, etc).

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

Public Attributes
vec3	m_probePosition = vec3::Zero()
	Position of the compression origin in world coordinates.

double	m_probeRadiusMin = 10.0
	Radius where the change in compression starts.

double	m_probeRadiusMax = 100.0
	Radius where the change in compression ends.

double	m_probeElevRatio = 1.0
	Elevational expansion ratio of probe model.

double	m_defNonLinearity = 0.0
	Non-linearity, higher means more deformed at smaller radius.

double	m_bulgeAmp = 0.0
	Additional bulging away from the central beam axis.

double	m_bulgeShape = 1e-2
	Controls how the amount of bulging scales with depth.

int	m_mode = 0
	Deformation mode (0 = spherical, 1 = ellipsoid, 2 = distance volume, 4 = bulging).

mat3	m_probeMatrix = mat3::Identity()
	Optional rotation and scale matrix for better fit.

double	m_defAmplitude = 0.0
	Amount of the overall compression.

bool	m_probeModify = false
	Add the probe geometry to the serialized parameters.

double	m_bulgeOutOfPlaneFactor = 1.0
	How strongly bulging affects the z axis of the sweep frames.

std::shared_ptr< SharedImageSet >	m_distImg = nullptr
	Optional probe-skin distance image.

GlImage	m_distVolPlaceHolder = {Image::FLOAT, 2, 2, 2}

UltrasoundSweep *	m_sweep = nullptr
	The sweep instance passed by setProbeParameters, for keeping track of the matrix.

Public Attributes inherited from Deformation
Signal< const DeformationEvent & >	signalChanged

Public Attributes inherited from Configurable
Signal	signalParametersChanged
	Emitted whenever one of the registered Parameters' or SubPropertys' `signalValueChanged` signal was emitted.

Virtual Methods Overriding ParametricDeformation
void	setParameters (const std::vector< double > &pars) override
	Sets the deformation parameters in percentage units (scaled by 100).

void	parameters (std::vector< double > &parsOut) const override
	Get the deformation parameters in percent.

int	numberOfParameters () const override
	Equivalent to usedParameters().size()

Additional Inherited Members
Public Types inherited from MultiIncludable< Deformation, const SharedImage * >
using	MultiIncludeType
	Alias for type of a multi-include instance of the original include.

Static Public Member Functions inherited from Deformation
static std::string	defineName ()
	Returns the define name of GlAbstractInclude for all deformations.

static std::string	defineSuffix ()
	Returns "DEFORM".

static std::string	multiIncludeDefine (const std::string &replacementToken)
	Returns `"IMAGE_" + toUpper(replacementToken)`

Protected Member Functions inherited from Deformation
void	notifyListeners (const DeformationEvent &event) const
	convenience function to call `signalChanged.emitSignal(event)`.

Protected Member Functions inherited from MultiIncludable< Deformation, const SharedImage * >
	MultiIncludable (Deformation *crtpInstance, const std::string &baseToken, Flags< ShaderTextReplacement > replacementScheme)
	Instantiate and configure the MultiIncludable interface.

Protected Member Functions inherited from SignalReceiver
void	disconnectAll ()
	Disconnects all existing connections.

Protected Attributes inherited from Deformation
bool	m_disabled
	Disabled flag for visualization.

Protected Attributes inherited from Configurable
std::vector< Param >	m_params
	List of all registered Parameter and SubProperty instances.

Constructor & Destructor Documentation

◆ GlProbeDeformation()

GlProbeDeformation ( std::shared_ptr< SharedImageSet > distImg )

explicit

Constructor taking a distance image, for example, computed by ProbeDeformationAlgorithm.

Note: Constructor accepts nullptr. In that case, the behavior is equivalent to the behavior of the default constructor.

Member Function Documentation

◆ setProbeParameters() [1/2]

void setProbeParameters	(	const vec3 &	position,
		double	radiusMin,
		double	radiusMax )

Set the geometric parameters of the compression model.

Note: If the parameters differ from the original ones then emits DeformationEvent to the listeners of the class.

◆ setProbeParameters() [2/2]

void setProbeParameters ( SharedImageSet * sweepOrVolume )

Set the geometric parameters from an ultrasound sweep instance or a compounded sweep.

Internally checks whether the input is an ultrasound sweep or not, and sets the probe parameters accordingly.

Parameters

sweepOrVolume An ultrasound sweep or a compounded sweep (volume)

Note: When possible it is better to use a sweep rather than a volume

◆ setDeformationParameters()

void setDeformationParameters	(	double	amplitude,
		double	nonLinearity )

Set the variable deformation parameters amplitude and non-linearity.

Note: If parameters differ from the previously held ones then notifies the listeners.

◆ parameter()

double parameter ( const std::string & name ) const

Get the value of the known optimizable parameter with given name.

Returns: The value of the parameter with the given name if such exists and std::numeric_limits<double>::quiet_NaN() otherwise.

◆ setMode()

void setMode ( int mode )

Set internal deformation mode.

Parameters

mode	0 = spherical, 1 = ellipsoid, 2 = distance volume (if available), 4 = bulging

Note: If m_mode differs, emits DeformationEvent::PARAMETER_SET_CHANGED to the listeners.

◆ mode()

int mode ( ) const

inline

Returns: Currently used internal deformation mode

◆ setModifyProbeParameters()

void setModifyProbeParameters ( bool flag )

Sets whether probe parameters should be included in the parameter list.

If set to true, parameters() will return the vector of parameters with additional 5 elements at the tail: probe deformation position (x, y, z) and probe deformation radius (min, max).

Note: Notifies listeners if the flag value changes.

◆ setParameters()

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

overridevirtual

Sets the deformation parameters in percentage units (scaled by 100).

This method overrides setParameters to interpret the input vector pars according to the currently selected deformation mode (set via setMode).

The non-linearity factor and overall compression will be set from pars[0] and pars[1] respectively, if the parameter array contains at least two elements.

Parameter interpretation depends on the mode:

Mode 0 (Spherical) and Mode 1 (Ellipsoid):
- Uses default values for bulging amplitude, shape, and out-of-plane factor.
- Sets probe position: x = pars[2], y = pars[3], z = pars[4].
- Sets minimum and maximum probe radius from pars[5] and pars[6] (if provided).
Mode 2 (Distance Volume):
- Sets the probe elevation ratio from pars[2] (if available).
Mode 4 (Bulging):
- Sets bulging amplitude and out-of-plane factor from pars[2] and pars[3].
- Optionally sets bulging shape from pars[4].

Warning: Ensure the correct mode is set and that the pars vector contains enough elements. Missing or mismatched parameters will be silently ignored.

Reimplemented from ParametricDeformation.

◆ parameters()

void parameters ( std::vector< double > & parsOut ) const

overridevirtual

Get the deformation parameters in percent.

Parameters

parsOut will be assigned to the deformation parameters.

Reimplemented from ParametricDeformation.

◆ numberOfParameters()

int numberOfParameters ( ) const

overridevirtual

Equivalent to usedParameters().size()

Returns: the number of currently active optimization parameters.

Reimplemented from ParametricDeformation.

◆ availableParameters()

std::vector< std::string > availableParameters ( ) const

Get the list of all known optimization parameters.

Returns: std::vector with the names of all optimization parameters available in the current mode.

◆ usedParameters()

std::vector< std::string > usedParameters ( ) const

Get the names of currently used optimization parameters.

Returns: the names of all currently used optimization parameters, in the same order used by setParameters(const std::vector<double>& pars)

◆ setUsedParameters()

bool setUsedParameters ( const std::vector< std::string > & names )

Set the currently used optimization parameters and the order in which values are expected by setParameters(const std::vector<double>& pars).

Returns: false if at least one of the provided parameter names is not available. In this case, no parameters will be set.

◆ clone()

Deformation * clone ( ) const

overridevirtual

Returns a copy of the deformation.

Implements Deformation.

◆ displacement()

vec3 displacement ( const vec3 & pos ) const

overridevirtual

Returns the displacement for pos (in world coordinates).

The returned displacement is also in world coordinates. The displacement indicates where pos originated from before applying the deformation.

Implements Deformation.

◆ isIdentity()

bool isIdentity ( ) const

overridevirtual

Returns if the current state of the deformation transformations the image or not.

Implements Deformation.

◆ setIdentity()

void setIdentity ( )

overridevirtual

Sets all displacements to 0.

Implements Deformation.

◆ setIncludeArguments()

int setIncludeArguments	(	GL::Program &	p,
		const SharedImage *	img,
		const std::string &	prefix ) const

overridevirtual

Override default arguments for GlMask includes.

Implements Deformation.

◆ dimension()

int dimension ( ) const

overridevirtual

Returns the dimension of the deformation.

Implements Deformation.

◆ configure()

void 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 Configurable.

◆ configuration()

void 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 Configurable.

◆ onDataDeleted()

void onDataDeleted ( const Data * data )

If data is the same as the internally stored sweep (set by setProbeParameters(UltrasoundSweep* sweep)) then reset the stored sweep.

Note: This function is used as a callback when the tracked by this class ultrasound sweep gets deleted.

◆ id()

std::string id ( ) const

inlineoverridevirtual

Returns a unique string identifier for this type of deformation.

Usually the name of the class.

Note: To avoid conflicts make sure to include potential plugin names into this ID. Due to the modular architecture of the ImFusion library, uniqueness of IDs cannot be checked at compile time. However, DeformationFactory will check the uniqueness of the ID during registration.

See also: DeformationFactory

Implements Deformation.

Member Data Documentation

◆ m_probePosition

vec3 m_probePosition = vec3::Zero()

Position of the compression origin in world coordinates.

It is configurable by the parameter name "probePosition".

◆ m_probeRadiusMin

double m_probeRadiusMin = 10.0

Radius where the change in compression starts.

It is configurable by the parameter name "probeRadiusMin".

◆ m_probeRadiusMax

double m_probeRadiusMax = 100.0

Radius where the change in compression ends.

It is configurable by the parameter name "probeRadiusMax".

◆ m_probeElevRatio

double m_probeElevRatio = 1.0

Elevational expansion ratio of probe model.

It is configurable by the parameter name "deformationAmplitude".

◆ m_defNonLinearity

double m_defNonLinearity = 0.0

Non-linearity, higher means more deformed at smaller radius.

It is configurable by the parameter name "deformationNonLinearity".

◆ m_bulgeAmp

double m_bulgeAmp = 0.0

Additional bulging away from the central beam axis.

It is configurable by the parameter name "bulgeAmp".

◆ m_bulgeShape

double m_bulgeShape = 1e-2

Controls how the amount of bulging scales with depth.

It is configurable by the parameter name "bulgeShape".

◆ m_mode

int m_mode = 0

Deformation mode (0 = spherical, 1 = ellipsoid, 2 = distance volume, 4 = bulging).

It is configurable by the parameter name "mode".

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

ImFusion/US/GlProbeDeformation.h

Detailed Description

Public Member Functions

Public Attributes

Virtual Methods Overriding ParametricDeformation

Additional Inherited Members

Constructor & Destructor Documentation

◆ GlProbeDeformation()

Member Function Documentation

◆ setProbeParameters() [1/2]

◆ setProbeParameters() [2/2]

◆ setDeformationParameters()

◆ parameter()

◆ setMode()

◆ mode()

◆ setModifyProbeParameters()

◆ setParameters()

◆ parameters()

◆ numberOfParameters()

◆ availableParameters()

◆ usedParameters()

◆ setUsedParameters()

◆ clone()

◆ displacement()

◆ isIdentity()

◆ setIdentity()

◆ setIncludeArguments()

◆ dimension()

◆ configure()

◆ configuration()

◆ onDataDeleted()

◆ id()

Member Data Documentation

◆ m_probePosition

◆ m_probeRadiusMin

◆ m_probeRadiusMax

◆ m_probeElevRatio

◆ m_defNonLinearity

◆ m_bulgeAmp

◆ m_bulgeShape

◆ m_mode