RIStream Reference

RIStream is a C++ header that builds on top of libri to provide a more advanced signal processing layer beyond the basic callbacks provided by libri.

Welcome to the RIStream reference page. Here you will find descriptions of the classes and functions defined in the ri_stream.hpp header file included with libri.

class RIGenericStream

RIGenericStream is the parent class the sample-type specific streams derive from.

This class defines all datatype-neutral functions that control the properties of an RIStream. The more specific #RIStream<float> and #RIStream<double> contain the datatype-specific methods for acquiring floating point samples from an RI device.

Since RIGenericStream is an purely-abstract class, streams cannot be created by constructing a new RIGenericStream. Instead, a pointer to a new RIStream can be created by calling ri_open_stream.

Subclassed by RIStream< dtype >

Public Functions

virtual ri_device *RIGenericStreamdevice() = 0

Get the ri_device associated with this stream.

Return
the ri_device pointer associated with this stream.

virtual double RIGenericStreamsamplerate() = 0

Get the sampling rate of data returned by this stream.

This includes reductions to the samplerate caused when downsampling is enabled.

Return
the samplerate of data returned by this stream

virtual int RIGenericStreamsamplesize() = 0

Get the size (in bytes) of the floating point samples returned by this stream.

Valid sizes are 4 (float) and 8 (double).

Return
Size of individual samples in bytes

virtual std::string RIGenericStreamcalibration_mode() = 0

Return the calibration mode of the stream.

Valid calibration modes are:

  • “none”: values are uncalibrated ADC code values
  • ”auto” (default): Use the onboard calibration to convert from ADC samples to uW.
  • ”custom”: Use a custom calibration set with set_custom_calibration

Return
The current calibration mode encoded as a std::string

virtual int RIGenericStreamset_calibration_mode(const std::string mode) = 0

Set the calibration mode.

See calibration_mode for valid modes.

Return
zero on success, an RI_ERROR_t on failure

virtual int RIGenericStreamset_calibration_mode(const char *mode) = 0

Set the calibration mode.

See calibration_mode for valid modes.

Return
zero on success, an RI_ERROR_t on failure

virtual int RIGenericStreamupdate_auto_calibration() = 0

Forces the “auto” calibration mode to update the calibration while the stream is collecting data.

This is only required if some calibration effecting setting (eg. highgain mode) is changed while the stream is collecting data.

Return
zero on success, an RI_ERROR_t on failure

virtual ri_calibration_t RIGenericStreamcalibration() = 0

Gets the current calibration setting as an ri_calibration_t.

Return
the current ADC

virtual int RIGenericStreamset_custom_calibration(const ri_calibration_t calibration) = 0

Set a custom calibration to multiply raw ADC samples by.

The calibrated samples will be computed by:

\[ \mathsf{calibrated} = \mathsf{raw} \times m + b \]

Setting a custom calibration automaticall sets the calibration_mode to “custom”.

Return
zero on success, an RI_ERROR_t on failure

virtual double RIGenericStreamcalibration_wavelength() = 0

Return the wavelength that is used to calculate incident power when the calibration mode is set to “auto”.

This defaults to the peak responsivity wavelength of the photodetector.

Return
the wavelength used to calculate measured power.

virtual int RIGenericStreamset_calibration_wavelength(const double wavelength) = 0

Sets the calibration wavelength used when the calibration fan is set to “auto”.

Setting this value changes calibration mode to “auto”.

Return
zero on success, an RI_ERROR_t on failure

virtual int RIGenericStreamcalibration_units() = 0

Gets the power of ten units for power that are used when the calibration_mode is set to “auto”.

By default calibration_units will return -6 and the power will be calibrated in micro Watts.

Return
the power of ten the calibrated power is multiplied by.

virtual int RIGenericStreamset_calibration_units(const int power_of_ten) = 0

Sets the power of ten units for power that are used when the calibration_mode is set to “auto”.

For example, setting this to -6 results in units of uW. -3 results in units of mW, and 0 results in units of Watts.

Return
zero on success, an RI_ERROR_t on failure

virtual std::string RIGenericStreamfilter() = 0

Gets the name of the filter applied to incoming data.

Valid filter modes are:

  • ”none” (default): No filter is applied
  • ”butterworth2”: A two-pole butterworth low-pass filter
  • ”butterworth4”: A four-pole butterworth low-pass filter
  • ”butterworth6”: A six-pole butterworth low-pass filter
  • ”fir”: A simple square window finite-impulse response low-pass filter.

To adjust the filter cutoff paramater, use set_cutoff.

Return
a std::string with the filter mode in use.

virtual int RIGenericStreamset_filter(const std::string filter) = 0

Sets the filter to apply to incoming samples.

See filter for valid filter types.

Return
zero on success, an RI_ERROR_t on failure

virtual double RIGenericStreamcutoff() = 0

Gets the cutoff frequency of the filter.

This has no effect if filter is set to “none”.

Return
The -3dB cutoff frequency in Hz.

virtual int RIGenericStreamset_cutoff(const double cutoff) = 0

Sets the cutoff frequency of the selected filter.

Return
zero on success, an RI_ERROR_t on failure

virtual int RIGenericStreamdownsampling() = 0

Gets The downsampling factor being applied to incoming data.

This reduced the samplerate by the downsampling factor. For example, when downsampling is disabled, this is set to 1. When the sample rate is reduced by half, it will be set to 2, and so on.

Return
The downsampling factor.

virtual int RIGenericStreamset_downsampling(const int downsampling) = 0

Sets the downsampling factor for the stream.

See
downsampling

virtual int RIGenericStreamset_decimation(const int decimation) = 0

Sets the decimation factor.

This automatically applies a filter, cutoff frequency, and downsampling rate that corresponds to the requested decimation factor.

Return
zero on success, an RI_ERROR_t on failure

virtual uint64_t RIGenericStreamsettling() = 0

Gets the number of samples the stream processs before saving data.

After a stream is started, the stream will acquire at least settling samples before it starts saving samples to the out buffer. This allows filters to settle to steady state conditions reducing artifacts from the unknown initial conditions of the filters.

virtual int RIGenericStreamset_settling(const uint64_t nsamples) = 0

Sets the number of samples the stream processes before starting to saving data.

This is the number of samples received from the device before any downsampling by RIStream occurs.

Return
zero on success, an RI_ERROR_t on failure