QUPS: Quick Ultrasound Processing & Simulation

| Features | Installation | Quick Start | Documentation | Citation | Parallel Processing | Troubleshooting |

Description

QUPS (pronounced "CUPS") is an abstract, lightweight, readable tool for prototyping pulse-echo ultrasound systems and algorithms. It provides a flexible, high-level representation of transducers, pulse sequences, imaging regions, and scattering media as well as hardware accelerated implementations of common signal processing functions for pulse-echo ultrasound systems. QUPS can interface with multiple other Ultrasound acquisition, simulation and processing tools including Verasonics, k-Wave, MUST, FieldII and USTB.

This package can readily be used to develop new transducer array designs by specifying element positions and orientations or develop new pulse sequence designs by specifying waveforms, element delays, and element weights (apodization). Simulating the received echoes (channel data) is supported for any valid UltrasoundSystem. Define custom properties or overload the built-in classes to create new types.

Features

• Flexible:

  • 3D space implementation
  • Transducers: Arbitrary transducer positions and orientations
  • Sequences: Arbitrary transmit waveform, delays, and apodization
  • Scans (Image Domain): Arbitrary pixel locations and beamforming apodization

• Performant:

  • Beamform a 1024 x 1024 image for 256 x 256 transmits/receives in < 2 seconds (RTX 3070)
  • Hardware acceleration via CUDA (Nvidia) or OpenCL (AMD, Apple, Intel, Nvidia), or natively via the Parallel Computing Toolbox
  • Memory efficient classes and methods such as separable beamforming delay and apodization ND-arrays minimize data storage and computational load
  • Batch simulations locally via parcluster or scale to a cluster with the MATLAB Parallel Server (optional) toolbox.

• Modular:

  • Transducer, pulse sequence, pulse waveform, scan region etc. each defined separately
  • Optionally overload classes to customize behaviour
  • Easily compare sequence to sequence or transducer to transducer
  • Simulate with MUST, FieldII, or k-Wave without redefining most parameters
  • Export or import data between USTB or Verasonics data structures

• Intuitive:

  • Native MATLAB semantics with argument validation and tab auto-completion
  • Overloaded plot and imagesc functions for data visualization
  • Documentation via help and doc

Installation

Prerequisites

QUPS requires the Signal Processing Toolbox and the Parallel Computing Toolbox to be installed.

MATLAB R2023b+ & git

Starting in MATLAB R2023b+, QUPS and most of it's extension packages can be installed from within MATLAB via buildtool if you have setup git for MATLAB.

1. Install qups

gitclone("https://github.com/thorstone25/qups.git");
cd qups;

2. (optional) Install and patch extension packages and compile mex and CUDA binaries (failures can be safely ignored)

buildtool install patch compile -continueOnFailure

3. (optional) Run tests (~10 min)

buildtool test

Legacy Installation

You can manually download and install each extension separately.

1. Download the desired extension packages into a folder adjacent to the "qups" folder e.g. if qups is located at /path/to/my/qups, kWave should be downloaded to an adjacent folder /path/to/my/kWave.

2. Create a MATLAB Project and add the root folder of the extension to the path e.g. /path/to/my/kWave.

• Note: The "prj" file in USTB is a Toolbox file, not a Project file - you will still need to make a new Project.

3. Open the Qups.prj project and add each extension package as a reference.

4. (optional) Apply patches to enable further parallel processing.

5. (optional) Run tests via the runProjectTests() function in the build directory.

addpath build; runProjectTests('verbosity', 'Concise'),

Extensions

All extensions to QUPS are optional, but must be installed separately from their respective sources.

| Extension | Description | Installation Paths | Citation | | ------ | ------ | ------ | ---------- | | FieldII | point scatterer simulator | addpath /path/to/fieldII| website | | k-Wave | distributed medium simulator | addpath /path/to/kWave | website | | kWaveArray | k-Wave transducer extension | addpath /path/to/kWaveArray | forum, paper | | MUST | point scatterer simulator | addpath /path/to/MUST| website | | USTB | signal processing library and toolbox | addpath /path/to/USTB | website | | Matlab-OpenCL | hardware acceleration | (see README) | website (via MatCL) | | CUDA | hardware acceleration | (see CUDA Support) | |

Quick Start

1. Start MATLAB R2020b or later and open the Project

openProject .

2. (optional) Setup any available acceleration

setup parallel CUDA cache; % setup the environment with any available acceleration

3. Create an ultrasound system and point scatterer to simulate

sct = Scatterers('pos', 1e-3*[0 0 30]'); % a single point scatterer at 30mm depth
xdc = TransducerArray.P4_2v(); % simulate a Verasonics P4-2v transducer
seq = Sequence('type', 'FSA', 'numPulse', xdc.numel); % full synthetic-aperture pulse sequence
scan = ScanCartesian('x', 1e-3*[-10, 10], 'z', 1e-3*[25 35]); % set the image boundaries - we'll set the resolution later
us = UltrasoundSystem('xdc', xdc, 'seq', seq, 'scan', scan, 'fs', 4*xdc.fc); % create a system description
[us.scan.dx, us.scan.dz] = deal(us.lambda / 4); % set the imaging resolution based on the wavelength

4. Display the geometry

figure; plot(us); hold on; plot(sct, 'cx'); % plot the ultrasound system and the point scatterers

5. Simulate channel data

chd = greens(us, sct); % create channel data using a shifted Green's function (CUDA/OpenCL-enabled)
% chd = calc_scat_multi(us, sct); %  ... or with FieldII
% chd = kspaceFirstOrder(us, sct); % ... or with k-Wave (CUDA-enabled)
% chd = simus(us, sct); %            ... or with MUST   (CUDA-enabled)

6. Display the channel data

figure; imagesc(chd); dbr echo 60; % 'echo' settings w/ 60 dB dynamic range
animate(chd.data, 'loop', false, 'title', "Tx: "+(1:chd.M)); % M = # of transmits

7. Beamform

b = DAS(us, hilbert(chd));

8. Display the B-mode image

figure; imagesc(us.scan, b); dbr b-mode 60;
title('B-mode image');

Documentation

QUPS is documented within MATLAB. To see all the available classes, use help ./src or doc ./src from within the QUPS folder. Use help or doc on any class or method with help classname or help classname.methodname e.g. help UltrasoundSystem.DAS.

For a walk through of going