API Reference

High-level MATLAB scripts

class arrus.Us4R(varargin)

Bases: handle

A handle to the Us4R system.

This class provides functions to configure the system and perform data acquisition using the Us4R.

static clear()

Clears Us4R object.

closeSession()

Closes session

static create(varargin)

Creates a handle to the Us4R system.

Syntax: obj = Us4R.create(name, value, …, name, value)

All inputs are organized in name-value pairs.

Parameters

  • configFile – Name of the prototxt file that contains the setup information. String scalar or character vector. Obligatory input.

  • logTime – Enables display of acquisition/processing time. Logical scalar. Optional.

Returns

Us4R handle.

delete()

Deletes the Us4R object

disableAdcHpf()

Disables digital high-pass filter (dHPF).

disableLnaHpf()

Disables analog high-pass filter (aHPF).

getImagingMetadata()

Returns the system and sequence metadata

Returns

system metadata and sequence metadata.

getNProbeElem()

Returns number of probe elements.

NOTE: the returned value comes from the prototxt config file. If the probe model in the config file is different from the one actuually attached to the system, the returned value may be wrong.

Returns

number of probe elements.

getSamplingFrequency()

Returns nominal sampling frequency of the system. The actual sampling frequency may be reduced by using decimation.

Returns

nominal sampling frequency of the system [Hz].

getSessionState()

Returns session state.

Returns

Us4R session state.

imageRawRf(varargin)

Displays a color-coded image of raw RF data.

Parameters

  • selectedLines – vector indicating the rf lines to be displayed. Rf lines are numbered as follows: 1:rxApertureSize*nTx*nRep. (optional name-value argument)

  • amplitudeLim – scalar defining the displayed amplitude range as [-amplitudeLim, amplitudeLim] (optional name-value argument)

plotRawRf(varargin)

Displays a plot of raw RF data.

Parameters

  • selectedLines – vector indicating the rf lines to be displayed. Rf lines are numbered as follows: 1:rxApertureSize*nTx*nRep. (optional name-value argument)

  • amplitudeLim – scalar defining the displayed amplitude range as [-amplitudeLim, amplitudeLim] (optional name-value argument)

  • boundsModeEnable – logical scalar determining if min and max values of each sample from a set of rf lines are displayed instead of individual rf lines. (optional name-value argument)

  • linRangeEnable – logical scalar determining if range of undistorted amplitudes is displayed. (optional name-value argument)

reconstructOffline(raw)

Performs offline reconstruction of raw data. The Us4R system should be prepared as if the data were to be collected and processed online.

Parameters

raw – raw data.

run()

Runs uploaded operations in the us4R system.

Returns

raw data frame, reconstructed image (if Reconstruction operation was uploaded), and frame metadata.

runLoop(isContinue, callback, varargin)

Runs the uploaded operations in a loop.

Parameters

  • isContinue – should the system continue executing the op? Takes no parameters and returns a boolean value.

  • callback – a function to call after executing the operation. Should take one parameter, which will be feed with the output of the executed op.

  • bufferType – type of data stored in the cineloop buffer, can be “none”, “raw”, “img”, or “all”. Optional, default=”none”.

  • bufferMode – mode of buffer operation. Can be “conc” for concurrent or “subs” for subsequent operation with the callback function. For “conc” the buffer is used as long as isContinue is true. For “subs” the buffer is used as soon as isContinue is false until the buffer is full.

  • bufferSize – size of the cineloop buffer as a number of sequence executions. Optional, default=1.

Returns

buffers containing raw data (rawBuffer), image data (imgBuffer), and sequence repetition intervals (sriBuffer).

selectSequence(seqId, sri)

Selects from pre-uploaded sequences the one to be executed.

Parameters

  • seqId – Tx/Rx sequence ID (index of the selected sequence in the vector of sequences passed to the uploadSequence method, counting from 1). Numerical scalar.

  • sri – sequence repeting interval [s]. Numerical scalar. Optional, default = as defined in the selected sequence.

Returns

updated Us4R object.

NOTE: selecting sequence erases the information on the previously uploaded reconstruction parameters.

setActiveTermination(impedance)

Sets active termination (input impedance).

Parameters

impedance – input impedance [ohm]. Numerical scalar.

setAdcHpfCornerFrequency(frequency)

Sets corner frequency of digital high-pass filter (dHPF).

Parameters

frequency – dHPF corner frequency [Hz]. Numerical scalar.

setDtgcAttenuation(attenuation)

Sets digital TGC attenuation.

Digital TGC is an alternative for analog TGC. It is limited to a number of constant but precise attenuation levels.

Analog TGC/VCAT has to be disabled prior to setting digital TGC.

Parameters

attenuation – attenuation level [dB]. Numerical scalar.

Setting attenuation empty disables digital TGC.

setLnaGain(gain)

Sets LNA (Low Noise Amplifier) gain.

Parameters

gain – LNA gain [dB]. Numerical scalar.

setLnaHpfCornerFrequency(frequency)

Sets corner frequency of analog high-pass filter (aHPF).

Parameters

frequency – aHPF corner frequency [Hz]. Numerical scalar.

setLpfCutoff(frequency)

Sets cutoff frequency of analog low-pass filter (aLPF).

Parameters

frequency – aLPF cutoff frequency [Hz]. Numerical scalar.

setMaximumPulseLength(maxPulseLength)

Sets Tx pulse length limit.

WARNING: this function is for experienced users only. It allows to change the safety limits which may lead to system damage.

Parameters

maxPulseLength – Max pulse length [s]. Numerical scalar.

setPgaGain(gain)

Sets PGA (Programmable Gain Amplifier) gain.

Parameters

gain – PGA gain [dB]. Numerical scalar.

setReconstruction(reconstructOperation)

Uploads reconstruction parameters.

Parameters

reconstructOperation – reconstruction to perform with the collected data. Reconstruction scalar.

Returns

updated Us4R object.

setTgcCurve(varargin)

Sets analog TGC (Time Gain Control) curve.

TGC curve here includes all the analog gains/attenuation in the system, i.e. LNA gain, PGA gain, and VCAT attenuation. However, the setTgcCurve method adjust the TGC curve by modifying only the VCAT curve. It does not affect the LNA gain and PGA gain. Any of these can be controlled individually using dedicated methods. The setTgcCurve method is for controlling the overall gain curve.

Syntax: Us4RObj.setTgcCurve(time,gain,applyCharacteristic,clip) Us4RObj.setTgcCurve(gain,applyCharacteristic,clip)

Parameters

  • time – sampling time with respect to the “sample 0” [s]. Numerical vector. Optional, must be the same length as gain, default = hardware sampling time.

  • gain – gain samples [dB]. Numerical vector. Obligatory.

  • applyCharacteristic – If set to true, enables compensation of nonlinear TGC characteristic. Logical scalar. Obligatory.

  • clip – If set to true, enables TGC clipping to the allowed TGC gain range (resulting from LNA and PGA gain settings); otherwise, if gain exceeds the allowed range, an error will be raised. Logical scalar. Obligatory.

The actual TGC curve is a result of a linear interpolation of the provided curve to the hardware sampling points. If curve extrapolation is needed, curve boundary samples are used.

If the input curve contains values that cannot be achieved for the current LNA/PGA settings, the TGC curve is modified (saturated).

Setting time and gain as empty vectors disables analog TGC.

setVcatCurve(time, attenuation, applyCharacteristic, clip)

Sets analog VCAT (Voltage Controlled Attenuator) curve.

Syntax: Us4RObj.setVcatCurve(time,attenuation,applyCharacteristic) Us4RObj.setVcatCurve(time,attenuation,applyCharacteristic,clip)

Parameters

  • time – sampling time with respect to the “sample 0” [s]. Numerical vector. Obligatory.

  • attenuation – attenuation samples [dB]. Numerical vector. Obligatory. Must be the same length as time.

  • applyCharacteristic – If set to true, enables compensation of nonlinear VCAT characteristic. Logical scalar. Obligatory.

  • clip – If set to true, enables VCAT clipping to the allowed attenuation range; otherwise, if attenuation exceeds the allowed range, an error will be raised. Logical scalar. Optional, default = false.

The actual VCAT curve is a result of a linear interpolation of the provided curve to the hardware sampling points. If curve extrapolation is needed, curve boundary samples are used.

Setting time and attenuation as empty vectors disables analog VCAT.

stopScheme()

Stops running scheme

upload(sequenceOperation, reconstructOperation, enableHardwareProgramming, preset)

Uploads operations to the us4R system.

Parameters

  • sequenceOperation – Tx/Rx sequence to perform on the us4R system. CustomTxRxSequence scalar.

  • reconstructOperation – reconstruction to perform with the collected data. Reconstruction scalar.

  • enableHardwareProgramming – determines if the hardware is programmed or not. Logical scalar. Optional, default = true.

  • preset – set of system presets. CustomPreset vector.

Returns

updated Us4R object.

uploadSequence(sequenceOperation, enableHardwareProgramming)

Uploads multiple sequences to the us4R system.

Parameters

  • sequenceOperation – Tx/Rx sequence to perform on the us4R system. CustomTxRxSequence vector.

  • enableHardwareProgramming – determines if the hardware is programmed or not. Logical scalar. Optional, default = true.

Returns

updated Us4R object.

class arrus.CustomTxRxSequence(varargin)

A class that stores parameters of the sequence of Tx/Rx operations to be performed on the device.

CustomTxRxSequence(varargin)

Creates a CustomTxRxSequence object.

Syntax: obj = CustomTxRxSequence(name, value, …, name, value)

All inputs are organized in name-value pairs.

Parameters

  • txCenterElement – Center elements of the Tx apertures [elem]. Numerical vector.

  • txApertureCenter – Center positions of the Tx apertures [m]. Numerical vector.

  • txApertureSize – Sizes of the Tx apertures [elem]. Numerical vector.

  • rxCenterElement – Center elements of the Rx apertures [elem]. Numerical vector.

  • rxApertureCenter – Center positions of the Rx apertures [m]. Numerical vector.

  • rxApertureSize – Size of the Rx apertures [elem]. Numerical scalar.

  • txFocus – Tx focal distances [m]. Numerical vector.

  • txAngle – Tx angles [rad]. Numerical vector.

  • speedOfSound – Speed of sound determining the Tx delay profiles [m/s]. Numerical scalar.

  • txVoltage – Tx voltage level [V]. Can be: a scalar (pulse voltage range is [-txVoltage +txVoltage] for the whole sequence), or a 2x2 array (defines two sets of negative and positive Tx voltage amplitudes: [v1neg, v1pos; v2neg, v2pos]; the voltage range can be selected individually for each Tx using txVoltageId). txVoltage must always be nonnegative and v1 must be higher than v2. “Legacy” systems only support scalar txVoltage.

  • txVoltageId – Tx voltage level identifiers (can be 1 for range [-v1neg +v1pos], or 2 for [-v2neg +v2pos]). Numerical vector.

  • txFrequency – Tx frequencies [Hz]. Numerical vector.

  • txNPeriods – Numbers of sine periods in the Tx burst (can be 0.5, 1, 1.5, etc.). Numerical vector.

  • rxDepthRange – Acquisition depth range [m]. If scalar, it defines the upper depth limit (the lower one is set to 0). If 2-elem vector, it defines the lower and upper depth limits. Numerical scalar/2-elem vector.

  • rxNSamples – Number of acquired samples. Numerical scalar.

  • hwDdcEnable – Enables hardware DDC (Digital Down Conversion). It results in complex iq output data. Logical scalar.

  • decimation – Hardware decimation factor. Numerical scalar, positive integer.

  • nRepetitions – Number of repetitions of the sequence. Numerical scalar, positive integer.

  • txPri – Tx pulse repetition interval [s]. Numerical scalar.

  • tgcStart – TGC starting gain [dB]. Numerical scalar.

  • tgcSlope – TGC gain slope [dB/m]. Numerical scalar.

  • txInvert – Tx pulse polarity inversion. Logical vector.

  • workMode – System mode of operation. String scalar, can be “MANUAL”, “HOST”, “SYNC”, or “ASYNC”.

  • sri – Sequence repeting interval [s]. Numerical scalar.

  • bufferSize – number of buffer elements (each element contains data for a single sequence execution). Numerical scalar.

  • txWaveform – TX waveform to use. Scalar object of arrus.ops.us4r.Waveform class.

TGC gain = tgcStart + tgcSlope * propagation distance

class arrus.Reconstruction(varargin)

A class that stores parameters of the reconstruction operation to be performed in the system.

Reconstruction(varargin)

Creates a Reconstruction object.

Syntax: obj = Reconstruction(name, value, …, name, value)

All inputs are organized in name-value pairs.

Parameters

  • gridModeEnable – If set to true, enables grid-based reconstruction. If set to false, reconstruction is done classically, in a line-by-line manner. Logical scalar, default = true.

  • filterEnable – Enables filtration of the raw data. Logical scalar, default = false.

  • filterACoeff – Denominator coefficients of the raw data filter. Numerical vector, default = [].

  • filterBCoeff – Numerator coefficients of the raw data filter. Numerical vector, default = [].

  • filterDelay – Delay introduced by the filter [samples].Numerical scalar, default = 0. Not yet implemented.

  • swDdcEnable – Enables software DDC (Digital Down Convertion). Logical scalar.

  • decimation – Software decimation factor. Numerical scalar.

  • xGrid – Coordinate grid x [m]. Numerical vector, default = [].

  • zGrid – Coordinate grid z [m]. Numerical vector, default = [].

  • sos – Speed of sound value used for reconstruction [m/s]. Numerical scalar.

  • rxApod – Rx apodization window. Numerical vector, default = [1 1].

  • bmodeEnable – Enables B-Mode reconstruction. Logical scalar, default = true.

  • colorEnable – Enables Color Doppler reconstruction and Duplex imaging. Logical scalar, default = false.

  • vectorEnable – Enables Vector Doppler reconstruction and Duplex imaging. Logical scalar, default = false.

  • bmodeFrames – Frame numbers to be used in B-Mode reconstruction. Numerical vector.

  • colorFrames – Frame numbers to be used in Color Doppler reconstruction. Numerical vector.

  • vector0Frames – Frame numbers to be used in Vector Doppler reconstruction as 1st projection. Numerical vector.

  • vector1Frames – Frame numbers to be used in Vector Doppler reconstruction as 2nd projection. Numerical vector.

  • bmodeRxTangLim – Rx tangent limits for B-Mode. Numerical array (K*, 2), default = [-0.5 0.5].

  • colorRxTangLim – Rx tangent limits for Color Doppler. Numerical array (M*, 2), default = [-0.5 0.5].

  • vector0RxTangLim – Rx tangent limits for Vector Doppler (1st projection). Numerical array (N*, 2), default = [-0.5 0.5].

  • vector1RxTangLim – Rx tangent limits for Vector Doppler (2nd projection). Numerical array (N*, 2), default = [-0.5 0.5].

  • wcFilterACoeff – Denominator coefficients of the Wall Clutter Filter (WCF) for Color/Vector Doppler. Numerical vector.

  • wcFilterBCoeff – Numerator coefficients of the Wall Clutter Filter (WCF) for Color/Vector Doppler. Numerical vector.

  • wcFiltInitSize – Number of initial WCF output samples to be rejected due to the filter initialization. Numerical scalar.

  • cohFiltEnable – Enables coherence-weighted filtration. Logical scalar, default = false.

  • cohCompEnable – Enables coherent compounding. If set to false, the compounding is performed on envelope images (incoherently). Logical scalar, default = false.

  • K, M, N - length of bmodeFrames, colorFrames, and vector0Frames or vector1Frames, respectively.

Returns

Reconstruction object.

Utilities

class arrus.BModeDisplay(varargin)

Bases: handle

B-mode image display class.

Currently implemented as a simple MATLAB figure with dynamically updated content.

Includes a cineloop buffer. The content of the buffer can be accessed through the getCineLoop method.

BModeDisplay(varargin)

Creates a BModeDisplay object.

Syntax: obj = BModeDisplay(reconstructionObject, name, value, …, name, value)

First input is obligatory, further inputs are optional and are organized in name-value pairs.

Parameters

  • reconstructionObject – Object of class “Reconstruction”. Obligatory input.

  • dynamicRange – Dynamic range limits [dB]. Two-element vector [min, max]. Optional name-value argument, default = [0 80].

  • cineLoopLength – Cineloop buffer size (number of frames stored in the buffer). Positive scalar. Optional name-value argument, default = 1.

  • persistence – If given, enables persistence. If scalar, it defines the persistence filter length. If vector, it defines the persistence filter coefficients. Optional name-value argument, default = 1 (no persistence).

  • bmodeTgc – If given, enables linear TGC from 0 dB at the top to the given value [dB] at the bottom of the image. Scalar. Optional name-value argument, default = 0.

  • bmodeAutoTgcResp – If given, enables linear TGC that adapts in time to the imaging conditions. The responsiveness of the adaptation: 0-no adaptation, 1-instant adaptation. Scalar, in the range <0,1>. Optional name-value argument, default = 0.

Returns

BModeDisplay object.

getCineLoop()

Returns the cineloop buffer.

Returns

Cineloop buffer.

isOpen()

Checks if the display window is open.

Returns

True if the display window was not closed, false otherwise.

updateImg(data)

Updates currently displayed image.

Parameters

data – B-mode data to be displayed.

class arrus.DuplexDisplay(varargin)

Bases: handle

Duplex image display class.

Currently implemented as a simple MATLAB figure with dynamically updated content.

Includes a cineloop buffer. The content of the buffer can be accessed through the getCineLoop method.

DuplexDisplay(varargin)

Creates a DuplexDisplay object.

Syntax: obj = DuplexDisplay(reconstructionObject, name, value, …, name, value)

First input is obligatory, further inputs are optional and are organized in name-value pairs.

Parameters

  • reconstructionObject – Object of class “Reconstruction”. Obligatory input.

  • dynamicRange – Dynamic range limits [dB]. Two-element vector [min, max]. Optional name-value argument, default = [0 80].

  • cineLoopLength – Cineloop buffer size (number of frames stored in the buffer). Positive scalar. Optional name-value argument, default = 1.

  • persistence – If given, enables persistence. If scalar, it defines the persistence filter length. If vector, it defines the persistence filter coefficients. Optional name-value argument, default = 1 (no persistence).

  • bmodeTgc – If given, enables linear TGC from 0 dB at the top to the given value [dB] at the bottom of the image. Scalar. Optional name-value argument, default = 0.

  • bmodeAutoTgcResp – If given, enables linear TGC that adapts in time to the imaging conditions. The responsiveness of the adaptation: 0-no adaptation, 1-instant adaptation. Scalar, in the range <0,1>. Optional name-value argument, default = 0.

  • powerThreshold – Power limit [dB] BELOW which the color data is not displayed. Scalar. Optional name-value argument, default = -inf (no thresholding).

  • turbuThreshold – Turbulence limit ABOVE which the color data is not displayed. Scalar. Optional name-value argument, default = 1 (no thresholding, as turbulence is limited to 0-1 range by definition).

  • stdevThreshold – Limit of standard deviation of color data ABOVE which the color data is not displayed. Scalar. Optional name-value argument, default = inf (no thresholding).

  • thresholdSmooth – Size [pix] of the circular smoothing kernel applied to the data that are used for thresholding, i.e. power, turbulence, and st. deviation. Scalar. Optional name-value argument, default = 0 (no smoothing).

  • subplotEnable – Enables separate display of Duplex, B-mode, power, and turbulence images. Logical scalar. Optional name-value argument, default = false.

Returns

DuplexDisplay object.

getCineLoop()

Returns the cineloop buffer.

Returns

Cineloop buffer.

isOpen()

Checks if the display window is open.

Returns

True if the display window was not closed, false otherwise.

updateImg(data)

Updates currently displayed image.

Parameters

data – Duplex data to be displayed.