zea.ops

Operations and Pipelines for ultrasound data processing.

This module contains two important classes, Operation and Pipeline, which are used to process ultrasound data. A pipeline is a sequence of operations that are applied to the data in a specific order.

Stand-alone manual usage

Operations can be run on their own:

Examples

data = np.random.randn(2000, 128, 1)
# static arguments are passed in the constructor
envelope_detect = EnvelopeDetect(axis=-1)
# other parameters can be passed here along with the data
envelope_data = envelope_detect(data=data)

Using a pipeline

You can initialize with a default pipeline or create your own custom pipeline.

pipeline = Pipeline.from_default()

operations = [
    EnvelopeDetect(),
    Normalize(),
    LogCompress(),
]
pipeline_custom = Pipeline(operations)

One can also load a pipeline from a config or yaml/json file:

json_string = '{"operations": ["identity"]}'
pipeline = Pipeline.from_json(json_string)

yaml_file = "pipeline.yaml"
pipeline = Pipeline.from_yaml(yaml_file)

Example of a yaml file:

pipeline:
  operations:
    - name: demodulate
    - name: "patched_grid"
      params:
        operations:
          - name: tof_correction
            params:
              apply_phase_rotation: true
          - name: pfield_weighting
          - name: delay_and_sum
        num_patches: 100
    - name: envelope_detect
    - name: normalize
    - name: log_compress

Functions

channels_to_complex(data)	Convert array with real and imaginary components at different channels to complex data array.
complex_to_channels(complex_data[, axis])	Unroll complex data to separate channels.
demodulate(data, center_frequency, ...[, axis])	Demodulates the input data to baseband.
demodulate_not_jitable(rf_data[, ...])	Demodulates an RF signal to complex base-band (IQ).
get_band_pass_filter(num_taps, ...)	Band pass filter
get_low_pass_iq_filter(num_taps, ...)	Design complex low-pass filter.
get_ops(ops_name)	Get the operation from the registry.
hilbert(x[, N, axis])	Manual implementation of the Hilbert transform function.
make_operation_chain(operation_chain)	Make an operation chain from a custom list of operations.
pipeline_from_config(config, **kwargs)	Create a Pipeline instance from a Config object.
pipeline_from_json(json_string, **kwargs)	Create a Pipeline instance from a JSON string.
pipeline_from_yaml(yaml_path, **kwargs)	Create a Pipeline instance from a YAML file.
pipeline_to_config(pipeline)	Convert a Pipeline instance into a Config object.
pipeline_to_json(pipeline)	Convert a Pipeline instance into a JSON string.
pipeline_to_yaml(pipeline, file_path)	Convert a Pipeline instance into a YAML file.
upmix(iq_data, sampling_frequency, ...[, ...])	Upsamples and upmixes complex base-band signals (IQ) to RF.

Classes

AnisotropicDiffusion([input_data_type, ...])	Speckle Reducing Anisotropic Diffusion (SRAD) filter.
BranchedPipeline(*args, **kwargs)	Operation that processes data through multiple branches.
ChannelsToComplex([input_data_type, ...])
Clip(*args, **kwargs)	Clip the input data to a given range.
Companding(*args, **kwargs)	Companding according to the A- or μ-law algorithm.
ComplexToChannels(*args, **kwargs)
DelayAndSum(*args, **kwargs)	Sums time-delayed signals along channels and transmits.
Demodulate(*args, **kwargs)	Demodulates the input data to baseband.
Downsample([factor, phase, axis])	Downsample data along a specific axis.
EnvelopeDetect(*args, **kwargs)	Envelope detection of RF signals.
GaussianBlur(sigma[, kernel_size, pad_mode, ...])	GaussianBlur is an operation that applies a Gaussian blur to an input image.
Identity([input_data_type, ...])	Identity operation.
Lambda(*args, **kwargs)	Use any function as an operation.
LeeFilter(*args, **kwargs)	The Lee filter is a speckle reduction filter commonly used in synthetic aperture radar (SAR) and ultrasound image processing.
LogCompress(*args, **kwargs)	Logarithmic compression of data.
Mean(*args, **kwargs)	Take the mean of the input data along a specific axis.
Merge(*args, **kwargs)	Operation that merges sets of input dictionaries.
Normalize(*args, **kwargs)	Normalize data to a given range.
Operation([input_data_type, ...])	A base abstract class for operations in the pipeline with caching functionality.
Pad(target_shape[, uniform, axis, ...])	Pad layer for padding tensors to a specified shape.
PatchedGrid(*args[, num_patches])	With this class you can form a pipeline that will be applied to patches of the grid.
PfieldWeighting(*args, **kwargs)	Weighting aligned data with the pressure field.
Pipeline(operations[, with_batch_dim, ...])	Pipeline class for processing ultrasound data through a series of operations.
ScanConvert(*args, **kwargs)	Scan convert images to cartesian coordinates.
Simulate(*args, **kwargs)	Simulate RF data.
Split(n, **kwargs)	Operation that splits an input dictionary n copies.
Stack(keys, axes, **kwargs)	Stack multiple data arrays along a new axis.
Sum(*args, **kwargs)	Sum data along a specific axis.
TOFCorrection(*args, **kwargs)	Time-of-flight correction operation for ultrasound data.
Threshold(*args, **kwargs)	Threshold an array, setting values below/above a threshold to a fill value.
Transpose(*args, **kwargs)	Transpose the input data along the specified axes.
UpMix(*args, **kwargs)	Upmix IQ data to RF data.

class zea.ops.AnisotropicDiffusion(input_data_type=None, output_data_type=None, key='data', output_key=None, cache_inputs=False, cache_outputs=False, jit_compile=True, with_batch_dim=True, jit_kwargs=None, jittable=True, **kwargs)

Bases: Operation

Speckle Reducing Anisotropic Diffusion (SRAD) filter.

Reference: - https://www.researchgate.net/publication/5602035_Speckle_reducing_anisotropic_diffusion - https://nl.mathworks.com/matlabcentral/fileexchange/54044-image-despeckle-filtering-toolbox

call(niter=100, lmbda=0.1, rect=None, eps=1e-06, **kwargs)

Anisotropic diffusion filter.

Assumes input data is non-negative.

Parameters:

• niter – Number of iterations.

• lmbda – Lambda parameter.

• rect – Rectangle [x1, y1, x2, y2] for homogeneous noise (optional).

• eps – Small epsilon for stability.

Returns:

Filtered image (2D tensor or batch of images).

class zea.ops.BranchedPipeline(*args, **kwargs)

Bases: Operation

Operation that processes data through multiple branches.

This operation takes input data, processes it through multiple parallel branches, and then merges the results from those branches using the specified merge strategy.

call(**kwargs)

Process input through branches and merge results.

Parameters:

**kwargs – Input keyword arguments

Returns:

Merged outputs from all branches according to merge strategy

Return type:

dict

flatten_outputs(outputs)

Flatten a nested dictionary by prefixing keys with the branch name. For each branch, the resulting key is “{branch_name}_{original_key}”.

Return type:

dict

get_config()

Return the config dictionary for serialization.

get_dict()

Get the configuration of the operation.

suffix_merge_outputs(outputs)

Flatten a nested dictionary by suffixing keys with the branch name. For each branch, the resulting key is “{original_key}_{branch_name}”.

Return type:

dict

class zea.ops.ChannelsToComplex(input_data_type=None, output_data_type=None, key='data', output_key=None, cache_inputs=False, cache_outputs=False, jit_compile=True, with_batch_dim=True, jit_kwargs=None, jittable=True, **kwargs)

Bases: Operation

call(**kwargs)

Abstract method that defines the processing logic for the operation. Subclasses must implement this method.

class zea.ops.Clip(*args, **kwargs)

Bases: Operation

Clip the input data to a given range.

call(**kwargs)

Abstract method that defines the processing logic for the operation. Subclasses must implement this method.

class zea.ops.Companding(*args, **kwargs)

Bases: Operation

Companding according to the A- or μ-law algorithm.

Invertible compressing operation. Used to compress dynamic range of input data (and subsequently expand).

μ-law companding: https://en.wikipedia.org/wiki/%CE%9C-law_algorithm A-law companding: https://en.wikipedia.org/wiki/A-law_algorithm

Parameters:

• expand (bool, optional) – If set to False (default), data is compressed, else expanded.

• comp_type (str) – either a or mu.

• mu (float, optional) – compression parameter. Defaults to 255.

• A (float, optional) – compression parameter. Defaults to 87.6.

call(mu=255, A=87.6, **kwargs)

Abstract method that defines the processing logic for the operation. Subclasses must implement this method.

class zea.ops.ComplexToChannels(*args, **kwargs)

Bases: Operation

call(**kwargs)

Abstract method that defines the processing logic for the operation. Subclasses must implement this method.

class zea.ops.DelayAndSum(*args, **kwargs)

Bases: Operation

Sums time-delayed signals along channels and transmits.

call(rx_apo=None, grid=None, **kwargs)

Performs DAS beamforming on tof-corrected input.

Parameters:

• tof_corrected_data (ops.Tensor) – The TOF corrected input of shape (n_tx, grid_size_z*grid_size_x, n_el, n_ch) with optional batch dimension.

• rx_apo (ops.Tensor) – Receive apodization window of shape (n_tx, grid_size_z*grid_size_x, n_el) with optional batch dimension. Defaults to 1.0.

Returns:

Dictionary containing beamformed_data

of shape (grid_size_z*grid_size_x, n_ch) when reshape_grid is False or (grid_size_z, grid_size_x, n_ch) when reshape_grid is True, with optional batch dimension.

Return type:

dict

process_image(data, rx_apo)

Performs DAS beamforming on tof-corrected input.

Parameters:

• data (ops.Tensor) – The TOF corrected input of shape (n_tx, n_pix, n_el, n_ch)

• rx_apo (ops.Tensor) – Receive apodization window of shape (n_tx, n_pix, n_el, n_ch).

Returns:

The beamformed data of shape (n_pix, n_ch)

Return type:

ops.Tensor

class zea.ops.Demodulate(*args, **kwargs)

Bases: Operation

Demodulates the input data to baseband. After this operation, the carrier frequency is removed (0 Hz) and the data is in IQ format stored in two real valued channels.

call(center_frequency=None, sampling_frequency=None, **kwargs)

Abstract method that defines the processing logic for the operation. Subclasses must implement this method.

class zea.ops.Downsample(factor=1, phase=0, axis=-3, **kwargs)

Bases: Operation

Downsample data along a specific axis.

call(sampling_frequency=None, n_ax=None, **kwargs)

Abstract method that defines the processing logic for the operation. Subclasses must implement this method.

class zea.ops.EnvelopeDetect(*args, **kwargs)

Bases: Operation

Envelope detection of RF signals.

call(**kwargs)

Parameters:

data (-) – The beamformed data of shape (…, grid_size_z, grid_size_x, n_ch).

Returns:

The envelope detected data

of shape (…, grid_size_z, grid_size_x).

Return type:

• envelope_data (Tensor)

class zea.ops.GaussianBlur(sigma, kernel_size=None, pad_mode='symmetric', truncate=4.0, **kwargs)

Bases: Operation

GaussianBlur is an operation that applies a Gaussian blur to an input image. Uses scipy.ndimage.gaussian_filter to create a kernel.

call(**kwargs)

Abstract method that defines the processing logic for the operation. Subclasses must implement this method.

get_kernel()

Create a gaussian kernel for blurring.

Returns:

A gaussian kernel for blurring.

Shape is (kernel_size, kernel_size, 1, 1).

Return type:

kernel (Tensor)

class zea.ops.Identity(input_data_type=None, output_data_type=None, key='data', output_key=None, cache_inputs=False, cache_outputs=False, jit_compile=True, with_batch_dim=True, jit_kwargs=None, jittable=True, **kwargs)

Bases: Operation

Identity operation.

call(**kwargs)

Returns the input as is.

Return type:

Dict

class zea.ops.Lambda(*args, **kwargs)

Bases: Operation

Use any function as an operation.

call(**kwargs)

Abstract method that defines the processing logic for the operation. Subclasses must implement this method.

class zea.ops.LeeFilter(*args, **kwargs)

Bases: Operation

The Lee filter is a speckle reduction filter commonly used in synthetic aperture radar (SAR) and ultrasound image processing. It smooths the image while preserving edges and details. This implementation uses Gaussian filter for local statistics and treats channels independently.

Lee, J.S. (1980). Digital image enhancement and noise filtering by use of local statistics. IEEE Transactions on Pattern Analysis and Machine Intelligence, (2), 165-168.

call(**kwargs)

Abstract method that defines the processing logic for the operation. Subclasses must implement this method.

property with_batch_dim

Get the with_batch_dim property of the LeeFilter operation.

class zea.ops.LogCompress(*args, **kwargs)

Bases: Operation

Logarithmic compression of data.

call(dynamic_range=None, **kwargs)

Apply logarithmic compression to data.

Parameters:

dynamic_range (tuple, optional) – Dynamic range in dB. Defaults to (-60, 0).

Returns:

Dictionary containing log-compressed data

Return type:

dict

class zea.ops.Mean(*args, **kwargs)

Bases: Operation

Take the mean of the input data along a specific axis.

call(**kwargs)

Abstract method that defines the processing logic for the operation. Subclasses must implement this method.

class zea.ops.Merge(*args, **kwargs)

Bases: Operation

Operation that merges sets of input dictionaries.

call(*args, **kwargs)

Merges the input dictionaries. Priority is given to the last input.

Return type:

Dict

class zea.ops.Normalize(*args, **kwargs)

Bases: Operation

Normalize data to a given range.

call(**kwargs)

Normalize data to a given range.

Parameters:

• output_range (tuple, optional) – Range to which data should be mapped. Defaults to (0, 1).

• input_range (tuple, optional) – Range of input data. If None, the range of the input data will be computed. Defaults to None.

Returns:

Dictionary containing normalized data, along with the computed

or provided input range (minval and maxval).

Return type:

dict

static to_float32(data)

Converts an iterable to float32 and leaves None values as is.

class zea.ops.Operation(input_data_type=None, output_data_type=None, key='data', output_key=None, cache_inputs=False, cache_outputs=False, jit_compile=True, with_batch_dim=True, jit_kwargs=None, jittable=True, **kwargs)

Bases: Operation

A base abstract class for operations in the pipeline with caching functionality.

call(**kwargs)

Abstract method that defines the processing logic for the operation. Subclasses must implement this method.

clear_cache()

Clear the input and output caches.

get_dict()

Get the configuration of the operation. Inherit from keras.Operation.

property jittable

Check if the operation can be JIT compiled.

set_input_cache(input_cache)

Set a cache for inputs, then retrace the function if necessary.

Parameters:

input_cache (Dict[str, Any]) – A dictionary containing cached inputs.

set_jit(jit_compile)

Set the JIT compilation flag and set the _call method accordingly.

set_output_cache(output_cache)

Set a cache for outputs, then retrace the function if necessary.

Parameters:

output_cache (Dict[str, Any]) – A dictionary containing cached outputs.

property static_params

Get the static parameters of the operation.

property valid_keys

Get the valid keys for the call method.

class zea.ops.Pad(target_shape, uniform=True, axis=None, fail_on_bigger_shape=True, pad_kwargs=None, **kwargs)

Bases: Operation, TFDataLayer

Pad layer for padding tensors to a specified shape.

call(**kwargs)

Abstract method that defines the processing logic for the operation. Subclasses must implement this method.

pad(z, target_shape, uniform=True, axis=None, fail_on_bigger_shape=True, **kwargs)

Pads the input tensor z to the specified shape.

Parameters:

• z (tensor) – The input tensor to be padded.

• target_shape (list or tuple) – The target shape to pad the tensor to.

• uniform (bool, optional) – If True, ensures that padding is uniform (even on both sides). Default is False.

• axis (int or list of int, optional) – The axis or axes along which target_shape was specified. If None, len(target_shape) == `len(ops.shape(z)) must hold. Default is None.

• fail_on_bigger_shape (bool, optional) – If True (default), raises an error if any target dimension is smaller than the input shape; if False, pads only where the target shape exceeds the input shape and leaves other dimensions unchanged.

• kwargs – Additional keyword arguments to pass to the padding function.

Returns:

The padded tensor with the specified shape.

Return type:

tensor

class zea.ops.PatchedGrid(*args, num_patches=10, **kwargs)

Bases: Pipeline

With this class you can form a pipeline that will be applied to patches of the grid. This is useful to avoid OOM errors when processing large grids.

Somethings to NOTE about this class:

• The ops have to use flatgrid and flat_pfield as inputs, these will be patched.

• Changing anything other than self.output_data_type in the dict will not be propagated!

• Will be jitted as a single operation, not the individual operations.

• This class handles the batching.

call(**inputs)

Process input data through the pipeline.

call_item(inputs)

Process data in patches.

get_dict()

Get the configuration of the pipeline.

jit()

JIT compile the pipeline.

property jit_options

Get the jit_options property of the pipeline.

jittable_call(**inputs)

Process input data through the pipeline.

unjit()

Un-JIT compile the pipeline.

property valid_keys: set

Get a set of valid keys for the pipeline. Adds the parameters that PatchedGrid itself operates on (even if not used by operations inside it).

property with_batch_dim

Get the with_batch_dim property of the pipeline.

class zea.ops.PfieldWeighting(*args, **kwargs)

Bases: Operation

Weighting aligned data with the pressure field.

call(flat_pfield=None, **kwargs)

Weight data with pressure field.

Parameters:

flat_pfield (ops.Tensor) – Pressure field weight mask of shape (n_pix, n_tx)

Returns:

Dictionary containing weighted data

Return type:

dict

class zea.ops.Pipeline(operations, with_batch_dim=True, jit_options='ops', jit_kwargs=None, name='pipeline', validate=True, timed=False)

Bases: object

Pipeline class for processing ultrasound data through a series of operations.

append(operation)

Append an operation to the pipeline.

call(**inputs)

Process input data through the pipeline.

copy()

Create a copy of the pipeline.

Return type:

Pipeline

classmethod from_config(config, **kwargs)

Create a pipeline from a dictionary or zea.Config object.

Parameters:

• config (dict or Config) – Configuration dictionary or zea.Config object.

• **kwargs – Additional keyword arguments to be passed to the pipeline.

Return type:

Pipeline

Note

Must have a pipeline key with a subkey operations.

Example

config = Config(
    {
        "operations": [
            "identity",
        ],
    }
)
pipeline = Pipeline.from_config(config)

classmethod from_default(num_patches=100, baseband=False, pfield=False, **kwargs)

Create a default pipeline.

Parameters:

• num_patches (int) – Number of patches for the PatchedGrid operation. Defaults to 100. If you get an out of memory error, try to increase this number.

• baseband (bool) – If True, assume the input data is baseband (I/Q) data, which has 2 channels (last dim). Defaults to False, which assumes RF data, so input signal has a single channel dim and is still on carrier frequency.

• pfield (bool) – If True, apply Pfield weighting. Defaults to False. This will calculate pressure field and only beamform the data to those locations.

• **kwargs – Additional keyword arguments to be passed to the Pipeline constructor.

Return type:

Pipeline

classmethod from_json(json_string, **kwargs)

Create a pipeline from a JSON string.

Parameters:

• json_string (str) – JSON string representing the pipeline.

• **kwargs – Additional keyword arguments to be passed to the pipeline.

Return type:

Pipeline

Note

Must have the operations key.

Example: `python json_string = '{"operations": ["identity"]}' pipeline = Pipeline.from_json(json_string) `

classmethod from_yaml(file_path, **kwargs)

Create a pipeline from a YAML file.

Parameters:

• file_path (str) – Path to the YAML file.

• **kwargs – Additional keyword arguments to be passed to the pipeline.

Return type:

Pipeline

Note

Must have the a pipeline key with a subkey operations.

Example: `python pipeline = Pipeline.from_yaml("pipeline.yaml") `

get_dict()

Convert the pipeline to a dictionary.

Return type:

dict

get_params(per_operation=False)

Get a snapshot of the current parameters of the operations in the pipeline.

Parameters:

per_operation (bool) – If True, return a list of dictionaries for each operation. If False, return a single dictionary with all parameters combined.

property input_data_type

Get the input_data_type property of the pipeline.

insert(index, operation)

Insert an operation at a specific index in the pipeline.

jit()

JIT compile the pipeline.

property jit_options

Get the jit_options property of the pipeline.

property jittable

Check if all operations in the pipeline are jittable.

property key: str

Input key of the pipeline.

classmethod load(file_path, **kwargs)

Load a pipeline from a JSON or YAML file.

Return type:

Pipeline

needs(key)

Check if the pipeline needs a specific key.

Return type:

bool

property operations

Alias for self.layers to match the zea naming convention

property output_data_type

Get the output_data_type property of the pipeline.

property output_key: str

Output key of the pipeline.

prepare_parameters(probe=None, scan=None, config=None, **kwargs)

Prepare Probe, Scan and Config objects for the pipeline.

Serializes zea.core.Object instances and converts them to dictionary of tensors.

Parameters:

• probe (Probe) – Probe object.

• scan (Scan) – Scan object.

• config (Config) – Config object.

• include (None, "all", or list) – Only include these parameter/computed property names. If None or “all”, include all.

• exclude (None or list) – Exclude these parameter/computed property names. If provided, these keys will be excluded from the output. Only one of include or exclude can be set.

• **kwargs – Additional keyword arguments to be included in the inputs.

Returns:

Dictionary of inputs with all values as tensors.

Return type:

dict

prepend(operation)

Prepend an operation to the pipeline.

set_params(**params)

Set parameters for the operations in the pipeline by adding them to the cache.

property static_params: List[str]

Get a list of static parameters for the pipeline.

timed_call(**inputs)

Process input data through the pipeline.

to_config()

Convert the pipeline to a zea.Config object.

Return type:

Config

to_json()

Convert the pipeline to a JSON string.

Return type:

str

to_yaml(file_path)

Convert the pipeline to a YAML file.

Return type:

None

unjit()

Un-JIT compile the pipeline.

property unjitable_ops

Get a list of operations that are not jittable.

property valid_keys: set

Get a set of valid keys for the pipeline.

validate()

Validate the pipeline by checking the compatibility of the operations.

property with_batch_dim

Get the with_batch_dim property of the pipeline.

class zea.ops.ScanConvert(*args, **kwargs)

Bases: Operation

Scan convert images to cartesian coordinates.

STATIC_PARAMS = ['fill_value']

call(rho_range=None, theta_range=None, phi_range=None, resolution=None, coordinates=None, fill_value=None, **kwargs)

Scan convert images to cartesian coordinates.

Parameters:

• rho_range (Tuple) – Range of the rho axis in the polar coordinate system. Defined in meters.

• theta_range (Tuple) – Range of the theta axis in the polar coordinate system. Defined in radians.

• phi_range (Tuple) – Range of the phi axis in the polar coordinate system. Defined in radians.

• resolution (float) – Resolution of the output image in meters per pixel. if None, the resolution is computed based on the input data.

• coordinates (Tensor) – Coordinates for scan convertion. If None, will be computed based on rho_range, theta_range, phi_range and resolution. If provided, this operation can be jitted.

• fill_value (float) – Value to fill the image with outside the defined region.

class zea.ops.Simulate(*args, **kwargs)

Bases: Operation

Simulate RF data.

STATIC_PARAMS = ['n_ax', 'apply_lens_correction']

call(scatterer_positions, scatterer_magnitudes, probe_geometry, apply_lens_correction, lens_thickness, lens_sound_speed, sound_speed, n_ax, center_frequency, sampling_frequency, t0_delays, initial_times, element_width, attenuation_coef, tx_apodizations, **kwargs)

Abstract method that defines the processing logic for the operation. Subclasses must implement this method.

class zea.ops.Split(n, **kwargs)

Bases: Operation

Operation that splits an input dictionary n copies.

call(**kwargs)

Splits the input dictionary into n copies.

Return type:

List[Dict]

class zea.ops.Stack(keys, axes, **kwargs)

Bases: Operation

Stack multiple data arrays along a new axis. Useful to merge data from parallel pipelines.

call(**kwargs)

Stacks the inputs corresponding to the specified keys along the specified axis. If a list of axes is provided, the length must match the number of keys.

Return type:

Dict

class zea.ops.Sum(*args, **kwargs)

Bases: Operation

Sum data along a specific axis.

call(**kwargs)

Abstract method that defines the processing logic for the operation. Subclasses must implement this method.

class zea.ops.TOFCorrection(*args, **kwargs)

Bases: Operation

Time-of-flight correction operation for ultrasound data.

STATIC_PARAMS = ['f_number', 'apply_lens_correction', 'apply_phase_rotation', 'grid_size_x', 'grid_size_z']

call(flatgrid, sound_speed, polar_angles, focus_distances, sampling_frequency, f_number, demodulation_frequency, t0_delays, tx_apodizations, initial_times, probe_geometry, apply_lens_correction=None, lens_thickness=None, lens_sound_speed=None, **kwargs)

Perform time-of-flight correction on raw RF data.

Parameters:

• raw_data (ops.Tensor) – Raw RF data to correct

• flatgrid (ops.Tensor) – Grid points at which to evaluate the time-of-flight

• sound_speed (float) – Sound speed in the medium

• polar_angles (ops.Tensor) – Polar angles for scan lines

• focus_distances (ops.Tensor) – Focus distances for scan lines

• sampling_frequency (float) – Sampling frequency

• f_number (float) – F-number for apodization

• demodulation_frequency (float) – Demodulation frequency

• t0_delays (ops.Tensor) – T0 delays

• tx_apodizations (ops.Tensor) – Transmit apodizations

• initial_times (ops.Tensor) – Initial times

• probe_geometry (ops.Tensor) – Probe element positions

• apply_lens_correction (bool) – Whether to apply lens correction

• lens_thickness (float) – Lens thickness

• lens_sound_speed (float) – Sound speed in the lens

Returns:

Dictionary containing tof_corrected_data

Return type:

dict

class zea.ops.Threshold(*args, **kwargs)

Bases: Operation

Threshold an array, setting values below/above a threshold to a fill value.

call(threshold=None, percentile=None, **kwargs)

Threshold the input data.

Parameters:

• threshold – Numeric threshold.

• percentile – Percentile to derive threshold from.

Returns:

Tensor with thresholding applied.

class zea.ops.Transpose(*args, **kwargs)

Bases: Operation

Transpose the input data along the specified axes.

call(**kwargs)

Abstract method that defines the processing logic for the operation. Subclasses must implement this method.

class zea.ops.UpMix(*args, **kwargs)

Bases: Operation

Upmix IQ data to RF data.

call(sampling_frequency=None, center_frequency=None, **kwargs)

Abstract method that defines the processing logic for the operation. Subclasses must implement this method.

zea.ops.channels_to_complex(data)

Convert array with real and imaginary components at different channels to complex data array.

Parameters:

data (ndarray) – input data, with at 0 index of axis real component and 1 index of axis the imaginary.

Returns:

complex array with real and imaginary components.

Return type:

ndarray

zea.ops.complex_to_channels(complex_data, axis=-1)

Unroll complex data to separate channels.

Parameters:

• complex_data (complex ndarray) – complex input data.

• axis (int, optional) – on which axis to extend. Defaults to -1.

Returns:

real array with real and imaginary components

unrolled over two channels at axis.

Return type:

ndarray

zea.ops.demodulate(data, center_frequency, sampling_frequency, axis=-3)

Demodulates the input data to baseband. The function computes the analytical signal (the signal with negative frequencies removed) and then shifts the spectrum of the signal to baseband by multiplying with a complex exponential. Where the spectrum was centered around center_frequency before, it is now centered around 0 Hz. The baseband IQ data are complex-valued. The real and imaginary parts are stored in two real-valued channels.

Parameters:

• data (ops.Tensor) – The input data to demodulate of shape (…, axis, …, 1).

• center_frequency (float) – The center frequency of the signal.

• sampling_frequency (float) – The sampling frequency of the signal.

• axis (int, optional) – The axis along which to demodulate. Defaults to -3.

Returns:

The demodulated IQ data of shape (…, axis, …, 2).

Return type:

ops.Tensor

zea.ops.demodulate_not_jitable(rf_data, sampling_frequency=None, center_frequency=None, bandwidth=None, filter_coeff=None)

Demodulates an RF signal to complex base-band (IQ).

Demodulates the radiofrequency (RF) bandpass signals and returns the Inphase/Quadrature (I/Q) components. IQ is a complex whose real (imaginary) part contains the in-phase (quadrature) component.

This function operates (i.e. demodulates) on the RF signal over the (fast-) time axis which is assumed to be the last axis.

Parameters:

• rf_data (ndarray) – real valued input array of size […, n_ax, n_el]. second to last axis is fast-time axis.

• sampling_frequency (float) – the sampling frequency of the RF signals (in Hz). Only not necessary when filter_coeff is provided.

• center_frequency (float, optional) – represents the center frequency (in Hz). Defaults to None.

• bandwidth (float, optional) – Bandwidth of RF signal in % of center frequency. Defaults to None. The bandwidth in % is defined by: B = Bandwidth_in_% = Bandwidth_in_Hz*(100/center_frequency). The cutoff frequency: Wn = Bandwidth_in_Hz/sampling_frequency, i.e: Wn = B*(center_frequency/100)/sampling_frequency.

• filter_coeff (list, optional) – (b, a), numerator and denominator coefficients of FIR filter for quadratic band pass filter. All other parameters are ignored if filter_coeff are provided. Instead the given filter_coeff is directly used. If not provided, a filter is derived from the other params (sampling_frequency, center_frequency, bandwidth). see https://docs.scipy.org/doc/scipy/reference/generated/scipy.signal.lfilter.html

Returns:

complex valued base-band signal.

Return type:

iq_data (ndarray)

zea.ops.get_band_pass_filter(num_taps, sampling_frequency, f1, f2)

Band pass filter

Parameters:

• num_taps (int) – number of taps in filter.

• sampling_frequency (float) – sample frequency in Hz.

• f1 (float) – cutoff frequency in Hz of left band edge.

• f2 (float) – cutoff frequency in Hz of right band edge.

Returns:

band pass filter

Return type:

ndarray

zea.ops.get_low_pass_iq_filter(num_taps, sampling_frequency, f, bw)

Design complex low-pass filter.

The filter is a low-pass FIR filter modulated to the center frequency.

Parameters:

• num_taps (int) – number of taps in filter.

• sampling_frequency (float) – sample frequency.

• f (float) – center frequency.

• bw (float) – bandwidth in Hz.

Raises:

ValueError – if cutoff frequency (bw / 2) is not within (0, sampling_frequency / 2)

Returns:

Complex-valued low-pass filter

Return type:

ndarray

zea.ops.get_ops(ops_name)

Get the operation from the registry.

zea.ops.hilbert(x, N=None, axis=-1)

Manual implementation of the Hilbert transform function. The function returns the analytical signal.

Operated in the Fourier domain.

Note

THIS IS NOT THE MATHEMATICAL THE HILBERT TRANSFORM as you will find it on wikipedia, but computes the analytical signal. The implementation reproduces the behavior of the scipy.signal.hilbert function.

Parameters:

• x (ndarray) – input data of any shape.

• N (int, optional) – number of points in the FFT. Defaults to None.

• axis (int, optional) – axis to operate on. Defaults to -1.

Returns:

complex iq data of any shape.k

Return type:

x (ndarray)

zea.ops.make_operation_chain(operation_chain)

Make an operation chain from a custom list of operations.

Parameters:

operation_chain (list) – List of operations to be performed. Each operation can be: - A string: operation initialized with default parameters - A dictionary: operation initialized with parameters in the dictionary - A Config object: converted to a dictionary and initialized - An Operation/Pipeline instance: used as-is

Returns:

List of operations to be performed.

Return type:

list

Example

chain = make_operation_chain(
    [
        "envelope_detect",
        {"name": "normalize", "params": {"output_range": (0, 1)}},
        SomeCustomOperation(),
    ]
)

zea.ops.pipeline_from_config(config, **kwargs)

Create a Pipeline instance from a Config object.

Return type:

Pipeline

zea.ops.pipeline_from_json(json_string, **kwargs)

Create a Pipeline instance from a JSON string.

Return type:

Pipeline

zea.ops.pipeline_from_yaml(yaml_path, **kwargs)

Create a Pipeline instance from a YAML file.

Return type:

Pipeline

zea.ops.pipeline_to_config(pipeline)

Convert a Pipeline instance into a Config object.

Return type:

Config

zea.ops.pipeline_to_json(pipeline)

Convert a Pipeline instance into a JSON string.

Return type:

str

zea.ops.pipeline_to_yaml(pipeline, file_path)

Convert a Pipeline instance into a YAML file.

Return type:

None

zea.ops.upmix(iq_data, sampling_frequency, center_frequency, upsampling_rate=6)

Upsamples and upmixes complex base-band signals (IQ) to RF.

Parameters:

• iq_data (ndarray) – complex valued input array of size […, n_ax, n_el]. second to last axis is fast-time axis.

• sampling_frequency (float) – the sampling frequency of the input IQ signal (in Hz). resulting sampling_frequency of RF data is upsampling_rate times higher.

• center_frequency (float, optional) – represents the center frequency (in Hz).

Returns:

output real valued rf data.

Return type:

rf_data (ndarray)