AIVUS-CAA (Automated IntraVascular UltraSound Image Processing and Quantification of Coronary Artery Anomalies)
python3 -m venv env
source env/bin/activate
pip install poetry
poetry installSometimes the nnUZoo can be problematic to install over github, so as a default it is commented out in pyproject.toml. In this case the installation should be performed like this:
python3 -m venv env
source env/bin/activate
pip install poetry
poetry install
poetry run pip install git+https://github.com/AI-in-Cardiovascular-Medicine/nnUZoo@mainFor developers download additionally the dev dependencies:
poetry install --with devIf you plan on using GPU acceleration for model training and inference, make sure to install the required tools (NVIDIA toolkit, etc.) and the corresponding version of Pytorch/Tensorflow.
The program was tested on Ubuntu 22.04.5 with python 3.10.12. We tested it on different hardware, NVIDIA drivers and CUDA tended to cause problems cross-platforms. Make sure to download the corresponding drivers and CUDA toolkit, e.g.:
sudo apt update
sudo apt upgrade
sudo apt install build-essential dkms
sudo ubuntu-drivers autoinstall
sudo reboot
# verify the installation of the driver
nvidia-smi
sudo apt install nvidia-cuda-toolkitPotentially extra steps are needed.
This application is designed for IVUS images in DICOM or NIfTi format and offers the following functionalities:
- Inspect IVUS images frame-by-frame and display DICOM metadata
- Manually draw lumen contours with automatic calculation of lumen area, circumference and elliptic ratio
- Automatic segmentation of lumen for all frames (work in progress)
- Automatic gating with extraction of diastolic/systolic frames
- Manually tag diastolic/systolic frames
- Ability to measure up to two distances per frame which will be stored in the report
- Auto-save of contours and tags enabled by default with user-definable interval
- Generation of report file containing detailed metrics for each frame
- Ability to save images and segmentations as NIfTi files, e.g. to train a machine learning model
Make sure to quickly check the config.yaml file and configure everything to your needs.
Display:
- image_size: In Pixel creates quadratic box displaying the IVUS images. Default 800x800 px.
- gating_display_stretch: input parameter for .setStretchFactor in class RightHalf
- lview_display_stretch: input parameter for .setStretchFactor in class RightHalf
- windowing_sensitivity: Defines how much windowing changes with RMB draging
- n_interactive_points: The dragable points on the contour, default 10 equally spaced points, however new one can also be added interactively by clicking on the contour
- alpha_contour: Used as input parameter for .setAlpha in class IVUSDisplay. Default 128 for 50% transparency, higher values more opaque.
Gating:
- normalize_step: If step=0 compute one global z-score over the entire data. If step > 0 split data into non-overlapping windows of length normalize_step and apply z-score to each window seperately.
- lowcut: lower frequency for Butterworth filter. Default 1.33Hz which is ~80bpm (since detecting systole and diastole this is equivalent to 40bpm).
- highcut: higher frequency for Butterworth filter. Default is 6.0Hz which is 360bpm (since detecting systole and diastole this is equivalent to 180bpm).
- order: Order for the Butterworth filter. Default 6 based on experiments with our data.
- extrema_y_lim: Setting for finding local extrema, next extrema most be >50th percentile of previous as default
- extrema_x_lim: Distance in frames for next local extrema. Default set to 6 frames.
After the config file is set up properly, you can run the application using:
python3 src/main.pyThis will open a graphical user interface (GUI) in which you have access to the above-mentioned functionalities.
For ease-of-use, this application contains several keyboard shortcuts.
In the current state, these cannot be changed by the user (at least not without changing the source code).
- Press Ctrl + O to open a DICOM/NIfTi file
- Use the A and D keys to move through the IVUS images frame-by-frame
- If gated (diastolic/systolic) frames are available, you can move through those using S and W
Make sure to select which gated frames you want to traverse using the corresponding button (blue for diastolic, red for systolic) - Press E to manually draw a new lumen contour
In case you accidentally delete a contour, you can use Ctrl + Z to undo - Use 1, 2 to draw measurements 1 and 2, respectively
- Use 3, 4 or 5 to apply image filters
- Hold the right mouse button RMB for windowing (can be reset by pressing R)
- Press C to toggle color mode
- Press H to hide all contours
- Press J to jiggle around the current frame
- Press Ctrl + S to manually save contours (auto-save is enabled by default)
- Press Ctrl + R to generate report file
- Press Ctrl + Q to close the program
- Press Alt + P to plot the results for gated frames (difference area systole and diastole, by distance)
- Press Alt + Delete to define a range of frames to remove gating
- Press Alt + S to define a range of frames to switch systole and diastole in gated frames
- Press Q to manually draw an external elastic membrane (EEM) contour
- Press Y to manually draw a calcification contour
- Press X to manually draw a side branch contour
An example case is provided under "/test_cases/patient_example", allowing to follow along.
This module implements gating by analyzing both image-derived metrics (e.g., pixel-wise correlation and blurriness) and vector-based contour measurements (e.g., distance and direction from the image center to each contour centroid). Changes in these metrics are displayed over the sequence of frames during a pullback.
The resting phases of the cardiac cycle—diastole and systole—are characterized by minimal vessel motion for several consecutive frames. We visualize these phases using two curves: the image-based curve (green) represents metrics such as correlation peaks and minimal blurriness, while the contour-based curve (yellow) reflects extrema in the vector measurements (i.e., alternating peaks and valleys corresponding to systolic and diastolic positions).
-
Image-Based Metrics: Select local maxima corresponding to frames with the highest pixel correlation and lowest blurriness.
-
Contour-Based Metrics: Select extrema in the distance vector, capturing the transition between diastole and systole.
Movement patterns may vary between datasets; consequently, the final frame selection is left to the user.
Peak Assignment: Detected peaks in each curve are matched by intersecting their frame indices. We apply a Butterworth filter (passband: 45–180 bpm) to smooth each curve; the unfiltered signal is displayed as a dotted line beneath the filtered curve.
Interactive Gating Interface:
- Range Selection: Specify the frame interval for gating.
- Zoom & Pan: Zoom into the plot and drag lines to adjust gating thresholds or remove unwanted markers by dragging them downward.
- Compare Frames: Click "Compare Frames" to open the nearest proximal frame for the selected phase (systole or diastole).
Version 1.1.0 and higher offer the additional possibility to segment the EEM, calcification and side branches. This works in the same style as for the base contours. Clicking on any contour in the image automatically sets it as the active contour.
Note
The segmentation models are currently only trained for lumen contours. In the future, we will implement additional models for EEM segmentation and calcium segmentation.
Please kindly cite the following paper if you use this repository.
@article{stark2025automated,
title={Automated intravascular ultrasound image processing and quantification of coronary artery anomalies: the AIVUS-CAA software},
author={Stark, Anselm W and Kazaj, Pooya Mohammadi and Balzer, Sebastian and Ilic, Marc and Bergamin, Manuel and Kakizaki, Ryota and Giannopoulos, Andreas and Haeberlin, Andreas and R{\"a}ber, Lorenz and Shiri, Isaac and others},
journal={Computer Methods and Programs in Biomedicine},
pages={109065},
year={2025},
publisher={Elsevier},
doi={10.1016/j.cmpb.2025.109065},
url={https://doi.org/10.1016/j.cmpb.2025.109065}
}
Stark, A. W., Kazaj, P. M., Balzer, S., Ilic, M., Bergamin, M., Kakizaki, R., Giannopoulos A., Haeberlin A., Räber L., Gräni, C. (2025). Automated intravascular ultrasound image processing and quantification of coronary artery anomalies: the AIVUS-CAA software. Computer Methods and Programs in Biomedicine, 109065.