ImageStreamRecorder Class Reference

#include <ImFusion/Stream/ImageStreamRecorder.h>

Records images from an ImageStream. More...

Inheritance diagram for ImageStreamRecorder:

Detailed Description

Records images from an ImageStream.

Stores emitted images in one or more SharedImageSet instances, with one SharedImageSet per image contained in ImageStreamData.

Can be used on its own or within StreamRecorderAlgorithm to simultaneously record multiple streams and enable extended functionality, such as live saving to an ImFusion .imf file.

Example usage:

FakeImageStream fakeImg; // any ImageStream can be used
fakeImg.start();
 
ImageStreamRecorder recorder{fakeImg};
recorder.start();
 
// Record for 5 seconds
auto endTime = std::chrono::steady_clock::now() + std::chrono::seconds(5);
while (std::chrono::steady_clock::now() < endTime)
  QApplication::processEvents(); // keep main application responsive
recorder.stop();
 
auto recordings = recorder.takeOutput();

Public Member Functions
	ImageStreamRecorder (ImageStream &stream)
ImageStream &	stream () const override
	Returns the associated stream being recorded.
std::unique_lock< std::mutex >	currentRecordingContainer (const SharedImageSet **img, int frameIndex=0) const
	Provides temporary access to the currently recorded SharedImageSet.
void	setNextAsyncRecordingOptions (const std::string &path="", bool ffv1Compression=false)
	Configures the output path (without extension) and compression settings for live background export during the next recording session.
OwningDataList	takeOutput () override
	Retrieves the recorded SharedImageSet%(s).
void	setMaxImagesKeptInMemory (const int val)
	Sets the number of images to retain in memory (per recorded SharedImageSet). Use -1 to keep all.
int	maxImagesKeptInMemory () const
	Returns the limit on the number of image to keep in memory (per recorded SharedImageSet). -1 indicates no limit.
Public Member Functions inherited from StreamRecorder
	StreamRecorder (Stream &stream)
	Constructs a StreamRecorder for the specified input stream. Recording is not started automatically.
void	start ()
	Starts recording if not already recording.
void	stop ()
	Stops recording if currently recording.
bool	isRecording () const
	Returns true if a recording is currently in progress.
bool	allStreamsRunning () const
	Returns true if all streams being recorded are currently active.
void	setTimeLimit (double seconds)
	Sets the maximum duration of a recording session (in seconds).
void	setSystemMemoryLimit (double maxMemoryFraction)
	Sets the maximum fraction of available system memory allowed for recording [0.0-1.0].
void	setSamplesLimit (int maxSamples)
	Sets the maximum number of samples (frames, tracking data, etc.) to record.
void	setRecordedBytesLimit (size_t maxBytes)
	Sets the maximum number of recorded bytes.
size_t	recordedBytesLimit () const
	Returns the configured maximum number of recorded bytes. Zero if no limit is set.
double	passedTime () const
	Returns the duration of the current or most recent recording session (in seconds).
int	recordedSamples () const
	Returns the number of samples recorded during the current or most recent session.
bool	hasReachedLimit () const
	Returns true if any recording limit (time, memory, samples, bytes) was reached.
bool	hasReachedMemoryLimit () const
	Returns true if the memory limit was specifically reached during recording.
size_t	recordedBytes () const
	Returns the number of bytes recorded during the current or most recent session.
void	setUseDeviceTimestamp (bool flag)
	Specifies whether to record the device timestamp or the arrival timestamp.
bool	usesDeviceTimestamps () const
	Returns true if device timestamps are recorded instead of arrival timestamps.
void	setRecordBothTimestamps (bool flag)
	Sets whether both device and arrival timestamps should be recorded.
bool	recordBothTimestamps () const
	Returns true if both timestamp types will be recorded in a TimestampDataComponent.
void	setCaptureMode (CaptureMode captureMode)
	Sets the desired capture mode.
CaptureMode	captureMode () const
	Returns the current capture mode.
void	setCaptureNextSample ()
	Requests the recording of the next StreamData emitted by the Stream.
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
Signal< StreamRecorder * >	imageSizeChanged
	Signal emitted when the image size or type has changed.
Signal< std::vector< ImageDescriptor > >	signalImageDescriptorsChanged
	Emits when input characteristics fundamentally change (e.g.
Public Attributes inherited from StreamRecorder
ProtectedSignal< StreamRecorder * >	signalLimitReached
	Signal emitted when recording has stopped due to a limit being reached.
ProtectedSignal< StreamRecorder *, size_t >	recordedBytesChanged
	Signal emitted whenever the recorded byte count changes (i.e. a new sample is added).

Protected Member Functions
void	init () override
	Initializes stream metadata (m_streamMetaData).
void	finalize () override
	Finalizes the recording session: applies display settings and completes live recording to disk.
size_t	processStreamData (const StreamData &data) override
	Adds images from ImageStreamData to SharedImageSet container(s).
void	onImageSaved (int idx)
	Frees memory when images have been saved to disk and the retained image count exceeds m_maxImagesInMemory.
Protected Member Functions inherited from StreamRecorder
double	extractTimestamp (const StreamData *data)
	Extracts either the device or arrival timestamp from the given StreamData, based on m_useDeviceTimestamp.
virtual void	recordFrameDataComponents (ElementwiseDataComponentList &ewdcl, const StreamData &streamDataWithDCs, int finalContainerSize)
	Copies the DataComponents from streamDataWithDCs and appends them to the provided ElementwiseDataComponentList (ewdcl), continuing until the container reaches the specified final size (finalContainerSize).
void	resetRecordingStatistics ()
	Resets the recorded samples counter m_samplesRead and recorded byte counter m_recordedBytes to Zero and the m_limitReached flag to false.
Protected Member Functions inherited from SignalReceiver
void	disconnectAll ()
	Disconnects all existing connections.

Additional Inherited Members
Public Types inherited from StreamRecorder
enum	CaptureMode { CaptureAll = 0 , OnRequest = 1 }

Member Function Documentation

stream()

ImageStream & stream ( ) const

overridevirtual

Returns the associated stream being recorded.

Reimplemented from StreamRecorder.

currentRecordingContainer()

std::unique_lock< std::mutex > currentRecordingContainer ( const SharedImageSet ** img, int frameIndex = 0 ) const

nodiscardthreadsafe

Provides temporary access to the currently recorded SharedImageSet.

Writes a pointer to the container into img. For ImageStreams emitting multiple images, frameIndex selects the appropriate container. The returned lock must remain in scope during inspection to ensure thread safety.

Note

While holding the lock, the ImageStreamRecorder cannot record any new images. Therefore, the access time should be limited as much as possible.

Can be called concurrently from any thread.

setNextAsyncRecordingOptions()

void setNextAsyncRecordingOptions	(	const std::string &	path = "",
		bool	ffv1Compression = false )

Configures the output path (without extension) and compression settings for live background export during the next recording session.

If path is empty, live background export is disabled. For streams emitting multiple images, filenames are suffixed with ascending indices. Must be called before start(). Later calls will be ignored.

takeOutput()

OwningDataList takeOutput ( )

overridevirtualthreadsafe

Retrieves the recorded SharedImageSet%(s).

Returns an empty OwningDataList if recording is still in progress.

Can be called concurrently from any thread.

Implements StreamRecorder.

init()

void init ( )

overrideprotectedvirtual

Initializes stream metadata (m_streamMetaData).

Implements StreamRecorder.

finalize()

void finalize ( )

overrideprotectedvirtualthreadsafe

Finalizes the recording session: applies display settings and completes live recording to disk.

Can be called concurrently from any thread.

Implements StreamRecorder.

processStreamData()

size_t processStreamData ( const StreamData & data )

overrideprotectedvirtualthreadsafe

Adds images from ImageStreamData to SharedImageSet container(s).

If live background export is enabled, forwards the frames to the corresponding BackgroundFrameExporter%(s). Emits signalImageDescriptorsChanged if image descriptor (e.g. size, pixel type, channels) or image count has changed. Returns the total number of recorded bytes.

Can be called concurrently from any thread.

Implements StreamRecorder.

Member Data Documentation

imageSizeChanged

Signal<StreamRecorder*> imageSizeChanged

Signal emitted when the image size or type has changed.

Deprecated

"imageSizeChanged has been deprecated in favor of the more general signalImageDescriptorsChanged"

signalImageDescriptorsChanged

Signal<std::vector<ImageDescriptor> > signalImageDescriptorsChanged

Emits when input characteristics fundamentally change (e.g.

size, pixel type, channels, or image count), making further recording to the same output containers impossible. When this signal is emitted, users should call takeOutput() to retrieve existing recordings and restart the session as needed.

---

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

• ImFusion/Stream/ImageStreamRecorder.h