dasIT is a delay-and-sum beamformer for planewave ultrasound implemented in Python. dasIT allows direct interaction with its functions and the exploration of processing techniques and data inside a sandbox environment in Google Colab.
This program is free software and licensed under the Apache License v2.0 - see the LICENSE file for details.
dasIT.beamform.Beamformer is a delay-and-sum core that takes everything it needs as arguments in SI units. The tutorial notebook beamform_image.ipynb is built on it and on dasIT.geometry, dasIT.signal and dasIT.plot.
from dasIT.geometry import linear_array, plane_wave
from dasIT.beamform import Beamformer
bf = Beamformer(element_x=linear_array(192, 0.23e-3), grid_x=x, grid_z=z, fs=20.8332e6, c=1540,
tx=plane_wave(angle_deg=0), t0=0.0, f_number=1.5, window='hann', interp='linear', engine='matrix')
image = bf(rf) # rf: [samples, channels] or [samples, channels, frames], real or analytic
bf.delays(element=96) # arrival sample of every pixel on one element, bf.weights(element=96) its weightsengine='matrix' keeps the whole beamformer as one sparse matrix (fast, many frames in one product), engine='loop' adds element after element (a few megabytes). Both give the same image. Measured with python tests/benchmark.py (Hann window, linear interpolation, double precision, one frame):
| case | matrix: build | matrix: apply | matrix size | loop: apply | loop: peak memory |
|---|---|---|---|---|---|
| 192 elements, 708 x 192 pixels | 1.0 s | 0.05 s | 117 MB | 0.8 s | 7 MB |
| 128 elements, 780 x 128 pixels | 0.8 s | 0.04 s | 75 MB | 0.4 s | 6 MB |
| 128 elements, 780 x 509 pixels | 3.2 s | 0.13 s | 301 MB | 2.3 s | 23 MB |
Three ways to use it:
# 1. one plane wave: rf [samples, channels]
image = Beamformer(x, grid_x, grid_z, fs, c, tx=plane_wave(0))(rf)
# 2. several steered plane waves, compounded coherently: rf [samples, channels, shots]
from dasIT.geometry import plane_waves
image = Beamformer(x, grid_x, grid_z, fs, c, tx=plane_waves([-12, 0, 12], x))(rf)
# 3. lines the scanner already beamformed: no Beamformer, only envelope, log compression and the axes
from dasIT.geometry import depth_axis, line_positions
from dasIT.signal import analytic, envelope, log_compress
from dasIT.plot import show_image
show_image(log_compress(envelope(analytic(lines)), 50), line_positions(x, lines.shape[1]), depth_axis(lines.shape[0], fs, c))Channel data that were recorded one receive element per shot with the same plane wave (as the Ultrasonix planewave_channels sequence does) are case 1: the shots together form one [samples, channels] record.
The beamformer has to be told what the data are. dasIT.description puts all of it into one plain dictionary that an acquisition system writes beside its data (JSON, YAML, attributes of an h5 file):
from dasIT import description as dd
description = {
"element_x": x.tolist(), "fs": 20e6, "c": 1540.0, # geometry and sampling
"transmits": [{"angle_deg": 0.0, "x0": x[0]}], # one plane wave per shot, x0: where its clock starts
"t0": 0.0, "band_hz": [3e6, 7e6], # time of sample 0, band-pass before beamforming
"f_number": 1.5, "window": "box", "interp": "linear",
"first_frame": 1, # frames before it are not to be used
"skip_samples": 0, # start of the channels to blank, one number or one per channel
}
rf = dd.prepare(rf, description, silent=pickup) # silent reference off, start blanked, band-pass
image = dd.beamformer(description, n_samples=rf.shape[0])(rf)
image = dd.beamformer(description, n_samples=rf.shape[0], f_number=1.0)(rf) # one setting changed, the rest kept
text = dd.dumps(description) # JSON; dd.loads(text) checks it againOnly element_x, fs, c and transmits are required. A missing or wrong key is refused with its name.
pip install git+https://github.com/ModularUS/dasIT # as a package
pip install -e .[test] # from a checkout, for development
pytest
The tests check the beamformer against synthetic point targets with known positions (tests/test_truth.py), several transmits and scanner lines (tests/test_shots.py), the signal steps (tests/test_signal.py), the description (tests/test_description.py), the bundled phantom frame against a stored reference and the nominal values of the phantom (tests/test_example.py), and they execute the code cells of beamform_image.ipynb, which have to arrive at the same frame. They run on every push (.github/workflows/tests.yml).
Tested with Python 3.10, NumPy 1.23, SciPy 1.10 and with Python 3.12, NumPy 2.5, SciPy 1.18.
What changed against dasIT 1.x: CHANGES.md.
