API Reference¶

Session¶

class arrus.Session(cfg_path: str = 'us4r.prototxt', medium: arrus.medium.Medium = None)¶

A communication session with the ultrasound system.

Currently, only localhost session is available.

This class is a context manager. All the processing to be done on the device on the devices should be done withing the session context.

get_device(path: str)¶

Returns a device identified by a given id.

The available devices are determined by the initial session settings.

The handle to device is invalid after the session is closed (i.e. the session object is disposed).

Parameters: path – a path to the device
Returns: a handle to device

start_scheme()¶: Starts the execution of the uploaded scheme.

stop_scheme()¶: Stops execution of the scheme.

upload(scheme: arrus.ops.us4r.Scheme)¶

Uploads a given sequence on devices.

Parameters: scheme – scheme to upload
Raises: ValueError when some of the input parameters are invalid
Returns: a data buffer and constant metadata

Operations¶

Scheme¶

class arrus.ops.us4r.Scheme(tx_rx_sequence: arrus.ops.us4r.TxRxSequence, rx_buffer_size: int = 2, output_buffer: arrus.ops.us4r.DataBufferSpec = DataBufferSpec(n_elements=4, type='FIFO'), work_mode: str = 'HOST', processing: object = None)¶

Bases: object

A scheme to load on the us4r device.

Parameters

tx_rx_sequence – a sequence of tx/rx parameters to perform
rx_buffer_size – number of elements the rx buffer (allocated on us4r ddr internal memory) should consists of
output_buffer – specification of the output buffer
work_mode – determines the system work mode, available values: ‘ASYNC’, ‘HOST’
processing – data processing to perform on the raw channel RF data currently only arrus.utils.imaging is supported

class arrus.ops.us4r.DataBufferSpec(n_elements: int, type: str)¶

Bases: object

Output data buffer specification.

Parameters

n_elements – number of elements the buffer should consists of
type – type of a buffer, available values: “FIFO”

Common Tx/Rx sequences¶

class arrus.ops.imaging.SimpleTxRxSequence(pulse: arrus.ops.us4r.Pulse, rx_sample_range: tuple, pri: float, sri: float = None, speed_of_sound: float = None, tx_focus: object = inf, angles: object = 0.0, downsampling_factor: int = 1, tx_aperture_center_element: list = None, tx_aperture_center: list = None, tx_aperture_size: list = None, rx_aperture_center_element: list = None, rx_aperture_center: list = None, rx_aperture_size: list = None, tgc_start: float = None, tgc_slope: float = None, tgc_curve: list = None)¶

Bases: object

A base class for Lin, PWI and STA sequences.

At most one of the following needs to be specified:

tx_aperture_center_element and tx_aperture_center,
rx_aperture_center_element and rx_aperture_center.

All the following parameters should have the same length (if they are not scalar):

tx_aperture_center_element/tx_aperture_center,
rx_aperture_center_element/rx_aperture_center,
tx_aperture_size,
angles,

_ tx_focus.

If any of the above parameters is a scalar, its value will be broadcasted to the size of the largest array.

All probe or aperture element numeration starts from 0.

Parameters

tx_aperture_center_element – a list of TX aperture center positions (ordinal number of element). Optional, by default the center of the probe will be used.
tx_aperture_center – a list of TX aperture center positions. Optional, by default the center of the probe will be used. [m]
tx_aperture_size – number of elements in TX aperture, by default all probe elements are used [m].
rx_aperture_center_element – a list of RX aperture center positions (ordinal number of element). Optional, by default the center of the probe will be used.
rx_aperture_center – a list of RX aperture center positions. Optional, by default the center of the probe will be used. [m]
rx_aperture_size – number of elements in RX aperture, by default all probe elements are used. Has to be scalar.
angles – transmission angles [rad]
tx_focus – transmission focus, must be a scalar (a single value for all TX/RXs) [m]
pulse – a pulse excitation to perform
pri – pulse repetition interval [s]
downsampling_factor – downsampling factor (decimation), integer factor to decrease sampling frequency of the output signal, by default 1.
speed_of_sound – assumed speed of sound [m/s]
tgc_start – tgc starting gain [dB]
tgc_slope – tgc gain slope [dB/m]
sri – sequence repetition interval - the time between consecutive RF frames. When None, the time between consecutive RF frames is determined by the total pri only. [s]

class arrus.ops.imaging.LinSequence(pulse: arrus.ops.us4r.Pulse, rx_sample_range: tuple, pri: float, sri: float = None, speed_of_sound: float = None, tx_focus: object = inf, angles: object = 0.0, downsampling_factor: int = 1, tx_aperture_center_element: list = None, tx_aperture_center: list = None, tx_aperture_size: list = None, rx_aperture_center_element: list = None, rx_aperture_center: list = None, rx_aperture_size: list = None, tgc_start: float = None, tgc_slope: float = None, tgc_curve: list = None, init_delay: str = 'tx_start')¶

Bases: arrus.ops.imaging.SimpleTxRxSequence

Linear scanning (classical beamforming) TX/RX sequence.

Requirements:

tx_focus must be finite positive and scalar,
tx angle must be a scalar.

Parameters: init_delay – when the record should start, available options: ‘tx_start’ - the first recorded sample is when the transmit starts, ‘tx_center’ - the first recorded sample is delayed by tx aperture center delay and burst factor.

class arrus.ops.imaging.PwiSequence(pulse: arrus.ops.us4r.Pulse, rx_sample_range: tuple, pri: float, sri: float = None, speed_of_sound: float = None, tx_focus: object = inf, angles: object = 0.0, downsampling_factor: int = 1, tx_aperture_center_element: list = None, tx_aperture_center: list = None, tx_aperture_size: list = None, rx_aperture_center_element: list = None, rx_aperture_center: list = None, rx_aperture_size: list = None, tgc_start: float = None, tgc_slope: float = None, tgc_curve: list = None)¶

Bases: arrus.ops.imaging.SimpleTxRxSequence

A sequence of Tx/Rx operations for plane wave imaging.

Requirements: - tx_focus has to be infinity (default value).

class arrus.ops.imaging.StaSequence(pulse: arrus.ops.us4r.Pulse, rx_sample_range: tuple, pri: float, sri: float = None, speed_of_sound: float = None, tx_focus: object = inf, angles: object = 0.0, downsampling_factor: int = 1, tx_aperture_center_element: list = None, tx_aperture_center: list = None, tx_aperture_size: list = None, rx_aperture_center_element: list = None, rx_aperture_center: list = None, rx_aperture_size: list = None, tgc_start: float = None, tgc_slope: float = None, tgc_curve: list = None)¶

Bases: arrus.ops.imaging.SimpleTxRxSequence

A sequence of Tx/Rx operations for synthetic transmit aperture (diverging beams).

Requirements: - tx focus has to be finite, non-positive.

Custom Tx/Rx sequences¶

class arrus.ops.us4r.TxRxSequence(ops: List[arrus.ops.us4r.TxRx], tgc_curve: numpy.ndarray, sri: float = None)¶

Bases: object

A sequence of tx/rx operations to perform.

Parameters

operations – sequence of TX/RX operations to perform
tgc_curve – TGC curve samples [dB]
sri – sequence repetition interval - the time between consecutive RF frames. When None, the time between consecutive RF frames is determined by the total pri only. [s]

get_n_samples()¶: Returns a set of number of samples that the Tx/Rx sequence defines.

class arrus.ops.us4r.Pulse(center_frequency: float, n_periods: float, inverse: bool)¶

Bases: object

A definition of the pulse that can be triggered by the us4r device.

Parameters

center_frequency – pulse center frequency [Hz]
n_periods – number of periods of the generated pulse, possible values: 0.5, 1, 1.5, …
inverse – true if the signal amplitude should be reversed, false otherwise

class arrus.ops.us4r.TxRx(tx: arrus.ops.us4r.Tx, rx: arrus.ops.us4r.Rx, pri: float)¶

Bases: object

Single atomic operation of pulse transmit and signal data reception.

Parameters

tx – signal transmit to perform
rx – signal reception to perform
pri – pulse repetition interval [s] - time to next event

class arrus.ops.us4r.Tx(aperture: numpy.ndarray, excitation: arrus.ops.us4r.Pulse, delays: Optional[numpy.ndarray] = None)¶

Bases: arrus.ops.operation.Operation

Single atomic operation of a signal transmit.

Parameters

aperture – a set of TX channels that should be enabled - a binary mask, where 1 at location i means that the channel should be turned on, 0 means that the channel should be turned off
pulse – an excitation to perform
delays – an array of delays to set to active elements. Should have the shape (n_a,), where n_a is a number of active elements determined by tx aperture. When None, firings are performed with no delay (delays=0) [s] The stored value is always of type numpy.ndarray.

class arrus.ops.us4r.Rx(aperture: numpy.ndarray, sample_range: tuple, downsampling_factor: int = 1, padding: tuple = (0, 0))¶

Bases: arrus.ops.operation.Operation

Single atomic operation of echo data reception.

Parameters

aperture – a set of RX channels that should be enabled - a binary mask, where 1 at location i means that the channel should be turned on, 0 means that the channel should be turned off. The stored value is always of type numpy.ndarray.
sample_range – a range of samples to acquire [start, end), starts from 0
downsampling_factor – a sampling frequency divider. For example, if nominal sampling frequency (fs) is equal to 65e6 Hz, fs_divider=1, means to use the nominal fs, fs_divider=2 means to use 32.5e6 Hz, etc.
padding – a pair of values (left, right); the left/right value means how many zero-channels should be added from the left/right side of the aperture. This parameter helps achieve a regular ndarray when a sequence of Rxs has a non-constant aperture size (e.g. classical beamforming).

Devices¶

Do not create instances of the below classes directly. Use session.get_device to acquire the appropriate device, for example: session.get_device('/Us4R:0').

class arrus.devices.us4r.Us4R(handle, parent_session)¶

Bases: arrus.devices.device.Device

A handle to Us4R device.

Wraps an access to arrus.core.Us4R object.

property sampling_frequency¶: Device sampling frequency [Hz].

set_hv_voltage(voltage)¶

Enables HV and sets a given voltage.

Parameters: voltage – voltage to set

class arrus.devices.gpu.GPU(index)¶: Bases: arrus.devices.device.Device

class arrus.devices.cpu.CPU(index)¶: Bases: arrus.devices.device.Device

Output data¶

An instance of the following class is returned by the sesion.upload function:

class arrus.framework.DataBuffer(buffer_handle)¶

Bases: object

The output data buffer.

This buffer allows to register a callback, that should called when new data arrives.

The buffer elements are automatically released after running all available callbacks.

append_on_new_data_callback(callback)¶

Append to the list of callbacks that should be run when new data arrives.

Note: the callback function should explicitly release buffer element using

Parameters: callback – a callback function, should take one parameter – DataBufferElement instance

Data buffers consists of multiple buffer elements.

class arrus.framework.DataBufferElement(element_handle)¶

Bases: object

Data buffer element. Allows to access the space of the acquired data.

property data¶: The data wrapped into a numpy array.

Metadata¶

class arrus.metadata.ConstMetadata(context: arrus.metadata.FrameAcquisitionContext, data_desc: arrus.metadata.DataDescription, input_shape, is_iq_data, dtype)¶

Bases: object

Metadata describing the acquired data.

This class is immutable.

Parameters

context – frame acquisition context
data_desc – data characteristic
custom – custom frame data (e.g. trigger counters, etc.)
input_shape – input shape of the data, a tuple
is_iq_data – true if we have bandpass data, false otherwise
dtype – data type

class arrus.metadata.EchoDataDescription(sampling_frequency: float, custom: dict = <factory>)¶

Bases: arrus.metadata.DataDescription

Data description of the ultrasound echo data.

Parameters

sampling_frequency – a sampling frequency of the data
custom – custom information

class arrus.metadata.FrameAcquisitionContext(device: arrus.devices.device.UltrasoundDeviceDTO, sequence: arrus.ops.operation.Operation, raw_sequence: arrus.ops.us4r.TxRxSequence, medium: arrus.medium.MediumDTO, custom_data: dict)¶

Bases: object

Metadata describing RF frame acquisition process.

Parameters

device – ultrasound device specification
sequence – a sequence that the user wanted to execute on the device
raw_sequence – an actual Tx/Rx sequence that was uploaded on the system
medium – description of the Medium assumed during communication session with the device
custom_data – a dictionary with custom data

Utility functions¶

B-mode imaging pipeline using cupy/numpy¶

class arrus.utils.imaging.Pipeline(steps, placement=None)¶

Bases: object

Imaging pipeline.

Processes given data using a given sequence of steps. The processing will be performed on a given device (‘placement’).

class arrus.utils.imaging.FirFilter(taps, num_pkg=None, filter_pkg=None)¶: Bases: arrus.utils.imaging.Operation

class arrus.utils.imaging.BandpassFilter(numtaps=7, bounds=(0.5, 1.5), filter_type='butter', num_pkg=None, filter_pkg=None)¶

Bases: arrus.utils.imaging.Operation

Bandpass filtering to apply to signal data.

A bandwidth [0.5, 1.5]*center_frequency is currently used.

The filtering is performed along the last axis.

Currently only FIR filter is available.

NOTE: consider using Filter op, which provides more possibilities to define what kind of filter is used (e.g. by providing filter coefficients).

class arrus.utils.imaging.QuadratureDemodulation(num_pkg=None)¶

Bases: arrus.utils.imaging.Operation

Quadrature demodulation (I/Q decomposition).

class arrus.utils.imaging.Decimation(decimation_factor, cic_order, num_pkg=None, impl='legacy')¶

Bases: arrus.utils.imaging.Operation

Decimation + CIC (Cascade Integrator-Comb) filter.

See: https://en.wikipedia.org/wiki/Cascaded_integrator%E2%80%93comb_filter

class arrus.utils.imaging.RxBeamforming(num_pkg=None)¶

Bases: arrus.utils.imaging.Operation

Classical rx beamforming (reconstructing scanline by scanline).

Expected input data shape: n_emissions, n_rx, n_samples

Currently the beamforming op works only for LIN sequence output data.

class arrus.utils.imaging.EnvelopeDetection(num_pkg=None)¶

Bases: arrus.utils.imaging.Operation

Envelope detection (Hilbert transform).

Currently this op works only for I/Q data (complex64).

class arrus.utils.imaging.Transpose(axes=None)¶

Bases: arrus.utils.imaging.Operation

Data transposition.

class arrus.utils.imaging.ScanConversion(x_grid, z_grid)¶

Bases: arrus.utils.imaging.Operation

Scan conversion (interpolation to target mesh).

Currently linear interpolation is used by default, values outside the input mesh will be set to 0.0.

Currently the op is implement for CPU only.

Currently, the op is available only for convex probes.

class arrus.utils.imaging.LogCompression¶

Bases: arrus.utils.imaging.Operation

Converts data to decibel scale.

class arrus.utils.imaging.Lambda(function)¶

Bases: arrus.utils.imaging.Operation

Custom function to perform on data from a given step.

class arrus.utils.imaging.Enqueue(queue, block=True, ignore_full=False)¶

Bases: arrus.utils.imaging.Operation

Copies the output data from the previous stage to the provided queue and passes the input data unmodified for further processing.

Works on queue.Queue objects.

Parameters

queue – queue.Queue instance
block – if true, will block the pipeline until a free slot is available, otherwise will raise queue.Full exception
ignore_full – when true and block = False, this step will not throw queue.Full exception. Set it to true if it is ok to ommit some of the acquired frames.

class arrus.utils.imaging.SelectFrames(frames)¶

Bases: arrus.utils.imaging.Operation

Selects frames for a given sequence for further processing.

class arrus.utils.imaging.Squeeze¶

Bases: arrus.utils.imaging.Operation

Squeezes input array (removes axes = 1).

class arrus.utils.imaging.ReconstructLri(x_grid, z_grid, rx_tang_limits=None)¶

Bases: arrus.utils.imaging.Operation

Rx beamforming for synthetic aperture imaging.

Expected input data shape: n_emissions, n_rx, n_samples :param x_grid: output image grid points (OX coordinates) :param z_grid: output image grid points (OZ coordinates) :param rx_tang_limits: RX apodization angle limits (given as the tangent of the angle), a pair of values (min, max). If not provided or None, [-0.5, 0.5] range will be used

class arrus.utils.imaging.Sum(axis=- 1)¶

Bases: arrus.utils.imaging.Operation

Sum of array elements over a given axis.

Parameters: axis – axis along which a sum is performed

class arrus.utils.imaging.Mean(axis=- 1)¶

Bases: arrus.utils.imaging.Operation

Average of array elements over a given axis.

Parameters: axis – axis along which a average is computed

Logging¶

arrus.set_clog_level(level)¶

Sets console log level output.

Parameters: level – log level to use

arrus.add_log_file(filepath, level)¶

Adds message logging to given file.

Parameters

filepath – path to output log file
level – severity level

The following log severity levels are available: arrus.logging.TRACE, arrus.logging.DEBUG, arrus.logging.INFO, arrus.logging.WARNING, arrus.logging.ERROR, arrus.logging.FATAL