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()¶

Runs the uploaded scheme.

The behaviour of this method depends on the work mode: - MANUAL: triggers execution of batch of sequences 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).

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

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

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.

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:

by providing (focus, angle, speed_of_sound): TX delays will be automatically determined based on the provided values and probe parameters.
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_pga_gain(gain: int)¶

Sets PGA gain.

Available: 24, 30 [dB].

Parameters: gain – gain value to set

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]

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

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

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 lenght 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 tramissions.

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.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) → 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. Available features are:

amplitude

energy

signal_duration_time

footprint_pcc

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
voltage – voltage to be used in tx/rx scheme
footprint – object of the Footprint class; if given, footprint tx/rx scheme will be used

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.