search

PROTEUS-SIM / PROTEUS

MIT License
11 stars 0 forks source link

readme

PROTEUS: A Physically Realistic Contrast-Enhanced Ultrasound Simulator

Nathan Blanken , Baptiste Heiles , Alina Kuliesh, Michel Versluis , Kartik Jain, David Maresca, and Guillaume Lajoinie

Contrast-enhanced ultrasound simulator for microbubbles in vascular flow

Link to the article: https://ieeexplore.ieee.org/document/10597664

System requirements

Installation of the simulator

Repository

Method 1: Download ZIP file

  1. Click code
  2. Click Download ZIP
  3. Unzip the repository in the desired location

Method 2: Clone with git

git clone https://github.com/PROTEUS-SIM/PROTEUS.git.

k-Wave

  1. Download k-Wave from k-wave.org We strongly recommend the use of k-Wave version 1.3. Place the root folder of k-Wave (k-wave-toolbox-version-1.3) in the root folder of this repository.
  2. Download the k-Wave C++ Simulation Codes for accelerated k-Wave simulations. These codes have already been compiled into binary files for 64-bit Linux and Windows systems. macOS users need to compile the C++ source code themselves. Place the binary files in the binaries folder (k-wave-toolbox-version-1.3/k-Wave/binaries).

Note: There is an issue with using k-Wave version 1.3 in MATLAB 2020A. A solution is provided here.

Note: If you use another k-Wave version or you install k-Wave in a different location (not recommended), you need to modify the installation paths in the file PATHS.mat, so that k-Wave can be located (see Custom installation below).

Example flow geometry data

Download example flow geometry data from Zenodo. There are three flow geometries:

Download the flow geometries you wish to use, unzip the ZIP files, and place the geometry folders in the folder geometry_data. As a minimum requirement, download the renal_tree geometry as this is the default flow geometry.

Flow solver module

Note: Users who only use the example flow data from Zenodo do not have to install the APES suite and Musubi.

vtkToolbox

Note: Users who only use the example flow data from Zenodo do not have to install the vtkToolbox.

The output of Musubi is in VTU format. You need the vtkToolbox to convert VTU data to a MATLAB readable format.

Custom installation

We strongly recommend to install the software components (such as k-Wave) in the specified locations. However, if you wish to install components in different locations, you need to modify the file PATHS.mat:

Simulation setup

Start MATLAB and navigate to the root folder of this directory. Start the graphical user interface (GUI) by running MainGUI.mlapp in the root folder. To do so, either:

The main window opens:

Screenshot of the main window after opening

Note: Do not open the application more than once (do not have more than one main window open at the same time) as this can lead to unexpected behavior with the MATLAB path.

Simulation settings panels

The seven panels are listed below. Click on the links for further information on each panel.

Generic behavior of the pop-up windows

Each of the pop-up menus that can be accessed by clicking Modify have the following generic buttons:

Note that only one pop-up window can be open at the same time. You need to click Apply or Cancel before you can move on to another window. This prevents unexpected behavior as the settings in the different windows are not independent.

Saving settings, loading settings, and running the simulation

At the bottom of the main window there are buttons to load and save simulation settings and to run a simulation:

Note: If your computer does not have a GPU with at least 8 GB of dedicated memory, we advise to prepare your settings and ground truth data locally, and run the simulation from the command line on a remote system.

Note If you are using the default settings and you click Simulate RF data or Simulate pressure field a computationally demanding simulation will start. If you only want to test the functionality of the code and are not interested in a physically realistic scenario, you can click Load settings and select the file test_settings.mat.

Running the simulation from the graphical user interface

After completion of the simulation setup, you can run the simulation directly on the local machine by clicking Simulate RF data at the bottom of the main window.

You may also choose to reuse previously generated ground truth bubble location, e.g., to compare pulsing schemes:

Interrupting the simulation

Once the simulation has started running, it does not return control to the graphical user interface until the simulation is complete. If you wish to quit the execution:

Similarly, if the execution is interrupted due to an unexpected error, the status can be reset by clicking Reset status.

Running the simulation from the command line

The simulation can also be run using the command line in MATLAB or a MATLAB script using the function main_RF.m. This is necessary for execution on a remote system without graphical output, e.g., a GPU server. Running from the command line or from a script offers additional advantages, such as:

The example script example_batched.m in example_scripts runs the simulation in several batches. The script assumes you have already generated a GUI parameters output file (settings file) and a ground truth bubble locations folder.

Note: the initial k-wave simulation will have to be rerun for each subset but this is a minor part of the runtime if the number of bubbles and/or frames is large.

To run an RF simulation on a remote system without graphical output:

Advanced modification of the k-Wave medium

To modify the k-Wave medium, for example, add a cyst or a specific geometry:

Delay-and-sum (DAS) image reconstruction

The folder delay-and-sum in the root directory of the simulator contains functions for delay-and-sum (DAS) image reconstruction. The folder example_scripts contains an example script for running a DAS reconstruction.

This will run the DAS image reconstruction, display the results, save a movie and the reconstructed data. The movie and the data are saved in the working directory, with the name of the simulation.

New geometries and flow simulations

Use the flow solver module (Musubi) to:

Refer to the documentation of Musubi for instructions on the flow simulations.

The simulator has been created and tested to be compatible with Musubi. Currently, the simulator is only compatible with steady flow simulations. We have not tested compatibility with other CFD simulators. Musubi will be integrated directly into the simulator in a future version.

The output of the flow simulations is in VTU format. Before the flow data can be used for the acoustic simulations, the data needs to be converted to MATLAB format, stored in the right folder, and supplemented with metadata. Detailed instructions on how to do this can be found in Importing new flow geometries and flow data.

If you believe your geometry is useful to other researchers, do not hesitate to share it with us so that we can add it to the database.

License and citation

This code is available under an MIT licencse. If you use (parts of) the code, please cite our IEEE T-UFFC article:

Blanken, N., Heiles, B., Kuliesh, A., Versluis, M., Jain, K., Maresca, D., & Lajoinie, G. (2024). PROTEUS: A Physically Realistic Contrast-Enhanced Ultrasound Simulator—Part I: Numerical Methods. IEEE Transactions on Ultrasonics, Ferroelectrics, and Frequency Control. https://doi.org/10.1109/TUFFC.2024.3427850

@article{Blanken2024,
  author  = {Blanken, Nathan and Heiles, Baptiste and Kuliesh, Alina and Versluis, Michel and Jain, Kartik and Maresca, David and Lajoinie, Guillaume},
  doi     = {10.1109/TUFFC.2024.3427850},
  journal = {IEEE Transactions on Ultrasonics, Ferroelectrics, and Frequency Control},
  title   = {{PROTEUS}: A Physically Realistic Contrast-Enhanced Ultrasound Simulator---{Part I}: Numerical Methods},
  year    = {2024}
}