Skip to content

Python ​

The furca Python package exposes the whole library with NumPy arrays and optional PyVista conversions, for scripts and notebooks.

Installation ​

From the repository, in a virtual environment with Python ≥ 3.10:

sh
pip install maturin
cd crates/furca-py
maturin develop --release          # or: maturin build --release && pip install target/wheels/*.whl
pip install pyvista                # optional, for to_pyvista() and plot()

A tour ​

python
import numpy as np
import furca

# Encode: from a path, a furca.Mesh, a (vertices, faces) pair or a pyvista.PolyData.
enc = furca.encode("vessel.vtp")
print(enc)                               # summary: geometry, model, residual, timings
enc.diagnostics["residual"]["mean"]      # what the encoder measured
enc.params                               # the parameters it used

# Parameters: keyword shortcuts or a (partial) dictionary with the TOML layout.
enc = furca.encode("vessel.vtp", theta_size=32, knots="uniform")
enc = furca.encode("vessel.vtp", params={"centerline": {"stiffness": 1.0}})

# Geometry.
tau, points = enc.centerline(200)
phi = np.linspace(0, 2 * np.pi, 8)
enc.wall(0.5, phi)                                     # wall points (x, y) in the section plane
enc.wall_points(0.5, phi)                              # the same points in space, (8, 3)
enc.radius(0.5, phi)                                   # their distance from the centerline
enc.equivalent_radius(0.5)                             # √(area / π) of the section
coords = enc.to_vcs(points_on_the_wall)                # (τ, θ, ρ), shape (n, 3)
back = enc.to_cartesian(coords)
enc.wall_coordinates(points_on_the_wall)               # (τ, φ, d): angle and signed distance to the wall

# Meshes.
surface = enc.to_mesh(theta_res=128)                   # furca.Mesh
surface.save("encoded.vtp")
grid = enc.ogrid(theta_res=48, radial_layers=12)       # furca.VolumeMesh
grid.save("lumen.vtu")

# PyVista.
enc.to_pyvista().plot(scalars="tau")
enc.plot()

# Documents.
enc.save("vessel.furca")
enc = furca.load("vessel.furca")

Branched vessels ​

A surface with more than two open boundaries encodes to a furca.Vessel: a tree of branches, each an Encoding (see Branched vessels).

python
v = furca.encode("aortic_arch.vtp")     # furca.Vessel
print(v)                                 # the tree, every branch, the residual
v.junctions                              # parent, children, apex, through
trunk = v.branches[0]                    # an Encoding: centerline, wall, coordinates
branch, coords = v.coordinates(points)   # the branch that dominates, and its (τ, θ, ρ)
v.field(points)                          # the implicit lumen: < 0 inside, 0 on the wall
v.to_mesh(spacing=0.1).save("model.vtp")
v.plot(color_by="branch")
v.save("arch.furca")

Inspecting the stages of the encoder ​

furca.encode_traced also returns the intermediate results: the open wall, the harmonic field, the level-set centroids, the fitted centerline, the vessel coordinates and the harmonic angle of every vertex.

python
enc, trace = furca.encode_traced("vessel.vtp")
trace.wall.to_pyvista(u=trace.harmonic, phi=trace.angle).plot(scalars="phi")

Cohorts ​

python
aligned, model = furca.cohort(paths, alignment="rigid", tau_size=24, centerline_size=14)
model.explained                    # variance explained by each mode
model.scores                       # subjects × modes, in standard deviations
model.instance([2.0]).plot()       # +2 SD along the first mode

The steps can also be run separately with furca.encode_cohort, furca.align and furca.fit_shape_model; see Cohorts and shape models. A cohort of branched vessels gives a furca.Vessel per subject and per instance. To compare its shapes vertex by vertex, carry one triangulation of the mean onto each of them:

python
mean = model.instance()
mesh = mean.to_mesh()
shapes = [mean.carry(mesh, model.instance([b])) for b in (-1.0, 0.0, 1.0)]  # same faces

Synthetic vessels ​

python
mesh = furca.synth("stenosis")
tree = furca.synth("bifurcation", spacing=0.5)   # branched: furca.synth_tree_presets()
spec = furca.synth_spec("arc")          # a dictionary: path and profile
spec["profile"]["ellipticity"] = 0.15
mesh = furca.synth(spec, rings=400, segments=64)
axis = furca.synth_centerline("arc")    # the exact centerline, (1000, 3)

Plots ​

furca.plot draws encodings, their parts and shape models. 3D views use PyVista: they show the view (in a notebook, as an interactive scene) or, with show=False, return the pyvista.Plotter to add more to it. 2D charts use Matplotlib: they draw into ax (a new figure when omitted) and return the axes.

python
import furca.plot as fp

fp.vessel(enc)                          # surface, centerline and tilted sections
fp.vessel(enc, color_by="fold")         # also "radius", "tau", "phi"
fp.error(mesh, enc)                     # input coloured by its distance to the model
fp.wall_map(enc, quantity="relative")   # unrolled wall over (arc length, φ); "radius", "relative", "fold"
fp.sections(enc, 6)                     # section outlines in their own planes
fp.diagnostics(enc)                     # mean radius, section tilt and fold along the vessel
fp.profiles(encodings, labels=names)    # equivalent radius along several vessels

fp.explained(model)                     # variance per mode
fp.scores(model, groups={"0015_H_AO_COA": "coarctation"})
fp.modes(model, count=3, sd=2)          # mean and ±2 SD along each mode
FunctionShows
vesselThe encoded surface (plain or coloured by radius, tau, phi or fold), the centerline and some cross-sections.
errorAn input surface coloured by its distance to the encoding, in % of the radius.
wall_mapThe wall unrolled (arc length × φ): the distance from the centerline, that distance relative to the equivalent radius of the section, or the fold.
sectionsCross-section outlines in their own planes, coloured by position.
diagnosticsMean radius, tilt of the sections and largest fold of each section, along the vessel.
profilesEquivalent radius along one or several vessels, against τ or arc length.
explained, scores, modesA shape model: explained variance, subjects in the plane of two modes, the modes in 3D.

The data behind them is also available directly: enc.sections(tau) gives the centre, plane normal, in-plane axes and centerline tangent of each section, and enc.fold(tau, phi) the fold on the wall.

Notebooks ​

notebooks/ in the repository has two worked examples on the real segments of data/, stored with their outputs: encoding one vessel (01-encoding.ipynb) and a shape model of six descending aortas (02-cohort.ipynb).

Reference ​

Object / functionPurpose
encode, encode_tracedEncode a surface.
loadRead a .furca document (an Encoding or a ShapeModel).
EncodingProperties diagnostics, params, domain, length, reference, control_points, wall_coefficients (radial and tangential), tau_breakpoints; methods wall, wall_points, radius, equivalent_radius, section_size, fold, sections, centerline, to_vcs, to_cartesian, wall_coordinates, feature_vector, with_features, same_structure, to_mesh, ogrid, to_pyvista, centerline_to_pyvista, plot, save.
Meshvertices, faces, cell_labels, boundary_count, save, to_pyvista.
VolumeMeshpoints, cells, point_data, region, min_scaled_jacobian, save, to_pyvista.
encode_cohort, align, fit_shape_model, cohortCohort pipeline.
ShapeModelsubjects, mean, modes, variances, explained, scores, instance, save.
read_mesh, synth, synth_spec, synth_presets, synth_centerline, distances, default_paramsUtilities.
furca.plotPlots (see above).

furca — parametric models of blood vessels.