Metadata-Version: 2.5
Name: ustb
Version: 0.2.0
Summary: Python reimplementation of the UltraSound ToolBox (USTB) for beamforming, processing, and visualization of ultrasonic signals.
Project-URL: Homepage, https://www.ustb.no
Project-URL: Repository, https://github.com/unioslo/USTB
Project-URL: Documentation, https://olemarius90.github.io/USTB/documentation.html
Author: USTB Contributors
Author-email: Ole Marius Hoel Rindal <omrindal@ifi.uio.no>
License: MIT
Keywords: beamforming,medical-imaging,signal-processing,ultrasound
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
Requires-Python: >=3.10
Requires-Dist: matplotlib
Requires-Dist: numba>=0.59
Requires-Dist: numpy
Requires-Dist: pyuff-ustb>=3.0.0
Requires-Dist: scipy
Provides-Extra: dev
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: ruff==0.17.2; extra == 'dev'
Description-Content-Type: text/markdown

# USTB for Python

Python reimplementation of the [UltraSound ToolBox (USTB)](https://www.ustb.no) — an open-source toolbox for beamforming, processing, and visualization of ultrasonic signals.

## Installation

```bash
pip install ustb
```

For development:

```bash
pip install -e ".[dev]"
```

Code is linted and formatted with [ruff](https://docs.astral.sh/ruff/), which CI checks:

```bash
ruff check --fix src examples tests
ruff format src examples tests
```

## Quick Start

```python
from pyuff_ustb.objects.uff import Uff
from ustb.midprocess import DAS
from ustb.enums import Dimension, Window

# Read channel data from UFF file
channel_data = Uff("data.uff").read("channel_data")

# Set up beamformer (same API as MATLAB)
mid = DAS()
mid.channel_data = channel_data
mid.scan = scan
mid.dimension = Dimension.both
mid.transmit_apodization.window = Window.scanline
mid.receive_apodization.window = Window.none

# Beamform
b_data = mid.go()

# Plot scan-converted B-mode image
b_data.plot(title="My Image")
```

## Features

- **`midprocess.DAS`** — Generalized Delay-And-Sum beamformer, compiled with numba and run in parallel over pixels
- **`preprocess`** — `FastDemodulation` and `Demodulation` (RF to IQ), `SVDFilter` (spatiotemporal clutter filter)
- **`postprocess`**:
  - compounding: `CoherentCompounding`, `IncoherentCompounding`
  - adaptive beamforming: `CoherenceFactor`, `GeneralizedCoherenceFactor`, `PhaseCoherenceFactor`, `CaponMinimumVariance`, `DelayMultiplyAndSum`, `ShortLagSpatialCoherence`
  - flow: `SVDFilter`, `AutocorrelationDisplacementEstimation`, `ModifiedAutocorrelationDisplacementEstimation`
  - image processing: `Median`
- **`Apodization`** — every window; receive, transmit (plane and diverging waves) and scanline (MLA) apodization
- **`Pipeline`** — chain preprocess/midprocess/postprocess steps in one call
- **`tools`** — `download`, `zenodo_dataset_files_base`, `scan_convert`, `power_spectrum`, `estimate_frequency`, `uniform_fov_weighting`
- **`BeamformedData.get_image()` / `.save_as_gif()`** — image extraction and animated B-mode export
- **Scan-converted display** — sector and linear scan visualization, plus raw channel-data preview via `plotting.plot_channel_data`
- **UFF I/O** — reads/writes USTB UFF files via [pyuff-ustb](https://github.com/magnusdk/pyuff_ustb)

Documentation: [USTB for Python](https://unioslo.github.io/USTB/api/python/index.html), including a [MATLAB to Python](https://unioslo.github.io/USTB/api/python/matlab_to_python.html) guide (class mapping and known differences).

## Examples

See the `examples/` directory:

- `minimal_example.py` — cardiac phased array imaging
- `maximal_example.py` — full pipeline (demod → DAS → CF → median)
- `cpwc_linear.py` — plane wave compound imaging
- `picmus_*.py` — PICMUS challenge datasets

## Relationship to MATLAB USTB

This package mirrors the MATLAB USTB API as closely as possible. The main classes (`DAS`, `Dimension`, `Window`, `Apodization`) use the same names, properties, and method signatures. The integration tests compare against MATLAB pixel by pixel: the beamformed output of every example (CPWC linear, phased array, and the four PICMUS datasets) matches MATLAB to about 1e-4 relative error, and the receive, transmit and scanline apodization match `uff.apodization` to float precision.
