Appearance
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 modeThe 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 facesSynthetic 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| Function | Shows |
|---|---|
vessel | The encoded surface (plain or coloured by radius, tau, phi or fold), the centerline and some cross-sections. |
error | An input surface coloured by its distance to the encoding, in % of the radius. |
wall_map | The wall unrolled (arc length × φ): the distance from the centerline, that distance relative to the equivalent radius of the section, or the fold. |
sections | Cross-section outlines in their own planes, coloured by position. |
diagnostics | Mean radius, tilt of the sections and largest fold of each section, along the vessel. |
profiles | Equivalent radius along one or several vessels, against τ or arc length. |
explained, scores, modes | A 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 / function | Purpose |
|---|---|
encode, encode_traced | Encode a surface. |
load | Read a .furca document (an Encoding or a ShapeModel). |
Encoding | Properties 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. |
Mesh | vertices, faces, cell_labels, boundary_count, save, to_pyvista. |
VolumeMesh | points, cells, point_data, region, min_scaled_jacobian, save, to_pyvista. |
encode_cohort, align, fit_shape_model, cohort | Cohort pipeline. |
ShapeModel | subjects, mean, modes, variances, explained, scores, instance, save. |
read_mesh, synth, synth_spec, synth_presets, synth_centerline, distances, default_params | Utilities. |
furca.plot | Plots (see above). |