Appearance
Python API
The furca package: encoding, vessel coordinates, cohorts, volume meshes and plots. See the Python guide for how the pieces fit together. This page is generated from the package (docs/reference/make_api.py).
Functions
Encoding a vessel
furca.read_mesh
python
furca.read_mesh(path: str | os.PathLike) -> MeshReads a surface mesh (.vtp, .vtk, .stl, .obj); STL vertices are welded.
furca.encode
python
furca.encode(
mesh: MeshLike,
params: dict | None = None,
**overrides,
) -> 'Encoding | Vessel'Encodes a vessel surface: an Encoding if it is unbranched (two open boundaries), a Vessel (a tree of branches) if it is branched.
params is a (partial) parameter dictionary; keyword shortcuts: centerline_size, tau_size, theta_size, smoothing ("auto" or a number), knots ("adaptive" or "uniform"), ends ("boundary" or "centroid"), inlet ("largest", "smallest" or a point) and reference (a direction).
furca.encode_traced
python
furca.encode_traced(
mesh: MeshLike,
params: dict | None = None,
samples: int = 200,
**overrides,
) -> tuple[Encoding, Trace]Like encode, also returning the intermediate results of every stage.
furca.load
python
furca.load(path: str | os.PathLike) -> 'Encoding | Vessel | ShapeModel'Reads a .furca document.
furca.default_params
python
furca.default_params(kind: str = 'encode') -> dictDefault parameters as a dictionary: "encode", "cohort" or "ogrid".
furca.distances
python
furca.distances(a: MeshLike, b: MeshLike) -> np.ndarrayPoint-to-surface distances from the vertices of a to the surface b.
Cohorts and shape models
furca.cohort
python
furca.cohort(
meshes: Sequence[MeshLike],
names: Sequence[str] | None = None,
alignment: str = 'rigid',
variance_fraction: float = 0.99,
params: dict | None = None,
**overrides,
) -> 'tuple[list[Encoding | Vessel], ShapeModel]'Encodes, aligns and models a cohort in one call, branched or not. Returns the aligned vessels and the shape model.
furca.encode_cohort
python
furca.encode_cohort(
meshes: Iterable[MeshLike],
params: dict | None = None,
**overrides,
) -> 'list[Encoding | Vessel]'Encodes meshes with a shared structure, so that feature vectors correspond.
The vessels must have the same tree of branches: all unbranched (each subject is an Encoding), or all with the same junctions (each a Vessel). params follows the cohort parameter layout (encode, alignment, model); keyword shortcuts apply to encode.
furca.align
python
furca.align(
encodings: 'Sequence[Encoding | Vessel]',
mode: str = 'rigid',
**params,
) -> 'tuple[list[Encoding | Vessel], list[dict]]'Generalized Procrustes alignment (mode: "none", "rigid" or "similarity"), on points of the wall of every branch. Returns the aligned vessels and the similarity applied to each.
furca.fit_shape_model
python
furca.fit_shape_model(
encodings: 'Sequence[Encoding | Vessel]',
names: Sequence[str] | None = None,
variance_fraction: float = 0.99,
) -> ShapeModelPrincipal component analysis of aligned vessels with a shared structure.
Synthetic vessels
furca.synth
python
furca.synth(
preset: str | dict,
rings: int = 400,
segments: int = 64,
jitter: float = 0.3,
spacing: float = 0.5,
) -> MeshA synthetic vessel with known geometry.
preset is a preset name (see synth_presets) or a specification dictionary {"path": {...}, "profile": {...}}, as returned by synth_spec. The branched presets (bifurcation, side-branch, crescent-branch, terminal-aneurysm) are triangulated with faces about spacing across; the others on a rings × segments grid.
furca.synth_spec
python
furca.synth_spec(preset: str) -> dictThe specification of a preset, to modify and pass to synth. Paths: straight (length), arc (radius, angle), helix (radius, pitch, turns), wave (length, amplitude, waves). Profile: radius, taper, ellipticity, twist, stenosis (position, width, severity, eccentricity) or None.
furca.synth_presets
python
furca.synth_presets() -> list[str]Names of the synthetic presets of unbranched vessels.
furca.synth_tree_presets
python
furca.synth_tree_presets() -> list[str]Names of the synthetic presets of branched vessels (see synth).
furca.synth_centerline
python
furca.synth_centerline(
preset: str | dict,
samples: int = 1000,
) -> np.ndarrayPoints of the exact centerline of a synthetic tube, shape (samples, 3).
Other
furca.SAC_LEVEL
python
furca.SAC_LEVEL(…)int([x]) -> integer int(x, base=10) -> integer
Convert a number or string to an integer, or return 0 if no arguments are given. If x is a number, return x.int(). For floating-point numbers, this truncates towards zero.
If x is not a number or if base is given, then x must be a string, bytes, or bytearray instance representing an integer literal in the given base. The literal can be preceded by '+' or '-' and be surrounded by whitespace. The base defaults to 10. Valid bases are 0 and 2-36. Base 0 means to interpret the base from the string as an integer literal.
int('0b100', base=0) 4
furca.open_wall
python
furca.open_wall(mesh: MeshLike, caps: dict | None = None) -> MeshThe open wall of a surface, as the encoder sees it: an open mesh as it is (without unused vertices), a closed one without its caps (from a cap label array, the flat faces of a face array such as ModelFaceID, or detected planar regions). caps overrides the caps parameters of the encoder.
furca.wall_flow
python
furca.wall_flow(
mesh: MeshLike,
params: dict | None = None,
) -> tuple[Mesh, np.ndarray]The open wall of a vessel and the flow at each of its vertices: how strongly the harmonic flow from the inlet to the outlets passes by it, relative to its level (about one along the branches, near zero in dead ends such as aneurysm sacs, where saccular lobes are sought). params override the encoder parameters.
Classes
furca.Encoding
python
furca.Encoding(native)An encoded unbranched vessel: centerline, frame reference and wall.
Encoding.diagnostics property
What the encoder measured (sizes, residuals, timings), or None.
Encoding.params property
Encoder parameters used, or None.
Encoding.domain property
Longitudinal extent (tau_a, tau_b) of the wall.
Encoding.length property
Length of the centerline (without end extensions).
Encoding.reference property
Unit vector defining theta = 0 at tau = 0.
Encoding.control_points property
Centerline control points, shape (n, 3).
Encoding.wall_coefficients property
Wall coefficients of x and y, shape (2, n_tau, n_theta).
Encoding.tau_breakpoints property
Knot breakpoints of the longitudinal wall basis, in tau.
Encoding.feature_vector
python
Encoding.feature_vector(self) -> np.ndarrayFlat feature vector: control points, reference direction, section tilt (if any), wall coefficients.
Encoding.with_features
python
Encoding.with_features(self, features: np.ndarray) -> 'Encoding'An encoding with this structure and the given feature vector.
Encoding.same_structure
python
Encoding.same_structure(self, other: 'Encoding') -> boolWhether the feature vectors of both encodings correspond component by component.
Encoding.wall
python
Encoding.wall(self, tau, phi) -> np.ndarrayWall points in the coordinates (x, y) of their section planes at (broadcast) tau and phi, shape (..., 2).
Encoding.wall_points
python
Encoding.wall_points(self, tau, phi) -> np.ndarrayWall points at (broadcast) tau and phi, shape (..., 3).
Encoding.radius
python
Encoding.radius(self, tau, phi) -> np.ndarrayDistance from the centerline to the wall at (broadcast) tau and phi.
Encoding.fold
python
Encoding.fold(self, tau, phi) -> np.ndarrayFold of the vessel coordinates on the encoded wall at (broadcast) tau and phi: neighbouring cross-sections meet where it reaches one.
Encoding.sections
python
Encoding.sections(
self,
tau,
) -> tuple[np.ndarray, np.ndarray, np.ndarray, np.ndarray, np.ndarray]Cross-sections at each tau: (center, normal, U, V, tangent), each of shape (n, 3). U and V span the section plane (θ = 0 and θ = π/2); tangent is the centerline tangent, so the tilt of a section is the angle between normal and tangent.
Encoding.equivalent_radius
python
Encoding.equivalent_radius(self, tau) -> np.ndarrayRadius of the circle with the area of the cross-section, at each tau.
Encoding.section_size
python
Encoding.section_size(self, tau) -> tuple[np.ndarray, np.ndarray]Area and perimeter of the cross-section at each tau.
Encoding.centerline
python
Encoding.centerline(
self,
samples: int = 200,
) -> tuple[np.ndarray, np.ndarray]Samples of the (extended) centerline over the wall domain: (tau, points).
Encoding.to_vcs
python
Encoding.to_vcs(self, points: np.ndarray) -> np.ndarrayVessel coordinates (tau, theta, rho) of Cartesian points, shape (n, 3).
Encoding.wall_coordinates
python
Encoding.wall_coordinates(self, points: np.ndarray) -> np.ndarrayWall coordinates (tau, phi, d) of Cartesian points, shape (n, 3): the section through the point, the harmonic angle of the nearest point of the wall in it and the signed distance to that point (negative inside).
Encoding.to_cartesian
python
Encoding.to_cartesian(self, coords: np.ndarray) -> np.ndarrayCartesian points of vessel coordinates (tau, theta, rho), shape (n, 3).
Encoding.to_mesh
python
Encoding.to_mesh(
self,
theta_res: int = 96,
tau_res: int | None = None,
) -> MeshTriangulated surface with theta_res vertices per ring.
Encoding.ogrid
python
Encoding.ogrid(self, **params) -> 'VolumeMesh'Structured hexahedral volume mesh of the lumen. Keyword arguments: tau_res, theta_res (multiple of 8), radial_layers, core_fraction, core_roundness, wall_growth and nodes ("auto", "algebraic" or "smoothed": how the nodes of the sections are placed).
Encoding.to_pyvista
python
Encoding.to_pyvista(self, theta_res: int = 96, tau_res: int | None = None)The encoded surface as pyvista.PolyData with tau and phi arrays.
Encoding.centerline_to_pyvista
python
Encoding.centerline_to_pyvista(self, samples: int = 200)The centerline as a pyvista.PolyData polyline with tau and equivalent_radius.
Encoding.plot
python
Encoding.plot(self, **kwargs)3D view of the vessel with its centerline and some cross-sections; keyword arguments go to furca.plot.vessel.
Encoding.save
python
Encoding.save(self, path: str | os.PathLike) -> NoneWrites a .furca document.
Encoding.summary
python
Encoding.summary(self) -> strEverything relevant about the encoding, as aligned text: geometry, model, residual of the wall fit and timings (the same report as furca encode).
furca.Mesh
python
furca.Mesh(vertices: np.ndarray, faces: np.ndarray)A triangle surface mesh.
Mesh.vertices property
Vertex coordinates, shape (n, 3).
Mesh.faces property
Triangles as vertex indices, shape (m, 3).
Mesh.cell_labels property
Integer cell arrays (for example CapID).
Mesh.boundary_count
python
Mesh.boundary_count(self) -> intNumber of open boundary loops.
Mesh.save
python
Mesh.save(
self,
path: str | os.PathLike,
point_data: dict[str, np.ndarray] | None = None,
) -> NoneWrites the mesh; the format follows the extension.
Mesh.to_pyvista
python
Mesh.to_pyvista(self, **point_data: np.ndarray)The mesh as pyvista.PolyData.
furca.ShapeModel
python
furca.ShapeModel(native)A linear statistical shape model x = mean + sum_k b_k sqrt(lambda_k) phi_k.
ShapeModel.subjects property
Names of the subjects the model was built from, in the order of scores.
ShapeModel.variances property
Variance of the cohort along each mode (the eigenvalues), largest first.
ShapeModel.explained property
Fraction of the total variance explained by each mode.
ShapeModel.mean property
Mean feature vector.
ShapeModel.modes property
Unit-norm modes, shape (k, features).
ShapeModel.scores property
Subject coordinates in standard deviations, shape (subjects, k).
ShapeModel.instance
python
ShapeModel.instance(self, b: Sequence[float] = ()) -> 'Encoding | Vessel'The shape at coordinates b (standard deviations; missing ones are 0): an Encoding for a model of unbranched vessels, a Vessel otherwise.
ShapeModel.save
python
ShapeModel.save(self, path: str | os.PathLike) -> NoneWrites a .furca document.
ShapeModel.summary
python
ShapeModel.summary(self) -> strSubjects, size of the feature vector and variance explained by each mode.
furca.Vessel
python
furca.Vessel(native)An encoded branched vessel: a tree of branches, each an Encoding (a tube), joined at junctions by a smooth union of their lumens.
Branch 0 starts at the inlet and every child comes after its parent. At a junction either the parent continues (through: side branches leave a trunk) or it ends and its children start (a bifurcation); apex is the flow divider.
Vessel.diagnostics property
What the encoder measured (residuals overall and at junctions, per branch, timings), or None.
Vessel.params property
Encoder parameters used, or None.
Vessel.branches property
The branches, each as an Encoding over its own wall domain.
Vessel.tree property
{"branches": [{"radius", "start", "end", "domain", "angle"}], "junctions": [{"parent", "children", "apex", "through"}], "lobes": [{"center", "radius", "degree", "frame"}], "smoothness"}; a branch's start and end name its junction and the window of tau over which it fades in or out, and its angle is "polar" or "harmonic", the angle its wall is parametrized by. A lobe is a saccular dead end of the vessel (an aneurysm sac): its centre, mean radius, the degree of its spherical harmonics and its frame.
Vessel.lobes property
The saccular lobes: center, radius, degree, frame, the coefficients a_lm of their spherical harmonics (l = 0, 1, … and, for each, m = -l, …, l) and their spectrum, the power Σ_m a_lm² at every degree l.
Vessel.sac
python
Vessel.sac(self, lobe: int = 0, level: int = 5) -> dict | NoneThe sac of a lobe: the part of its wall outside every branch, sampled on an icosphere of level subdivisions, with its morphology. {"mesh": Mesh, "neck": array (n, 2, 3) of the segments of the neck, "neck_center", "neck_normal" (from the vessel into the sac), "morphology": {"height", "max_height", "max_diameter", "neck_diameter", "parent_diameter", "volume", "area", "aspect_ratio", "size_ratio", "nonsphericity", "undulation", "ellipticity"}}, or None if the lobe lies inside the branches.
Vessel.with_lobe_degree
python
Vessel.with_lobe_degree(self, degree: int) -> 'Vessel'The vessel with every lobe described by its spherical harmonics up to degree only: its shape at a coarser scale.
Vessel.parts
python
Vessel.parts(self, points: np.ndarray) -> np.ndarrayThe part of the model that dominates at each point: branch b, lobe j as len(branches) + j, and -1 where nothing is present.
Vessel.junctions property
The junctions: parent, children, apex and through.
Vessel.to_mesh
python
Vessel.to_mesh(
self,
spacing: float | None = None,
theta_res: int = 48,
) -> MeshThe wall, triangulated with faces about spacing across (default: the spacing of theta_res vertices around the narrowest branch).
Vessel.carry
python
Vessel.carry(self, mesh: MeshLike, other: 'Vessel') -> MeshA triangulation of this vessel's wall carried onto other, a vessel with the same structure (for example another shape of a ShapeModel): the same faces, every vertex at the same coordinates of the same branch, then moved onto the wall of other. Meshes carried from one mesh of the mean correspond vertex by vertex.
Vessel.to_pyvista
python
Vessel.to_pyvista(self, spacing: float | None = None, theta_res: int = 48)The wall as pyvista.PolyData with branch, tau and theta arrays.
Vessel.coordinates
python
Vessel.coordinates(
self,
points: np.ndarray,
) -> tuple[np.ndarray, np.ndarray]Vessel coordinates of Cartesian points in the branch that dominates at each: (branch, coords) with coords of shape (n, 3) holding (tau, theta, rho); branch -1 (and NaN) where no branch is present.
Vessel.field
python
Vessel.field(self, points: np.ndarray) -> np.ndarrayThe implicit function of the lumen: negative inside, zero on the wall.
Vessel.plot
python
Vessel.plot(self, **kwargs)3D view of the vessel with the centerlines of its branches; keyword arguments go to furca.plot.vessel.
Vessel.save
python
Vessel.save(self, path: str | os.PathLike) -> NoneWrites a .furca document.
Vessel.summary
python
Vessel.summary(self) -> strThe tree, its branches and the residual of the fit, as aligned text (the same report as furca encode).
furca.VolumeMesh
python
furca.VolumeMesh(native)A hexahedral volume mesh with per-node vessel coordinates.
VolumeMesh.points property
Coordinates of the mesh nodes, shape (nodes, 3).
VolumeMesh.cells property
Hexahedra in VTK vertex order, shape (m, 8).
VolumeMesh.point_data property
tau, phi and relative_radius (0 at the centre, 1 on the wall).
VolumeMesh.region property
Per cell: 0 for the central block, 1 for the ring.
VolumeMesh.min_scaled_jacobian
python
VolumeMesh.min_scaled_jacobian(self) -> floatSmallest scaled Jacobian of the hexahedra (1 for a perfect cube; below 0 a cell is inverted).
VolumeMesh.save
python
VolumeMesh.save(self, path: str | os.PathLike) -> NoneWrites a .vtu file.
VolumeMesh.to_pyvista
python
VolumeMesh.to_pyvista(self)The mesh as pyvista.UnstructuredGrid.
Plots: furca.plot
Plots of encodings, of their parts and of shape models.
3D views use PyVista. They draw into plotter (a new pyvista.Plotter when omitted); with show=True (the default) they show it and return what Plotter.show returns, which a notebook displays, otherwise they return the plotter so that more can be added to it.
2D charts use Matplotlib. They draw into ax (a new figure when omitted) and return the axes.
Lengths along the vessel are arc lengths of the centerline, τ · length.
furca.plot.vessel
python
furca.plot.vessel(
enc: Encoding,
*,
color_by: str | None = None,
sections: int | Sequence[float] = 8,
centerline: bool = True,
opacity: float | None = None,
theta_res: int = 96,
cmap: str = 'viridis',
plotter=None,
show: bool = True,
)The encoded vessel with its centerline and some cross-sections.
color_by: None (plain), "radius" (distance from the centerline), "tau", "phi" or "fold" (how close the sections come to crossing; they cross at one). sections: how many sections to outline (evenly spaced), or their τ. The outlines are the encoded wall on each section plane, so tilted sections show as tilted rings.
A branched furca.Vessel shows its wall (color_by: None or "branch"), the centerline of every branch and the apex of every junction.
furca.plot.error
python
furca.plot.error(
mesh: Mesh,
enc: Encoding,
*,
clim: tuple[float, float] | None = None,
cmap: str = 'viridis',
plotter=None,
show: bool = True,
)The input surface coloured by its distance to the encoded surface, in % of the mean radius. The colour range defaults to the 99th percentile.
furca.plot.modes
python
furca.plot.modes(
model: ShapeModel,
count: int = 2,
sd: float = 2.0,
*,
theta_res: int = 64,
show: bool = True,
**plotter_kwargs,
)The first count modes of a shape model, side by side: the mean (grey) and −sd (blue) and +sd (red) standard deviations along each mode.
furca.plot.wall_map
python
furca.plot.wall_map(
enc: Encoding,
*,
quantity: str = 'radius',
tau_res: int = 400,
theta_res: int = 180,
cmap: str | None = None,
ax=None,
)The wall unrolled: arc length along the vessel against the harmonic angle φ.
quantity: "radius" (distance from the centerline to the wall), "relative" (that distance over the equivalent radius of its section: the shape of the sections without their size) or "fold".
furca.plot.sections
python
furca.plot.sections(
enc: Encoding,
taus: int | Sequence[float] = 6,
*,
theta_res: int = 180,
cmap: str = 'viridis',
ax=None,
)Outlines of cross-sections in their own planes (the axis U to the right), coloured by position along the vessel.
furca.plot.profiles
python
furca.plot.profiles(
encodings: Encoding | Iterable[Encoding],
labels: Sequence[str] | None = None,
*,
x: str = 'tau',
samples: int = 300,
colors: Sequence[str] | None = None,
ax=None,
)Mean radius of the sections along one or several vessels; x is "tau" or "length" (arc length).
furca.plot.diagnostics
python
furca.plot.diagnostics(
enc: Encoding,
*,
samples: int = 400,
theta_res: int = 96,
axes=None,
)Three panels along the vessel: mean radius, tilt of the sections with respect to the normal planes of the centerline, and largest fold of each section.
furca.plot.explained
python
furca.plot.explained(model: ShapeModel, *, ax=None)Variance explained by each mode of a shape model (bars) and cumulated (line).
furca.plot.scores
python
furca.plot.scores(
model: ShapeModel,
*,
modes: tuple[int, int] = (1, 2),
groups: Mapping[str, str] | Sequence[str] | None = None,
ax=None,
)Subjects of a shape model in the plane of two modes (numbered from 1), in standard deviations. groups gives each subject a group (by name, or in subject order), shown by colour.