zea.ops¶

Operations and Pipelines for ultrasound data processing.

The zea.ops module contains a collection of operations (Operation) that can be applied to ultrasound data. These operations can be used on their own or as part of a pipeline. A Pipeline is a sequence of operations that are applied to the data in a specific order.

We implement a range of common operations for ultrasound data processing, but also support a variety of basic tensor operations. Lastly, all existing Keras operations (see Keras Ops API) are available as zea operations as well (see zea.ops.keras_ops), and thus can be easily integrated in common ultrasound processing pipelines.

Stand-alone usage of operations¶

In many settings, it can be useful to apply an Operation directly to the data, without using a Pipeline. In that case, you can simply initialize the operation and call it with the data.

>>> import keras
>>> from zea.ops import EnvelopeDetect
>>> data = keras.random.uniform((2000, 128, 1))
>>> # static arguments are passed in the constructor
>>> envelope_detect = EnvelopeDetect(axis=-1)
>>> # other (dynamic) parameters can be passed here along with the data
>>> # the output is again a dictionary
>>> envelope_data = envelope_detect(data=data)["data"]

Note

Besides the zea.ops API, we also have a functional (zea.func) API which contains the functional building blocks that many of the zea.ops operations are built on. These can be used for more low-level processing, and can be found in the zea.func module. For instance, the EnvelopeDetect operation is built on top of the zea.func.envelope_detect() function in zea.func. You can use these functions directly as well, if you prefer a more functional programming style. The advantage of using the zea.ops API is that these operations can be easily integrated into pipelines.

Using a pipeline¶

There are many ways to initialize a Pipeline. In its essence, a Pipeline is just a sequence of multiple Operation. A Pipeline will chain these operations together, so that the output of one operation is the input of the next. All operations takes a dictionary of tensors and parameters as inputs and passes these along to the next operation, only picking the parameters they need.

One of the more common pipelines you will encounter is a basic ultrasound raw channel data to B-mode image pipeline, which consists of a sequence of operations like demodulation, beamforming, envelope detection, normalization and log compression:

>>> from zea.ops import (
...     Beamform,
...     Cast,
...     Demodulate,
...     Pipeline,
...     EnvelopeDetect,
...     Normalize,
...     LogCompress,
... )

>>> operations = [
...     Cast(dtype="float32"),
...     Demodulate(),
...     Beamform(beamformer="delay_and_sum"),
...     EnvelopeDetect(),
...     Normalize(),
...     LogCompress(),
... ]
>>> pipeline = Pipeline(operations)

In fact this is so common that we created a handy utility function to create this pipeline with default parameters:

>>> pipeline = Pipeline.from_default()

Calling a pipeline¶

A Operation or Pipeline is called with keyword arguments only. The primary input data (often raw RF data) should be passed under the key given by Pipeline.key ("data" by default), and the result is a dictionary whose final output is stored under Pipeline.output_key. All other parameters that the operations need — such as scan geometry, probe layout, and reconstruction settings — are passed as additional keyword arguments alongside the data. In simple terms, a flat dictionary of tensors containing all the necessary information is passed to the pipeline, and a dictionary of outputs is returned. This dictionary is internally routed through each operation in the pipeline, which picks the parameters it needs and produces intermediate outputs until the final output is produced.

Additionally, all these input arguments should be converted to tensors at the start, as the operations and pipelines are implemented with the machine learning backend of choice (JAX, TensorFlow, or PyTorch). One can use the Pipeline.prepare_parameters() method to convert a Parameters object (which merges the probe and scan parameters found in the file) into a flat dictionary of tensors that can be directly passed to the pipeline.

See the tutorial notebook Working with zea.Pipeline for a complete example including data loading, parameter preparation, and pipeline execution on real ultrasound data. Below a minimal stand-alone snippet is shown to illustrate the calling convention:

>>> import keras
>>> from zea.ops import Pipeline, Normalize, LogCompress

>>> pipeline = Pipeline(
...     operations=[Normalize(), LogCompress()],
...     with_batch_dim=False,
... )

>>> data = keras.ops.abs(keras.random.normal((64, 64)))

>>> # Pass data under pipeline.key (default: "data") together with any needed parameters
>>> parameters = {"dynamic_range": (-60, 0)}
>>> inputs = {"data": data}
>>> outputs = pipeline(**inputs, **parameters)
>>> data_out = outputs[pipeline.output_key]
>>> data_out = keras.ops.convert_to_numpy(data_out)
>>> print(f"min: {data_out.min()}, max: {data_out.max()}")
min: -60.0, max: 0.0

Saving and loading pipelines¶

It can be quite handy to share pipelines across machines, or accompany a dataset or publication with a specific zea pipeline configuration. For this reason, we support saving and loading pipelines in a human-readable YAML format. The preferred way to persist a pipeline is Pipeline.to_yaml() for saving and Pipeline.from_path() for loading. Together they form a lossless round-trip: every operation and its parameters are serialized to a plain YAML file that can be version-controlled, shared, or reproduced on any machine.

>>> from zea import Pipeline
>>> from zea.ops import Beamform, Cast, EnvelopeDetect, Normalize, LogCompress

>>> pipeline = Pipeline(
...     operations=[
...         Cast(dtype="float32"),
...         Demodulate(),
...         Beamform(beamformer="delay_and_sum"),
...         EnvelopeDetect(),
...         Normalize(),
...         LogCompress(),
...     ],
... )

>>> # Save to YAML
>>> pipeline.to_yaml("bmode_pipeline.yaml")
>>> # Load back from YAML
>>> loaded_pipeline = Pipeline.from_path("bmode_pipeline.yaml")

Pipelines hosted on the Hugging Face Hub can be loaded directly using an hf:// URI, without manually downloading any files:

>>> pipeline = Pipeline.from_path("hf://zeahub/picmus/config_iq.yaml", revision="v0.1.0")
>>> print(pipeline)
Beamform(PatchedGrid(TOFCorrection -> DelayAndSum) -> ReshapeGrid) -> EnvelopeDetect -> Normalize -> LogCompress

The YAML format is human-readable and straightforward to edit by hand. A typical B-mode pipeline looks like this:

pipeline:
  operations:
    - name: cast
        params:
            dtype: float32
    - name: demodulate
    - name: beamform
      params:
        beamformer: delay_and_sum
        num_patches: 100
    - name: envelope_detect
    - name: normalize
    - name: log_compress

Device selection¶

It can be handy to execute a Pipeline on a specific device (GPU / CPU). Call zea.init_device() at the start of a script to select a device. It returns the selected device string — or a list of strings when multiple GPUs are requested — which can be passed directly to the pipeline or used with the device context manager:

import zea

# Single GPU — auto-selects the one with the most free memory
device = zea.init_device("auto:1")  # e.g. "gpu:0"

# Two GPUs — auto-selects by free memory, returns a list
devices = zea.init_device("auto:2")  # e.g. ["gpu:0", "gpu:1"]

Note

zea.init_device() should be called before importing heavy ML libraries (JAX, TensorFlow, PyTorch) so that CUDA_VISIBLE_DEVICES is configured before they initialise.

To run a pipeline on a specific device, use the device context manager or pass device= to the pipeline constructor. Whereas everything created and executed inside the context manager will be placed on the specified device, passing device= to the pipeline will ensure that tensors passed to the pipeline are automatically moved to the specified device.

pipeline = zea.Pipeline([zea.ops.keras_ops.Abs()])

# Option 1: context manager
with zea.device("gpu:0"):
    data = np.random.randn(100, 100)
    # make sure data is created inside the context manager
    data = keras.ops.convert_to_tensor(data)
    output = pipeline(data=data)["data"]

# Option 2: device argument on the pipeline itself
data = np.random.randn(100, 100)
data = keras.ops.convert_to_tensor(data)
pipeline = zea.Pipeline([zea.ops.keras_ops.Abs()], device="gpu:0")
# data will be automatically moved to the specified device when passed to the pipeline
output = pipeline(data=data)["data"]

Functions

get_ops(ops_name)

Retrieve an Operation subclass from the registry by name.

Classes

`Identity`([input_data_type, ...])	Identity operation.
`Lambda`(args, *kwargs)	Use any function as an operation.
`Mean`(args, *kwargs)	Take the mean of the input data along a specific axis.
`Operation`([input_data_type, ...])	Abstract base class for pipeline operations with caching and JIT support.
`DelayAndSum`(args, *kwargs)	Sums time-delayed signals along channels and transmits.
`DelayMultiplyAndSum`(args, *kwargs)	Performs the operations for the Delay-Multiply-and-Sum beamformer except the delay.
`CoherenceFactor`(args, *kwargs)	Coherence Factor (CF) Beamformer.
`GeneralizedCoherenceFactor`(args, *kwargs)	Generalized Coherence Factor (GCF) Beamformer.
`Beamform`([beamformer, num_patches, ...])	Classical beamforming pipeline for ultrasound image formation.
`Map`(operations, argnames[, in_axes, ...])	A pipeline that maps its operations over specified input arguments.
`PatchedGrid`(*args[, num_patches])	A pipeline that maps its operations over flatgrid and flat_pfield keys.
`Pipeline`(operations[, with_batch_dim, ...])	Pipeline class for processing ultrasound data through a series of operations.
`Refocus`(args, *kwargs)	REFoCUS (Retrospective Encoding For Conventional Ultrasound Sequences).
`GaussianBlur`(sigma[, order, mode, cval, ...])	GaussianBlur is an operation that applies a Gaussian blur to an input image.
`Normalize`(args, *kwargs)	Normalize data to a given range.
`Pad`(target_shape[, uniform, axis, ...])	Pad layer for padding tensors to a specified shape.
`Threshold`(args, *kwargs)	Threshold an array, setting values below/above a threshold to a fill value.
`AnisotropicDiffusion`([input_data_type, ...])	Speckle Reducing Anisotropic Diffusion (SRAD) filter.
`ApplyWindow`(args, *kwargs)	Apply a window function to the input data along a specific axis.
`BandPassFilter`([axis, num_taps, filter_key, ...])	Apply a band-pass FIR filter to the real input signal using convolution.
`ChannelsToComplex`([input_data_type, ...])
`Companding`(args, *kwargs)	Companding according to the A- or μ-law algorithm.
`ComplexToChannels`(args, *kwargs)
`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.
`FirFilter`(axis[, complex_channels, filter_key])	Apply a FIR filter to the input signal using convolution.
`LeeFilter`(sigma[, mode, cval, truncate, axes])	The Lee filter is a speckle reduction filter commonly used in synthetic aperture radar (SAR) and ultrasound image processing.
`LogCompress`([clip])	Logarithmic compression of data.
`LowPassFilterIQ`([axis, num_taps, filter_key])	Apply a low-pass FIR filter to the demodulated IQ (n_ch=2) input signal using convolution.
`PfieldWeighting`(args, *kwargs)	Weighting aligned data with the pressure field.
`ReshapeGrid`(args, *kwargs)	Reshape flat grid data to grid shape.
`ScanConvert`(args, *kwargs)	Scan convert images to cartesian coordinates.
`Simulate`(args, *kwargs)	Simulate RF data.
`TOFCorrection`(args, *kwargs)	Time-of-flight correction operation for ultrasound data.
`TissueSuppression`([cutoff])	Tissue suppression using SVD-based clutter filtering.
`UpMix`(args, *kwargs)	Upmix IQ data to RF data.
`CommonMidpointPhaseError`([input_data_type, ...])	Calculates the Common Midpoint Phase Error (CMPE)
`Cast`(args, *kwargs)	Operation wrapping keras.ops.cast.

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, additional_output_keys=None, **kwargs)[source]¶

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

Parameters:

input_data_type (Optional[DataTypes]) – Expected data type of the input tensor. Used for pipeline data-type validation; pass None to skip.
output_data_type (Optional[DataTypes]) – Data type produced by this operation.
key (Optional[str]) – Dict key the operation reads from (and writes to by default). Defaults to "data".
output_key (Optional[str]) – Dict key the operation writes its result to. Defaults to key. Set to a different value to preserve the original input under key while producing a new key for downstream operations.
cache_inputs (bool) – When True, values stored via set_input_cache() are merged into every call. False means the cache is empty by default. Selective per-key caching is not supported; use set_input_cache() directly to control which keys are stored.
cache_outputs (bool) – Memoize outputs keyed by a hash of the merged inputs.
jit_compile (bool) – Wrap call() with jit() for faster execution. Disable for easier interactive debugging.
with_batch_dim (bool) – Whether inputs carry a leading batch dimension. Affects default axis selection in filter-type operations.
jit_kwargs (dict | None) – Extra keyword arguments forwarded to the JIT compiler.
jittable (bool) – Mark the operation as JIT-compilable. Set to False for operations that use Python control flow incompatible with tracing.
additional_output_keys (List[str]) – Extra dict keys this operation may produce beyond output_key. Used for pipeline key-availability validation. Defaults to the class-level ADD_OUTPUT_KEYS list.

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

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.ApplyWindow(*args, **kwargs)[source]¶

Bases: Operation

Apply a window function to the input data along a specific axis.

This operation can be used to zero out the end and/or beginning of the signal and apply a window of some size to transition from the zeroed region to the unmodified region.

The axis is divided into five regions: [start (zero)] - [size (window)] - [middle (unmodified)] - [size (window)] - [end (zero)]

Parameters:

axis (int) – Axis along which to apply the window.
size (int) – Size of the window to apply at the start and end regions.
start (int) – Number of elements to zero at the end.
end (int) – Number of elements to zero at the end.
window_type (str) – Type of window to apply. Supported types are “hanning” and “linear”.

call(**kwargs)[source]¶: Abstract method that defines the processing logic for the operation. Subclasses must implement this method.

class zea.ops.BandPassFilter(axis=-3, num_taps=127, filter_key='band_pass_filter', passband=None, **kwargs)[source]¶

Bases: FirFilter

Apply a band-pass FIR filter to the real input signal using convolution.

By default, the call-time bandwidth defines the passband centered around demodulation_frequency, with edges at demodulation_frequency - bandwidth/2 and demodulation_frequency + bandwidth/2.

Optionally, a fixed passband=(f1, f2) can be provided at initialization, or a call-time passband can be provided to override both the fixed passband and the demodulation_frequency/bandwidth-based computation. Make sure this is used before demodulation to baseband.

This operation is provided for convenience and will recompute the filter weights every time it is called. Alternatively, you can use FirFilter with pre-computed filter taps.

Initialize the BandPassFilter operation.

Parameters:

axis (int) – Axis along which to apply the filter. Cannot be the batch dimension. Default is -3, which is the n_ax axis for standard ultrasound data layout.
num_taps (int) – Number of taps in the FIR filter. Default is 127. Odd will result in a type I filter, even in a type II filter.
passband (tuple[float, float] | None) – Lower and upper cutoff frequencies for the bandpass filter. See class docstring for detailed behavior. None disables explicit passband parameters and derives these from call-time frequency parameters.

call(sampling_frequency, demodulation_frequency=None, bandwidth=None, passband=None, **kwargs)[source]¶

Apply band-pass filter with specified bandwidth.

Parameters:

sampling_frequency (float) – Sampling frequency in Hz.
demodulation_frequency (float) – Center frequency in Hz. Used only when no passband override is provided.
bandwidth (float) – Bandwidth in Hz. Used only when no passband override is provided. The filter will pass frequencies from demodulation_frequency - bandwidth/2 to demodulation_frequency + bandwidth/2.
passband (tuple) – Optional tuple containing the lower and upper frequencies in Hz. This overrides both init-time passband and the demodulation_frequency/bandwidth-based passband.

Returns:

Dictionary containing filtered signal.

Return type:

dict

class zea.ops.Beamform(beamformer='delay_and_sum', num_patches=100, enable_pfield=False, **kwargs)[source]¶

Bases: Pipeline

Classical beamforming pipeline for ultrasound image formation.

Expected input data type is DataTypes.RF_DATA which has shape (n_tx, n_ax, n_el, n_ch).

Will run the following operations in sequence: - TOFCorrection (output type DataTypes.ALIGNED_DATA: (n_tx, n_ax, n_el, n_ch)) - PfieldWeighting (optional, output type DataTypes.ALIGNED_DATA: (n_tx, n_ax, n_el, n_ch)) - Sum over channels (DAS) - Sum over transmits (Compounding) (output type DataTypes.BEAMFORMED_DATA: (grid_size_z, grid_size_x, n_ch)) - ReshapeGrid (flattened grid is also reshaped to (grid_size_z, grid_size_x))

Initialize a Delay-and-Sum beamforming zea.Pipeline.

Parameters:

beamformer (str) – Type of beamformer to use. Currently supporting: - “delay_and_sum” - “delay_multiply_and_sum” - “coherence_factor” - “generalized_coherence_factor” Defaults to “delay_and_sum”.
num_patches (int) – Number of patches to split the grid into for patch-wise beamforming. If 1, no patching is performed.
enable_pfield (bool) – Whether to include pressure field weighting in the beamforming.

get_dict(compact=True)[source]¶

Convert the pipeline to a dictionary.

Unlike Pipeline.get_dict(), this does NOT include the internal operations list, since Beamform auto-generates its operations from beamformer, num_patches, and enable_pfield.

Return type:: dict

class zea.ops.Cast(*args, **kwargs)[source]¶

Bases: Lambda

Operation wrapping keras.ops.cast.

Parameters:

input_data_type (DataTypes or None) – Expected data type of the input tensor. Used for pipeline data-type validation; pass None to skip.
output_data_type (DataTypes or None) – Data type produced by this operation.
key (str or None) – Dict key the operation reads from (and writes to by default). Defaults to "data".
output_key (str or None) – Dict key the operation writes its result to. Defaults to key. Set to a different value to preserve the original input under key while producing a new key for downstream operations.
cache_inputs (bool) – When True, values stored via set_input_cache() are merged into every call. False means the cache is empty by default. Selective per-key caching is not supported; use set_input_cache() directly to control which keys are stored.
cache_outputs (bool) – Memoize outputs keyed by a hash of the merged inputs.
jit_compile (bool) – Wrap call() with jit() for faster execution. Disable for easier interactive debugging.
with_batch_dim (bool) – Whether inputs carry a leading batch dimension. Affects default axis selection in filter-type operations.
jit_kwargs (dict or None) – Extra keyword arguments forwarded to the JIT compiler.
jittable (bool) – Mark the operation as JIT-compilable. Set to False for operations that use Python control flow incompatible with tracing.
additional_output_keys (list of str or None) – Extra dict keys this operation may produce beyond output_key. Used for pipeline key-availability validation. Defaults to the class-level ADD_OUTPUT_KEYS list.

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, additional_output_keys=None, **kwargs)[source]¶

Bases: Operation

Parameters:

input_data_type (Optional[DataTypes]) – Expected data type of the input tensor. Used for pipeline data-type validation; pass None to skip.
output_data_type (Optional[DataTypes]) – Data type produced by this operation.
key (Optional[str]) – Dict key the operation reads from (and writes to by default). Defaults to "data".
output_key (Optional[str]) – Dict key the operation writes its result to. Defaults to key. Set to a different value to preserve the original input under key while producing a new key for downstream operations.
cache_inputs (bool) – When True, values stored via set_input_cache() are merged into every call. False means the cache is empty by default. Selective per-key caching is not supported; use set_input_cache() directly to control which keys are stored.
cache_outputs (bool) – Memoize outputs keyed by a hash of the merged inputs.
jit_compile (bool) – Wrap call() with jit() for faster execution. Disable for easier interactive debugging.
with_batch_dim (bool) – Whether inputs carry a leading batch dimension. Affects default axis selection in filter-type operations.
jit_kwargs (dict | None) – Extra keyword arguments forwarded to the JIT compiler.
jittable (bool) – Mark the operation as JIT-compilable. Set to False for operations that use Python control flow incompatible with tracing.
additional_output_keys (List[str]) – Extra dict keys this operation may produce beyond output_key. Used for pipeline key-availability validation. Defaults to the class-level ADD_OUTPUT_KEYS list.

call(**kwargs)[source]¶: Abstract method that defines the processing logic for the operation. Subclasses must implement this method.

class zea.ops.CoherenceFactor(*args, **kwargs)[source]¶

Bases: Operation

Coherence Factor (CF) Beamformer.

The Coherence Factor is a pixel-dependent weight used to quantify the focus quality of the beamformed signal. It is the ratio of the coherent power to the incoherent power of the signals received across the transducer aperture.

For a set of delayed signals \(x_i\) across \(N\) elements:

\[\mathrm{CF} = \frac{\left|\sum_{i=1}^{N} x_i\right|^2} {N \sum_{i=1}^{N} \left|x_i\right|^2}\]

The CF ranges from 0 (completely incoherent) to 1 (perfectly coherent). The beamformed output is the standard DAS sum weighted by CF per transmit, then compounded across transmits.

Reference

Hollman, K. W., Rigby, K. W., & O’Donnell, M. (1999). Coherence factor of speckle from a multi-row probe. IEEE Ultrasonics Symposium.

Parameters:

**kwargs – Additional arguments passed to the Operation base class.
input_data_type (DataTypes or None) – Expected data type of the input tensor. Used for pipeline data-type validation; pass None to skip.
output_data_type (DataTypes or None) – Data type produced by this operation.
key (str or None) – Dict key the operation reads from (and writes to by default). Defaults to "data".
output_key (str or None) – Dict key the operation writes its result to. Defaults to key. Set to a different value to preserve the original input under key while producing a new key for downstream operations.
cache_inputs (bool) – When True, values stored via set_input_cache() are merged into every call. False means the cache is empty by default. Selective per-key caching is not supported; use set_input_cache() directly to control which keys are stored.
cache_outputs (bool) – Memoize outputs keyed by a hash of the merged inputs.
jit_compile (bool) – Wrap call() with jit() for faster execution. Disable for easier interactive debugging.
with_batch_dim (bool) – Whether inputs carry a leading batch dimension. Affects default axis selection in filter-type operations.
jit_kwargs (dict or None) – Extra keyword arguments forwarded to the JIT compiler.
jittable (bool) – Mark the operation as JIT-compilable. Set to False for operations that use Python control flow incompatible with tracing.
additional_output_keys (list of str or None) – Extra dict keys this operation may produce beyond output_key. Used for pipeline key-availability validation. Defaults to the class-level ADD_OUTPUT_KEYS list.

call(**kwargs)[source]¶

Performs CF beamforming on tof-corrected input.

Parameters:

tof_corrected_data (ops.Tensor) – TOF-corrected input of shape (n_tx, n_pix, n_el, n_ch), with optional batch dimension.

Returns:

Dictionary containing beamformed data of shape: (n_pix, n_ch), with optional batch dimension.

Return type:

dict

process_image(data)[source]¶

Applies CF weighting and compounding on tof-corrected input.

Parameters:

data (ops.Tensor) – TOF-corrected input of shape (n_tx, n_pix, n_el, n_ch), with optional batch dimension.

Returns:

Beamformed image of shape (n_pix, n_ch),: with optional batch dimension.

Return type:

ops.Tensor

class zea.ops.CommonMidpointPhaseError(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, additional_output_keys=None, **kwargs)[source]¶

Bases: Operation

Calculates the Common Midpoint Phase Error (CMPE)

Computes CMPE between translated transmit and receive apertures with a common midpoint.

Important

Only works for multistatic datasets, e.g. synthetic aperture data.

Note

This was directly adapted from the Differentiable Beamforming for Ultrasound Autofocusing (DBUA) paper, see original paper and code.

Parameters:

input_data_type (Optional[DataTypes]) – Expected data type of the input tensor. Used for pipeline data-type validation; pass None to skip.
output_data_type (Optional[DataTypes]) – Data type produced by this operation.
key (Optional[str]) – Dict key the operation reads from (and writes to by default). Defaults to "data".
output_key (Optional[str]) – Dict key the operation writes its result to. Defaults to key. Set to a different value to preserve the original input under key while producing a new key for downstream operations.
cache_inputs (bool) – When True, values stored via set_input_cache() are merged into every call. False means the cache is empty by default. Selective per-key caching is not supported; use set_input_cache() directly to control which keys are stored.
cache_outputs (bool) – Memoize outputs keyed by a hash of the merged inputs.
jit_compile (bool) – Wrap call() with jit() for faster execution. Disable for easier interactive debugging.
with_batch_dim (bool) – Whether inputs carry a leading batch dimension. Affects default axis selection in filter-type operations.
jit_kwargs (dict | None) – Extra keyword arguments forwarded to the JIT compiler.
jittable (bool) – Mark the operation as JIT-compilable. Set to False for operations that use Python control flow incompatible with tracing.
additional_output_keys (List[str]) – Extra dict keys this operation may produce beyond output_key. Used for pipeline key-availability validation. Defaults to the class-level ADD_OUTPUT_KEYS list.

call(**kwargs)[source]¶: Abstract method that defines the processing logic for the operation. Subclasses must implement this method.

create_subapertures(data, halfsa, dx)[source]¶

Create subapertures from the data.

Parameters:

data (ops.Tensor) – The data to create subapertures from.
halfsa (int) – Half of the subaperture.
dx (float) – The spacing between the subapertures.

Returns:

The transmit subapertures. receive_subap (ops.Tensor): The receive subapertures.

Return type:

transmit_subap (ops.Tensor)

process_phase_map(data, **kwargs)[source]¶

Create the common midpoint subaperture phase error map.

Parameters:: data (ops.Tensor) – The data to create the phase error map from.
Returns:: The phase error map.
Return type:: phase_error_map (ops.Tensor)

class zea.ops.Companding(*args, **kwargs)[source]¶

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.
input_data_type (DataTypes or None) – Expected data type of the input tensor. Used for pipeline data-type validation; pass None to skip.
output_data_type (DataTypes or None) – Data type produced by this operation.
key (str or None) – Dict key the operation reads from (and writes to by default). Defaults to "data".
output_key (str or None) – Dict key the operation writes its result to. Defaults to key. Set to a different value to preserve the original input under key while producing a new key for downstream operations.
cache_inputs (bool) – When True, values stored via set_input_cache() are merged into every call. False means the cache is empty by default. Selective per-key caching is not supported; use set_input_cache() directly to control which keys are stored.
cache_outputs (bool) – Memoize outputs keyed by a hash of the merged inputs.
jit_compile (bool) – Wrap call() with jit() for faster execution. Disable for easier interactive debugging.
with_batch_dim (bool) – Whether inputs carry a leading batch dimension. Affects default axis selection in filter-type operations.
jit_kwargs (dict or None) – Extra keyword arguments forwarded to the JIT compiler.
jittable (bool) – Mark the operation as JIT-compilable. Set to False for operations that use Python control flow incompatible with tracing.
additional_output_keys (list of str or None) – Extra dict keys this operation may produce beyond output_key. Used for pipeline key-availability validation. Defaults to the class-level ADD_OUTPUT_KEYS list.

call(mu=255, A=87.6, **kwargs)[source]¶: Abstract method that defines the processing logic for the operation. Subclasses must implement this method.

class zea.ops.ComplexToChannels(*args, **kwargs)[source]¶

Bases: Operation

Parameters:

input_data_type (DataTypes or None) – Expected data type of the input tensor. Used for pipeline data-type validation; pass None to skip.
output_data_type (DataTypes or None) – Data type produced by this operation.
key (str or None) – Dict key the operation reads from (and writes to by default). Defaults to "data".
output_key (str or None) – Dict key the operation writes its result to. Defaults to key. Set to a different value to preserve the original input under key while producing a new key for downstream operations.
cache_inputs (bool) – When True, values stored via set_input_cache() are merged into every call. False means the cache is empty by default. Selective per-key caching is not supported; use set_input_cache() directly to control which keys are stored.
cache_outputs (bool) – Memoize outputs keyed by a hash of the merged inputs.
jit_compile (bool) – Wrap call() with jit() for faster execution. Disable for easier interactive debugging.
with_batch_dim (bool) – Whether inputs carry a leading batch dimension. Affects default axis selection in filter-type operations.
jit_kwargs (dict or None) – Extra keyword arguments forwarded to the JIT compiler.
jittable (bool) – Mark the operation as JIT-compilable. Set to False for operations that use Python control flow incompatible with tracing.
additional_output_keys (list of str or None) – Extra dict keys this operation may produce beyond output_key. Used for pipeline key-availability validation. Defaults to the class-level ADD_OUTPUT_KEYS list.

call(**kwargs)[source]¶: Abstract method that defines the processing logic for the operation. Subclasses must implement this method.

class zea.ops.DelayAndSum(*args, **kwargs)[source]¶

Bases: Operation

Sums time-delayed signals along channels and transmits.

Parameters:

input_data_type (DataTypes or None) – Expected data type of the input tensor. Used for pipeline data-type validation; pass None to skip.
output_data_type (DataTypes or None) – Data type produced by this operation.
key (str or None) – Dict key the operation reads from (and writes to by default). Defaults to "data".
output_key (str or None) – Dict key the operation writes its result to. Defaults to key. Set to a different value to preserve the original input under key while producing a new key for downstream operations.
cache_inputs (bool) – When True, values stored via set_input_cache() are merged into every call. False means the cache is empty by default. Selective per-key caching is not supported; use set_input_cache() directly to control which keys are stored.
cache_outputs (bool) – Memoize outputs keyed by a hash of the merged inputs.
jit_compile (bool) – Wrap call() with jit() for faster execution. Disable for easier interactive debugging.
with_batch_dim (bool) – Whether inputs carry a leading batch dimension. Affects default axis selection in filter-type operations.
jit_kwargs (dict or None) – Extra keyword arguments forwarded to the JIT compiler.
jittable (bool) – Mark the operation as JIT-compilable. Set to False for operations that use Python control flow incompatible with tracing.
additional_output_keys (list of str or None) – Extra dict keys this operation may produce beyond output_key. Used for pipeline key-availability validation. Defaults to the class-level ADD_OUTPUT_KEYS list.

call(**kwargs)[source]¶

Performs DAS beamforming on tof-corrected input.

Parameters:

tof_corrected_data (ops.Tensor) – The TOF corrected input of shape (n_tx, prod(grid.shape), n_el, n_ch) with optional batch dimension.

Returns:

Dictionary containing beamformed_data: of shape (prod(grid.shape), n_ch) with optional batch dimension.

Return type:

dict

class zea.ops.DelayMultiplyAndSum(*args, **kwargs)[source]¶

Bases: Operation

Performs the operations for the Delay-Multiply-and-Sum beamformer except the delay. The delay should be performed by the TOF correction operation.

Parameters:

input_data_type (DataTypes or None) – Expected data type of the input tensor. Used for pipeline data-type validation; pass None to skip.
output_data_type (DataTypes or None) – Data type produced by this operation.
key (str or None) – Dict key the operation reads from (and writes to by default). Defaults to "data".
output_key (str or None) – Dict key the operation writes its result to. Defaults to key. Set to a different value to preserve the original input under key while producing a new key for downstream operations.
cache_inputs (bool) – When True, values stored via set_input_cache() are merged into every call. False means the cache is empty by default. Selective per-key caching is not supported; use set_input_cache() directly to control which keys are stored.
cache_outputs (bool) – Memoize outputs keyed by a hash of the merged inputs.
jit_compile (bool) – Wrap call() with jit() for faster execution. Disable for easier interactive debugging.
with_batch_dim (bool) – Whether inputs carry a leading batch dimension. Affects default axis selection in filter-type operations.
jit_kwargs (dict or None) – Extra keyword arguments forwarded to the JIT compiler.
jittable (bool) – Mark the operation as JIT-compilable. Set to False for operations that use Python control flow incompatible with tracing.
additional_output_keys (list of str or None) – Extra dict keys this operation may produce beyond output_key. Used for pipeline key-availability validation. Defaults to the class-level ADD_OUTPUT_KEYS list.

call(**kwargs)[source]¶

Performs DMAS beamforming on tof-corrected input.

Parameters:

tof_corrected_data (ops.Tensor) – The TOF corrected input of shape (n_tx, prod(grid.shape), n_el, n_ch) with optional batch dimension.

Returns:

Dictionary containing beamformed_data: of shape (grid_size_z*grid_size_x, n_ch) with optional batch dimension.

Return type:

dict

process_image(data)[source]¶

Performs DMAS beamforming on tof-corrected input.

Parameters:: data (ops.Tensor) – The TOF corrected input 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)[source]¶

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.

Parameters:

input_data_type (DataTypes or None) – Expected data type of the input tensor. Used for pipeline data-type validation; pass None to skip.
output_data_type (DataTypes or None) – Data type produced by this operation.
key (str or None) – Dict key the operation reads from (and writes to by default). Defaults to "data".
output_key (str or None) – Dict key the operation writes its result to. Defaults to key. Set to a different value to preserve the original input under key while producing a new key for downstream operations.
cache_inputs (bool) – When True, values stored via set_input_cache() are merged into every call. False means the cache is empty by default. Selective per-key caching is not supported; use set_input_cache() directly to control which keys are stored.
cache_outputs (bool) – Memoize outputs keyed by a hash of the merged inputs.
jit_compile (bool) – Wrap call() with jit() for faster execution. Disable for easier interactive debugging.
with_batch_dim (bool) – Whether inputs carry a leading batch dimension. Affects default axis selection in filter-type operations.
jit_kwargs (dict or None) – Extra keyword arguments forwarded to the JIT compiler.
jittable (bool) – Mark the operation as JIT-compilable. Set to False for operations that use Python control flow incompatible with tracing.
additional_output_keys (list of str or None) – Extra dict keys this operation may produce beyond output_key. Used for pipeline key-availability validation. Defaults to the class-level ADD_OUTPUT_KEYS list.

ADD_OUTPUT_KEYS: List[str] = ['center_frequency', 'n_ch']¶

call(demodulation_frequency=None, sampling_frequency=None, **kwargs)[source]¶: 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)[source]¶

Bases: Operation

Downsample data along a specific axis.

Parameters:

input_data_type (DataTypes or None) – Expected data type of the input tensor. Used for pipeline data-type validation; pass None to skip.
output_data_type (DataTypes or None) – Data type produced by this operation.
key (str or None) – Dict key the operation reads from (and writes to by default). Defaults to "data".
output_key (str or None) – Dict key the operation writes its result to. Defaults to key. Set to a different value to preserve the original input under key while producing a new key for downstream operations.
cache_inputs (bool) – When True, values stored via set_input_cache() are merged into every call. False means the cache is empty by default. Selective per-key caching is not supported; use set_input_cache() directly to control which keys are stored.
cache_outputs (bool) – Memoize outputs keyed by a hash of the merged inputs.
jit_compile (bool) – Wrap call() with jit() for faster execution. Disable for easier interactive debugging.
with_batch_dim (bool) – Whether inputs carry a leading batch dimension. Affects default axis selection in filter-type operations.
jit_kwargs (dict or None) – Extra keyword arguments forwarded to the JIT compiler.
jittable (bool) – Mark the operation as JIT-compilable. Set to False for operations that use Python control flow incompatible with tracing.
additional_output_keys (list of str or None) – Extra dict keys this operation may produce beyond output_key. Used for pipeline key-availability validation. Defaults to the class-level ADD_OUTPUT_KEYS list.

ADD_OUTPUT_KEYS: List[str] = ['sampling_frequency', 'n_ax']¶

call(sampling_frequency=None, n_ax=None, **kwargs)[source]¶: Abstract method that defines the processing logic for the operation. Subclasses must implement this method.

class zea.ops.EnvelopeDetect(*args, **kwargs)[source]¶

Bases: Operation

Envelope detection of RF signals.

Parameters:

input_data_type (DataTypes or None) – Expected data type of the input tensor. Used for pipeline data-type validation; pass None to skip.
output_data_type (DataTypes or None) – Data type produced by this operation.
key (str or None) – Dict key the operation reads from (and writes to by default). Defaults to "data".
output_key (str or None) – Dict key the operation writes its result to. Defaults to key. Set to a different value to preserve the original input under key while producing a new key for downstream operations.
cache_inputs (bool) – When True, values stored via set_input_cache() are merged into every call. False means the cache is empty by default. Selective per-key caching is not supported; use set_input_cache() directly to control which keys are stored.
cache_outputs (bool) – Memoize outputs keyed by a hash of the merged inputs.
jit_compile (bool) – Wrap call() with jit() for faster execution. Disable for easier interactive debugging.
with_batch_dim (bool) – Whether inputs carry a leading batch dimension. Affects default axis selection in filter-type operations.
jit_kwargs (dict or None) – Extra keyword arguments forwarded to the JIT compiler.
jittable (bool) – Mark the operation as JIT-compilable. Set to False for operations that use Python control flow incompatible with tracing.
additional_output_keys (list of str or None) – Extra dict keys this operation may produce beyond output_key. Used for pipeline key-availability validation. Defaults to the class-level ADD_OUTPUT_KEYS list.

call(**kwargs)[source]¶

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.FirFilter(axis, complex_channels=False, filter_key='fir_filter_taps', **kwargs)[source]¶

Bases: Operation

Apply a FIR filter to the input signal using convolution.

Looks for the filter taps in the input dictionary using the specified filter_key.

Parameters:

axis (int) – Axis along which to apply the filter. Cannot be the batch dimension and not the complex channel axis when complex_channels=True.
complex_channels (bool) – Whether the last dimension of the input signal represents complex channels (real and imaginary parts). When True, it will convert the signal to complex dtype before filtering and convert it back to two channels after filtering.
filter_key (str) – Key in the input dictionary where the FIR filter taps are stored. Default is “fir_filter_taps”.

call(**kwargs)[source]¶: Abstract method that defines the processing logic for the operation. Subclasses must implement this method.

property valid_keys¶: Get the valid keys for the call method.

class zea.ops.GaussianBlur(sigma, order=0, mode='symmetric', cval=None, truncate=4.0, axes=(-3, -2), **kwargs)[source]¶

Bases: Filter

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

Parameters:

sigma (float) – Standard deviation for Gaussian kernel. The standard deviations of the Gaussian filter are given for each axis as a sequence, or as a single number, in which case it is equal for all axes.
order (Union[int, Tuple[int]]) – The order of the filter along each axis is given as a sequence of integers, or as a single number. An order of 0 corresponds to convolution with a Gaussian kernel. A positive order corresponds to convolution with that derivative of a Gaussian. Default is 0.
mode (str) – Padding mode for the input image. Default is ‘symmetric’. See [keras docs](https://www.tensorflow.org/api_docs/python/tf/keras/ops/pad) for all options and [tensorflow docs](https://www.tensorflow.org/api_docs/python/tf/pad) for some examples. Note that the naming differs from scipy.ndimage.gaussian_filter!
cval (float | None) – Value to fill past edges of input if mode is ‘constant’. Default is None.
truncate (float) – Truncate the filter at this many standard deviations. Default is 4.0.
axes (Tuple[int]) – If None, input is filtered along all axes. Otherwise, input is filtered along the specified axes. When axes is specified, any tuples used for sigma, order, mode and/or radius must match the length of axes. The ith entry in any of these tuples corresponds to the ith entry in axes. Default is (-3, -2), which corresponds to the height and width dimensions of a (…, height, width, channels) tensor.

call(**kwargs)[source]¶

Apply a Gaussian filter to the input data.

Parameters:: data (ops.Tensor) – Input image data of shape (height, width, channels) with optional batch dimension if self.with_batch_dim.

class zea.ops.GeneralizedCoherenceFactor(*args, **kwargs)[source]¶

Bases: Operation

Generalized Coherence Factor (GCF) Beamformer.

The GCF is a coherence-based adaptive weighting technique used to improve the quality of ultrasound images by suppressing sidelobes and clutter. It is defined as the ratio of the power within a low-frequency region of the spatial spectrum to the total power across the aperture.

For a given pixel, let \(A(k)\) be the spatial Fourier transform of the delayed channel data across \(N\) elements. The GCF is:

\[\mathrm{GCF} = \frac{\sum_{k \in \mathcal{M}_0} \left|A(k)\right|^2} {\sum_{k=0}^{N-1} \left|A(k)\right|^2}\]

where \(\mathcal{M}_0 = \{k : k \leq m_0\} \cup \{k : k \geq N - m_0\}\) is the low spatial-frequency region controlled by \(m_0\).

Reference

Li, P. C., & Li, M. L. (2003). “Adaptive imaging using the generalized coherence factor.” IEEE Transactions on Ultrasonics, Ferroelectrics, and Frequency Control, 50(2), 128-141.

Parameters:

m_zero (int) – Cutoff frequency index for the low-frequency spatial region. Higher values increase tolerance to phase aberrations. Defaults to 4.
**kwargs – Additional arguments passed to the Operation base class.
input_data_type (DataTypes or None) – Expected data type of the input tensor. Used for pipeline data-type validation; pass None to skip.
output_data_type (DataTypes or None) – Data type produced by this operation.
key (str or None) – Dict key the operation reads from (and writes to by default). Defaults to "data".
output_key (str or None) – Dict key the operation writes its result to. Defaults to key. Set to a different value to preserve the original input under key while producing a new key for downstream operations.
cache_inputs (bool) – When True, values stored via set_input_cache() are merged into every call. False means the cache is empty by default. Selective per-key caching is not supported; use set_input_cache() directly to control which keys are stored.
cache_outputs (bool) – Memoize outputs keyed by a hash of the merged inputs.
jit_compile (bool) – Wrap call() with jit() for faster execution. Disable for easier interactive debugging.
with_batch_dim (bool) – Whether inputs carry a leading batch dimension. Affects default axis selection in filter-type operations.
jit_kwargs (dict or None) – Extra keyword arguments forwarded to the JIT compiler.
jittable (bool) – Mark the operation as JIT-compilable. Set to False for operations that use Python control flow incompatible with tracing.
additional_output_keys (list of str or None) – Extra dict keys this operation may produce beyond output_key. Used for pipeline key-availability validation. Defaults to the class-level ADD_OUTPUT_KEYS list.

call(m_zero=None, **kwargs)[source]¶

Performs GCF beamforming on tof-corrected input.

Parameters:

m_zero (int, optional) – Cutoff frequency index, overrides the instance default when provided via pipeline parameters.
tof_corrected_data (ops.Tensor) – TOF-corrected input of shape (n_tx, n_pix, n_el, n_ch), with optional batch dimension.

Returns:

Dictionary containing beamformed data of shape: (n_pix, n_ch), with optional batch dimension.

Return type:

dict

process_image(data, m_zero=None)[source]¶

Applies GCF weighting and compounding on tof-corrected input.

Parameters:

data (ops.Tensor) – TOF-corrected input of shape (n_tx, n_pix, n_el, n_ch), with optional batch dimension.
m_zero (int, optional) – Overrides the instance m_zero for this call.

Returns:

Beamformed image of shape (n_pix, n_ch),: with optional batch dimension.

Return type:

ops.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, additional_output_keys=None, **kwargs)[source]¶

Bases: Operation

Identity operation.

Parameters:

input_data_type (Optional[DataTypes]) – Expected data type of the input tensor. Used for pipeline data-type validation; pass None to skip.
output_data_type (Optional[DataTypes]) – Data type produced by this operation.
key (Optional[str]) – Dict key the operation reads from (and writes to by default). Defaults to "data".
output_key (Optional[str]) – Dict key the operation writes its result to. Defaults to key. Set to a different value to preserve the original input under key while producing a new key for downstream operations.
cache_inputs (bool) – When True, values stored via set_input_cache() are merged into every call. False means the cache is empty by default. Selective per-key caching is not supported; use set_input_cache() directly to control which keys are stored.
cache_outputs (bool) – Memoize outputs keyed by a hash of the merged inputs.
jit_compile (bool) – Wrap call() with jit() for faster execution. Disable for easier interactive debugging.
with_batch_dim (bool) – Whether inputs carry a leading batch dimension. Affects default axis selection in filter-type operations.
jit_kwargs (dict | None) – Extra keyword arguments forwarded to the JIT compiler.
jittable (bool) – Mark the operation as JIT-compilable. Set to False for operations that use Python control flow incompatible with tracing.
additional_output_keys (List[str]) – Extra dict keys this operation may produce beyond output_key. Used for pipeline key-availability validation. Defaults to the class-level ADD_OUTPUT_KEYS list.

call(**kwargs)[source]¶

Returns the input as is.

Return type:: Dict

class zea.ops.Lambda(*args, **kwargs)[source]¶

Bases: Operation

Use any function as an operation.

Parameters:

input_data_type (DataTypes or None) – Expected data type of the input tensor. Used for pipeline data-type validation; pass None to skip.
output_data_type (DataTypes or None) – Data type produced by this operation.
key (str or None) – Dict key the operation reads from (and writes to by default). Defaults to "data".
output_key (str or None) – Dict key the operation writes its result to. Defaults to key. Set to a different value to preserve the original input under key while producing a new key for downstream operations.
cache_inputs (bool) – When True, values stored via set_input_cache() are merged into every call. False means the cache is empty by default. Selective per-key caching is not supported; use set_input_cache() directly to control which keys are stored.
cache_outputs (bool) – Memoize outputs keyed by a hash of the merged inputs.
jit_compile (bool) – Wrap call() with jit() for faster execution. Disable for easier interactive debugging.
with_batch_dim (bool) – Whether inputs carry a leading batch dimension. Affects default axis selection in filter-type operations.
jit_kwargs (dict or None) – Extra keyword arguments forwarded to the JIT compiler.
jittable (bool) – Mark the operation as JIT-compilable. Set to False for operations that use Python control flow incompatible with tracing.
additional_output_keys (list of str or None) – Extra dict keys this operation may produce beyond output_key. Used for pipeline key-availability validation. Defaults to the class-level ADD_OUTPUT_KEYS list.

call(**kwargs)[source]¶: Abstract method that defines the processing logic for the operation. Subclasses must implement this method.

get_dict(compact=True)[source]¶

Serialize lambda-based operations.

Generic zea.ops.Lambda instances are intentionally rejected because arbitrary callables cannot be reliably serialized. Registered subclasses (e.g. zea.ops.keras_ops wrappers) are serialized by operation name and the callable keyword arguments.

class zea.ops.LeeFilter(sigma, mode='symmetric', cval=None, truncate=4.0, axes=(-3, -2), **kwargs)[source]¶

Bases: Filter

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.

Parameters:

sigma (float) – Standard deviation for Gaussian kernel. The standard deviations of the Gaussian filter are given for each axis as a sequence, or as a single number, in which case it is equal for all axes.
mode (str) – Padding mode for the input image. Default is ‘symmetric’. See [keras docs](https://www.tensorflow.org/api_docs/python/tf/keras/ops/pad) for all options and [tensorflow docs](https://www.tensorflow.org/api_docs/python/tf/pad) for some examples. Note that the naming differs from scipy.ndimage.gaussian_filter!
cval (float | None) – Value to fill past edges of input if mode is ‘constant’. Default is None.
truncate (float) – Truncate the filter at this many standard deviations. Default is 4.0.
axes (Tuple[int]) – If None, input is filtered along all axes. Otherwise, input is filtered along the specified axes. When axes is specified, any tuples used for sigma, order, mode and/or radius must match the length of axes. The ith entry in any of these tuples corresponds to the ith entry in axes. Default is (-3, -2), which corresponds to the height and width dimensions of a (…, height, width, channels) tensor.

call(**kwargs)[source]¶

Apply the Lee filter to the input data.

Parameters:: data (ops.Tensor) – Input image data of shape (height, width, channels) with optional batch dimension if self.with_batch_dim.

class zea.ops.LogCompress(clip=True, **kwargs)[source]¶

Bases: Operation

Logarithmic compression of data.

Initialize the LogCompress operation.

Parameters:: clip (bool) – Whether to clip the output to a dynamic range. Defaults to True.

call(dynamic_range=None, **kwargs)[source]¶

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.LowPassFilterIQ(axis=-3, num_taps=127, filter_key='low_pass_filter', **kwargs)[source]¶

Bases: FirFilter

Apply a low-pass FIR filter to the demodulated IQ (n_ch=2) input signal using convolution.

It is recommended to use FirFilter with pre-computed filter taps for jittable operations. The LowPassFilterIQ operation itself is not jittable and is provided for convenience only.

Uses get_low_pass_iq_filter() to compute the filter taps.

Initialize the LowPassFilterIQ operation.

Parameters:

axis (int) – Axis along which to apply the filter. Cannot be the batch dimension and cannot be the complex channel axis (the last axis). Default is -3, which is the n_ax axis for standard ultrasound data layout.
num_taps (int) – Number of taps in the FIR filter. Default is 127. Odd will result in a type I filter, even in a type II filter.

call(bandwidth, sampling_frequency, center_frequency, **kwargs)[source]¶: Abstract method that defines the processing logic for the operation. Subclasses must implement this method.

class zea.ops.Map(operations, argnames, in_axes=0, out_axes=0, chunks=None, batch_size=None, **kwargs)[source]¶

Bases: Pipeline

A pipeline that maps its operations over specified input arguments.

This can be used to reduce memory usage by processing data in chunks.

Notes

When chunks and batch_size are both None (default), this behaves like a normal Pipeline.
Changing anything other than self.output_key in the dict will not be propagated.
Will be jitted as a single operation, not the individual operations.
This class handles the batching.

For more information on how to use in_axes, out_axes, see the documentation for jax.vmap.

Example

>>> from zea.ops import Map, Pipeline, Demodulate, TOFCorrection

>>> # apply operations in batches of 8
>>> # in this case, over the first axis of "data"
>>> # or more specifically, process 8 transmits at a time

>>> pipeline_mapped = Map(
...     [
...         Demodulate(),
...         TOFCorrection(),
...     ],
...     argnames="data",
...     batch_size=8,
... )

>>> # you can also map a subset of the operations
>>> # for example, demodulate in 4 chunks
>>> # or more specifically, split the transmit axis into 4 parts

>>> pipeline_mapped = Pipeline(
...     [
...         Map([Demodulate()], argnames="data", chunks=4),
...         TOFCorrection(),
...     ],
... )

Parameters:

operations (List[Operation]) – List of operations to be performed.
argnames (Union[List[str], str]) – List of argument names (or keys) to map over. Can also be a single string if only one argument is mapped over.
in_axes (Union[List[Optional[int]], int]) – Axes to map over for each argument. If a single int is provided, it is used for all arguments.
out_axes (Union[List[Optional[int]], int]) – Axes to map over for each output. If a single int is provided, it is used for all outputs.
chunks (int | None) – Number of chunks to split the input data into. If None, no chunking is performed. Mutually exclusive with batch_size.
batch_size (int | None) – Size of batches to process at once. If None, no batching is performed. Mutually exclusive with chunks.

call(**inputs)[source]¶: Process input data through the pipeline.

call_item(**inputs)[source]¶: Process data in patches.

get_dict(compact=True)[source]¶: Get the configuration of the pipeline.

property jit_options¶: Get the jit_options property of the pipeline.

jittable_call(**inputs)[source]¶: Process input data through the pipeline.

property with_batch_dim¶: Get the with_batch_dim property of the pipeline.

class zea.ops.Mean(*args, **kwargs)[source]¶

Bases: Operation

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

Parameters:

input_data_type (DataTypes or None) – Expected data type of the input tensor. Used for pipeline data-type validation; pass None to skip.
output_data_type (DataTypes or None) – Data type produced by this operation.
key (str or None) – Dict key the operation reads from (and writes to by default). Defaults to "data".
output_key (str or None) – Dict key the operation writes its result to. Defaults to key. Set to a different value to preserve the original input under key while producing a new key for downstream operations.
cache_inputs (bool) – When True, values stored via set_input_cache() are merged into every call. False means the cache is empty by default. Selective per-key caching is not supported; use set_input_cache() directly to control which keys are stored.
cache_outputs (bool) – Memoize outputs keyed by a hash of the merged inputs.
jit_compile (bool) – Wrap call() with jit() for faster execution. Disable for easier interactive debugging.
with_batch_dim (bool) – Whether inputs carry a leading batch dimension. Affects default axis selection in filter-type operations.
jit_kwargs (dict or None) – Extra keyword arguments forwarded to the JIT compiler.
jittable (bool) – Mark the operation as JIT-compilable. Set to False for operations that use Python control flow incompatible with tracing.
additional_output_keys (list of str or None) – Extra dict keys this operation may produce beyond output_key. Used for pipeline key-availability validation. Defaults to the class-level ADD_OUTPUT_KEYS list.

call(**kwargs)[source]¶: Abstract method that defines the processing logic for the operation. Subclasses must implement this method.

class zea.ops.Normalize(*args, **kwargs)[source]¶

Bases: Operation

Normalize data to a given range.

Parameters:

output_range (tuple) – (min, max) range the data is mapped to. Defaults to (0, 1).
input_range (tuple) – (min, max) range of the input data; the data is clipped to this range before mapping. Either element may be None to infer that bound from the data. If input_range itself is None, both bounds are inferred. Defaults to None.
percentile (float) – When the max bound is inferred, use this percentile of the data instead of its maximum. Defaults to None (use the max).

ADD_OUTPUT_KEYS: List[str] = ['minval', 'maxval']¶

call(**kwargs)[source]¶

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)[source]¶: Converts an iterable to float32 and leaves None values as is.

property valid_keys¶: Get the valid keys for the call method.

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, additional_output_keys=None, **kwargs)[source]¶

Bases: Operation

Abstract base class for pipeline operations with caching and JIT support.

Every operation:

receives and returns a dict of named tensors
is identified by a key in ops_registry
can be composed into a Pipeline
optionally caches inputs and/or outputs for repeated calls with the same arguments

Subclasses must implement call(), which performs the actual computation and must return a dict.

Examples

from zea.internal.registry import ops_registry
from zea.ops.base import Operation


@ops_registry("my_scale")
class MyScale(Operation):
    def __init__(self, factor: float = 2.0, **kwargs):
        super().__init__(**kwargs)
        self.factor = factor

    def call(self, data, **kwargs):
        return {"data": data * self.factor}

Parameters:

input_data_type (Optional[DataTypes]) – Expected data type of the input tensor. Used for pipeline data-type validation; pass None to skip.
output_data_type (Optional[DataTypes]) – Data type produced by this operation.
key (Optional[str]) – Dict key the operation reads from (and writes to by default). Defaults to "data".
output_key (Optional[str]) – Dict key the operation writes its result to. Defaults to key. Set to a different value to preserve the original input under key while producing a new key for downstream operations.
cache_inputs (bool) – When True, values stored via set_input_cache() are merged into every call. False means the cache is empty by default. Selective per-key caching is not supported; use set_input_cache() directly to control which keys are stored.
cache_outputs (bool) – Memoize outputs keyed by a hash of the merged inputs.
jit_compile (bool) – Wrap call() with jit() for faster execution. Disable for easier interactive debugging.
with_batch_dim (bool) – Whether inputs carry a leading batch dimension. Affects default axis selection in filter-type operations.
jit_kwargs (dict | None) – Extra keyword arguments forwarded to the JIT compiler.
jittable (bool) – Mark the operation as JIT-compilable. Set to False for operations that use Python control flow incompatible with tracing.
additional_output_keys (List[str]) – Extra dict keys this operation may produce beyond output_key. Used for pipeline key-availability validation. Defaults to the class-level ADD_OUTPUT_KEYS list.

ADD_OUTPUT_KEYS: List[str] = []¶

__call__(*args, **kwargs)[source]¶

Process the input keyword arguments and return the processed results.

Parameters:: kwargs – Keyword arguments to be processed.
Return type:: Dict
Returns:: Combined input and output as kwargs.

call(**kwargs)[source]¶: Abstract method that defines the processing logic for the operation. Subclasses must implement this method.

clear_cache()[source]¶: Clear the input and output caches.

get_dict(compact=True)[source]¶

Get the configuration of the operation.

Parameters:: compact (bool) – If True (default), only include parameters that differ from their defaults. If False, include all parameters for full reproducibility.

property jit_compile¶: Get the JIT compilation flag.

property jittable¶: Check if the operation can be JIT compiled.

property needs_keys: set¶: Get a set of all input keys needed by the operation.

property output_keys: List[str]¶: Get the output keys of the operation.

set_input_cache(input_cache)[source]¶

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)[source]¶: Set the JIT compilation flag and set the _call method accordingly.

set_output_cache(output_cache)[source]¶

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: set¶: 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)[source]¶

Bases: Operation, DataLayer

Pad layer for padding tensors to a specified shape.

Parameters:

input_data_type (DataTypes or None) – Expected data type of the input tensor. Used for pipeline data-type validation; pass None to skip.
output_data_type (DataTypes or None) – Data type produced by this operation.
key (str or None) – Dict key the operation reads from (and writes to by default). Defaults to "data".
output_key (str or None) – Dict key the operation writes its result to. Defaults to key. Set to a different value to preserve the original input under key while producing a new key for downstream operations.
cache_inputs (bool) – When True, values stored via set_input_cache() are merged into every call. False means the cache is empty by default. Selective per-key caching is not supported; use set_input_cache() directly to control which keys are stored.
cache_outputs (bool) – Memoize outputs keyed by a hash of the merged inputs.
jit_compile (bool) – Wrap call() with jit() for faster execution. Disable for easier interactive debugging.
with_batch_dim (bool) – Whether inputs carry a leading batch dimension. Affects default axis selection in filter-type operations.
jit_kwargs (dict or None) – Extra keyword arguments forwarded to the JIT compiler.
jittable (bool) – Mark the operation as JIT-compilable. Set to False for operations that use Python control flow incompatible with tracing.
additional_output_keys (list of str or None) – Extra dict keys this operation may produce beyond output_key. Used for pipeline key-availability validation. Defaults to the class-level ADD_OUTPUT_KEYS list.

call(**kwargs)[source]¶: 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)[source]¶

Pads the input tensor z to the specified shape.

Parameters:

z (tensor) – The input tensor to be padded.
target_shape (list | tuple) – The target shape to pad the tensor to.
uniform (bool) – If True, ensures that padding is uniform (even on both sides). Default is False.
axis (Union[int, List[int]]) – 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) – 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)[source]¶

Bases: Map

A pipeline that maps its operations over flatgrid and flat_pfield keys.

This can be used to reduce memory usage by processing data in chunks.

For more information and flexibility, see zea.ops.Map.

Parameters:

operations (list) – List of operations to be performed.
argnames (str or list) – List of argument names (or keys) to map over. Can also be a single string if only one argument is mapped over.
in_axes (int or list) – Axes to map over for each argument. If a single int is provided, it is used for all arguments.
out_axes (int or list) – Axes to map over for each output. If a single int is provided, it is used for all outputs.
chunks (int, optional) – Number of chunks to split the input data into. If None, no chunking is performed. Mutually exclusive with batch_size.
batch_size (int, optional) – Size of batches to process at once. If None, no batching is performed. Mutually exclusive with chunks.

get_dict(compact=True)[source]¶: Get the configuration of the pipeline.

class zea.ops.PfieldWeighting(*args, **kwargs)[source]¶

Bases: Operation

Weighting aligned data with the pressure field.

Parameters:

input_data_type (DataTypes or None) – Expected data type of the input tensor. Used for pipeline data-type validation; pass None to skip.
output_data_type (DataTypes or None) – Data type produced by this operation.
key (str or None) – Dict key the operation reads from (and writes to by default). Defaults to "data".
output_key (str or None) – Dict key the operation writes its result to. Defaults to key. Set to a different value to preserve the original input under key while producing a new key for downstream operations.
cache_inputs (bool) – When True, values stored via set_input_cache() are merged into every call. False means the cache is empty by default. Selective per-key caching is not supported; use set_input_cache() directly to control which keys are stored.
cache_outputs (bool) – Memoize outputs keyed by a hash of the merged inputs.
jit_compile (bool) – Wrap call() with jit() for faster execution. Disable for easier interactive debugging.
with_batch_dim (bool) – Whether inputs carry a leading batch dimension. Affects default axis selection in filter-type operations.
jit_kwargs (dict or None) – Extra keyword arguments forwarded to the JIT compiler.
jittable (bool) – Mark the operation as JIT-compilable. Set to False for operations that use Python control flow incompatible with tracing.
additional_output_keys (list of str or None) – Extra dict keys this operation may produce beyond output_key. Used for pipeline key-availability validation. Defaults to the class-level ADD_OUTPUT_KEYS list.

call(flat_pfield=None, **kwargs)[source]¶

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.Refocus(*args, **kwargs)[source]¶

Bases: Operation

REFoCUS (Retrospective Encoding For Conventional Ultrasound Sequences).

Decodes any transmit data into synthetic aperture (multistatic / full-matrix capture) data by inverting the transmit encoding model in the frequency domain.

The transmit encoding is modelled as a matrix \(H\) whose entry \(H_{t,e}\) describes the complex phase shift applied to element \(e\) during transmit event \(t\):

\[H_{t,e}(f) = a_{t,e} \exp(-j 2\pi f \tau_{t,e})\]

where \(\tau_{t,e}\) is the transmit delay in samples and \(a_{t,e}\) is the apodization.

At each temporal frequency the received RF spectrum is decoded by multiplying with the pseudo-inverse \(H^{-1}\):

\[\hat{U}(f) = H^{-1}(f) \, S(f)\]

producing a synthetic aperture dataset where each decoded channel corresponds to a virtual single-element transmission.

The input data has shape (n_tx, n_ax, n_el, n_ch) and the output has shape (n_el, n_ax, n_el, n_ch), where the new first axis indexes the decoded virtual transmit elements.

References

Bottenus, N. (2018). “Recovery of the complete data set from focused transmit beams.” IEEE Transactions on Ultrasonics, Ferroelectrics, and Frequency Control, 65(1), 30–38.

Ali, R., Dahl, J., & Bottenus, N. (2019). “Extending Retrospective Encoding for Robust Recovery of the Multistatic Dataset.” IEEE Transactions on Ultrasonics, Ferroelectrics, and Frequency Control, 67(5), 943–956.

https://github.com/nbottenus/REFoCUS

Parameters:

method (str) –
Inversion method. One of:
- 'adjoint': Adjoint (matched-filter) pseudo-inverse with an optional ramp filter in frequency. Default.
- 'tikhonov': Tikhonov-regularized inverse.
- 'rsvd': Regularized SVD-based inverse.
- 'tsvd': Truncated SVD-based inverse.
param (float or None) –
Regularization / filter parameter.
- 'adjoint': None applies a ramp filter (multiply by \(f\)). Set to 0 to disable the ramp filter. Defaults to None.
- 'tikhonov', 'rsvd', 'tsvd': Relative regularization strength. Defaults to 1e-2 when None.
**kwargs – Additional arguments forwarded to Operation.
input_data_type (DataTypes or None) – Expected data type of the input tensor. Used for pipeline data-type validation; pass None to skip.
output_data_type (DataTypes or None) – Data type produced by this operation.
key (str or None) – Dict key the operation reads from (and writes to by default). Defaults to "data".
output_key (str or None) – Dict key the operation writes its result to. Defaults to key. Set to a different value to preserve the original input under key while producing a new key for downstream operations.
cache_inputs (bool) – When True, values stored via set_input_cache() are merged into every call. False means the cache is empty by default. Selective per-key caching is not supported; use set_input_cache() directly to control which keys are stored.
cache_outputs (bool) – Memoize outputs keyed by a hash of the merged inputs.
jit_compile (bool) – Wrap call() with jit() for faster execution. Disable for easier interactive debugging.
with_batch_dim (bool) – Whether inputs carry a leading batch dimension. Affects default axis selection in filter-type operations.
jit_kwargs (dict or None) – Extra keyword arguments forwarded to the JIT compiler.
jittable (bool) – Mark the operation as JIT-compilable. Set to False for operations that use Python control flow incompatible with tracing.
additional_output_keys (list of str or None) – Extra dict keys this operation may produce beyond output_key. Used for pipeline key-availability validation. Defaults to the class-level ADD_OUTPUT_KEYS list.

call(t0_delays, sampling_frequency, probe_geometry, initial_times, tx_apodizations=None, **kwargs)[source]¶

Decode plane-wave / focused transmit data into multistatic data.

After decoding the output is a synthetic-aperture (SA) dataset where each virtual transmit corresponds to a single element firing. The pipeline parameters that describe the transmit sequence are updated accordingly so that downstream operations (TOF correction, pfield weighting, etc.) remain consistent with the new data shape.

Parameters:

t0_delays – (n_tx, n_el) transmit delays in seconds.
sampling_frequency – Sampling frequency in Hz.
probe_geometry – (n_el, 3) element positions in metres.
tx_apodizations – (n_tx, n_el) transmit apodization weights. Defaults to all-ones (uniform apodization).
**kwargs – Must contain the input data tensor under self.key.

Returns:

self.output_key — decoded data (n_el, n_ax, n_el, n_ch) (or batched variant).
"t0_delays" — zeros (n_el, n_el) (SA: no extra delay).
"tx_apodizations" — identity (n_el, n_el) (one element per virtual transmit).
"polar_angles" — zeros (n_el,) (no steering).
"focus_distances" — zeros (n_el,) (no focus).
"transmit_origins" — element positions (n_el, 3).
"initial_times" — zeros (n_el,).
"t_peak" — shared transmit-waveform peak time (n_el,).
"flat_pfield" — None (resets pfield so downstream PfieldWeighting becomes a no-op).

Return type:

dict with keys

class zea.ops.ReshapeGrid(*args, **kwargs)[source]¶

Bases: Operation

Reshape flat grid data to grid shape.

Parameters:

input_data_type (DataTypes or None) – Expected data type of the input tensor. Used for pipeline data-type validation; pass None to skip.
output_data_type (DataTypes or None) – Data type produced by this operation.
key (str or None) – Dict key the operation reads from (and writes to by default). Defaults to "data".
output_key (str or None) – Dict key the operation writes its result to. Defaults to key. Set to a different value to preserve the original input under key while producing a new key for downstream operations.
cache_inputs (bool) – When True, values stored via set_input_cache() are merged into every call. False means the cache is empty by default. Selective per-key caching is not supported; use set_input_cache() directly to control which keys are stored.
cache_outputs (bool) – Memoize outputs keyed by a hash of the merged inputs.
jit_compile (bool) – Wrap call() with jit() for faster execution. Disable for easier interactive debugging.
with_batch_dim (bool) – Whether inputs carry a leading batch dimension. Affects default axis selection in filter-type operations.
jit_kwargs (dict or None) – Extra keyword arguments forwarded to the JIT compiler.
jittable (bool) – Mark the operation as JIT-compilable. Set to False for operations that use Python control flow incompatible with tracing.
additional_output_keys (list of str or None) – Extra dict keys this operation may produce beyond output_key. Used for pipeline key-availability validation. Defaults to the class-level ADD_OUTPUT_KEYS list.

call(grid, **kwargs)[source]¶

Parameters:

data (-) – The flat grid data of shape (…, n_pix, …).

Returns:

The reshaped data of shape (…, grid.shape, …).

Return type:

reshaped_data (Tensor)

class zea.ops.ScanConvert(*args, **kwargs)[source]¶

Bases: Operation

Scan convert images to cartesian coordinates.

Initialize the ScanConvert operation.

Parameters:: order (int, optional) – Interpolation order. Defaults to 1. Currently only GPU support for order=1.

ADD_OUTPUT_KEYS: List[str] = ['resolution', 'x_lim', 'y_lim', 'z_lim', 'rho_range', 'theta_range', 'phi_range', 'd_rho', 'd_theta', 'd_phi']¶

STATIC_PARAMS = ['fill_value']¶

call(rho_range=None, theta_range=None, phi_range=None, resolution=None, coordinates=None, fill_value=None, **kwargs)[source]¶

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)[source]¶

Bases: Operation

Simulate RF data.

Parameters:

input_data_type (DataTypes or None) – Expected data type of the input tensor. Used for pipeline data-type validation; pass None to skip.
output_data_type (DataTypes or None) – Data type produced by this operation.
key (str or None) – Dict key the operation reads from (and writes to by default). Defaults to "data".
output_key (str or None) – Dict key the operation writes its result to. Defaults to key. Set to a different value to preserve the original input under key while producing a new key for downstream operations.
cache_inputs (bool) – When True, values stored via set_input_cache() are merged into every call. False means the cache is empty by default. Selective per-key caching is not supported; use set_input_cache() directly to control which keys are stored.
cache_outputs (bool) – Memoize outputs keyed by a hash of the merged inputs.
jit_compile (bool) – Wrap call() with jit() for faster execution. Disable for easier interactive debugging.
with_batch_dim (bool) – Whether inputs carry a leading batch dimension. Affects default axis selection in filter-type operations.
jit_kwargs (dict or None) – Extra keyword arguments forwarded to the JIT compiler.
jittable (bool) – Mark the operation as JIT-compilable. Set to False for operations that use Python control flow incompatible with tracing.
additional_output_keys (list of str or None) – Extra dict keys this operation may produce beyond output_key. Used for pipeline key-availability validation. Defaults to the class-level ADD_OUTPUT_KEYS list.

ADD_OUTPUT_KEYS: List[str] = ['n_ch']¶

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)[source]¶: Abstract method that defines the processing logic for the operation. Subclasses must implement this method.

class zea.ops.TOFCorrection(*args, **kwargs)[source]¶

Bases: Operation

Time-of-flight correction operation for ultrasound data.

Parameters:

input_data_type (DataTypes or None) – Expected data type of the input tensor. Used for pipeline data-type validation; pass None to skip.
output_data_type (DataTypes or None) – Data type produced by this operation.
key (str or None) – Dict key the operation reads from (and writes to by default). Defaults to "data".
output_key (str or None) – Dict key the operation writes its result to. Defaults to key. Set to a different value to preserve the original input under key while producing a new key for downstream operations.
cache_inputs (bool) – When True, values stored via set_input_cache() are merged into every call. False means the cache is empty by default. Selective per-key caching is not supported; use set_input_cache() directly to control which keys are stored.
cache_outputs (bool) – Memoize outputs keyed by a hash of the merged inputs.
jit_compile (bool) – Wrap call() with jit() for faster execution. Disable for easier interactive debugging.
with_batch_dim (bool) – Whether inputs carry a leading batch dimension. Affects default axis selection in filter-type operations.
jit_kwargs (dict or None) – Extra keyword arguments forwarded to the JIT compiler.
jittable (bool) – Mark the operation as JIT-compilable. Set to False for operations that use Python control flow incompatible with tracing.
additional_output_keys (list of str or None) – Extra dict keys this operation may produce beyond output_key. Used for pipeline key-availability validation. Defaults to the class-level ADD_OUTPUT_KEYS list.

STATIC_PARAMS = ['f_number', 'apply_lens_correction']¶

call(flatgrid, sound_speed, polar_angles, focus_distances, sampling_frequency, f_number, demodulation_frequency, t0_delays, tx_apodizations, initial_times, probe_geometry, t_peak, transmit_origins, apply_lens_correction=None, lens_thickness=None, lens_sound_speed=None, sos_map=None, sos_grid_x=None, sos_grid_z=None, **kwargs)[source]¶

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
t_peak (float) – Time to peak of the transmit pulse of shape (n_tx,)
transmit_origins (ops.Tensor) – Transmit origins of shape (n_tx, 3)
apply_lens_correction (bool) – Whether to apply lens correction
lens_thickness (float) – Lens thickness
lens_sound_speed (float) – Sound speed in the lens
sos_map (Tensor) – Speed-of-sound map of shape (Nz, Nx) in m/s.
sos_grid_x (Tensor) – x-coordinates of sos_map rows.
sos_grid_z (Tensor) – z-coordinates of sos_map columns.

Returns:

Dictionary containing tof_corrected_data

Return type:

dict

class zea.ops.Threshold(*args, **kwargs)[source]¶

Bases: Operation

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

Parameters:

input_data_type (DataTypes or None) – Expected data type of the input tensor. Used for pipeline data-type validation; pass None to skip.
output_data_type (DataTypes or None) – Data type produced by this operation.
key (str or None) – Dict key the operation reads from (and writes to by default). Defaults to "data".
output_key (str or None) – Dict key the operation writes its result to. Defaults to key. Set to a different value to preserve the original input under key while producing a new key for downstream operations.
cache_inputs (bool) – When True, values stored via set_input_cache() are merged into every call. False means the cache is empty by default. Selective per-key caching is not supported; use set_input_cache() directly to control which keys are stored.
cache_outputs (bool) – Memoize outputs keyed by a hash of the merged inputs.
jit_compile (bool) – Wrap call() with jit() for faster execution. Disable for easier interactive debugging.
with_batch_dim (bool) – Whether inputs carry a leading batch dimension. Affects default axis selection in filter-type operations.
jit_kwargs (dict or None) – Extra keyword arguments forwarded to the JIT compiler.
jittable (bool) – Mark the operation as JIT-compilable. Set to False for operations that use Python control flow incompatible with tracing.
additional_output_keys (list of str or None) – Extra dict keys this operation may produce beyond output_key. Used for pipeline key-availability validation. Defaults to the class-level ADD_OUTPUT_KEYS list.

call(threshold=None, percentile=None, **kwargs)[source]¶

Threshold the input data.

Parameters:

threshold – Numeric threshold.
percentile – Percentile to derive threshold from.

Returns:

Tensor with thresholding applied.

class zea.ops.TissueSuppression(cutoff=5, **kwargs)[source]¶

Bases: Operation

Tissue suppression using SVD-based clutter filtering.

Removes stationary tissue components from multi-frame ultrasound data by zeroing the dominant singular values of the Casorati matrix.

Parameters:

input_data_type (DataTypes or None) – Expected data type of the input tensor. Used for pipeline data-type validation; pass None to skip.
output_data_type (DataTypes or None) – Data type produced by this operation.
key (str or None) – Dict key the operation reads from (and writes to by default). Defaults to "data".
output_key (str or None) – Dict key the operation writes its result to. Defaults to key. Set to a different value to preserve the original input under key while producing a new key for downstream operations.
cache_inputs (bool) – When True, values stored via set_input_cache() are merged into every call. False means the cache is empty by default. Selective per-key caching is not supported; use set_input_cache() directly to control which keys are stored.
cache_outputs (bool) – Memoize outputs keyed by a hash of the merged inputs.
jit_compile (bool) – Wrap call() with jit() for faster execution. Disable for easier interactive debugging.
with_batch_dim (bool) – Whether inputs carry a leading batch dimension. Affects default axis selection in filter-type operations.
jit_kwargs (dict or None) – Extra keyword arguments forwarded to the JIT compiler.
jittable (bool) – Mark the operation as JIT-compilable. Set to False for operations that use Python control flow incompatible with tracing.
additional_output_keys (list of str or None) – Extra dict keys this operation may produce beyond output_key. Used for pipeline key-availability validation. Defaults to the class-level ADD_OUTPUT_KEYS list.

call(**kwargs)[source]¶: Abstract method that defines the processing logic for the operation. Subclasses must implement this method.

suppress_tissue(data)[source]¶

Suppresses tissue using Direct SVD.

Parameters:: data (ops.Tensor) – Shape (n_frames, …)

class zea.ops.UpMix(*args, **kwargs)[source]¶

Bases: Operation

Upmix IQ data to RF data.

Parameters:

input_data_type (DataTypes or None) – Expected data type of the input tensor. Used for pipeline data-type validation; pass None to skip.
output_data_type (DataTypes or None) – Data type produced by this operation.
key (str or None) – Dict key the operation reads from (and writes to by default). Defaults to "data".
output_key (str or None) – Dict key the operation writes its result to. Defaults to key. Set to a different value to preserve the original input under key while producing a new key for downstream operations.
cache_inputs (bool) – When True, values stored via set_input_cache() are merged into every call. False means the cache is empty by default. Selective per-key caching is not supported; use set_input_cache() directly to control which keys are stored.
cache_outputs (bool) – Memoize outputs keyed by a hash of the merged inputs.
jit_compile (bool) – Wrap call() with jit() for faster execution. Disable for easier interactive debugging.
with_batch_dim (bool) – Whether inputs carry a leading batch dimension. Affects default axis selection in filter-type operations.
jit_kwargs (dict or None) – Extra keyword arguments forwarded to the JIT compiler.
jittable (bool) – Mark the operation as JIT-compilable. Set to False for operations that use Python control flow incompatible with tracing.
additional_output_keys (list of str or None) – Extra dict keys this operation may produce beyond output_key. Used for pipeline key-availability validation. Defaults to the class-level ADD_OUTPUT_KEYS list.

call(sampling_frequency=None, demodulation_frequency=None, **kwargs)[source]¶: Abstract method that defines the processing logic for the operation. Subclasses must implement this method.

zea.ops.get_ops(ops_name)[source]¶

Retrieve an Operation subclass from the registry by name.

Two lookup forms are supported:

Registry name (plain string): A key previously registered with @ops_registry("name"), e.g. "demodulate". The lookup is case-insensitive.
Module path (dotted string containing a "."): A fully-qualified import path such as "my_package.my_module.MyOp". The module is imported automatically, then the class is located in the registry by object identity — so the registry key does not need to match the class name.

Parameters:

ops_name (str) – Registry name or dotted module path of the operation.

Returns:

The Operation subclass registered under ops_name.

Return type:

Type[Operation]

Raises:

ValueError – If ops_name is a dotted module path but the class cannot be found in the registry after importing the module.
KeyError – If ops_name is a plain name that is not registered.

Examples

# By registry name
cls = get_ops("demodulate")

# By module path — the class may be registered under any key
cls = get_ops("my_project.processing.MyCustomOp")
pipeline = Pipeline(operations=[cls(factor=2.0)])

Modules

keras_ops

Auto-generated zea.Operation for all unary keras.ops and keras.ops.image functions.