#include <ImFusion/US/UltrasoundSweepRingBuffer.h>

Class for ring buffer version of freehand ultrasound sweep. More...

Inheritance diagram for UltrasoundSweepRingBuffer:

Detailed Description

Class for ring buffer version of freehand ultrasound sweep.

This container behaves as a ring buffer and internally reorders the shared images. The most recent image is always kept at the last index of the shared images vector.

Note: In many use cases, such as live sweep recording, this is just a temporary data structure. Changes to the registration or calibration matrices will only affect the UI, since the value is held in the sweep recorder.

Public Member Functions
	UltrasoundSweepRingBuffer (int bufferSize=50)
	Constructor for creating a sweep ring buffer with a specified maximum buffer size.

virtual void	insert (std::shared_ptr< SharedImage > img, double time)
	Inserts a new image to the ring buffer This method adds the new image, `img`, and its timestamp to the last index of the shared images vector (of SharedImageSet) and removes the oldest image from the buffer if maximum buffer size is reached.

virtual void	insert (std::shared_ptr< SharedImage > img, const mat4 &m)
	Inserts a new image and its transformation to the ring buffer This method adds the new image, `img`, and its transformation to the last index of the shared images vector (of SharedImageSet) and removes the oldest image from the buffer if maximum buffer size is reached.

virtual void	setBufferSize (int bufferSize)
	Sets the maximum size of the ring buffer Old images and tracking data are also deleted if the new buffer size is smaller than the number of available images.

virtual int	bufferSize () const
	Returns the current ring buffer size.

void	trimTrackingData ()
	Removes old tracking data when timestamps are used for tracking synchronization This method deletes all tracking data which their time difference with the oldest buffered image is larger than the bufferTime.

void	setTrimBufferTime (double bufferTime)
	Sets the trimming buffer time for tracking sequences.

void	setTrimAllTrackings (bool trimAll)
	If true, all tracking sequences are trimmed; otherwise, only the used tracking index is trimmed.

void	setAutoTrim (bool autoTrim)
	If true, trimTrackingData() method is called after each image insertion. Default value is true.

void	addTrackingMatrix (mat4 mat, double timestamp, double quality, int buttonStatus, int trackingIndex=-1)
	Thread-safe method to add a tracking matrix.

std::optional< mat4 >	trackingMatrix (double timestamp, int trackingIndex=-1, double *qualityOut=nullptr) const
	Thread-safe method to get a tracking matrix.

std::optional< mat4 >	lastTrackingMatrix (int trackingIndex=-1) const
	Thread-safe method to get the last tracking matrix.

Public Member Functions inherited from UltrasoundSweep
	UltrasoundSweep (const UltrasoundSweep &other)=delete

std::unique_ptr< UltrasoundSweep >	clone (Flags< CloneOptions > cloneOptions=Everything) const
	Create a copy of this UltrasoundSweep instance.

template<typename T>
void	fromVolume (const TypedImage< T > &volume, int dir)
	Fill sweep from a volume along given axis.

const TypedImage< unsigned char > *	typed (int which=-1) const
	Return a selected image from the sweep directly as 8-bit data.

Modality	modality () const override
	Always returns ULTRASOUND.

void	setSize (double sizeX, double sizeY, bool doClearCaches=true) override
	Set the physical image width and height in mm.

void	setFrameGeometry (std::unique_ptr< FrameGeometry > geometry)
	Set the ultrasound frame geometry.

void	setFrameGeometry (const FrameGeometry &geometry)
	Set the ultrasound frame geometry.

std::unique_ptr< FrameGeometry >	frameGeometry (CoordinateSystem cooSystem) const
	Return a copy of the ultrasound frame geometry in the given unit.

const FrameGeometry &	frameGeometry () const
	Return the ultrasound frame geometry, may internally use either pixels or millimeters.

Geometry::AlignedBox	bounds () const override
	Returns the axis-aligned bounding box of all images in world space considering the frame geometry.

void	globalBoundingBox (bool useSelection, bool useFrameGeometry, vec3 &centerOut, vec3 &extOut) const
	Compute global bounding box in world coordinates.

void	localBoundingBox (bool useSelection, bool useFrameGeometry, mat4 &matOut, vec3 &extOut) const
	Compute local bounding box in sweep-aligned coordinates considering the image orientation and sweep direction.

mat4	transformationForAxisAlignment ()
	Compute the transformation to align the images with the mean normal vector of all slices.

Public Member Functions inherited from TrackedSharedImageSet
	TrackedSharedImageSet (const TrackedSharedImageSet &other)=delete

std::unique_ptr< TrackedSharedImageSet >	clone (Flags< CloneOptions > cloneOptions=Everything) const
	Create a copy of this TrackedSharedImageSet instance.

void	add (std::shared_ptr< SharedImage > img) override
	Add a shared image to the data set.

void	swapWithImageSet (SharedImageSet &is)
	Swaps all images, timestamps, and properties from `is`, but does not create any tracking sequence.

DataList	children () const override
	Exposes the tracking sequences if exposesTrackingAsChildren is on.

void	setTimestamp (double time, int which=-1) override
	Set specific or focused timestamp in seconds.

void	remove (int pos, int count=1) override
	Adjusts tracking info when images are removed.

void	removeBefore (double timestamp)
	Removes images and tracking samples before the passed timestamp.

void	addTracking (std::unique_ptr< TrackingSequence > ts)
	Add a tracking sequence, transferring ownership.

std::unique_ptr< TrackingSequence >	removeTracking (int num=-1)
	Removes a tracking sequence from the set.

void	clearTrackings ()
	Deletes all tracking sequences.

TrackingSequence *	tracking (int num=-1)
	Returns a tracking sequence If the desired sequence number is not specified, the currently active one is returned.

const TrackingSequence *	tracking (int num=-1) const
	Returns a tracking sequence If the desired sequence number is not specified, the currently active one is returned.

void	setUseTracking (int val)
	Specify which tracking sequence to use.

void	setUseTimestamps (bool val)
	Define if video-tracking timestamp synchronization is to be used.

int	numTracking () const
	Return the number of available tracking sequences.

bool	hasTransformations () const override
	Return true if the images have transformations.

virtual bool	canSetMatricesIndividually () const
	Return true if it is possible to set image matrices individually, i.e.

int	width () const
	Return the width of an image in pixels.

int	height () const
	Return the height of an image in pixels.

double	sizeX () const
	Return the horizontal extent of an image in mm.

double	sizeY () const
	Return the vertical extent of an image in mm.

int	trackingUsed () const
	Return number of active tracking sequence.

bool	useTimestamps () const
	Return whether timestamps are used for tracking synchronization.

void	clearCaches ()
	Will mark all caches as outdated. Called when the main tracking sequence updates.

bool	exposesTrackingAsChildren () const
	Returns whether the inner tracking sequences should be exposed through the CompoundData interface or not.

void	setExposeTrackingAsChildren (bool value)
	Sets whether the inner tracking sequences should be exposed through the CompoundData interface or not.

double	avgTimestepBetweenImageFrames () const
	Caclulate average timestep between frames.

double	medianTimestepBetweenImageFrames () const
	Calculate median timestep between frames.

void	clear () override
	Clears the tracking information and the cached information, resets all member variables to their default values.

void	clearSharedImageSet ()
	Internally calls SharedImageSet::clear, clearing image-data, time-stamps, properties, signals.

void	add (std::shared_ptr< Image > img)
	Add a single image to the data set.

void	add (std::shared_ptr< Image > img, const mat4 &m)
	Add a single image with its transformation matrix.

void	add (const std::vector< std::shared_ptr< SharedImage > > &images)
	Add a list of shared images.

Pose::TransformationConvention	matrixConvention () const override

void	setMatrix (const mat4 &m, int which, bool updateAll=false) override
	Attempts to update tracking matrices.

mat4	matrix (int which) const override
	Get specific (`which` >=0) or focused (`which` ==-1) image matrix.

void	setMatrix (const mat4 &m) override
	This method just issues a warning since matrices cannot be edited here.

mat4	matrix () const override
	Get the focused image matrix.

void	setMatrixFromWorld (const mat4 &m, int which, bool updateAll=false) override
	Attempts to update tracking matrices.

void	setMatrixToWorld (const mat4 &m, int which, bool updateAll=false) override
	Attempts to update tracking matrices, directly calls setMatrix(const mat4&, int, bool).

mat4	matrixFromWorld (int which) const override
	Get specific (`which` >=0) or focused (`which` ==-1) image matrix mapping from the world coordinate system. Inverse of matrix.

mat4	matrixToWorld (int which) const override
	Get specific (`which` >=0) or focused (`which` ==-1) image matrix mapping to the world coordinate system. Same as matrix.

void	setRegistration (const mat4 &m)
	Sets the registration matrix on the active tracking sequence and invokes transformation listeners.

Public Member Functions inherited from SharedImageSet
	SharedImageSet (std::shared_ptr< Image > img)
	Construct from a single Image.

	SharedImageSet (std::shared_ptr< SharedImage > img)
	Construct from a single SharedImage.

	SharedImageSet ()
	Construct an empty SharedImageSet.

SharedImageSet &	operator= (const SharedImageSet &)=delete

std::unique_ptr< SharedImageSet >	clone (Flags< CloneOptions > cloneOptions=Everything) const
	Create a copy of this SharedImageSet instance.

void	add (std::shared_ptr< Image > img)
	Add a single image to the data set.

void	add (std::shared_ptr< Image > img, const mat4 &m)
	Add a single image with its transformation matrix.

void	add (const std::vector< std::shared_ptr< SharedImage > > &images)
	Add a list of shared images.

bool	replace (int pos, std::shared_ptr< SharedImage > img)
	Replace a particular shared image entry, will not do anything if no image of that index exist yet.

void	remove (const SharedImage *img)
	Removes a specific image and deletes it if owned.

std::string	describe () const override
	Short description of the image set.

void	setModalityOverride (std::optional< Data::Modality > modalityOverride)
	Set a modalityOverride.

virtual void	setModality (Modality m)
	Set image modality for all frames.

virtual bool	isMultiModal () const
	Return true if set contains images of different modalities, false otherwise.

virtual void	prepare (bool shiftOnly=false)
	Prepare the image in memory for most common scenarios Integral types are converted to unsigned representation if applicable, double-precision will be converted to single-precision float.

void	uploadGl () const
	Upload all images as OpenGL textures.

bool	hasMem (int which=-1) const
	Query whether an up-to-date memory image is present. If not, a sync is required.

bool	hasGl (int which=-1) const
	Query whether an up-to-date OpenGL image is present. If not, a sync is required.

const DataComponentList &	components () const
	Returns the list of DataComponents for this data.

DataComponentList &	components ()

const DataComponentList &	components (int i) const
	Returns the DataComponents associated to the element with that index.

virtual SharedImage *	get (int which=-1)
	Get specific or selected shared image.

std::shared_ptr< SharedImage >	getShared (int which=-1)
	Get specific or selected shared image.

MemImage *	mem (int which=-1)
	Get specific or selected image in memory If required image will be synchronized.

GlImage *	gl (int which=-1)
	Get specific or selected OpenGL image If required image will be synchronized.

const std::vector< std::shared_ptr< SharedImage > > &	images ()
	Return entire vector of images.

std::vector< std::shared_ptr< SharedImage > >	selectedImages (Selection::NonePolicy noneSelectionHandling)
	Return vector of all selected images.

virtual const SharedImage *	get (int which=-1) const
	Get specific or selected shared image.

std::shared_ptr< const SharedImage >	getShared (int which=-1) const
	Get specific or selected shared image.

const Image *	img (int which=-1) const
	Get specific or selected image descriptor.

const MemImage *	mem (int which=-1) const
	Get specific or selected image in memory If required image will be synchronized.

const GlImage *	gl (int which=-1) const
	Get specific or selected OpenGL image If required image will be synchronized.

std::vector< std::shared_ptr< const SharedImage > >	images () const
	Return entire vector of images.

std::vector< std::shared_ptr< const SharedImage > >	selectedImages (Selection::NonePolicy noneSelectionHandling) const
	Return vector of all selected images.

virtual void	setDeformation (std::shared_ptr< Deformation > def, int which=-1)
	Sets a deformation for specified or focus image.

virtual std::shared_ptr< Deformation >	deformation (int which=-1) const
	Returns the deformation for the specified or focused image, or 0 if not deformation is set.

virtual void	setMask (std::shared_ptr< Mask > mask, int which=-1)
	Sets a mask for specified or focus image.

virtual std::shared_ptr< Mask >	mask (int which=-1) const
	Returns the mask for the specified or focused image, or 0 if not mask is set.

virtual mat4	matrixFromWorld () const
	Get matrix mapping from the world coordinate system to the data coordinate system.

virtual mat4	matrixToWorld () const
	Get matrix mapping from the data coordinate system to the world coordinate system.

virtual void	setMatrixFromWorld (const mat4 &m)
	Set matrix mapping from the world coordinate system to the data coordinate system.

virtual void	setMatrixToWorld (const mat4 &m)
	Set matrix mapping from the data coordinate system to the world coordinate system.

double	timestamp (int which=-1) const
	Get specific or focused timestamp in seconds.

const std::vector< double >	timestamps () const
	Get the timestamps sequence.

bool	hasTimestamps () const
	Return if all image frames have timestamps.

int	size () const override
	Return the size of the image set.

bool	allEqual () const
	Return if all image descriptors are the same.

Kind	kind () const override
	Return the kind of data contained here.

Properties *	properties ()
	Return auxiliary data structures stored in Properties.

const Properties *	properties () const
	Return auxiliary data structures stored in Properties.

Public Member Functions inherited from Data
	Data (const std::string &name="")

	Data (const Data &other)

Data &	operator= (const Data &other)

virtual	~Data ()
	Mandatory virtual destructor.

const std::string &	name () const
	Return the name of this data.

void	setName (const std::string &name)
	Sets the name of this data.

virtual bool	isAnnotationType () const
	Return whether this data type is visualized through an annotation (e.g. mesh)

const DataComponentList &	components () const
	Returns the list of DataComponents for this data.

DataComponentList &	components ()

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 Member Functions inherited from ElementwiseDataComponentData
ElementwiseDataComponentList &	elementwiseComponents ()
	Returns elementwise data component list.

const ElementwiseDataComponentList &	elementwiseComponents () const
	Returns elementwise data component list.

DataComponentList &	mutableComponents (int i)
	Returns the DataComponents associated to the element with that index, creating it if necessary.

const DataComponentList &	components (int i) const
	Returns the DataComponents associated to the element with that index.

Public Member Functions inherited from Selectable
	Selectable (const Selectable &)

	Selectable (Selectable &&)

Selectable &	operator= (const Selectable &)

Selectable &	operator= (Selectable &&)

virtual Selection	selection () const

virtual int	focus () const

virtual void	setSelection (const Selection &sel)
	Set the underlying selection.

virtual void	setFocus (int index)
	Set focus of the selection.

Public Attributes
Signal	signalImageAdded
	Signal emitted when a new image has been added.

Public Attributes inherited from UltrasoundSweep
Signal< const UltrasoundSweep * >	signalFrameGeometryChanged

Public Attributes inherited from TrackedSharedImageSet
Signal< const TrackedSharedImageSet * >	signalUsedTrackingSequenceChanged
	Signal emitted when the used tracking sequence changed or reset due to deletion.

Public Attributes inherited from Data
Signal< const Data * >	signalDeleted
	Signal emitted when this instance is deleted.

Signal< const Data * >	signalMatrixChanged
	Signal emitted when the transformation of this Data has changed.

Signal< std::string >	signalNameChanged
	Signal emitted when the name changed.

Public Attributes inherited from Selectable
ProtectedSignal	signalSelectionChanged
	Signals that the selection or size might have changed.

Public Attributes inherited from CompoundData
Signal< Data * >	signalChildAdded
	Signal emitted when a new Data instance has been added to children()

Signal< Data * >	signalChildMoved
	Signal emitted when a Data instance has changed its position in children()

Signal< Data * >	signalChildAboutToBeRemoved
	Signal emitted when a Data instance is about to be removed or taken from children()

Protected Member Functions
void	addImageToBuffer (std::shared_ptr< SharedImage > img)
	Adds the `img` to SharedImage vector and removes old images if the buffer is full.

Protected Member Functions inherited from UltrasoundSweep
mat4	mainAxisTransformation (bool useSelelection, bool useFrameGeometry) const
	Compute the transformation to align the sweep with the world coordinate system (sweep direction in z-direction).

Geometry::AlignedBox	boundingBox (bool useSelection, bool useFrameGeometry, const mat4 &mainAxisInverse) const
	Compute the bounding box of the sweep with an optional main axis transformation.

UltrasoundSweep *	createCloneContainer () const override
	Internal method for creating the container object holding the clone.

Protected Member Functions inherited from TrackedSharedImageSet
void	convertToGray (TypedImage< unsigned char > **img) const
	Convert a 3 or 4-channel image to gray-scale, see createGrayscale.

void	cloneInternal (SharedImageSet &other, Flags< CloneOptions > cloneFlags) const override
	Internal method for cloning which should be called from derived container classes.

Protected Member Functions inherited from SharedImageSet
virtual void	swapWith (SharedImageSet &other)
	Internal method for swapping the contents of this container with `other`.

Protected Member Functions inherited from Data
void	swapWith (Data &other)
	Swaps the data and emits a matrix and name changed signal for both.

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

Protected Attributes
int	m_bufferSize = 50
	Maximum size of the ring buffer for the images.

bool	m_autoTrim = true
	If true, tracking sequences are automatically trimmed after each image insertion.

bool	m_trimAllTrackings = true
	If true, all tracking sequences are trimmed; otherwise, only the used tracking index is trimmed.

double	m_trimBufferTime = 5
	Buffer time in [s] for trimming old tracking data.

std::recursive_mutex	m_bufferMutex

std::recursive_mutex	m_trackingBufferMutex

Protected Attributes inherited from SharedImageSet
std::vector< std::shared_ptr< SharedImage > >	m_images
	Vector of shared image pointers.

std::vector< double >	m_timestamps
	Optional timestamps of the image frames.

Properties	m_properties
	Auxiliary information properties.

Geometry::AlignedBox	m_bounds
	Axis-aligned bounding box of all images in world space.

bool	m_updateBounds = true
	Flag specifying whether the bounds should be re-computed.

std::optional< Data::Modality >	m_modalityOverride
	Overrides the modality of the containing SharedImages. This is used e.g. for the ConeBeamData concept in CT.

Protected Attributes inherited from Data
mat4	m_matrix
	Transformation matrix.

std::recursive_mutex *	m_matrixMutex
	Used to internally synchronize access to the matrix of data.

DataComponentList	m_dataComponentList
	The list of DataComponents for this data.

Protected Attributes inherited from ElementwiseDataComponentData
ElementwiseDataComponentList	m_elementwiseComponents
	Encodes elementwise data components.

Protected Attributes inherited from Selectable
std::mutex	m_selectionMutex
	Mutex protecting the selection.

Selection	m_sel

Additional Inherited Members
Public Types inherited from SharedImageSet
enum	CloneOptions { Everything = 0 , NoImageData = 1 << 0 , NoDataComponents = 1 << 1 , ShallowImageCopy = 1 << 2 , NoSelection = 1 << 3 , NoTracking = 1 << 4 }
	Bitset enumeration to configure which aspects of a SharedImageSet to copy. More...

Public Types inherited from Data
enum	Kind { UNKNOWN = 0 , IMAGE = 1 , VOLUME = 2 , IMAGESET = 3 , VOLUMESET = 4 , IMAGESTREAM = 5 , VOLUMESTREAM = 6 , POINTSET = 7 , SURFACE = 8 , TRACKINGSTREAM = 9 , LIVETRACKINGSTREAM = TRACKINGSTREAM , TRACKINGDATA = 10 , TREE = 11 , TENSOR = 12 , POLYDATASTREAM = 13 , STEREOIMAGESET = 14 , STEREOIMAGESTREAM = 15 , VOLUMETRICMESH = 16 }
	Kind of data. More...

enum	Modality { NA = 0 , XRAY = 1 , CT = 2 , MRI = 3 , ULTRASOUND = 4 , VIDEO = 5 , NM = 6 , OCT = 7 , LABEL = 8 , DISTANCE = 9 }
	Image modality of the data. More...

Static Public Member Functions inherited from Data
static std::string	modalityString (Data::Modality m)
	Return the name of an image modality.

static Data::Modality	stringToModality (const std::string &s)
	Returns the modality corresponding to a modality string or NA if nothing matches.

Constructor & Destructor Documentation

◆ UltrasoundSweepRingBuffer()

UltrasoundSweepRingBuffer ( int bufferSize = 50 )

Constructor for creating a sweep ring buffer with a specified maximum buffer size.

This constructor initializes the ring buffer. The buffer maximum size must be a positive integer. If a non-positive value is provided, an exception will be thrown to indicate invalid input.

Exceptions

std::invalid_argument if bufferSize is non-positive

Member Function Documentation

◆ insert() [1/2]

virtual void insert	(	std::shared_ptr< SharedImage >	img,
		double	time )

virtual

Inserts a new image to the ring buffer This method adds the new image, img, and its timestamp to the last index of the shared images vector (of SharedImageSet) and removes the oldest image from the buffer if maximum buffer size is reached.

Call this method when the tracking sequences are using timestamp synchronization; otherwise, the insert method with tracking matrix must be called.

Note: When the auto-trim option is set, the trimTrackingData() method is called after each image insertion. If the auto trim is off, trimTrackingData() should be called manually; otherwise, old tracking information are not deleted by this class.; This method is thread-safe and reentrant. However, manipulating tracking sequences or the image vector of this object, while this method is being executed, can result in race condition.

Parameters

img	The new image to be added to the ring buffer. Ownership is transferred to this class.
time	Timestamp of the image

◆ insert() [2/2]

virtual void insert	(	std::shared_ptr< SharedImage >	img,
		const mat4 &	m )

virtual

Inserts a new image and its transformation to the ring buffer This method adds the new image, img, and its transformation to the last index of the shared images vector (of SharedImageSet) and removes the oldest image from the buffer if maximum buffer size is reached.

Call this method when timestamps are not used for tracking data synchronization; otherwise, the insert method with the timestamp must be called.

Note: Old tracking data are automatically deleted by this method when the buffer is full.; This method is thread-safe and reentrant. However, manipulating tracking sequences or the image vector of this object, while this method is being executed, can result in race condition.

Parameters

img	The new image to be added to the ring buffer. Ownership is transferred to this class.
m	Transformation matrix of the image.

◆ setBufferSize()

virtual void setBufferSize ( int bufferSize )

virtual

Sets the maximum size of the ring buffer Old images and tracking data are also deleted if the new buffer size is smaller than the number of available images.

In the case of deletion, if the auto trim option is set, the trimTrackingData() method is automatically called after this method.

Note: This method is thread-safe and reentrant. But if the new buffer size is smaller than the number of available images, manipulating tracking sequences or the image vector of this object, while this method is being executed, can result in race condition.

◆ setTrimBufferTime()

void setTrimBufferTime ( double bufferTime )

Sets the trimming buffer time for tracking sequences.

Parameters

bufferTime Trimming buffer time; the unit of this parameter must be the same as the tracking sequences timestamp unit, default unit is [s], and default value is 5. Must be positive.

◆ setTrimAllTrackings()

void setTrimAllTrackings ( bool trimAll )

If true, all tracking sequences are trimmed; otherwise, only the used tracking index is trimmed.

Default value is true.

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

ImFusion/US/UltrasoundSweepRingBuffer.h

Detailed Description

Public Member Functions

Public Attributes

Protected Member Functions

Protected Attributes

Additional Inherited Members

Constructor & Destructor Documentation

◆ UltrasoundSweepRingBuffer()

Member Function Documentation

◆ insert() [1/2]

◆ insert() [2/2]

◆ setBufferSize()

◆ setTrimBufferTime()

◆ setTrimAllTrackings()