Metadata-Version: 2.4
Name: stentfit
Version: 0.1.1
Summary: Semi-automated virtual stent implantation via contact simulation
License: MIT
License-File: LICENSE
Author: Vural Aktas
Author-email: vuralaktas6741@gmail.com
Requires-Python: >=3.13,<3.14
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Requires-Dist: beamme (>=0.2.0,<0.3.0)
Requires-Dist: fourcipp (>=1.132.0)
Requires-Dist: gmsh (>=4.15.0)
Requires-Dist: matplotlib (>=3.11.0)
Requires-Dist: numpy (>=2.5.1)
Requires-Dist: pandas (>=3.0.3)
Requires-Dist: plotly (>=6.8.0)
Requires-Dist: scikit-image (>=0.26.0)
Requires-Dist: scikit-learn (>=1.9.0)
Requires-Dist: scipy (>=1.18.0)
Requires-Dist: trimesh (>=4.12.2)
Description-Content-Type: text/markdown

# stentFIT

[![Documentation Status](https://readthedocs.org/projects/stentfit/badge/?version=latest)](https://stentfit.readthedocs.io/en/latest/?badge=latest)

Semi-automated virtual stent implantation with mixed-dimensional modelling

Full documentation, including the API reference and workflow diagrams, is hosted at [stentfit.readthedocs.io](https://stentfit.readthedocs.io/en/latest/).

`stentFIT` turns a stent surface mesh (`.stl`) into a 1D beam-element model ready for beam-to-solid contact simulation. It samples the stent surface, detects its rings, extracts a 2D skeleton per ring, wraps that skeleton back onto the 3D mid-surface, fits a B-spline to each strut curve, and meshes the result into Simo–Reissner beams with [BeamMe](https://beamme-py.github.io/beamme/). Extracting the stent's 1D wireframe is a semi-automated process: it allows manual edits of intermediate steps such as ring detection and 2D skeletonisation. It also provides a smoke test that verifies the quality of the 1D stent model inside a generated pipe-like 3D vessel.

## Installation

Requires **Python 3.13** (pinned to match [BeamMe](https://beamme-py.github.io/beamme/)'s supported range) and **Git** installed and available on your `PATH` — BeamMe uses the `git` executable to write commit metadata into generated 4C input files, and raises an error at runtime if it can't find one. Git is not a Python package, so `pip`/`poetry` cannot install it for you — the steps below install it via conda alongside everything else.

**Option A — Just use the package**

Same steps on macOS, Linux, and Windows (PowerShell) — on Windows, just make sure to run `python`/`pip`, not the `py` launcher, which ignores the active conda environment:

```bash
conda create -n stentfit-env python=3.13
conda activate stentfit-env
conda install -c conda-forge git
pip install stentfit
```

Core dependencies such as `beamme` (stent beam meshing and artery solid meshing), `gmsh` (artery solid meshing), and `fourcipp` are installed automatically by `pip`. Running the generated simulation input files additionally requires a compiled **4C** executable, which is not included in this package.

**Option B — Clone the repo and start developing**

```bash
git clone https://github.com/VuralAktas/stentFIT.git
cd stentFIT
conda env create -f environment.yml   # Python 3.13 + pip + git
conda activate env_stentfit
poetry install                        # installs stentfit + all dependency groups
```

This path pulls `git` in automatically via `environment.yml`, and also gives you the example notebooks, tests, and locked dependency versions (`poetry.lock`) matching the rest of the project.

## What it does & How to use it

**1. Stent skeletonisation** ([`examples/stent_skeleton.ipynb`](examples/stent_skeleton.ipynb))

- Sample a point cloud from the stent STL and align it to its centreline axis.
- Detect rings and skeletonise each ring in 2D (optional auto-tuning + manual edits).
- Wrap the 2D skeleton onto the local mid-surface, clean up the graph, and fit a B-spline per strut.
- Mesh the fitted splines into a 1D Simo–Reissner beam mesh with BeamMe.

Each stage writes `skeleton_points.csv`, `skeleton_splines.json`, `stent_features.json`, and interactive HTML views into the output directory.

![Unrolled 2D skeleton with per-ring tuning diagnostics](https://raw.githubusercontent.com/VuralAktas/stentFIT/main/docs/images/skeleton_splines_2d.png)

**2. Test artery generation & simulation setup** ([`examples/test_sim_generation.ipynb`](examples/test_sim_generation.ipynb))

A synthetic/parametric smoke test exercises the full mixed-dimensional chain end-to-end:

- Generate a parametric test artery (straight / curved / S-bend) sized to the stent, and mesh its wall as a 3D solid with GMSH.
- Warp the stent beam mesh onto the artery centreline.
- Check beam-to-solid coupling compatibility (stiffness ratio, element-size ratios) and visualize the stent inside the artery via Paraview.
- Tie the beam mesh to the artery lumen and write a schema-validated 4C simulation input file with a quasi-static radial expansion load.

This confirms the stent-to-artery mapping and 4C input generation work end-to-end, using placeholder materials and tied meshtying rather than real contact such as full deployment physics (contact, HGO-C artery material, elasto-plastic beam bending) is planned but not yet implemented.

![Stent beam mesh warped into a curved artery, viewed in ParaView](https://raw.githubusercontent.com/VuralAktas/stentFIT/main/docs/images/paraview_stent_artery.png)

## License

`stentfit` was created by Vural Aktas. It is licensed under the terms of the MIT license.

## Contributing

Interested in contributing? Reach out at [vural.aktas@rwth-aachen.de](mailto:vural.aktas@rwth-aachen.de).

## Credits

`stentfit` was created with [`cookiecutter`](https://cookiecutter.readthedocs.io/en/latest/)
and the `py-pkgs-cookiecutter` [template](https://github.com/py-pkgs/py-pkgs-cookiecutter).

