ImFusion SDK 4.3
Stream Class Referenceabstract

#include <ImFusion/Stream/Stream.h>

Base class representing a stream of changing data in the DataModel. More...

+ Inheritance diagram for Stream:

Detailed Description

Base class representing a stream of changing data in the DataModel.

Streams are used to represent data that is continuously changing over time, such as video and ultrasound image streams, sensor data, or any other time-dependent data. They differ from other Data (especially TrackingSequence and SharedImageSet) in that they are not finite collections of data, but rather a continuous flow of data that can be processed in real-time.

The main way of consuming data from a Stream is by connecting to the signalStreamData signal, which is emitted whenever new data is available. For example, you can connect a slot to this signal to update a display widget with the latest data from the stream.

Note
For ImageStreams, the ImageStreamCache can be used when only occasional access to the latest data is needed. However, this is not intended for real-time processing.

The data emitted by the Stream must be a subclass of StreamData and depending on the type of Stream (see kind()), it is expected to emit different types of StreamData:

All Streams follow a state machine, where the states correspond to the lifecycle of the stream:

  • Closed: The stream is not open and not running.
  • Open: The stream is open and ready to be started, but not yet running.
  • Running: The stream is running and producing data.
  • Paused: The stream is paused and not producing data. The stream can be in one of these states at any time, and can transition between them, with corresponding intermediate states.

When implementing a Stream, you need to specify the desired threading mode as well as override the openImpl(), closeImpl(), startImpl(), and stopImpl() methods to perform the appropriate actions (e.g. open connection to a hardware device).

See also
Stream::threadingMode()
Stream::doWork()
Stream::workerThreadRequiresOpenGl()
Examples
ExampleStreams.cpp.

Classes

struct  StateChange
 
struct  WorkContinuation
 

Public Types

enum class  ThreadingMode { BaseClassRunsWorkerThread , DerivedClassHandlesThreading }
 This flag represents the two supported threading modes of a Stream. More...
 
enum class  State {
  Closed , Opening , Open , Starting ,
  Running , Pausing , Paused , Resuming ,
  Stopping , Closing
}
 
- 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...
 

Public Member Functions

 Stream (const std::string &name="")
 Constructor with the name for this stream.
 
virtual ThreadingMode threadingMode () const
 Configures threading mode of stream.
 
virtual bool supportsAsyncOperation ()
 Returns true if xxxAsync() methods support execution in a background thread.
 
std::shared_future< bool > openAsync ()
 Open stream in an asynchronous fashion (wait on the returned future before taking further actions). Returns whether the operation was successful.
 
std::shared_future< bool > closeAsync ()
 Close stream in an asynchronous fashion (wait on the returned future before taking further actions). Returns whether the operation was successful.
 
std::shared_future< bool > startAsync ()
 Start stream in an asynchronous fashion (wait on the returned future before taking further actions). Returns whether the operation was successful.
 
std::shared_future< bool > stopAsync ()
 Stop stream in an asynchronous fashion (wait on the returned future before taking further actions). Returns whether the operation was successful.
 
std::shared_future< bool > pauseAsync ()
 Pause stream in an asynchronous fashion (wait on the returned future before taking further actions). Returns whether the operation was successful.
 
std::shared_future< bool > resumeAsync ()
 Resume stream in an asynchronous fashion (wait on the returned future before taking further actions). Returns whether the operation was successful.
 
bool open ()
 Open stream and wait for the operation to complete. Returns whether the operation was successful.
 
bool close ()
 Close stream and wait for the operation to complete. Returns whether the operation was successful.
 
bool start ()
 Start stream and wait for the operation to complete. Returns whether the operation was successful.
 
bool stop ()
 Stop stream and wait for the operation to complete. Returns whether the operation was successful.
 
bool pause ()
 Pause stream and wait for the operation to complete. Returns whether the operation was successful.
 
bool resume ()
 Resume stream and wait for the operation to complete. Returns whether the operation was successful.
 
virtual bool supportsPausing () const
 Override and return true if this stream implements the pausing and resume operations.
 
bool restart ()
 Stops, closes, opens and starts the stream. Returns whether the operation was successful.
 
virtual bool reset ()
 Reverts stream to first frame, if possible. Returns whether the operation was successful.
 
virtual bool isRunning () const
 Return whether stream is currently running.
 
virtual std::string uuid ()=0
 Unique identifier for stream.
 
State currentState () const
 
bool isStateOneOf (const std::vector< State > &states) const
 
Geometry::AlignedBox bounds () const override
 Per default a Stream has empty/invalid bounds.
 
Pose::TransformationConvention matrixConvention () const override
 Matrices of streams by default map to the world coordinate system.
 
virtual bool createDefaultStreamController ()
 Indicates whether a StreamController should be created for the stream (by default returns true).
 
double updateRate () const
 Average update rate in Hz of the signalStreamData.
 
std::string describe () const override
 Short description of the stream including latest state and update rate information.
 
- Public Member Functions inherited from Data
 Data (const std::string &name="")
 
 Data (const Data &other)
 
Dataoperator= (const Data &other)
 
virtual ~Data ()
 Mandatory virtual destructor.
 
virtual Kind kind () const =0
 Return the kind of this data.
 
virtual Modality modality () const
 Return the modality of this data.
 
const std::stringname () 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 DataComponentListcomponents () const
 Returns the list of DataComponents for this data.
 
DataComponentListcomponents ()
 
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.
 
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 mat4 matrix () const
 Return the transformation matrix.
 
virtual void setMatrix (const mat4 &m)
 Set the transformation matrix.
 
- Public Member Functions inherited from Configurable
virtual void configure (const Properties *p)
 Configure this object instance by de-serializing the given Properties.
 
virtual void configuration (Properties *p) const
 Serialize the current object configuration into the given Properties object.
 
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
 
Configurableoperator= (const Configurable &)
 
Configurableoperator= (Configurable &&) noexcept
 

Static Public Member Functions

static std::string stateToString (State state)
 
- 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.
 

Public Attributes

ProtectedSignal< StateChangesignalStateChanged
 Emitted after a state change has been completed with the old and new state.
 
ProtectedSignal signalEnded
 Indicates that the stream reached the end of its data, e.g. when a video stream has played to the end.
 
ProtectedSignal< std::shared_ptr< const StreamData > > signalStreamData
 Signal that is emitted by the stream when a new StreamData is available.
 
DeprecatedSignal< ProtectedSignal< std::shared_ptr< const StreamData > >, const StreamData & > signalNewData
 Signal that is emitted by the stream when a new StreamData is available.
 
- 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::stringsignalNameChanged
 Signal emitted when the name changed.
 
- Public Attributes inherited from Configurable
Signal signalParametersChanged
 Emitted whenever one of the registered Parameters' or SubPropertys' signalValueChanged signal was emitted.
 

Protected Member Functions

virtual bool openImpl ()=0
 Open stream.
 
virtual bool closeImpl ()=0
 Close stream.
 
virtual bool startImpl ()=0
 Start stream.
 
virtual bool stopImpl ()=0
 Stop stream.
 
virtual bool pauseImpl ()
 Pause stream (not required to be supported).
 
virtual bool resumeImpl ()
 Resume stream from pause (only required to be supported when pauseImpl() is supported).
 
virtual bool workerThreadRequiresOpenGl () const
 Override and return true if worker thread should create a GL::Context.
 
virtual std::optional< WorkContinuationdoWork ()=0
 Create one StreamData and publish it (this function will be called at the desired frame rate) If this is not desired, you can do the following: return std::nullopt;.
 
virtual bool worksWhilePaused () const
 Override if doWork() should be called also in the Paused state.
 
void changeState (State newState)
 
std::shared_future< bool > attemptStateChange (std::function< bool()> work, State stateWorking, State stateSuccess, State stateError)
 
- Protected Member Functions inherited from Data
void swapWith (Data &other)
 Swaps the data and emits a matrix and name changed signal for both.
 

Additional Inherited Members

- Protected Attributes inherited from Data
mat4 m_matrix
 Transformation matrix.
 
std::recursive_mutexm_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 Configurable
std::vector< Paramm_params
 List of all registered Parameter and SubProperty instances.
 

Member Enumeration Documentation

◆ ThreadingMode

enum class ThreadingMode
strong

This flag represents the two supported threading modes of a Stream.

Enumerator
BaseClassRunsWorkerThread 

Stream starts thread upon open call and calls doWork in a loop when running.

State transition methods (openImpl, startImpl, etc.) are not immediately called upon (open/openAsync, start/startAsync, etc.), but added to a queue to be called on the worker thread.

DerivedClassHandlesThreading 

Stream does not start any thread and never calls doWork.

State transition methods (openImpl, startImpl, etc.) are called on the same thread of the methods that calls (open/openAsync, start/startAsync, etc.). Therefore, the *Impl-methods need to be threadsafe.

Constructor & Destructor Documentation

◆ Stream()

Stream ( const std::string & name = "")
explicit

Constructor with the name for this stream.

The name is passed to the Data constructor.

Member Function Documentation

◆ threadingMode()

virtual ThreadingMode threadingMode ( ) const
virtual

Configures threading mode of stream.

Returns ThreadingMode::BaseClassRunsWorkerThread by default. Override and return DerivedClassHandlesThreading if stream should not run a worker thread by its own. Overridden method must be constexpr-essible and thread-safe.

Reimplemented in CombinedTrackingStream, and VideoFileStream.

◆ supportsAsyncOperation()

virtual bool supportsAsyncOperation ( )
virtual

Returns true if xxxAsync() methods support execution in a background thread.

Deprecated
"Method is deprecated. Use `streamThreadingMode` instead"

◆ supportsPausing()

virtual bool supportsPausing ( ) const
inlinevirtual

Override and return true if this stream implements the pausing and resume operations.

Overridden method must be constexpr-essible and thread-safe.

Reimplemented in AlgorithmExecutorStream, FakeImageStream, GroupedStereoImageStream, OrbbecRGBDStream, PlaybackStereoImageStream, PlaybackStream, PlaybackTrackingStream, RemoteVideoStream, StereoImageStream, and VideoFileStream.

◆ reset()

virtual bool reset ( )
virtual

Reverts stream to first frame, if possible. Returns whether the operation was successful.

Reimplemented in PlaybackStereoImageStream, PlaybackStream, PlaybackTrackingStream, RGBDPlayback, ROSTopicRGBDStream, VideoCameraStream, and VideoFileStream.

◆ isRunning()

virtual bool isRunning ( ) const
inlinevirtual

Return whether stream is currently running.

Deprecated
"Check the Stream state instead"

Reimplemented in ROSTopicRGBDStream.

◆ uuid()

◆ bounds()

Geometry::AlignedBox bounds ( ) const
overridevirtual

Per default a Stream has empty/invalid bounds.

Implements Data.

◆ matrixConvention()

Pose::TransformationConvention matrixConvention ( ) const
overridevirtual

Matrices of streams by default map to the world coordinate system.

Implements Data.

◆ createDefaultStreamController()

virtual bool createDefaultStreamController ( )
virtual

Indicates whether a StreamController should be created for the stream (by default returns true).

Override this method in your class derived from Stream, if you have a custom data controller for it, and you don't want the StreamController to be created in addition to your custom data controller

Reimplemented in RGBDStream.

◆ updateRate()

double updateRate ( ) const

Average update rate in Hz of the signalStreamData.

Value is reset to zero on pause and stop. Note: Value is not updated when there are no signal updates because it is a simple moving average of the last N events internally.

See also
StreamFPS

◆ describe()

std::string describe ( ) const
overridevirtual

Short description of the stream including latest state and update rate information.

Reimplemented from Data.

Reimplemented in TrackingStream, VideoCameraStream, and VideoFileStream.

◆ openImpl()

◆ closeImpl()

◆ startImpl()

◆ stopImpl()

◆ pauseImpl()

virtual bool pauseImpl ( )
inlineprotectedvirtual

Pause stream (not required to be supported).

Returns whether the operation was successful. This method is intended to temporarily pause data acquisition.

Reimplemented in AlgorithmExecutorStream, FakeImageStream, GroupedStereoImageStream, OrbbecRGBDStream, PlaybackStereoImageStream, PlaybackStream, PlaybackTrackingStream, RemoteVideoStream, SeekableStream< TrackingInstrument, TrackingStream >, StereoImageStream, and VideoFileStream.

◆ resumeImpl()

virtual bool resumeImpl ( )
inlineprotectedvirtual

Resume stream from pause (only required to be supported when pauseImpl() is supported).

Returns whether the operation was successful. This method should resume data acquisition after a pause.

Reimplemented in AlgorithmExecutorStream, FakeImageStream, GroupedStereoImageStream, OrbbecRGBDStream, PlaybackStereoImageStream, PlaybackStream, PlaybackTrackingStream, RemoteVideoStream, SeekableStream< TrackingInstrument, TrackingStream >, StereoImageStream, and VideoFileStream.

◆ workerThreadRequiresOpenGl()

virtual bool workerThreadRequiresOpenGl ( ) const
inlineprotectedvirtual

Override and return true if worker thread should create a GL::Context.

Only has an effect if base class runs worker thread (see threadingMode()). Overridden method must be constexpr-essible and thread-safe.

Reimplemented in ImageStream, PlaybackStereoImageStream, and PlaybackStream.

◆ doWork()

◆ worksWhilePaused()

virtual bool worksWhilePaused ( ) const
inlineprotectedvirtual

Override if doWork() should be called also in the Paused state.

Only has an effect if base class runs worker thread (see threadingMode()).

Member Data Documentation

◆ signalStreamData

ProtectedSignal<std::shared_ptr<const StreamData> > signalStreamData

Signal that is emitted by the stream when a new StreamData is available.

On the emitting side, the stream must ensure that the StreamData is not modified / reused after it has been emitted.

Note
signalStreamData and the deprecated signalNewData are "linked", so if there is a connection to one of them, the receiver will be notified when either of the signals is emitted.

◆ signalNewData

Signal that is emitted by the stream when a new StreamData is available.

Deprecated.

Note
signalStreamData and the deprecated signalNewData are "linked", so if there is a connection to one of them, the receiver will be notified when either of the signals is emitted.
Deprecated
"signalNewData is deprecated. Use signalStreamData instead"

The documentation for this class was generated from the following file:
Search Tab / S to search, Esc to close