Vessel Voxelizer

GPU accelerated (fuzzy) voxelization of vascular structures

Demo · Report Bug / Request Feature · Documentation

Table of Contents

1. About The Project
2. Getting Started
   • Prerequisites
   • Installation
3. Documentation
   • How it works
   • Installation
   • Example
4. License
5. Acknowledgments

About The Project

vessel-voxelizer is a CUDA-accelerated tool designed to convert vascular structures, defined by line segments with associated radii, into fuzzy voxel volumes, where each voxel's value represents the fraction of its volume occupied by the vessels. This fuzzy representation is essential for simulations where the volume fraction plays a critical role in assigning the correct parameters to each voxel, ensuring precise modeling of e.g. physical processes. The project leverages CUDA for high performance and includes Python bindings for seamless integration into existing workflows.

Getting Started

Prerequisites

• a CUDA-capable GPU

Installation

1. install from pip

pip install vessel_voxelizer

or clone the repository

git clone https://github.com/faberno/vessel_voxelizer.git
cd vessel_voxelizer
pip install .

2. make sure you have a cuda-capable array library installed (currently cupy and torch are supported)

• how to install cupy: https://docs.cupy.dev/en/stable/install.html
• how to install pytorch: https://pytorch.org/get-started/locally/#start-locally

Documentation

How it works

A vessel segment Vⁱ is represented by a startpoint p₀ⁱ, an endpoint p₁ⁱ and a radius rⁱ. We determine the value of a voxel by supersampling K³ points within it and checking how many of those points lie within the radius of the vessel (no points -> 0.0, all points -> 1.0). Currently K is chosen as 10, so 1000 points per voxel are checked.
To avoid unnecessary checks of voxels that lie far away from any vessel, an initial bounding box intersection check is performed.

API

The voxelization is run by the function voxelize. It requires:

• volume: The volume that is written to
• volume_origin: origin coordinates (x₀, y₀, z₀) of the volume ( (x₀, y₀) in figure)
• volume_spacing: voxel side length (d in figure)
• vessel_positions: list of all vessel segments ((p₀⁰, p₁⁰), ..., (p₀^N, p₁^N))
• vessel_radii: list of all vessel radii

The array parameters should lie on the GPU, either as a cupy.ndarray or torch.Tensor.

Example

For a full example, take a look at the following notebook.

License

Distributed under the MIT License. See LICENSE.txt for more information.

(back to top)

TODO

• make number of sample points adaptable
• add prebuilt wheels

(back to top)

Acknowledgments

• the bindings are created using nanobind (https://nanobind.readthedocs.io/en/latest/index.html)