Metadata-Version: 2.3
Name: vessel-centerline
Version: 0.1.0
Summary: Compute vessel centerline with VTK.
Author: alessia-z
Author-email: alessia-z <alessia.zanni@dvisionlab.com>
Requires-Dist: scipy>=1.13.1
Requires-Dist: vtk>=9.5.0
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# Vessel Centerline

Compute vessel centerline with [VTK](https://vtk.org/).

## Goal

A python package to extract the centerline of blood vessels starting from 3D model. This is the workflow followed by the provided scripts:

- Load the 3D model (`.stl` of `.vtp` file).
- Cap the holes in surface.
- Set the input point and the target points or find them automatically.
- Compute the centerline from the source to each target point.
- Save the centerline to file.

## Package

## API

### Modules:

The API is organized around these modules:

- `cap_polydata`: functions to perform 3D model capping.
- `centerline_geometry`: functions to compute geometric analysis of the centerline.
- `find_points`: functions to find the center points of the cap surfaces, to be used as target and source points.
- `polydata_centerlines`: functions to extract centerlines from a single source to multiple targets.
- `centerline_io`: input/output functions and complete workflow to extract the centerline: from model loading to output file saving.

In each module you'll find documented functions. You can get the help for each function using the python build-in `help` function or via your editor, if supports doc strings:

```
$ python3
>>> import vessel_centerline.module
>>> help(vessel_centerline.module.function)
```

### Prerequisites

- Python3
- pip

## Installation:

**Install with pip**

```
pip install vessel-centerline
```

**Install from the repository (using uv)**

clone the repository:

```
git clone [github remote url]
cd vessel_centerline
```

build the package:

```
uv build
```

install the package locally:

```
pip install dist/vessel_centerline-0.1.0-py3-none-any.whl
```

**Import in your code**

```
import vessel_centerline
```

## Usage examples

- examples/cap_surface.py: example on how to cap the polydata surface and save the model.
- examples/points_search.py: example on how to find points coordinates that can be used ad source and targets for the centerline.
- examples/centerline_and_geometry.py: example on how to compute the centarline and the geometric analysis.

## Command-line interface (CLI)

### Prerequisites

- Python3
- uv

### Clone the repository:

```
git clone [github remote url]
cd vessel_centerline
```

### Usage

There are some arguments to specify:

- `--search-points` : this option allows to search for points coordinates that can be used as input and targets for the centarline. Using this option, the centerline is not calculated, it just logs the coordinate of each point found.
- `--save-output-files` : save the results of centerline and geometric computation to output files.
- `--model-path` : path to input 3D model (`.stl` or `.vtp`).
- `--source-point` : list of source point coordinates [x, y, z] (only one pont).
- `--target-points` : list of target points coorfinates [[x, y, z], [x, y, z], ...] (one or more points).
- `--source-orientation` : used to set the source point if the points are extracted automatically. The argument must be one of the following: "up", "down", "left", "right".

You have to pass either `--source-point` and `--target-points` or `--source-orientation`, both are not accepted. Otherwise you should pass `--search-points` to find the points coordinates.

#### Run this command for points search:

```
uv run python main.py --model-path /path/to/model --search-points
```

#### Run one of these commands for centerline computation:

```
uv run python main.py --model-path /path/to/model --source-orientation "up"|"down"|"left"|"right"
```

or

```
uv run python main.py --model-path /path/to/model --source-point "[x, y, z]" --target-points "[x, y, z]" "[x, y, z]" ...
```

### Output

At the end of the script the centerline is saved as `.vtp` file.
File path and file name are the same as those of the input model, only the extension `.centerline.vtp` is added to identify the centerline.
The output can be checked and visualized with visualization engines such as [ParaView](https://www.paraview.org/).
