VSMOD is a 3D Slicer plugin that aims to ease Vessel Segmentation and MODelization for angiography images.
The plugin works thanks to a RANSAC algorithm that tries to fit cylinders into vessels you want to track in order to approximate their shape.
The vessels are defined by a centerline, an evolving radius along the centerline, and contour points. This data is later used to generate seeds that initialize a region-growing segmentation.
To perform a full modeling process, follow these three steps:
- Place points to indicate the vessel's direction and diameter.
- Start a centerline segmentation from these points; repeat steps 1 and 2 until you have captured all desired vessels.
- Once all vessels are defined, paint the segmentation to generate an initial region-growing seed.
To install the plugin, you have to do the following steps:
- Download the plugin as a zip file or clone this repository. If you downloaded a zip file, extract it. You can clone/extract it wherever you want.
- Start 3D Slicer, in the
moduledrop-down menu, click onDeveloper Tools -> Extension Wizard. - Click on
Select Extension, a folder tab will appear, select the repository folder / the zip folder you extracted, and click onChoose. - A popup will show, select
Yes.⚠️ Make sure you are connected to the internet. When loading the module, it will check if you have all the dependencies and attempt to download the missing ones.⚠️ - After downloading the missing dependencies, 3D Slicer will be automatically restarted, the plugin can be found in the module drop-down menu, under the
Segmentationcategory.
plugin_install.webm
Tips: If you struggle to find any of those modules, you can use the magnifying glass to search modules by name.
- Download the plugin as a zip file or clone this repository. If you downloaded a zip file, extract it. You can clone/extract it wherever you want.
- Start 3D Slicer, in the menu top bar of Slicer's window, click
Edit -> Application Settings, a new window will open :
- Select
Modules. - Click on the arrow on the right.
- Click
add. - Now you will have to select the VSMOD module, meaning the VSMOD directory which is inside the VSMOD github repository directory. (check the path selected)
- Click on the OK button, Slicer should restart. VSMOD should now appear in the module drop-down menu under the
Segmentationcategory. Note: Due to a restart issue on macOS, you may end up with two Slicer instances open. Close both and start a new instance of Slicer.
macOS-specific notes:
- The plugin uses a different threading layer on macOS (built-in numba threading instead of intel-openmp) which may be slightly slower but ensures compatibility.
- If you encounter any Python console errors during installation, this is expected behavior on macOS.
VSMOD includes comprehensive automated tests to verify the functionality of the software. The test suite covers individual functions with multiple test cases and includes an end-to-end integration test.
To run the automated tests:
- Ensure VSMOD is properly installed and loaded in 3D Slicer.
- Set 3D Slicer to Developer Mode:
- Go to
Edit -> Application Settings -> Developer - Check "Enable developer mode"
- Restart 3D Slicer
- Go to
- Navigate to the VSMOD module in 3D Slicer.
- Click the "Reload and Test" button in the module interface.
Important notes:
⚠️ The tests take approximately 4-5 minutes to complete.- The test suite includes multiple test cases per function and a comprehensive end-to-end test.
- Do not interrupt the testing process once it has started.
The tests will automatically verify that all plugin functionality works correctly on your system.
If you do not have your own data to test the plugin, and you wish to, you can use the MRA images from the IXI dataset. For our automated tests, we used the IXI002-Guys-0828-MRA.nii.gz file, which you can find here in the repository.
The plugin is divided into two tabs:
- Centerline which is used to create a tree from the vessels' centerline.
- Segmentation which creates a segmentation and fills it according to the centerline tree.
In order to make a segmentation, you first have to create a vessel centerline tree. To do so, you have to use the tools present in the centerline tab.
You must select a volume, a starting point, a list of direction points, and a distance line (all except the volume are created and selected by default).
Once the prerequisites are met, click on the Place a new starting and direction point button to add two points: one indicating the starting position and the other indicating the direction for the algorithm to follow.
Next, measure the vessel's diameter near your previously placed points. Click the Measure diameter button, then place two points along the vessel's diameter; the measured value will be automatically entered in the diameter field. Alternatively, if you prefer not to measure the diameter again, check the Automatic Diameter Selection box to use the diameter from the closest previously fitted cylinder.
Additionally, you can configure the Centerline Resolution parameter to ensure that a point is generated at least every X mm, which refines the centerline after tracking.
Finally, click on the Create root / Create new branch button in order to start finding a centerline !
note: the first time you will start a tracking, the program will compile some crucial functions (it will also happen each time you modifies the files that needs to be compiled), and thus will result in a 1-2 minutes of 3D Slicer freezing asking to be shutdown. Do not shut it down.
plugin_first_branch.webm
Once the processing is done, you can add new branches to the tree by adding two new starting and direction points by doing the same process.
plugin_second_branch.webm
You can delete a branch from the hierarchy by clicking on the bin icon, or clear the whole tree by clicking on the Clear tree button.
plugin_delete_branch.webm
If the centerline is correct until a certain point where it is not, you can delete the irrelevant part by selecting the last correct point and right-clicking the concerned artery in the hierarchy, and selecting Remove end of the branch.
This correction is also available for the beginning of the root which can be removed as well.
plugin_trim_branch.webm
If you want, you can also save the hierarchy of all the vessel points into a NetworkX graph, which is exported in a .json file. The json file can later be used to reload a previous hierarchy thanks to the Load Tree from graph button.
plugin_save_branch.webm
This tab is made to configure how the RANSAC algorithm will behave.
How the RANSAC algorithm works:
In this plugin, RANSAC is used to fit cylinders inside a vessel to approximate its shape. Points are sampled from a region around the vessel, and the algorithm tries to build cylinders from these points. It evaluates each cylinder based on the distance of points to its central axis, categorizing points as "inliers" or "outliers", and ultimately selects the cylinder with the most inliers. Consequently, the parameters control the algorithm's flexibility.
These are the configurable parameters of the RANSAC algorithm, and their meaning:
Inlier points: A threshold parameter defining the minimum number of inliers required for a cylinder to be considered valid.Threshold: The maximum allowed distance (as a fraction of the cylinder's radius) for a point to be considered an inlier. For example, if the previous cylinder radius is 1 mm, a point 1.2 mm away is considered an inlier with a threshold of 33%, since (1.2 - 1 = 0.2) and (0.2 < 0.33).
Here is an illustration showing a point cloud with points at distances between 0.8 and 1.2 from the cylinder axis and the impact of the Theshold parameter on the inliers.
-
Maximum inter-cylinder angle: The maximum angle allowed between two consecutive cylinders. For highly curved vessels, you may set this value near 90°; for straighter vessels, closer to 60°. -
Min Attempts per Cylinder: The minimum number of attempts the algorithm will make to find a suitable cylinder. -
Max Attempts per Cylinder: The maximum number of attempts the algorithm will make if it does not find a suitable cylinder. (Thus, the actual number of tries will lie in the interval ([minimum, minimum + maximum]).) -
Max Cylinders per Vessel: The maximum number of cylinders the algorithm can fit during a single tracking session.
The segmentation tab is straightforward. You have a button labeled Create Segmentation Seeds. Clicking this button generates a new segmentation, which serves as the initialization for 3D Slicer's region-growing algorithm. You can further adjust or edit the generated segmentation using the segmentation widget.
plugin_seeds_branch.webm
To finalize segmentation, you just have to run 3D Slicer's region-growing algorithm which can be found in the plugin directly in the tools of the segmentation widget.
plugin_region_branch.webm
Through the Segmentation Options panel, you can further adjust how the segmentation is generated.
Two parameters help to avoid over-segmentation of large vessels:
Reduction FactorandDiameter Lowering Threshold: These reduce the diameter of vessels that exceed a certain threshold by a given factor. For instance, the following code demonstrates the process:
if diameter <= reduction_threshold:
segmented_diameter = diameter
else:
# This ensures a continuous transition of the diameter values.
segmented_diameter = (diameter - reduction_threshold) * reduction_factor + reduction_threshold-
Distance of Contour Region: Configures the gap between the vessels and the external boundary. -
Merge all vessels into a single segment: Allows you to merge all individual vessel segments into one.
This plugin was initially an end-of-study project, made by Azéline Aillet (Former student at EPITA) and Gabriel Husak (Former student at EPITA), under the direction of Odyssée Merveille (CREATIS) and Morgane Des Ligneris (CREATIS).
The RANSAC code is based on the previous work of Jack CARBONERO (CReSTIC), Guillaume DOLLE (LMR) and Nicolas PASSAT (CReSTIC) on the plugin vestract.
The hierarchy code is based on the work of Lucie Macron (Kitware SAS), Thibault Pelletier (Kitware SAS), Camille Huet (Kitware SAS), Leo Sanchez (Kitware SAS) from the RVesselX plugin.
The IXI002-Guys-0828-MRA.nii.gz file used in the tests is part of the IXI MRA image dataset and can be found here. This specific data file is made available under the Creative Commons CC BY-SA 3.0 license.