python3 -m venv env
source env/bin/activate
pip install poetry
poetry install
If 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 Tensorflow.
The program was tested on Ubuntu 22.04.5 with python 3.10.12. We tested it on differnt 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-toolkit
Potentially extra steps are needed.
In case you prefer a single executable file instead of running the application from the terminal or an IDE, you can follow these steps to generate an executable for the OS you are executing the command on, i.e. if you run this in a Linux environment, you will create an executable for Linux.
First, you need to install the application on your system (e.g. with the commands above on Linux) and ensure it is properly set up and can be run.
Then you can use Pyinstaller to create an executable:
pyinstaller -F --hiddenimport=pydicom.encoders.gdcm --hiddenimport=pydicom.encoders.pylibjpeg --hiddenimport=scipy.special._cdflib main.py
You can find the executable main in the dist folder. If you are having trouble launching the application from the executable, try running it in a terminal to see potential errors:
./dist/main
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.
After the config file is set up properly, you can run the application using:
python3 main.py
This 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
The starting point of this project was the DeepIVUS public repository by David (cloned on May 22, 2023).