Metadata-Version: 2.5
Name: zea
Version: 0.1.9
Summary: A Toolbox for Cognitive Ultrasound Imaging. Provides a set of tools for processing of ultrasound data, all built in your favorite machine learning framework.
Project-URL: Homepage, https://github.com/tue-bmd/zea/
Project-URL: Repository, https://github.com/tue-bmd/zea/
Project-URL: Documentation, https://zea.readthedocs.io
Project-URL: Issues, https://github.com/tue-bmd/zea/issues
Project-URL: Contributing, https://zea.readthedocs.io/en/latest/contributing.html
Author-email: Tristan Stevens <t.s.w.stevens@tue.nl>, Wessel van Nierop <w.l.v.nierop@tue.nl>, Ben Luijten <w.m.b.luijten@tue.nl>, Vincent van de Schaft <v.v.d.schaft@tue.nl>, Oisín Nolan <o.i.nolan@tue.nl>, Beatrice Federici <b.federici@tue.nl>, Louis van Harten <l.d.v.harten@tue.nl>, Simon Penninga <s.w.penninga@tue.nl>, Noortje Schueler <n.i.p.schueler@tue.nl>, Ruud van Sloun <r.j.g.v.sloun@tue.nl>
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: beamforming,machine learning,ultrasound
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.11
Requires-Dist: decorator>=5
Requires-Dist: fsspec[http]
Requires-Dist: grain>=0.2.8
Requires-Dist: h5py>=3.11
Requires-Dist: hdf5plugin>=4.4
Requires-Dist: huggingface-hub>=2.0
Requires-Dist: imageio[ffmpeg]>=2.0
Requires-Dist: keras>=3.15.0
Requires-Dist: matplotlib>=3.10
Requires-Dist: numcodecs>=0.13
Requires-Dist: numpy>=1.24
Requires-Dist: pillow>=12.2.0
Requires-Dist: pyyaml>=6
Requires-Dist: scikit-image>=0.23
Requires-Dist: scikit-learn>=1.4
Requires-Dist: scipy>=1.13
Requires-Dist: tqdm>=4
Requires-Dist: tyro>=1.0
Requires-Dist: wget>=3.2
Provides-Extra: app
Requires-Dist: gradio>=6.0; extra == 'app'
Provides-Extra: backends
Requires-Dist: jax>=0.4.35; extra == 'backends'
Requires-Dist: tensorflow>=2.16.1; extra == 'backends'
Requires-Dist: torch>=2.2; extra == 'backends'
Provides-Extra: display
Requires-Dist: opencv-python>=4; extra == 'display'
Provides-Extra: display-headless
Requires-Dist: opencv-python-headless>=4; extra == 'display-headless'
Provides-Extra: jax
Requires-Dist: jax>=0.4.35; (sys_platform != 'linux') and extra == 'jax'
Requires-Dist: jax[cuda12]>=0.4.35; (sys_platform == 'linux') and extra == 'jax'
Provides-Extra: models
Requires-Dist: onnxruntime>=1.15; extra == 'models'
Description-Content-Type: text/markdown

<p align="center">
  <a href="https://zea.readthedocs.io/en/stable/getting-started.html"><img src="https://raw.githubusercontent.com/tue-bmd/zea/main/docs/_static/zea-logo.png" width="140" alt="zea logo"></a>
</p>

<h1 align="center">zea</h1>
<p align="center"><em>A Toolbox for Cognitive Ultrasound Imaging</em></p>

<p align="center">
  <a href="https://pypi.org/project/zea/"><img src="https://img.shields.io/pypi/v/zea?logo=pypi&logoColor=white&labelColor=56395B&color=FBB53E" alt="PyPI version"></a>
  <a href="https://pypi.org/project/zea/"><img src="https://img.shields.io/pypi/pyversions/zea?logo=python&logoColor=white&labelColor=56395B&color=FBB53E" alt="Python versions"></a>
  <a href="https://github.com/tue-bmd/zea/actions/workflows/tests.yaml"><img src="https://img.shields.io/github/actions/workflow/status/tue-bmd/zea/tests.yaml?branch=main&label=tests&logo=githubactions&logoColor=white&labelColor=56395B" alt="Tests"></a>
  <a href="https://zea.readthedocs.io/en/stable/?badge=stable"><img src="https://img.shields.io/readthedocs/zea?logo=readthedocs&logoColor=white&labelColor=56395B" alt="Documentation Status"></a>
  <a href="https://codecov.io/gh/tue-bmd/zea"><img src="https://codecov.io/gh/tue-bmd/zea/branch/main/graph/badge.svg" alt="Coverage"></a>
  <a href="https://github.com/tue-bmd/zea/blob/main/LICENSE"><img src="https://img.shields.io/github/license/tue-bmd/zea?labelColor=56395B&color=FBB53E" alt="License"></a>
  <a href="https://joss.theoj.org/papers/fa923917ca41761fe0623ca6c350017d"><img src="https://img.shields.io/badge/JOSS-10.21105%2Fjoss.09881-FBB53E?labelColor=56395B" alt="JOSS"></a>
  <a href="https://arxiv.org/abs/2512.01433"><img src="https://img.shields.io/badge/arXiv-2512.01433-B31B1B?logo=arxiv&logoColor=white&labelColor=56395B" alt="arXiv"></a>
  <a href="https://huggingface.co/zeahub"><img src="https://img.shields.io/badge/Hugging%20Face-zeahub-FBB53E?logo=huggingface&logoColor=white&labelColor=56395B" alt="Hugging Face"></a>
  <a href="https://github.com/tue-bmd/zea/stargazers"><img src="https://img.shields.io/github/stars/tue-bmd/zea?style=social" alt="GitHub stars"></a>
</p>

<p align="center">
  <a href="https://zea.readthedocs.io"><b>Documentation</b></a> ·
  <a href="https://zea.readthedocs.io/en/stable/getting-started.html"><b>Getting Started</b></a> ·
  <a href="https://zea.readthedocs.io/en/stable/examples.html"><b>Examples</b></a> ·
  <a href="https://zea.readthedocs.io/en/stable/models.html"><b>Models</b></a> ·
  <a href="https://huggingface.co/zeahub"><b>Datasets</b></a>
</p>

`zea` is a Python library for ultrasound signal processing, image reconstruction, and deep learning. It is built on [Keras 3](https://keras.io/keras_3/), so everything runs on [JAX](https://github.com/google/jax), [PyTorch](https://github.com/pytorch/pytorch), or [TensorFlow](https://github.com/tensorflow/tensorflow).

<!-- Showcase animation: rendered and hosted in https://gist.github.com/tristan-deep/6d0bb210f95fc530ca63fd8721402c30 -->
<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://gist.githubusercontent.com/tristan-deep/6d0bb210f95fc530ca63fd8721402c30/raw/zea_showcase_dark.webp">
    <img src="https://gist.githubusercontent.com/tristan-deep/6d0bb210f95fc530ca63fd8721402c30/raw/zea_showcase_light.webp" width="100%" alt="Animated tour of the zea modules: Pipeline, models, Parameters and Probe, and File, Dataset and Dataloader">
  </picture>
</p>

## Installation

```shell
pip install zea
```

Additionally, `zea` needs one of the Keras backends installed: [JAX](https://jax.readthedocs.io/en/latest/installation.html) (recommended), [PyTorch](https://pytorch.org/get-started/locally/), or [TensorFlow](https://www.tensorflow.org/install). See the [installation guide](https://zea.readthedocs.io/en/stable/installation.html) for details regarding more advanced installation options, such as GPU support.

## Quick start

`zea` offers many models and tooling for advanced ultrasound processing. But in the most basic sense it offers a fast and flexible ultrasound processing pipeline implemented in a deep learning framework for easy integration with state-of-the-art models. The following example streams an in-vivo recording from [Hugging Face](https://huggingface.co/zeahub), beamforms it, and saves the B-mode image:

```python
import zea

zea.init_device()

config = zea.Config.from_path("hf://zeahub/picmus/config_iq.yaml")
path = (
    "hf://zeahub/picmus/in_vivo/carotid_cross/"
    "carotid_cross_expe_dataset_iq/carotid_cross_expe_dataset_iq.hdf5"
)

with zea.File(path) as file:
    data = file.data.raw_data[0]
    parameters = file.load_parameters()

parameters.update(**config.parameters)

pipeline = zea.Pipeline.from_config(config, with_batch_dim=False)
inputs = pipeline.prepare_parameters(parameters)
image = pipeline(data=data, **inputs, return_numpy=True)["data"]

image = zea.display.to_8bit(image)
image.save("bmode.png")
```

The [Getting Started](https://zea.readthedocs.io/en/stable/getting-started.html) guide walks through this example step by step, and the [Examples](https://zea.readthedocs.io/en/stable/examples.html) page has many more notebooks you can open in Colab.

## Core modules

<table>
  <tr>
    <td nowrap>🔧&nbsp;<b><a href="https://zea.readthedocs.io/en/stable/pipeline.html">Pipeline</a></b></td>
    <td>Flexible, differentiable signal processing and image reconstruction, written in your favorite deep learning framework.</td>
  </tr>
  <tr>
    <td nowrap>💾&nbsp;<b><a href="https://zea.readthedocs.io/en/stable/data-acquisition.html">Data</a></b></td>
    <td>Loading tools for ultrasound data and acquisition parameters, designed for deep learning workflows. Datasets on Hugging Face are streamed, so only the frames you read are fetched.</td>
  </tr>
  <tr>
    <td nowrap>🧠&nbsp;<b><a href="https://zea.readthedocs.io/en/stable/models.html">Models</a></b></td>
    <td>Pretrained models for ultrasound image and signal processing, hosted on <a href="https://huggingface.co/zeahub">Hugging Face</a>.</td>
  </tr>
  <tr>
    <td nowrap>🎯&nbsp;<b><a href="https://zea.readthedocs.io/en/stable/agent.html">Agent</a></b></td>
    <td>Action selection for cognitive ultrasound, with flexible transmit and acquisition design: an action decides what to acquire next, such as which scan lines to fire.</td>
  </tr>
</table>

Read the [About](https://zea.readthedocs.io/en/stable/about.html) page for the motivation behind `zea` and the [research](https://zea.readthedocs.io/en/stable/about.html#papers) it supports.

## Contributing

Questions and suggestions are welcome as an [issue on GitHub](https://github.com/tue-bmd/zea/issues). If you want to contribute, see the [Contributing](https://zea.readthedocs.io/en/latest/contributing.html) guide.

## Citation

If `zea` helps your research, please cite our [JOSS paper](https://doi.org/10.21105/joss.09881). More citation info is in the [docs](https://zea.readthedocs.io/en/stable/getting-started.html#citation).

<details>
<summary>BibTeX</summary>

```bibtex
@article{stevens2026zea,
    author       = {Stevens, Tristan S.W. and van Nierop, Wessel L. and Luijten, Ben and van de Schaft, Vincent and Nolan, Oisín and Federici, Beatrice and van Harten, Louis D. and Penninga, Simon W. and Schueler, Noortje I.P. and van Sloun, Ruud J.G.},
    title        = {{zea}: A Toolbox for Cognitive Ultrasound Imaging},
    year         = 2026,
    journal      = {Journal of Open Source Software},
    publisher    = {The Open Journal},
    volume       = 11,
    number       = 121,
    pages        = 9881,
    doi          = {10.21105/joss.09881},
}
```

</details>
