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.

close()

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 exception.

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

get_parameter(key: str) → Sequence[numbers.Number]

Returns the current value for parameter with the given name.

property medium

Returns currently set Medium. NOTE: this method is not thread-safe!

run(sync: bool = False, timeout: int = None)

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. This parameter only matters when the work mode is set to MANUAL or MANUAL_OP.

  • 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.

set_parameter(key: str, value: Sequence[numbers.Number])

Sets the value for parameter with the given name. TODO: note: this method currently is not thread-safe

set_subsequence(start, end, processing=None, sri=None)

Sets the current TX/RX sequence to the [start, end] subsequence (both inclusive).

This method requires that:

  • start <= end (when start= == end, the system will run a single TX/RX sequence),

  • the scheme was uploaded,

  • the TX/RX sequence length is greater than the end value,

  • the scheme is stopped.

You can specify the new SRI with the sri parameter, if None, the total PRI will be used.

Returns

the new data buffer and metadata

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, digital_down_conversion: arrus.ops.us4r.DigitalDownConversion = None, constants: List[arrus.framework.constant.Constant] = ())

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’, ‘MANUAL’, ‘MANUAL_OP’

  • 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, pri: float, rx_sample_range: tuple = None, sri: float = None, speed_of_sound: float = None, tx_focus: Union[object, arrus.framework.constant.Constant] = inf, angles: object = 0.0, downsampling_factor: int = 1, tx_aperture_center_element: list = None, tx_aperture_center: list = None, tx_aperture_size: int = None, rx_aperture_center_element: list = None, rx_aperture_center: list = None, rx_aperture_size: int = None, tgc_start: float = None, tgc_slope: float = None, tgc_curve: list = None, n_repeats: int = 1, init_delay: str = 'tx_start', rx_depth_range: tuple = 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]

  • n_repeats – size of a single batch – how many times this sequence should be repeated before data is transferred to computer (integer)

  • init_delay – when the recording 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.

  • rx_depth_range – defines the beginning and the end (if two-element vector) of the acquisition expressed by depth range [m] Optional exactly one of the following should be provided: rx_sample_range or rx_depth_range.

get_subsequence(start, end)

Limits the sequence to the given sub-sequence [start, end] both inclusive.

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

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.

class arrus.ops.imaging.PwiSequence(pulse: arrus.ops.us4r.Pulse, pri: float, rx_sample_range: tuple = None, sri: float = None, speed_of_sound: float = None, tx_focus: Union[object, arrus.framework.constant.Constant] = inf, angles: object = 0.0, downsampling_factor: int = 1, tx_aperture_center_element: list = None, tx_aperture_center: list = None, tx_aperture_size: int = None, rx_aperture_center_element: list = None, rx_aperture_center: list = None, rx_aperture_size: int = None, tgc_start: float = None, tgc_slope: float = None, tgc_curve: list = None, n_repeats: int = 1, init_delay: str = 'tx_start', rx_depth_range: tuple = 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, pri: float, rx_sample_range: tuple = None, sri: float = None, speed_of_sound: float = None, tx_focus: Union[object, arrus.framework.constant.Constant] = inf, angles: object = 0.0, downsampling_factor: int = 1, tx_aperture_center_element: list = None, tx_aperture_center: list = None, tx_aperture_size: int = None, rx_aperture_center_element: list = None, rx_aperture_center: list = None, rx_aperture_size: int = None, tgc_start: float = None, tgc_slope: float = None, tgc_curve: list = None, n_repeats: int = 1, init_delay: str = 'tx_start', rx_depth_range: tuple = 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: Union[numpy.ndarray, Iterable] = <factory>, sri: float = None, n_repeats: int = 1)

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.

get_sample_range()

Returns a set of sample ranges that the Tx/Rx sequence defines.

get_sample_range_unique()

Returns a unique sample range that the Tx/Rx sequence defines. If there are couple of different number of samples in a single sequence, a ValueError will be raised.

get_subsequence(start, end)

Limits the sequence to the given sub-sequence [start, end] both inclusive.

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: Union[numpy.ndarray, arrus.ops.us4r.Aperture], excitation: arrus.ops.us4r.Pulse, delays: Optional[numpy.ndarray] = None, focus: Optional[float] = None, angle: Optional[float] = None, speed_of_sound: Optional[float] = None)

Bases: arrus.ops.operation.Operation

Single atomic operation of a signal transmit.

Users can specify TX delays in one of the following ways:

  1. by providing (focus, angle, speed_of_sound): TX delays will be automatically determined based on the provided values and probe parameters.

  2. by providing array of raw TX delays.

Exactly one of the following parameter combination should be provided (otherwise you will get validation error): (focus, angle, speed_of_sound) or delays.

The transmit focus can be specified by pair (focus, angle), which are polar coordinates of the TX focus to be applied. A vector with such coordinates is hooked at the center of the aperture. focus = np.inf means plane wave transmission.

The focus depth can be negative, which means TX form a virtual source located above the probe (i.e. diverging beam transmission).

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, or an instance of Aperture class.

  • excitation – an excitation to perform

  • delays – an array of delays to set to active elements [s]. Should have the shape (n_a,), where n_a is a number of active elements determined by tx aperture. The stored value is always of type numpy.ndarray.

  • focus – transmission focus depth [m] np.inf means to transmit plane wave

  • angle – transmission angles [rad]

  • speed_of_sound – assumed speed of sound [m/s]

class arrus.ops.us4r.Rx(aperture: Union[numpy.ndarray, arrus.ops.us4r.Aperture], sample_range: tuple, downsampling_factor: int = 1, padding: tuple = (0, 0), init_delay: str = 'tx_start')

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, or an instance of Aperture class.

  • 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, downsampling_factor=1, means to use the nominal fs, downsampling_factor=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).

  • init_delay – when the recording 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.

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)

Bases: arrus.devices.device.Device, arrus.devices.ultrasound.Ultrasound

A handle to Us4R device.

Wraps an access to arrus.core.Us4R object.

property channels_mask

Returns a list of system channels that are masked in the configuration.

property current_sampling_frequency

Device current Rx data sampling frequency [Hz]. This value depends on the TX/RX and DDC parameters (e.g. decimation factor) uploaded on the system.

disable_hpf()

Disables digital high-pass filter.

disable_hv()

Turns off HV.

get_afe(addr)

Reads AFE register value

Parameters

addr – register address (8-bit)

get_backplane() → arrus.devices.us4r.Backplane

Returns a handle to us4R digital backplane.

get_data_description(upload_result, sequence)

DEPRECATED: This method will be removed after moving most of the session-related code to the ARRUS core.

get_dto()

Returns descriptor of this device.

get_us4oem(ordinal: int)

Returns a handle to us4OEM with the given number.

Returns

an object of type arrus.devices.us4oem.Us4OEM

property sampling_frequency

Device NOMINAL sampling frequency [Hz].

set_afe(addr, reg)

Writes AFE register

Parameters

  • addr – register address (8-bit)

  • k – write value (16-bit)

set_dtgc_attenuation(attenuation: Optional[int])

Sets DTGC attenuation.

Available: 0, 6, 12, 18, 24, 30, 36, 42 [dB] or None; None turns off DTGC.

Parameters

attenuation – attenuation value to set

Returns

set_hpf_corner_frequency(frequency: int)

Enables digital High-Pass Filter and sets a given corner frequency. Available corner frequency values (Hz): 4520’000, 2420’000, 1200’000, 600’000, 300’000, 180’000, 80’000, 40’000, 20’000.

Parameters

frequency – corner high-pass filter frequency to set

set_hv_voltage(voltage)

Enables HV and sets a given voltage.

Parameters

voltage – voltage to set

set_kernel_context(kernel_context)

This method is intended to provide any session specific data to the device, on the stage of sequence upload.

set_lna_gain(gain: int)

Sets LNA gain.

Available: 12, 18, 24 [dB].

Parameters

gain – gain value to set

set_maximum_pulse_length(max_length)

Sets maximum pulse length that can be set during the TX/RX sequence programming. None means to use up to 32 TX cycles.

Parameters

max_length – maxium pulse length (s) nullopt means to use 32 TX cycles (legacy OEM constraint)

set_pga_gain(gain: int)

Sets PGA gain.

Available: 24, 30 [dB].

Parameters

gain – gain value to set

set_stop_on_overflow(is_stop)

Set the system to stop when (RX or host) buffer overflow is detected (ASYNC mode only). This property is set by default to true.

set_test_pattern(pattern)

Sets given test ADC test pattern to be run by Us4OEM components.

set_tgc(tgc_curve)

Sets TGC samples for given TGC description.

Parameters

samples – a given TGC to set.

class arrus.devices.us4oem.Us4OEM(handle)

Bases: arrus.devices.device.Device

get_firmware_version() → int

Returns us4OEM’s main firmware version.

get_fpga_temperature() → float

Returns Us4OEM FPGA temperature [Celsius]

get_revision() → str

Returns revision number of the device.

get_serial_number() → str

Returns serial number of the device.

get_tx_firmware_version() → int

Returns TX Firmware version.

get_ucd_external_temperature() → float

Returns Us4OEM UCD external temperature [Celsius]

get_ucd_temperature() → float

Returns Us4OEM UCD temperature [Celsius]

set_wait_for_hvps_measurement_done()

Configures the system to sync with the HVPS Measurement done irq.

This method is intended to be used in the probe_check implementation.

wait_for_hvps_measurement_done(timeout: int = None)

Waits for the HVPS Measurement done irq.

This method is intended to be used in the probe_check implementation.

class arrus.devices.us4r.Backplane(us4r)

Bases: object

Digital backplane of the us4R device.

get_revision() → str

Returns revision number of the digital backplane.

get_serial_number() → str

Returns serial number of the digital backplane.

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.Metadata(context: arrus.metadata.FrameAcquisitionContext, data_desc: arrus.metadata.DataDescription, custom: dict)

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.)

class arrus.metadata.EchoDataDescription(sampling_frequency: float, custom: dict = <factory>, spacing: Optional[arrus.metadata.Grid] = None)

Bases: arrus.metadata.DataDescription

Data description of the ultrasound echo data.

Parameters

  • sampling_frequency – a sampling frequency of the data

  • custom – custom information

  • spacing – spacing (physical coordinates) of the data array values. The subsequent values should correspond to the subsequent data array axes.

class arrus.metadata.FrameAcquisitionContext(device: arrus.devices.ultrasound.UltrasoundDTO, sequence: arrus.ops.operation.Operation, raw_sequence: arrus.ops.operation.Operation, medium: arrus.medium.MediumDTO, custom_data: dict, constants: List)

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, name=None)

Bases: object

Imaging pipeline.

Processes given data using a given sequence of steps. The processing will be performed on a given device (‘placement’). :param steps: processing steps to run :param placement: device on which the processing should take place,

default: GPU:0

class arrus.utils.imaging.FirFilter(taps, num_pkg=None, filter_pkg=None)

Bases: arrus.utils.imaging.Operation

class arrus.utils.imaging.BandpassFilter(order=63, bounds=(0.5, 1.5), filter_type='hamming', num_pkg=None, filter_pkg=None, **kwargs)

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, filter_type='cic', filter_coeffs=None, cic_order=2, num_pkg=None)

Bases: arrus.utils.imaging.Operation

Downsampling + Low-pass filter.

By default CIC filter is used.

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

Bases: arrus.utils.imaging.Operation

Classical rx beamforming (reconstruct image scanline by scanline). This operator implements beamforming for linear scanning (element by element) and phased scanning (angle by angle).

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, prepare_func=None)

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

Probe check functionality

class arrus.utils.probe_check.FeatureDescriptor(name: str, active_range: tuple, masked_elements_range: tuple, params: Dict[str, Any] = <factory>)

Bases: object

Descriptor class for signal features used for probe ‘diagnosis’.

Parameters

  • name – feature name (“amplitude” or “signal_duration_time”)

  • active_range – feature range of values possible to obtain from active ‘healthy’ transducer

  • masked_elements_range – feature range of values possible to obtain from inactive ‘healthy’ transducer

class arrus.utils.probe_check.ElementValidationVerdict(value)

Bases: enum.Enum

Contains element validation verdict.

class arrus.utils.probe_check.ProbeElementValidatorResult(verdict: arrus.utils.probe_check.ElementValidationVerdict, valid_range: tuple)

Bases: object

Contains single element validation result.

Parameters

  • verdict – ElementValidationVerdict object

  • valid_range – tuple contained valid range for examined feature

class arrus.utils.probe_check.ProbeElementFeatureDescriptor(name: str, value: float, validation_result: arrus.utils.probe_check.ProbeElementValidatorResult)

Bases: object

Descriptor class for results of element checking.

Parameters

  • name – name of the feature used for element check

  • value – value of the feature

  • validation_result – ProbeElementValidationResult object contained verdict and valid range for examined feature

class arrus.utils.probe_check.ProbeElementHealthReport(is_masked: bool, features: Dict[str, arrus.utils.probe_check.ProbeElementFeatureDescriptor], element_number: int)

Bases: object

Report of a single probe element health check.

The probe element can be in one of the following states: - “VALID”: the element seems to work correctly, - “TOO_HIGH”: the element is characterised by too high feature value, - “TOO_LOW”: the element is characterised by too low feature value, - “INDEFINITE”: the estimate of the feature value failed. The information on feature value are in features attribute, where the list of ProbeElementFeatureDescriptor instances are stored.

Parameters

  • is_masked – whether the element was masked in the system cfg

  • features – dict of ProbeElementFeatureDescriptor oebjects [feature name -> feature descriptor]

  • element_number – element number

class arrus.utils.probe_check.ProbeHealthReport(params: dict, sequence_metadata: arrus.metadata.ConstMetadata, elements: Iterable[arrus.utils.probe_check.ProbeElementHealthReport], data: numpy.ndarray, footprint: numpy.ndarray, validator: arrus.utils.probe_check.ProbeElementValidator, aux: Dict[str, Any])

Bases: object

A complete report of the probe health.

Currently, the health report contains only information about the health of each probe element separately.

Parameters

  • params – a dictionary with health verifier method parameters

  • sequence_metadata – description of the TX/RX sequence used in the probe health verification procedure

  • elements – a list of ProbeElementHealthReport objects

  • data – an RF data on the basis of which the probe verification was performed

class arrus.utils.probe_check.MaxAmplitudeExtractor(metadata)

Bases: arrus.utils.probe_check.ProbeElementFeatureExtractor

Feature extractor class for extracting maximal amplitudes from array of rf signals. Returns vector of length equal to number of transmissions (ntx), where each element is a median over the frames of maximum amplitudes (absolute values) occurred in each of the transmissions.

class arrus.utils.probe_check.EnergyExtractor(metadata)

Bases: arrus.utils.probe_check.ProbeElementFeatureExtractor

Feature extractor class for extracting normalised signal energies from array of rf signals. It is assumed that input data is acquired after very short excitation of a tested transducer. The signal is normalised, thus when there is only noise, or the signal is long (ringing), the energy is high.

extract(data: numpy.ndarray) → numpy.ndarray

Function extract parameter correlated with normalized signal energy.

Parameters

data – numpy array of rf data with the following shape: (number of frames, number of tx, number of samples, number of rx channels)

Returns

numpy array of signal energies

class arrus.utils.probe_check.SignalDurationTimeExtractor(metadata)

Bases: arrus.utils.probe_check.ProbeElementFeatureExtractor

Feature extractor class for extracting signal duration times from array of rf signals. It is assumed that input data is acquired after very short excitation of a tested transducer. The pulse length (signal duration) is estimated via fitting gaussian function to _envelope of a high-pass filtered signal.

extract(data: numpy.ndarray) → numpy.array

Extracts parameter correlated with signal duration time.

Parameters

data – numpy array of rf data with following dimensions:

[number of repetitions,

number of tx, number of samples, number of rx channels]

Returns

np.array of signal duration times

class arrus.utils.probe_check.MaxHVPSCurrentExtractor(metadata, polarity=1, level=0)

Bases: arrus.utils.probe_check.ProbeElementFeatureExtractor

Feature extractor class for extracting maximal P current from HVPS current measurement.

NOTE! this feature extractor removes the hardware-specific bias by removing the average HVPS amplitude per oem. The “normalization” procedure causes that the lowest measured current will be always zero. Therefore, values returned by this extractor should be considered in arbitrary units.

Parameters

  • polarity – signal polarity: 0: MINUS, 1: PLUS

  • level – rail level

class arrus.utils.probe_check.ByThresholdValidator

Bases: arrus.utils.probe_check.ProbeElementValidator

Validator that check the value of the feature and compares it with given value range. When the value of the feature is within the given range the element is marked as VALID, otherwise it is marked as TOO_HIGH or TOO_LOW.

class arrus.utils.probe_check.ByNeighborhoodValidator(group_size=32, feature_range_in_neighborhood=(0.5, 2), min_num_of_neighbors=5)

Bases: arrus.utils.probe_check.ProbeElementValidator

Validator that compares each element with its neighborhood.

Parameters

  • group_size – number of elements in the group

  • feature_range_in_neighborhood – pair (feature_min, feature_max) (see the description above)

  • min_num_of_neighbors – minimum number of active neighborhood elements that can be used to estimate group’s (lower, upper) bound of amplitude; if the number of active elements is < min_nim_of_neighbors, the verdict for the elements will be INDEFINITE

class arrus.utils.probe_check.ProbeHealthVerifier

Bases: object

Probe health verifier class.

check_probe(cfg_path: str, n: int, tx_frequency: float, features: List[arrus.utils.probe_check.FeatureDescriptor], validator: arrus.utils.probe_check.ProbeElementValidator, nrx: int = 32, voltage: int = 10, footprint: arrus.utils.probe_check.Footprint = None, signal_type: str = 'rf') → arrus.utils.probe_check.ProbeHealthReport

Checks probe elements by validating selected features of the acquired data. This method: - runs data acquisition, - computes signal features, - tries to determine which elements are valid or not.

RF data features are:

  1. amplitude

  2. energy

  3. signal_duration_time

  4. footprint_pcc

HVPS current features are:

  1. amplitude

Parameters

  • cfg_path – a path to the system configuration file

  • n – number of TX/RX sequences to execute (this may improve feature value estimation)

  • tx_frequency – pulse transmit frequency to be used in tx/rx scheme

  • features – a list of features to check

  • validator – ProbeElementValidator object, i.e. a validator that should be used to determine if given parameter have value within valid range

  • nrx – size of the receiving aperture. This parameter will be ignored if signal_type = hvps_current

  • voltage – voltage to be used in tx/rx scheme

  • footprint – object of the Footprint class; if given, footprint tx/rx scheme will be used

  • signal_type – type of signal to be verified; available values: rf, hvps_current. NOTE: hvps is only available for the us4OEM+ rev 1 or later.

Returns

an instance of the ProbeHealthReport

get_footprint(cfg_path: str, n: int, tx_frequency: float, nrx: int = 32, voltage: int = 10) → arrus.utils.probe_check.Footprint

Creates and returns Footprint object.