Skip to content
ModularUSPublic

About

dasIT is a delay-and-sum beamformer for plane-wave ultrasound. πŸ”ŠπŸŽžοΈ

Topics

Resources

Stars

11 stars

Watchers

1 watching

Forks

Latest commit

Β 

History

117 Commits

Folders and files

Repository files navigation

Open In Colab License

dasIT

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.

License

This program is free software and licensed under the Apache License v2.0 - see the LICENSE file for details.

Beamforming from explicit inputs

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 weights

engine='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.

A recording described by one dictionary

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 again

Only element_x, fs, c and transmits are required. A missing or wrong key is refused with its name.

Install and test

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.

About

dasIT is a delay-and-sum beamformer for plane-wave ultrasound. πŸ”ŠπŸŽžοΈ

Topics

Resources

Stars

11 stars

Watchers

1 watching

Forks

Releases

Packages

Used by

Contributors

Languages