Skip to main content

vbeam: a fast and differentiable beamformer

Project description

vbeam: a Fast and Differentiable Beamformer for Optimizing Ultrasound Imaging

vbeam logo

vbeam is an open-source beamforming library built on top of machine learning frameworks. This enables fast processing, rapid prototyping, and integrating beamforming into machine learning algorithms.

Run An Example In Google Colab (In Your Browser)

Run one of the examples in your browser via Google Colab:

(Make sure to select an A100 (or V100 if not available) GPU to make the examples run fast!)

Installation

python3 -m pip install vbeam

You probably also want to install JAX. See JAX installation instructions for how to do so.

IUS 2023 Q&A and Discussion

Visit the GitHub Discussion page for IUS 2023 if you have any questions!

Overview

vbeam is a pixel-based beamformer. This means that it centers around a function called signal_for_point which returns the delayed, interpolated signal for a single point/pixel. To get a full image, simply repeat signal_for_point for all pixels, all receiving elements, transmitted waves, frames, etc.

We take advantage of JAX's vmap transformation to call signal_for_point in parallel on the GPU. vbeam is a "vmapped beamformer", hence the name.

We refer to the dimensions of our data by name, using a library called spekk. This lets us write beamforming code that looks like this:

beamformer = compose(
    signal_for_point,
    # Make it run in parallel for all points (pixels), sending-, and receiving- elements
    ForAll("points"),
    ForAll("senders"),
    ForAll("receivers"),
    # We sum over all sending-, and receiving- elements
    Apply(jnp.sum, [Axis("senders"), Axis("receivers")]),
    # Iteratively sum the result of each transmit event to reduce memory usage
    Reduce.Sum("transmits"),
    # Postprocessing
    Apply(setup.scan.unflatten),  # Points are flattened by default; reshape them back
    Apply(normalized_decibels),  # Decibels, and the maximum value is normalized to 0 dB
    Apply(scan_convert, setup.scan),  # Scan convert from beam-space to cartesian space
    # Just-in-time compile the function
    Wrap(jax.jit),
    # Build the function to let vbeam know about the dimensions of the input data
).build(setup.spec)

But usually, vbeam's out-of-the-box beamformer will be enough:

beamformer = jax.jit(get_das_beamformer(setup))

The above example refers to 4 dimensions: "points", "senders", "receivers", and "transmits". In this case, "senders" refers to the individual contributing elements used during wave transmission, and is part of our time-domain REFoCUS implementation Open In Colab. vbeam allows you to run any arbitrary dimension in parallel as part of your beamformer: perhaps you want to beamform multiple frames in parallel, or with multiple F#s.

If you want to use a different wavefront model, or a different apodization function, you simply pass in the new object when you call the beamformer:

kwargs = setup.data
kwargs["apodization"] = MyCustomApodization()
result = beamformer(**kwargs)

Every beamforming component in vbeam is differentiable, so you can use vbeam to optimize your beamforming algorithm using gradient descent. You can also integrate machine learning into your beamformer, or integrate beamforming as a step in your machine learning algorithm. Using JAX, it is easy to get the gradient of any of the beamformer arguments:

from vbeam.util.jax import grad_for_argname

# Minimize the pixel-values (just for illustration purposes) of the beamformed image by 
# "optimizing" the apodization:
my_loss = lambda **kwargs: jnp.sum(beamformer(**kwargs))
loss_grad = grad_for_argname(my_loss, "apodization")

Documentation

You can read the documentation of vbeam's core here.

Citing vbeam

If you use vbeam in your research, please cite the following paper: https://doi.org/10.1109/IUS51837.2023.10307255

M. D. Kvalevåg et al., "vbeam: a Fast and Differentiable Beamformer for Optimizing Ultrasound Imaging,"
2023 IEEE International Ultrasonics Symposium (IUS), Montreal, QC, Canada, 2023, pp. 1-4,
doi: 10.1109/IUS51837.2023.10307255.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

vbeam-1.0.8.tar.gz (3.5 MB view details)

Uploaded Source

Built Distribution

vbeam-1.0.8-py3-none-any.whl (92.3 kB view details)

Uploaded Python 3

File details

Details for the file vbeam-1.0.8.tar.gz.

File metadata

  • Download URL: vbeam-1.0.8.tar.gz
  • Upload date:
  • Size: 3.5 MB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/5.1.1 CPython/3.9.20

File hashes

Hashes for vbeam-1.0.8.tar.gz
Algorithm Hash digest
SHA256 24ce662ef1055afe74576665e9ba76d7a157da5461467cac16d997de3c993999
MD5 a555850965d8ea859f9f6f9c58bcb1a3
BLAKE2b-256 d922e3a55e5db20f40d7b3df71fae54cc02fd59071c0ef686e562565edd9e979

See more details on using hashes here.

File details

Details for the file vbeam-1.0.8-py3-none-any.whl.

File metadata

  • Download URL: vbeam-1.0.8-py3-none-any.whl
  • Upload date:
  • Size: 92.3 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/5.1.1 CPython/3.9.20

File hashes

Hashes for vbeam-1.0.8-py3-none-any.whl
Algorithm Hash digest
SHA256 8f89cef4331f73b585220fd40364275902788af37a8e8b6b902b34f22a99a35a
MD5 4d0f7192d5c7c6bb7939044914670130
BLAKE2b-256 9a317e6b2005625a592f329443b4450143224bc55df37173b75645bdde3c0f1b

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page