HolOrama: A unified platform for cardiac image analysis

"A mixture from greek 'Holo' meaning full and 'Orama' meaning vision. Together building the promise of this GUI application to visualize the whole heart from different modalities."

Currently spans:

• Quantification of Coronary Artery Anomalies
• Quantification of Optical Coherence Tomography
• Quantification of Coronary Computed Tomography Angiography

Demo

Segment, modify and analyze IVUS images, inclusive with gating functionalities:

Also spans to OCT images, address uncertainty systematically:

Segment and visualize CCTA data in 3D, remove outliers with intuitiv tools:

Fuse CCTA and intravascular data into one single geometry:

Table of contents

• Installation
• Basic
• Functionalities
• Configuration
• Usage
• Keyboard shortcuts
• Acknowledgements

Installation

The easiest way to install is via the provided scripts — they handle all platform-specific steps automatically. If you run into problems, follow the step-by-step instructions further below.

Linux / macOS — script

bash install.sh

The default install is GPU-ready (CUDA 11.8). Optional flags:

Flag	Effect
--dev	Also install dev dependencies
--nnuzoo	Install nnUZoo from GitHub
--cpu	Switch to CPU-only torch (no GPU)
--cuda 121	Switch to CUDA 12.1 build instead of the default cu118

Windows — script

First install the Visual C++ Redistributable 2022 (x64) if not already present, then run in PowerShell:

.\install.ps1

The script automatically applies all Windows-specific fixes (missing OpenMP DLL, optree version pin). The default install is GPU-ready (CUDA 11.8). Optional flags:

Flag	Effect
-Dev	Also install dev dependencies
-NnUZoo	Install nnUZoo from GitHub
-Cpu	Switch to CPU-only torch (no GPU)
-Cuda 121	Switch to CUDA 12.1 build instead of the default cu118

---

Step-by-step installation (if the scripts fail)

Linux / macOS

pip install uv
uv sync
source .venv/bin/activate

For developers:

uv sync --group dev

For nnUZoo (automatic segmentation):

uv pip install git+https://github.com/AI-in-Cardiovascular-Medicine/nnUZoo@main

For GPU (CUDA 11.8):

uv pip install --reinstall "torch==2.4.0+cu118" "torchvision==0.19.0+cu118" \
    --index-url https://download.pytorch.org/whl/cu118

If you plan on using GPU acceleration, install the required NVIDIA drivers and CUDA toolkit beforehand:

sudo apt update && sudo apt upgrade
sudo apt install build-essential dkms
sudo ubuntu-drivers autoinstall
sudo reboot
nvidia-smi  # verify driver installation
sudo apt install nvidia-cuda-toolkit

Windows — step by step

1. Install Visual C++ Redistributable

Download and install the Visual C++ Redistributable 2022 (x64) if not already present.

2. Base install

pip install uv
uv sync
.\.venv\Scripts\Activate.ps1

3. Fix missing LLVM OpenMP runtime (libomp140.x86_64.dll)

PyTorch 2.4.0 on Windows depends on libomp140.x86_64.dll which is not bundled in the pip wheel. Run this once after installation:

import urllib.request, tarfile, io, os, sys

url = 'https://conda.anaconda.org/conda-forge/win-64/llvm-openmp-14.0.0-h2d74725_0.tar.bz2'
data = urllib.request.urlopen(url).read()
dest = os.path.join(sys.prefix, 'Lib', 'site-packages', 'torch', 'lib', 'libomp140.x86_64.dll')

with tarfile.open(fileobj=io.BytesIO(data), mode='r:bz2') as t:
    f = t.extractfile('Library/bin/libomp.dll')
    with open(dest, 'wb') as out:
        out.write(f.read())
print('Done:', dest)

Note: This file will be lost if torch is reinstalled — re-run the script afterwards.

4. Fix optree version incompatibility

optree >= 0.14 is incompatible with torch 2.4.0 and causes a C-level access violation. Downgrade it:

uv pip install "optree==0.13.1"

5. GPU acceleration (CUDA)

Install the CUDA-enabled torch build matching your driver. With CUDA driver ≤ 12.0 (check with nvidia-smi), use the CUDA 11.8 build:

uv pip install --reinstall "torch==2.4.0+cu118" "torchvision==0.19.0+cu118" \
    --index-url https://download.pytorch.org/whl/cu118

After installing the CUDA build, re-run the libomp140.x86_64.dll script from step 3.

Functionalities

This application is designed for IVUS, OCT and CCTA images in DICOM or NIfTi format and offers the following functionalities:

IVUS / OCT

• Inspect IVUS/OCT images frame-by-frame and display DICOM metadata
• Manually draw one or several contours (lumen, eem, calcium, side branch, macrophage, lipid) with automatic calculation of several measurements
• Either draw closed spline, open spline or a closed spline with an uncertain region indicated by start- and end point
• Automatic segmentation of (currently only IVUS) lumen for all frames
• Automatic gating with extraction of diastolic/systolic frames if in IVUS mode
• Manually tag diastolic/systolic frames
• Longitudinal view: toggle visibility of the diastolic/systolic marker lines, breathing curve, and area dots independently
• Breathing motion is detected automatically from the lumen area signal and can be reviewed/corrected by hand, then used to reorder gated frames into a breathing-corrected pullback
• Ability to measure up to two distances per frame which will be stored in the report
• Indicate the wire shadow using an angle
• Create automatic masks from contour with predefined rulesets
• Copy/paste contours from neighbouring, gated or tagged frames
• Auto-save of contours and tags enabled by default with user-definable interval
• Generation of report file containing detailed metrics for each frame
• Save coordinate data as csv files
• Ability to save images and segmentations as NIfTi files, e.g. to train a machine learning model

CCTA

• Read CT volumes from a DICOM folder or a NIfTi file and view them as synchronized axial, coronal and sagittal slices
• Load an existing segmentation mask (NIfTi) or start from a blank, multi-label mask
• Brush tool to manually add or erase mask labels on any of the 2D views, with adjustable radius and per-label color
• 3D volume rendering of all visible mask labels (surface extraction via VTK)
• Lasso tool in the 3D render to draw a closed region and delete the voxels of a chosen label that fall inside it
• Toggle label visibility/color and rename labels, synced across the 2D views, brush tool and 3D render
• Draw cut lines on the axial/coronal views to define the LVOT and aortic root, then extract the coronaries/aorta/LV as a combined NIfTi mask or STL mesh
• Auto-save of the mask enabled by default with user-definable interval, with versioned mask files and auto-reload of the latest mask on reopening a volume

Configuration

Make sure to quickly check the src/config.yaml file and configure everything to your needs.

Display:

• image_size: In pixels, creates the quadratic box displaying the IVUS/OCT 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: How much windowing (level/width) changes per pixel dragged with RMB. 1 is default, below 1 slower, above 1 faster.
• zoom_sensitivity: Fraction of zoom applied per pixel dragged. Below 0.005 for slower, above for faster.
• n_interactive_points: The draggable points on the contour (lumen); calcium, lipid, macrophage and branch contours default to half of this. New points can also be added interactively by clicking on the contour.
• n_points_contour: Number of points used to represent the interpolated contour outline. Ideally a multiple of 100 (used when calculating closest points).
• contour_thickness / point_thickness / point_radius: Line and knot-point drawing sizes for contours.
• color_contour / color_eem / color_calcium / color_branch / color_start_point / color_end_point / color_angle: Colors used for each contour/marker type. Accepts any of the 20 predefined PyQt colors or a hex code (see Qt colors).
• alpha_contour: Contour fill transparency, 0-255 (higher is 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 separately.
• f_cardiac_min / f_cardiac_max: Heart-rate search range in Hz for the cardiac frequency detection, covering rest (~45 BPM) to stress (~200 BPM).
• bandpass_lo_frac: Lower bandpass cutoff as a fraction of the detected cardiac frequency; removes slow pullback trend (sub-cardiac drift).
• bandpass_hi_frac: Upper bandpass cutoff as a fraction of the detected cardiac frequency; passes the 2nd harmonic while removing speckle noise.

Report:

• plot: Whether to display a plot of the gated-frame results after report generation.
• save_as_csv: Whether to additionally save contour coordinate data as csv files.

Save:

• autosave_interval: Auto-save interval in ms for contours/tags (IVUS/OCT) and the mask (CCTA).
• nifti_dir: Default output directory for images/segmentations exported from segment_files.py.
• save_niftis: Which frames to save as NIfTi when exporting — 'contoured', 'all' or 'none'.
• save_2d: Whether to additionally save each frame's image/mask as an individual NIfTi file.
• save_3d: Whether to save the full stack of frames as a single 3D NIfTi volume.

Segmentation:

• model_file: Path to the (nnU-Net) automatic IVUS lumen segmentation model.
• model_fold: Model fold to use for inference.
• normalize: Set to True when using a TensorFlow model that expects normalized input.
• input_dir: Input directory used only by segment_files.py for batch segmentation.
• batch_size: Batch size used during inference.
• conserve_memory: Set to True on devices with less than 32 GB RAM; increases inference time but lowers memory use.

Usage

After the config file is set up properly, you can run the application using:

python3 src/main.py

This will open a graphical user interface (GUI) in which you have access to the above-mentioned functionalities.

Keyboard shortcuts

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
• Drag RMB left/righ up/down 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 Esc to exit drawing mode and return to a neutral state
• Press RMB on an existing knot point to remove it
• Scroll MW to scroll through frames (forward/backward)
• Drag LMB up/down for zooming (can be reset by pressing F)
• Drag Ctrl + LMB to move the image inside it's widget
• Press Ctrl + MW to shrink or expand the currently selected contour (moves all knot points toward/away from their centroid)
• Press Q to manually draw an external elastic membrane (EEM) contour
• Press Shift + Q to spawn an EEM contour from an existing lumen contour (20 % radial expansion from lumen centroid); does nothing if EEM already exists on that frame
• Press Shift + A to copy the active contour from the previous frame to the current frame
• Press Shift + D to copy the active contour from the next frame to the current frame
• Press Shift + W to copy the active contour from the next gated/tagged frame (only works when the current frame is itself gated/tagged)
• Press Shift + S to copy the active contour from the previous gated/tagged frame (only works when the current frame is itself gated/tagged)
• Press 7 to manually draw a calcification contour
• Press Ctrl + 7 to draw an additional calcification contour in the current active spline tool (open or closed)
• Press 8 to manually draw a side branch contour
• Press Ctrl + 8 to draw an additional side branch contour in the current active spline tool (open or closed)
• Press 9 to manually draw a lipid contour (only open spline)
• Press Ctrl + 9 to draw an additional lipid contour
• Press 0 to manually draw a macrophage contour (only open spline)
• Press Ctrl + 0 to draw an additional macrophage contour

Citation

Please kindly cite the following papers if you use this repository.

@article{stark2025automated,
  title={Automated intravascular ultrasound image processing and quantification of coronary artery anomalies: the HolOrama 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}
}

@article{kazaj2026unified,
  title  = {A Unified Framework for Comprehensive Cardiac CT Segmentation and Phenotyping:
Human-in-the-Loop Data Annotation, Vision Foundation Model Development, Multicenter Evaluation and Clinical Validation},
  author = {Mohammadi Kazaj, Pooya and Weber, Leo Fridolin and Xie, Wen and Safavi-Naini, Seyed Amir Ahmad and Stark,
Anselm and Baj, Giovanni and Mokhtari, Ali and Yoshida, Toshiya and Ryffel, Christoph and Okuno, Taishi and Akashi,
Yoshihiro and Buechel, Ronny R. and Pilgrim, Thomas and Valenzuela, Waldo and Siontis, George C. M. and Xu, Xiaowei
and Hundertmark, Moritz and Windecker, Stephan and Grani, Christoph and Shiri, Isaac},
  journal = {arXiv preprint arXiv:2607.11287},
  year   = {2026},
  doi    = {10.48550/arXiv.2607.11287},
  url    = {https://arxiv.org/abs/2607.11287}
}

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 HolOrama software. Computer Methods and Programs in Biomedicine, 109065.

Mohammadi Kazaj, P., Weber, L. F., Xie, W., Safavi-Naini, S. A. A., Stark, A., Baj, G., Mokhtari, A., Yoshida, T., Ryffel, C., Okuno, T., Akashi, Y., Buechel, R. R., Pilgrim, T., Valenzuela, W., Siontis, G. C. M., Xu, X., Hundertmark, M., Windecker, S., Grani, C., Shiri, I. (2026). A unified framework for comprehensive cardiac CT segmentation and phenotyping: human-in-the-loop data annotation, vision foundation model development, multicenter evaluation and clinical validation. arXiv preprint arXiv:2607.11287.