#include <ImFusion/US/FrameGeometry.h>

Represents the (fan) geometry of an ultrasound frame acquired through scanline-based imaging. More...

Inheritance diagram for FrameGeometry:

Detailed Description

Represents the (fan) geometry of an ultrasound frame acquired through scanline-based imaging.

Currently, there are four types of possible frame geometries:

Linear: The scanlines are parallel to each other and originate from a flat transducer array, i.e. shaped like a parallelogram.
Convex: The scanlines diverge from a virtual center point somewhere inside or behind a curved transducer array, i.e. shaped like a ring sector.
Sector: The scanlines diverge from a virtual center point somewhere inside or behind a linear transducer array, i.e. shaped like a trapezoid, with an optionally round bottom.
Circular: The scanlines extend radially from a center point up to a given radius. Unlike the other two geometries above, the offset is the center of ring.

The linear geometry looks like this:

Linear frame geometry

In contrast, sector and convex geometries are defined in the following way:

Convex (orange) and sector (blue) frame geometries

The circular geometry represents a simple circle.

Each of these types are implemented in separate derived classes. They share the following common properties:

Both image and pixel coordinates are supported. At construction, one of the two need to be assigned. The convertTo() method can be used to convert between the two, given that an image descriptor (with dimensions and spacing) is known to the object.
The offset is the center of the transducer array in the selected coordinate system. Since ultrasound frames assume a top-left image orientation, i.e. the pixel (0,0) is in the top-left corner, this means that the offset is given relative to the image's center when image coordinates are used, or relative to the top-left corner when pixel coordinates are used.
All geometries can be defined in a top-down or a bottom-up fashion. For instance, in prostate US images, the general convention is that the transducer array is displayed at the bottom of the image.
The orientation indicator position refers to where the little colored knob is on the US transducer. This serves clinicians as a landmark to figure out where the patient's left and right side are relative to how they are holding the probe. It only influences how the US ruler triangle is rendered and is purely cosmetic.

The class combines all internal computations for drawing the frame geometry into the views, and to provide manipulators for intuitive parameter changes.

Use an instance of the class FrameGeometryMetadata as a value-type member in algorithms, if you want the frame geometry to be configurable.

Classes
struct	Fan
	Helper struct for drawing the fan and fan manipulation. More...

Public Types
enum class	OrientationIndicatorPosition { Nearside = 0 , Farside = 1 }
	Position of external orientation indicator (e.g. colored knob) More...

enum class	TransformationMode { NormalizedRawToScanConverted = 0 , NormalizedPrescanToScanConverted = 0 , ScanConvertedToNormalizedRaw = 1 , ScanConvertedToNormalizedPrescan = 1 }
	Used in transformPoint() to specify which geometric transformation to apply. More...

Public Member Functions
	FrameGeometry (CoordinateSystem coordSys)
	Constructor requires the coordinate system to be defined. It cannot be changed afterward.

virtual bool	operator== (const FrameGeometry &rhs) const
	Checks for equality, also considering the image descriptor.

bool	operator!= (const FrameGeometry &rhs) const
	Checks for inequality, also considering the image descriptor.

vec2	offset () const
	Offset of the geometry within the image.

void	setOffset (const vec2 &offset)
	Sets the offset of the geometry.

bool	isTopDown () const
	Returns if the geometry is oriented top to bottom, where the frame geometry origin is higher on the image than the end.

void	setTopDown (bool b)
	Sets if the geometry is oriented top to bottom, or bottom to top.

const ImageDescriptor &	imgDesc () const
	Returns the ImageDescriptor for the frame geometry.

const ImageDescriptor &	imgDescPrescan () const
	Returns the ImageDescriptor for the pre-scanconverted image.

void	setImgDesc (const ImageDescriptor &imgDescr)
	Sets the ImageDescriptor for the frame geometry.

void	setImgDescPrescan (const ImageDescriptor &imgDescrPrescan)
	Sets the ImageDescriptor for the pre-scanconverted image.

OrientationIndicatorPosition	indicatorPos () const
	Returns the OrientationIndicatorPosition for the frame geometry.

void	setIndicatorPos (OrientationIndicatorPosition pos)
	Sets the OrientationIndicatorPosition for the frame geometry.

CoordinateSystem	coordinateSystem () const
	Returns the CoordinateSystem used in the frame geometry.

Geometry::AlignedBox	bounds () const
	Returns the Bounds of the frame geometry.

mat4	transformation () const
	Convenience method to get the 2D transformation formed by the offset and orientation.

virtual std::unique_ptr< FrameGeometry >	convertTo (CoordinateSystem coordSys) const
	Returns a copy where internal values were converted to new units.

virtual std::unique_ptr< FrameGeometry >	clone () const =0
	Clones the current frame geometry, including the image descriptor.

virtual vec2	transformPoint (const vec2 &p, TransformationMode mode) const =0
	Applies the specified geometric transformation to a point.

virtual std::unique_ptr< GlGeometricTransform >	glGeometricTransform () const
	Returns the geometric transformation between image coordinates and pre-scan converted coordinates, if available.

virtual bool	contains (vec2 coord) const =0
	Returns true if the given point is within the fan.

virtual double	depth () const =0
	Returns the depth.

virtual vec2	frameCenter () const
	Returns the center of the frame.

virtual void	setDepth (double newDepth)=0
	Sets a new depth. If the depth is derived from multiple members, the bottom one will be changed, i.e. the top remains fixed.

bool	isLinear () const
	Convenience type check.

bool	isCircular () const
	Convenience type check.

bool	isConvex () const
	Convenience type check.

bool	isSector () const
	Convenience type check.

virtual FrameGeometryLinear *	asLinear ()
	Convenience cast to the derived type, or nullptr if not possible.

virtual FrameGeometryConvex *	asConvex ()
	Convenience cast to the derived type, or nullptr if not possible.

virtual FrameGeometryConvexSteered *	asConvexSteered ()

virtual FrameGeometrySector *	asSector ()
	Convenience cast to the derived type, or nullptr if not possible.

virtual FrameGeometryCircular *	asCircular ()
	Convenience cast to the derived type, or nullptr if not possible.

const FrameGeometryLinear *	asLinear () const
	Convenience cast to the derived type, or nullptr if not possible.

const FrameGeometryConvex *	asConvex () const
	Convenience cast to the derived type, or nullptr if not possible.

const FrameGeometryConvexSteered *	asConvexSteered () const

const FrameGeometrySector *	asSector () const
	Convenience cast to the derived type, or nullptr if not possible.

const FrameGeometryCircular *	asCircular () const
	Convenience cast to the derived type, or nullptr if not possible.

virtual bool	isSimilar (const FrameGeometry *other, bool ignoreOffset=false, double eps=1e-1) const =0
	Compares the frame geometry to another one.

virtual FrameGeometry::Fan	createFan ()
	Computes the fan geometry edges and points.

Protected Member Functions
virtual FrameGeometry::Fan	createFanImpl ()=0
	Internal fan geometry generation to be implemented by subclass.

void	configure (const Properties *) override
	Sets general properties. Only intended to be called from derived classes. See FrameGeometryMetadata.

void	configuration (Properties *) const override
	Retrieves general properties. Only intended to be called from derived classes. See FrameGeometryMetadata.

void	onCenterChanged (vec2 delta)
	Manipulation callback.

vec2	conversionSpacing () const
	Internal helper methods returning the spacing or its inverse, dependent on the current coordinate system, either as vec2, are as the diagonal of a 2x2 matrix.

mat2	localCoordinateFrame () const

Protected 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
vec2	m_offset = vec2::Zero()
	location of the fan center (virtual apex) wrt. transducer center (image top)

bool	m_isTopDown = true
	Orientation of fan.

OrientationIndicatorPosition	m_indicatorPosition
	Position of the external orientation indicator.

CoordinateSystem	m_coordSys = CoordinateSystem::Image
	Coordinate system this geometry is defined in.

ImageDescriptor	m_imgDesc
	Image descriptor for frame conversion.

ImageDescriptor	m_imgDescPrescan
	Image descriptor for pre-scanconverted image conversion.

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

Signal	signalParametersChanged
	Emitted whenever one of the registered Parameters' or SubPropertys' `signalValueChanged` signal was emitted.

Static Protected Attributes
static constexpr double	m_insetEpsilon = 1e-7
	Inset distance to avoid numerical errors when computing frame boundaries.

Member Enumeration Documentation

◆ OrientationIndicatorPosition

enum class OrientationIndicatorPosition

strong

Position of external orientation indicator (e.g. colored knob)

Enumerator
Nearside	Indicator is at the near side of the US frame (close to the first beam)
Farside	Indicator is at the far side of the US frame (close to the last beam)

◆ TransformationMode

enum class TransformationMode

strong

Used in transformPoint() to specify which geometric transformation to apply.

Enumerator
NormalizedRawToScanConverted	Non-scan-converted to scan-converted.
NormalizedPrescanToScanConverted	Non-scan-converted to scan-converted.
ScanConvertedToNormalizedRaw	Scan-converted to non-scan-converted.
ScanConvertedToNormalizedPrescan	Scan-converted to non-scan-converted.

Member Function Documentation

◆ operator==()

virtual bool operator== ( const FrameGeometry & rhs ) const

virtual

Checks for equality, also considering the image descriptor.

Reimplemented in FrameGeometryCircular, FrameGeometryConvex, FrameGeometryConvexSteered, FrameGeometryLinear, and FrameGeometrySector.

◆ offset()

vec2 offset ( ) const

Offset of the geometry within the image.

In image coordinates, this is the distance from the center of the image to the center of the geometry. In pixel coordinates, this is the distance from the top-left corner of the image to the top-left corner of the geometry.

◆ setOffset()

void setOffset ( const vec2 & offset )

Sets the offset of the geometry.

In image coordinates, this is the distance from the center of the image to the center of the geometry. In pixel coordinates, this is the distance from the top-left corner of the image to the top-left corner of the geometry.

◆ convertTo()

virtual std::unique_ptr< FrameGeometry > convertTo ( CoordinateSystem coordSys ) const

virtual

Returns a copy where internal values were converted to new units.

The image descriptor of the object is used for the conversion.

Exceptions

std::runtime_error if image descriptor is not valid.

Reimplemented in FrameGeometryCircular, FrameGeometryConvex, FrameGeometryConvexSteered, FrameGeometryLinear, and FrameGeometrySector.

◆ clone()

virtual std::unique_ptr< FrameGeometry > clone ( ) const

pure virtual

Clones the current frame geometry, including the image descriptor.

Implemented in FrameGeometryCircular, FrameGeometryConvex, FrameGeometryConvexSteered, FrameGeometryLinear, and FrameGeometrySector.

◆ transformPoint()

virtual vec2 transformPoint	(	const vec2 &	p,
		TransformationMode	mode ) const

pure virtual

Applies the specified geometric transformation to a point.

Implemented in FrameGeometryCircular, FrameGeometryConvex, FrameGeometryConvexSteered, FrameGeometryLinear, and FrameGeometrySector.

◆ glGeometricTransform()

virtual std::unique_ptr< GlGeometricTransform > glGeometricTransform ( ) const

virtual

Returns the geometric transformation between image coordinates and pre-scan converted coordinates, if available.

Reimplemented in FrameGeometryConvex, FrameGeometryConvexSteered, FrameGeometryLinear, and FrameGeometrySector.

◆ contains()

virtual bool contains ( vec2 coord ) const

pure virtual

Returns true if the given point is within the fan.

Note that whenever angular computations are made, these should be done in the image coordinate system to avoid errors when non-isotropic spacing is used.

Implemented in FrameGeometryCircular, FrameGeometryConvex, FrameGeometryConvexSteered, FrameGeometryLinear, and FrameGeometrySector.

◆ depth()

virtual double depth ( ) const

pure virtual

Returns the depth.

Implemented in FrameGeometryCircular, FrameGeometryConvex, FrameGeometryConvexSteered, FrameGeometryLinear, and FrameGeometrySector.

◆ frameCenter()

virtual vec2 frameCenter ( ) const

virtual

Returns the center of the frame.

Reimplemented in FrameGeometryCircular, and FrameGeometryLinear.

◆ setDepth()

virtual void setDepth ( double newDepth )

pure virtual

Sets a new depth. If the depth is derived from multiple members, the bottom one will be changed, i.e. the top remains fixed.

Implemented in FrameGeometryCircular, FrameGeometryConvex, FrameGeometryConvexSteered, FrameGeometryLinear, and FrameGeometrySector.

◆ asLinear() [1/2]

virtual FrameGeometryLinear * asLinear ( )

virtual

Convenience cast to the derived type, or nullptr if not possible.

Reimplemented in FrameGeometryLinear.

◆ asConvex() [1/2]

virtual FrameGeometryConvex * asConvex ( )

virtual

Convenience cast to the derived type, or nullptr if not possible.

Reimplemented in FrameGeometryConvex.

◆ asConvexSteered() [1/2]

virtual FrameGeometryConvexSteered * asConvexSteered ( )

virtual

Reimplemented in FrameGeometryConvexSteered.

◆ asSector() [1/2]

virtual FrameGeometrySector * asSector ( )

virtual

Convenience cast to the derived type, or nullptr if not possible.

Reimplemented in FrameGeometrySector.

◆ asCircular() [1/2]

virtual FrameGeometryCircular * asCircular ( )

virtual

Convenience cast to the derived type, or nullptr if not possible.

Reimplemented in FrameGeometryCircular.

◆ asLinear() [2/2]

const FrameGeometryLinear * asLinear ( ) const

Convenience cast to the derived type, or nullptr if not possible.

◆ asConvex() [2/2]

const FrameGeometryConvex * asConvex ( ) const

Convenience cast to the derived type, or nullptr if not possible.

◆ asConvexSteered() [2/2]

const FrameGeometryConvexSteered * asConvexSteered ( ) const

◆ asSector() [2/2]

const FrameGeometrySector * asSector ( ) const

Convenience cast to the derived type, or nullptr if not possible.

◆ asCircular() [2/2]

const FrameGeometryCircular * asCircular ( ) const

Convenience cast to the derived type, or nullptr if not possible.

◆ isSimilar()

virtual bool isSimilar	(	const FrameGeometry *	other,
		bool	ignoreOffset = false,
		double	eps = 1e-1 ) const

pure virtual

Compares the frame geometry to another one.

Implemented in FrameGeometryCircular, FrameGeometryConvex, FrameGeometryConvexSteered, FrameGeometryLinear, and FrameGeometrySector.

◆ createFan()

virtual FrameGeometry::Fan createFan ( )

virtual

Computes the fan geometry edges and points.

Reimplemented in FrameGeometryConvexSteered.

◆ createFanImpl()

virtual FrameGeometry::Fan createFanImpl ( )

protectedpure virtual

Internal fan geometry generation to be implemented by subclass.

Implemented in FrameGeometryCircular, FrameGeometryConvex, FrameGeometryConvexSteered, FrameGeometryLinear, and FrameGeometrySector.

◆ configure()

void configure ( const Properties * )

overrideprotectedvirtual

Sets general properties. Only intended to be called from derived classes. See FrameGeometryMetadata.

Reimplemented from Configurable.

Reimplemented in FrameGeometryCircular, FrameGeometryConvex, FrameGeometryConvexSteered, FrameGeometryLinear, and FrameGeometrySector.

◆ configuration()

void configuration ( Properties * ) const

overrideprotectedvirtual

Retrieves general properties. Only intended to be called from derived classes. See FrameGeometryMetadata.

Reimplemented from Configurable.

Reimplemented in FrameGeometryCircular, FrameGeometryConvex, FrameGeometryConvexSteered, FrameGeometryLinear, and FrameGeometrySector.

Member Data Documentation

◆ m_indicatorPosition

OrientationIndicatorPosition m_indicatorPosition

protected

Initial value:

=

OrientationIndicatorPosition::Nearside

ImFusion::US::FrameGeometry::OrientationIndicatorPosition::Nearside

@ Nearside

Indicator is at the near side of the US frame (close to the first beam)

Definition FrameGeometry.h:85

Position of the external orientation indicator.

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

ImFusion/US/FrameGeometry.h

Detailed Description

Classes

Public Types

Public Member Functions

Protected Member Functions

Protected Attributes

Static Protected Attributes

Member Enumeration Documentation

◆ OrientationIndicatorPosition

◆ TransformationMode

Member Function Documentation

◆ operator==()

◆ offset()

◆ setOffset()

◆ convertTo()

◆ clone()

◆ transformPoint()

◆ glGeometricTransform()

◆ contains()

◆ depth()

◆ frameCenter()

◆ setDepth()

◆ asLinear() [1/2]

◆ asConvex() [1/2]

◆ asConvexSteered() [1/2]

◆ asSector() [1/2]

◆ asCircular() [1/2]

◆ asLinear() [2/2]

◆ asConvex() [2/2]

◆ asConvexSteered() [2/2]

◆ asSector() [2/2]

◆ asCircular() [2/2]

◆ isSimilar()

◆ createFan()

◆ createFanImpl()

◆ configure()

◆ configuration()

Member Data Documentation

◆ m_indicatorPosition