C++ API Reference¶

Caution

ARRUS C++ API is currently under development and its API will be modified in the future. Please expect breaking changes.

Notation¶

Class::Handle is a typedef for std::unique_ptr<Class>
Class::SharedHandle is a typedef for std::shared_ptr<Class>

Session¶

ARRUS_CPP_EXPORT Session::Handle arrus::session::createSession(const std::string &filepath)¶

Reads given configuration file and returns a handle to new session.

Parameters: filepath – a path to session settings
Returns: a unique handle to session

class arrus::session::Session¶

A communication session with the device.

Public Types

enum class State¶

Session state.

STOPPED: the session is stopped (no device is running).
STARTED: the session is started (at least one of the session devices is running).
CLOSED: the session was closed (the connection to all the session devices was closed).

Values:

enumerator STOPPED¶

enumerator STARTED¶

enumerator CLOSED¶

Public Functions

virtual arrus::devices::Device *getDevice(const std::string &deviceId) = 0¶

Returns a handle to device with given Id. The string format is: /DeviceType:Ordinal, e.g. “/Us4R:0”.

Parameters: deviceId – device identifier
Returns: a handle to the device

virtual arrus::devices::Device *getDevice(const arrus::devices::DeviceId &deviceId) = 0¶

Returns a handle to device with given Id.

Parameters: deviceId – device identifier
Returns: a handle to the device

virtual UploadResult upload(const ::arrus::ops::us4r::Scheme &scheme) = 0¶

Uploads a given scheme on the available devices.

Currently, the scheme upload is performed on the Us4R:0 device only.

After uploading a new sequence the previously returned output buffers will be in invalid state.

Parameters: scheme – scheme to upload
Returns: upload result information

virtual void startScheme() = 0¶: Starts currently uploaded scheme.

virtual void stopScheme() = 0¶: Stops currently uploaded scheme.

virtual void run(bool sync = false, std::optional<long long> timeout = std::nullopt) = 0¶

Runs the uploaded scheme.

The behaviour of this method depends on the work mode:

MANUAL: triggers execution of batch of sequences only ONCE,
MANUAL_OP: triggers execution of a single TX/RX only ONCE,
HOST, ASYNC: triggers execution of batch of sequences IN A LOOP (Host: trigger is on buffer element release). The run function can be called only once (before the scheme is stopped).

Parameters

sync – whether this method should work in a synchronous or asynchronous; true means synchronous, i.e. the caller will wait until the triggered TX/RX or sequence of TX/RXs has been done. The sync = true is only allowed when the work mode is set to MANUAL or MANUAL_OP. NOTE: For the US4R device, this method ONLY waits for the completion of the TX/RX sequence. Currently, it DOES NOT WAIT for the data transfer to the host PC or for the processing to finish — to wait for these two events, either wait for the final data using buffer.get(), or register your own callback function.
timeout – timeout [ms]; std::nullopt means to wait infinitely. This parameter is only relevant when sync = true; the value of this parameter only matters when work mode is set to MANUAL or MANUAL_OP

virtual void close() = 0¶

Closes session.

This method disconnects with all the devices available during this session. Sets the state of the session to closed, any subsequent call to the object methods (e.g. upload, startScheme..) will result in InvalidStateException.

virtual State getCurrentState() = 0¶: Returns the current state of the session. See also Session::State.

virtual UploadResult setSubsequence(uint16 start, uint16 end, std::optional<float> sri, uint16 arrayId) = 0¶

Turns on the sequence with the arrayId and sets the TX/RXs to the [start, end) range. This method turns off all the uploaded TX/RX sequences except sequence pointed by arrayId.

This method requires that:

start < end (start == end would mean that the given sequence should bet turned off, and that would mean that all TX/RXs sequences should be turned off, which current does not make sense),
the scheme was uploaded,
the TX/RX sequence length is greater than the end value,
the scheme is stopped.

Parameters

start – the TX/RX number which should now be the first TX/RX
end – the TX/RX number which should now be the last TX/RX
sri – the new SRI to apply
arrayId – id array to select, default: array with id 0

Returns

the new data buffer and metadata

virtual UploadResult setSubsequences(const std::vector<Slice> &slices, const std::vector<std::optional<float>> &sris) = 0¶

Selects [start, end) slices for each sub-sequence.

The slices array should have exactly n elements, where n is the number of currently uploaded sequences. The element slice[i] sets the [start, end) range for the i-th sequence.

The sris should have eactly n elements, or should be empty (which means that no additional sri should be applied).

To turn off the given sequence, just set start equal to end (e.g. Slice(0, 0)). For such sequences, the metadata will

Parameters

slices – slices to set to each Scheme sub-sequence
sris – sris to apply to each Scheme sub-sequence

Returns

returns the buffer and metadata for the modified Scheme. The metadata array size is always equal to the number of seqeuences in the original Scheme

virtual bool hasDevice(const std::string &deviceId) const = 0¶

Returns true if this session has been configured to work with the given device, otherwise false.

Parameters: deviceId – device identifier

virtual bool hasDevice(const arrus::devices::DeviceId &deviceId) const = 0¶

Returns true if this session has been configured to work with the given device, otherwise false.

Parameters: deviceId – device identifier

Public Static Functions

static inline std::string getSessionStateAsString(const State state)¶

Returns a Session State name.

Parameters: state – Session State
Returns: a Session State name (string)

Operations¶

Scheme¶

class arrus::ops::us4r::Scheme¶

A scheme to be executed within the session.

Public Types

enum class WorkMode¶

How the scheme should be executed on the us4r-lite device.

This enum value determines the source of the signal trigger (i.e. whether the signal is triggered by us4oem modules or host PC).

Values:

enumerator ASYNC¶: Trigger generated by us4r, error on overflow.

enumerator SYNC¶: Trigger generated by us4r, us4r waits on overflow

enumerator HOST¶: Trigger generated by host, no error on overflow. DEPRECATED: will be replaced in the future by MANUAL mode

enumerator MANUAL¶: New data acquisition and processing is manually triggered by user. The systems stops per sequence execution.

enumerator MANUAL_OP¶: New data acquisition and processing is manually triggered by user. The systems stops per TX/RX execution.

Public Functions

inline bool isWorkModeManual() const¶: Returns true if the work mode is MANUAL (MANUAL per sequence or MANUAL_TX_RX (per TX/RX).

ARRUS_CPP_EXPORT Scheme(TxRxSequence txRxSequence, uint16 rxBufferSize, const framework::DataBufferSpec &outputBuffer, WorkMode workMode, std::optional<DigitalDownConversion> ddc, const std::vector<arrus::framework::NdArray> &constants)¶: TODO(0.12.0) Deprecated: please use Scheme::create instead

ARRUS_CPP_EXPORT inline Scheme(TxRxSequence txRxSequence, uint16 rxBufferSize, const framework::DataBufferSpec &outputBuffer, WorkMode workMode)¶

Scheme constructor. This scheme turns off hardware IQ demodulator. TODO(0.12.0) Deprecated: please use Scheme::create instead

Parameters

txRxSequence – tx/rx sequence to perform
rxBufferSize – the size of the data acquisition buffer in the memory of the Us4R device (a single element of the buffer is an output of a single tx/rx sequence execution)
outputBuffer – output buffer specification
workMode – scheme work mode

ARRUS_CPP_EXPORT inline Scheme(TxRxSequence txRxSequence, uint16 rxBufferSize, const framework::DataBufferSpec &outputBuffer, WorkMode workMode, DigitalDownConversion ddc)¶

Scheme constructor. This scheme turns on hardware IQ demodulator (sees digital down conversion parameter).

TODO(0.12.0) Deprecated: please use Scheme::create instead

Parameters

txRxSequence – tx/rx sequence to perform
rxBufferSize – the size of the data acquisition buffer in the memory of the Us4R device (a single element of the buffer is an output of a single tx/rx sequence execution)
outputBuffer – output buffer specification
workMode – scheme work mode
digitalDownConversion – DDC parameters

ARRUS_CPP_EXPORT inline Scheme(TxRxSequence txRxSequence, uint16 rxBufferSize, const framework::DataBufferSpec &outputBuffer, WorkMode workMode, const std::vector<framework::NdArray> &constants)¶: TODO(0.12.0) Deprecated: please use Scheme::create instead

ARRUS_CPP_EXPORT const TxRxSequence &getTxRxSequence() const¶: TODO(0.12.0) Deprecated: please use getTxRxSequence(int ordinal) instead

Public Static Functions

static inline bool isWorkModeManual(WorkMode workMode)¶: Returns true if the work mode is MANUAL (MANUAL per sequence or MANUAL_TX_RX (per TX/RX).

class arrus::framework::DataBufferSpec¶

Class describing output data buffer properties.

Public Types

enum class Type¶

Buffer type.

Values:

enumerator FIFO¶: First in first out buffer.

Public Functions

inline DataBufferSpec(Type bufferType, const unsigned &nElements)¶

Data buffer specification constructor.

Parameters

bufferType – buffer type
nElements – number of elements (a single element of the buffer is an output of a single tx/rx sequence execution)

inline DataBufferSpec(Type bufferType, const unsigned &nElements, const ::arrus::devices::DeviceId &placement)¶

Data buffer specification constructor.

Parameters

bufferType – buffer type
nElements – number of elements
placement – device on which the buffer should be allocated. Allowed values: (CPU, 0), (GPU, 0). Default: (CPU, 0).

inline unsigned getNumberOfElements() const¶: Returns number of elements the buffer consists of.

inline const ::arrus::devices::DeviceId &getPlacement() const¶: Returns the device on which the buffer is placed.

Custom Tx/Rx sequences¶

class arrus::ops::us4r::TxRxSequence¶

Public Functions

inline TxRxSequence(std::vector<TxRx> sequence, TGCCurve tgcCurve, float sri = NO_SRI, int16 nRepeats = 1, std::string name = "")¶

Tx/Rx sequence to execute on Us4R device.

Parameters

sequence – a list of tx/rxs that compose a given sequence
tgcCurve – tgc curve to apply
sri – sequence repetition interval - the total time that a given sequence should take.
nRepeats – - the number of repetitions of a given sequence. Determines the size of the batch

inline const std::vector<TxRx> &getOps() const¶: Returns vector of operations to perform.

inline const TGCCurve &getTgcCurve() const¶: Initial TGC curve points.

inline const std::optional<float> getSri() const¶: Returns sequence repetition interval (the total time the given sequence should actually take). nullopt means that the frame acquisition time should be determined by total PRI only.

inline devices::DeviceId getRxProbeId() const¶: Returns the ordinal number of the probe used for RX. If the RX probe is not-unique, this method will throw IllegalStateException.

inline devices::DeviceId getTxProbeId() const¶: Returns the ordinal number of the probe used for RX. If the RX probe is not-unique, this method will throw IllegalStateException.

inline size_t size() const¶: Returns the number of ops in the given TX/RX sequence.

inline const std::string &getName() const¶: Returns the name of sequence.

class arrus::ops::us4r::Pulse¶

A single pulse (sine wave) produced by us4r device.

DEPRECATED: please use the arrus::ops::us4r::Waveform

Public Functions

inline Pulse(float centerFrequency, float nPeriods, bool inverse, AmplitudeLevel amplitudeLevel = 2)¶

Pulse constructor.

Parameters

centerFrequency – center frequency of the transmitted pulse
nPeriods – pulse number of periods, should be a multiple of 0.5
inverse – if set to true - inverse the pulse polarity
amplitudeLevel – amplitude level to use, default: 2 (HVM/P 0)

inline float getPulseLength() const¶: Returns pulse duration [s].

Public Static Functions

static inline std::optional<Pulse> fromWaveform(const Waveform &waveform)¶

Converts the input waveform to a pulse. The conversion is possible only when the structure of the waveform is conformant with the output of the toWaveform method — the nullopt is returned otherwise.

Returns: pulse recovered from the input waveform or std::nullopt, if it was not possible to convert the waveform to the Pulse object

class arrus::ops::us4r::TxRx¶

A single tx/rx operation to perform.

Public Functions

inline TxRx(Tx tx, Rx rx, float pri)¶

TxRx constructor.

Parameters

tx – - tx description
rx – - rx description
pri – - pulse repetition interval

class arrus::ops::us4r::Tx¶

A single pulse transmission.

Public Functions

inline Tx(std::vector<bool> aperture, std::vector<float> delays, const Pulse &pulse, devices::DeviceId placement)¶

Tx constructor.

Parameters

aperture – transmit aperture specified as a bit mask; aperture[i] means that the i-th channel should be turned on
delays – transmit delays to apply; delays[i] applies to channel i
pulse – pulse to transmit @parma placement probe on which the Tx should be performed

inline std::vector<float> getDelaysApertureOnly() const¶: Returns an array with delays for active (i.e. aperture[i] = true) channels only.

template<typename T> inline std::vector<float> limitToApertureOnly(const std::vector<T> &values) const¶: Returns an array with delays for active (i.e. aperture[i] = true) channels only.

inline bool isNOP() const¶: Returns true if this operator does not perform TX at all (i.e. aperture is set to false).

class arrus::ops::us4r::Rx¶

An operation that performs a single data reception (Rx).

Public Functions

inline Rx(std::vector<bool> aperture, std::pair<unsigned int, unsigned int> sampleRange, unsigned int downsamplingFactor = 1, std::pair<unsigned short, unsigned short> padding = {(ChannelIdx)0, (ChannelIdx)0}, devices::DeviceId placement = devices::DeviceId(devices::DeviceType::Probe, 0))¶

Rx constructor.

Parameters

aperture – receive aperture to use; aperture[i] = true means that the i-th channel should be turned on
rxSampleRange – [start, end) range of samples to acquire, starts from 0
downsamplingFactor – the factor by which the sampling frequency should be divided, an integer
placement – probe on which the RX should be performed.

class arrus::ops::us4r::TxRxSequence

Public Functions

inline TxRxSequence(std::vector<TxRx> sequence, TGCCurve tgcCurve, float sri = NO_SRI, int16 nRepeats = 1, std::string name = "")

Tx/Rx sequence to execute on Us4R device.

Parameters

sequence – a list of tx/rxs that compose a given sequence
tgcCurve – tgc curve to apply
sri – sequence repetition interval - the total time that a given sequence should take.
nRepeats – - the number of repetitions of a given sequence. Determines the size of the batch

inline const std::vector<TxRx> &getOps() const: Returns vector of operations to perform.

inline const TGCCurve &getTgcCurve() const: Initial TGC curve points.

inline const std::optional<float> getSri() const: Returns sequence repetition interval (the total time the given sequence should actually take). nullopt means that the frame acquisition time should be determined by total PRI only.

inline devices::DeviceId getRxProbeId() const: Returns the ordinal number of the probe used for RX. If the RX probe is not-unique, this method will throw IllegalStateException.

inline devices::DeviceId getTxProbeId() const: Returns the ordinal number of the probe used for RX. If the RX probe is not-unique, this method will throw IllegalStateException.

inline size_t size() const: Returns the number of ops in the given TX/RX sequence.

inline const std::string &getName() const: Returns the name of sequence.

class arrus::ops::us4r::DigitalDownConversion¶

Public Functions

inline DigitalDownConversion(float demodulationFrequency, std::vector<float> firCoefficients, float decimationFactor, float gain = 12.0)¶

Us4R Digital Down Conversion block.

Note: the decimation factor can also have a fractional part: 0.25, 0.5 or 0.75.

Note: the FIR filter order (i.e. total number of taps)depends on the decimation factor and should be equal: decimationFactor*16 for integer decimation factor; decimationFactor*32 for decimation factor with fractional part 0.5; decimationFactor*64 for decimation facator with fractional part 0.25 or 0.75.

Note: only a upper half of the FIR filter coefficients should be provided.

Parameters

demodulationFrequency – demodulation frequency to apply [Hz]
firCoefficients – FIR filter coefficients to apply
decimationFactor – decimation factor to apply, should be in range [2, 63]
gain – an extra digital gain to apply (after decimation filter), by default set to 12 dB. Currently only 0 and 12 dB are supported [dB]

float getGain() const¶: Returns an extra digital gain to apply (after the decimation filter).

using arrus::ops::us4r::TGCCurve = std::vector<TGCSampleValue>¶: TGC curve to apply on the us4r device.

class Waveform¶

A complete Tx waveform to be applied on the ultrasound pulsers.

NOTE: please use WaveformBuilder class to create new TX Waveforms (avoid constructing objects of this class directly).

Parameters

segments – subsequent segments of the waveform
nRepetitions – how many times the segments[i] should be repeated

class WaveformSegment¶

Us4R TX waveform segment.

WaveformSegment is a part of the TX waveform, that can be repated multiple times.

The duration[i] is the duration of the i-th state, i.e. state[i].

Parameters

state – the sequence of of states, one of the following values: -2 (HVM0), -1 (HVM1), 0 (CLAMP), 1 (HVP1), 2 (HVP0)
duration – the duration of the i-th state [seconds]

class WaveformBuilder¶: Tx Waveform builder class.

Devices¶

class arrus::devices::Us4R : public arrus::devices::Ultrasound, public arrus::devices::DeviceWithComponents¶

Us4R system: a group of Us4OEM modules and related components.

By default system starts with IQ demodulator turned off.

Public Functions

virtual Us4OEM *getUs4OEM(Ordinal ordinal) = 0¶

Returns a handle to Us4OEM identified by given ordinal number.

Parameters: ordinal – ordinal number of the us4oem to get
Returns: a handle to the us4oem module

virtual void setVoltage(unsigned char voltage) = 0¶

Sets HV voltage.

The voltage is set for the TX amplitude 2 (rail 0).

Parameters: voltage – voltage to set [V]

virtual void setVoltage(const std::vector<HVVoltage> &voltages) = 0¶

Sets HV voltage. The input vector describes what voltages should be set for each tx voltage level (rail).

voltages[0] are for the TX amplitude/state 1 (-/+), voltage[1] are for TX amplitude/state level 2 and so on.

For the legacy systems (using e.g. the legacy HV256 or us4rPSC) this method expects a list of voltages {0, -/+ voltage}.

Parameters: voltages – voltages to set [V]

virtual unsigned char getVoltage() = 0¶

Returns configured HV voltage.

Returns: hv voltage value configured on device [V]

virtual float getMeasuredPVoltage() = 0¶

Returns measured HV voltage (plus).

Returns: hv voltage measured by device [V]

virtual float getMeasuredMVoltage() = 0¶

Returns measured HV voltage (minus).

Returns: hv voltage measured by devivce [V]

virtual float getMeasuredHVPVoltage(uint8_t oemId) = 0¶

Gets positive HV voltage measurement by UCD chip on OEM.

Parameters: oemId – OEM ID
Returns: positive HV voltage UCD measurement [V]

virtual float getMeasuredHVMVoltage(uint8_t oemId) = 0¶

Gets negative HV voltage measurement by UCD chip on OEM.

Parameters: oemId – OEM ID
Returns: negative HV voltage UCD measurement [V]

virtual void disableHV() = 0¶: Disables HV voltage.

virtual void setTgcCurve(const std::vector<float> &tgcCurvePoints) = 0¶: Equivalent to setTgcCurve(curve, true).

virtual void setTgcCurve(const std::vector<float> &tgcCurvePoints, bool applyCharacteristic, bool clip = false) = 0¶

Sets TGC curve points asynchronously.

Setting empty vector turns off analog TGC. Setting non-empty vector turns off DTGC and turns on analog TGC.

TGC curve can have up to 1022 samples.

Parameters

tgcCurvePoints – tgc curve points to set (gain [dB])
applyCharacteristic – set it to true if you want to compensate response characteristic (pre-computed by us4us). If true, LNA and PGA gains should be set to 24 an 30 dB, respectively, otherwise an arrus::IllegalArgumentException will be thrown.
clip – set it true if you would like to get TGC clipped to the min/max possible gain value; otherwise, an IllegalArgumentException will be raised with message that the maximum possible gain value (resulting from amplifier settings such as LNA and PGA) is exceeded.

virtual void setTgcCurve(const std::vector<float> &t, const std::vector<float> &y, bool applyCharacteristic, bool clip = false) = 0¶

Sets TGC curve points asynchronously.

Setting empty vectors t and y turns off analog TGC. Setting non-empty vector turns off DTGC and turns on analog TGC.

Vectors t and y should have exactly the same size. The input t and y values will be interpolated into target hardware sampling points (according to getCurrentSamplingFrequency and getCurrentTgcPoints). Linear interpolation will be performed, the TGC curve will be extrapolated with the first (left-side of the cure) and the last sample (right side of the curve).

NOTE: TGC curve can have up to 1022 samples.

Parameters

t – sampling time, relative to the “sample 0”
y – gain values to apply at given sampling time [dB]
applyCharacteristic – set it to true if you want to compensate response characteristic (pre-computed by us4us). If true, LNA and PGA gains should be set to 24 an 30 dB, respectively, otherwise an arrus::IllegalArgumentException will be thrown.
clip – set it true if you would like to get TGC clipped to the min/max possible gain value; otherwise, an IllegalArgumentException will be raised with message that the maximum possible gain value (resulting from amplifier settings such as LNA and PGA) is exceeded.

virtual std::vector<float> getTgcCurvePoints(float maxT) const = 0¶

Returns us4R TGC sampling points (along time axis, relative to the “sample 0”), up to given maximum time.

Parameters: maxT – maximum time range
Returns: TGC time points at which TGC curve sample takes place

virtual void setVcat(const std::vector<float> &t, const std::vector<float> &y, bool applyCharacteristic, bool clip = false) = 0¶

Sets VCAT time points asynchronously.

Setting empty vectors t and y turns off analog TGC. Setting non-empty vector turns off DTGC and turns on analog TGC.

Vectors t and y should have exactly the same size. The input t and y values will be interpolated into target hardware sampling points (according to getCurrentSamplingFrequency and getCurrentTgcPoints). Linear interpolation will be performed, the TGC curve will be extrapolated with the first (left-side of the cure) and the last sample (right side of the curve).

NOTE: the curve can have up to 1022 samples.

Parameters

t – sampling time, relative to the “sample 0”
y – attenuation values to apply at given sampling time [dB]
applyCharacteristic – set it to true if you want to compensate response characteristic (pre-computed by us4us). If true, LNA and PGA gains should be set to 24 an 30 dB, respectively, otherwise an arrus::IllegalArgumentException will be thrown.
clip – set it true if you would like to get TGC clipped to the min/max possible gain value; otherwise, an IllegalArgumentException will be raised with message that the maximum possible gain value (resulting from amplifier settings such as LNA and PGA) is exceeded.

virtual void setVcat(const std::vector<float> &tgcCurvePoints) = 0¶: Equivalent to setVcat(curve, true, false).

virtual void setVcat(const std::vector<float> &tgcCurvePoints, bool applyCharacteristic, bool clip = false) = 0¶

Sets VCAT points asynchronously.

Setting empty vector turns off analog TGC. Setting non-empty vector turns off DTGC and turns on analog TGC.

The curve can have up to 1022 samples.

Parameters

tgcCurvePoints – tgc curve points to set (gain [dB])
applyCharacteristic – set it to true if you want to compensate response characteristic (pre-computed by us4us). If true, LNA and PGA gains should be set to 24 an 30 dB, respectively, otherwise an arrus::IllegalArgumentException will be thrown.
clip – set it true if you would like to get TGC clipped to the min/max possible gain value; otherwise, an IllegalArgumentException will be raised with message that the maximum possible gain value (resulting from amplifier settings such as LNA and PGA) is exceeded.

virtual void setPgaGain(uint16 value) = 0¶

Sets PGA gain.