![]() |
ImFusion SDK 4.3
|
#include <ImFusion/Stream/Stream.h>
Base class representing a stream of changing data in the DataModel. More...
Inheritance diagram for Stream: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.
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:
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).
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) | |
| Data & | operator= (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::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 () |
| 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 | |
| Configurable & | operator= (const Configurable &) |
| Configurable & | operator= (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< StateChange > | signalStateChanged |
| 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::string > | signalNameChanged |
| 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< WorkContinuation > | doWork ()=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_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 Configurable | |
| std::vector< Param > | m_params |
| List of all registered Parameter and SubProperty instances. | |
|
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. |
|
explicit |
Constructor with the name for this stream.
The name is passed to the Data constructor.
|
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.
|
virtual |
Returns true if xxxAsync() methods support execution in a background thread.
|
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.
|
virtual |
Reverts stream to first frame, if possible. Returns whether the operation was successful.
Reimplemented in PlaybackStereoImageStream, PlaybackStream, PlaybackTrackingStream, RGBDPlayback, ROSTopicRGBDStream, VideoCameraStream, and VideoFileStream.
|
inlinevirtual |
Return whether stream is currently running.
Reimplemented in ROSTopicRGBDStream.
|
pure virtual |
Unique identifier for stream.
Implemented in AlgorithmExecutorStream, BasicProcessingStream, CombinedTrackingStream, FakeImageStream, FakePolyDataStream, FakeTrackingStream, GroupedStereoImageStream, Connection, IgtlImageStream, IgtlPolyDataStream, IgtlTrackingStream, KinectAzureStream, PixelwiseLearningStream, OpenNI2RGBDStream, OrbbecRGBDStream, OutStream, PlaybackStereoImageStream, PlaybackStream, PlaybackTrackingStream, PolarisAuroraTrackingStream< NDIType >, RealSenseStream, RemoteVideoStream, RGBDPlayback, FakeRobotControlStream, FrankaControlStream, KeyboardTrackingStream, RobotTrackingStream, URControlStream, URStateStream, MoveItControlStream, ROSTfTrackingStream, ROSTopicImageOutStream, ROSTopicImageStream, ROSTopicRGBDStream, ROSTopicTrackingOutStream, ROSTopicTrackingStream, SeekableTrackingStream, SmoothedTrackingStream, ProcessedUltrasoundStream, VideoCameraStream, and VideoFileStream.
|
overridevirtual |
|
overridevirtual |
Matrices of streams by default map to the world coordinate system.
Implements Data.
|
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.
| 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.
|
overridevirtual |
Short description of the stream including latest state and update rate information.
Reimplemented from Data.
Reimplemented in TrackingStream, VideoCameraStream, and VideoFileStream.
|
protectedpure virtual |
Open stream.
Returns whether the operation was successful. This method is responsible for allocating necessary resources, initializing device handles, and establishing connections to devices. Implementers should ensure that all one-time setup tasks are completed here.
Implemented in AlgorithmExecutorStream, BasicProcessingStream, CombinedTrackingStream, FakeImageStream, FakePolyDataStream, FakeTrackingStream, GroupedStereoImageStream, Connection, IgtlImageStream, IgtlPolyDataStream, IgtlTrackingStream, KinectAzureStream, PixelwiseLearningStream, OpenNI2RGBDStream, OrbbecRGBDStream, OutStream, PlaybackStereoImageStream, PlaybackStream, PlaybackTrackingStream, PolarisAuroraTrackingStream< NDIType >, RealSenseStream, RemoteVideoStream, RGBDPlayback, FakeRobotControlStream, FrankaControlStream, KeyboardTrackingStream, RobotTrackingStream, URControlStream, URStateStream, MoveItControlStream, ROSTfTrackingStream, ROSTopicImageOutStream, ROSTopicImageStream, ROSTopicRGBDStream, ROSTopicTrackingOutStream, ROSTopicTrackingStream, SmoothedTrackingStream, StereoImageStream, ProcessedUltrasoundStream, VideoCameraStreamOpenPnp, and VideoFileStream.
|
protectedpure virtual |
Close stream.
Returns whether the operation was successful. This method should be used to free any resources that were allocated during the openImpl() call and to disconnect from any devices. Implementers must ensure that all resources are properly released to avoid memory leaks.
Implemented in AlgorithmExecutorStream, BasicProcessingStream, CombinedTrackingStream, FakeImageStream, FakePolyDataStream, FakeTrackingStream, GroupedStereoImageStream, Connection, IgtlImageStream, IgtlPolyDataStream, IgtlTrackingStream, KinectAzureStream, PixelwiseLearningStream, OpenNI2RGBDStream, OrbbecRGBDStream, OutStream, PlaybackStereoImageStream, PlaybackStream, PlaybackTrackingStream, PolarisAuroraTrackingStream< NDIType >, RealSenseStream, RemoteVideoStream, RGBDPlayback, FakeRobotControlStream, FrankaControlStream, KeyboardTrackingStream, RobotTrackingStream, URControlStream, URStateStream, MoveItControlStream, ROSTfTrackingStream, ROSTopicImageOutStream, ROSTopicImageStream, ROSTopicRGBDStream, ROSTopicTrackingOutStream, ROSTopicTrackingStream, SeekableStream< TrackingInstrument, TrackingStream >, SmoothedTrackingStream, StereoImageStream, ProcessedUltrasoundStream, VideoCameraStreamOpenPnp, and VideoStreamBackendOpenCV.
|
protectedpure virtual |
Start stream.
Returns whether the operation was successful. This method is intended to initiate the actual data readout process or to connect a callback function for data handling. Implementers should ensure that the stream is ready and producing data after this call.
Implemented in AlgorithmExecutorStream, BasicProcessingStream, CombinedTrackingStream, FakeImageStream, FakePolyDataStream, FakeTrackingStream, GroupedStereoImageStream, Connection, IgtlImageStream, IgtlPolyDataStream, IgtlTrackingStream, KinectAzureStream, PixelwiseLearningStream, OpenNI2RGBDStream, OrbbecRGBDStream, OutStream, PlaybackStereoImageStream, PlaybackStream, PlaybackTrackingStream, PolarisAuroraTrackingStream< NDIType >, RealSenseStream, RemoteVideoStream, RGBDPlayback, FakeRobotControlStream, FrankaControlStream, KeyboardTrackingStream, RobotTrackingStream, URControlStream, URStateStream, MoveItControlStream, ROSTfTrackingStream, ROSTopicImageOutStream, ROSTopicImageStream, ROSTopicRGBDStream, ROSTopicTrackingOutStream, ROSTopicTrackingStream, SmoothedTrackingStream, StereoImageStream, ProcessedUltrasoundStream, VideoCameraStreamOpenPnp, VideoFileStream, and VideoStreamBackendOpenCV.
|
protectedpure virtual |
Stop stream.
Returns whether the operation was successful. This method should halt any ongoing data readouts or callbacks, effectively pausing the data flow to reduce CPU load. Implementers should ensure that the stream can be restarted after this call.
Implemented in AlgorithmExecutorStream, BasicProcessingStream, CombinedTrackingStream, FakeImageStream, FakePolyDataStream, FakeTrackingStream, GroupedStereoImageStream, Connection, IgtlImageStream, IgtlPolyDataStream, IgtlTrackingStream, KinectAzureStream, PixelwiseLearningStream, OpenNI2RGBDStream, OrbbecRGBDStream, OutStream, PlaybackStereoImageStream, PlaybackStream, PlaybackTrackingStream, PolarisAuroraTrackingStream< NDIType >, RealSenseStream, RemoteVideoStream, RGBDPlayback, FakeRobotControlStream, FrankaControlStream, KeyboardTrackingStream, RobotTrackingStream, URControlStream, URStateStream, MoveItControlStream, ROSTfTrackingStream, ROSTopicImageOutStream, ROSTopicImageStream, ROSTopicRGBDStream, ROSTopicTrackingOutStream, ROSTopicTrackingStream, SeekableStream< TrackingInstrument, TrackingStream >, SmoothedTrackingStream, StereoImageStream, ProcessedUltrasoundStream, VideoCameraStreamOpenPnp, and VideoStreamBackendOpenCV.
|
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.
|
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.
|
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.
|
protectedpure virtual |
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;.
Implemented in AlgorithmExecutorStream, BasicProcessingStream, CombinedTrackingStream, FakeImageStream, FakePolyDataStream, FakeTrackingStream, GroupedStereoImageStream, Connection, IgtlImageStream, IgtlPolyDataStream, IgtlTrackingStream, KinectAzureStream, PixelwiseLearningStream, OpenNI2RGBDStream, OrbbecRGBDStream, OutStream, PlaybackStereoImageStream, PlaybackStream, PlaybackTrackingStream, PolarisAuroraTrackingStream< NDIType >, RealSenseStream, RemoteVideoStream, RGBDPlayback, FakeRobotControlStream, FrankaControlStream, KeyboardTrackingStream, RobotTrackingStream, URControlStream, URStateStream, MoveItControlStream, ROSTfTrackingStream, ROSTopicImageStream, ROSTopicRGBDStream, ROSTopicTrackingStream, SmoothedTrackingStream, StereoImageStream, Substream< TrackingStream >, ProcessedUltrasoundStream, VideoCameraStreamOpenPnp, and VideoStreamBackendOpenCV.
|
inlineprotectedvirtual |
Override if doWork() should be called also in the Paused state.
Only has an effect if base class runs worker thread (see threadingMode()).
| 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.
| DeprecatedSignal<ProtectedSignal<std::shared_ptr<const StreamData> >, const StreamData&> signalNewData |
Signal that is emitted by the stream when a new StreamData is available.
Deprecated.