Skip to content

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) -> Mesh

Reads 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') -> dict

Default parameters as a dictionary: "encode", "cohort" or "ogrid".

furca.distances ​

python
furca.distances(a: MeshLike, b: MeshLike) -> np.ndarray

Point-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,
) -> ShapeModel

Principal 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,
) -> Mesh

A 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) -> dict

The 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.ndarray

Points 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) -> Mesh

The 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.ndarray

Flat 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') -> bool

Whether the feature vectors of both encodings correspond component by component.

Encoding.wall ​

python
Encoding.wall(self, tau, phi) -> np.ndarray

Wall 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.ndarray

Wall points at (broadcast) tau and phi, shape (..., 3).

Encoding.radius ​

python
Encoding.radius(self, tau, phi) -> np.ndarray

Distance from the centerline to the wall at (broadcast) tau and phi.

Encoding.fold ​

python
Encoding.fold(self, tau, phi) -> np.ndarray

Fold 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.ndarray

Radius 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.ndarray

Vessel coordinates (tau, theta, rho) of Cartesian points, shape (n, 3).

Encoding.wall_coordinates ​

python
Encoding.wall_coordinates(self, points: np.ndarray) -> np.ndarray

Wall 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.ndarray

Cartesian 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,
) -> Mesh

Triangulated 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) -> None

Writes a .furca document.

Encoding.summary ​

python
Encoding.summary(self) -> str

Everything 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) -> int

Number of open boundary loops.

Mesh.save ​

python
Mesh.save(
    self,
    path: str | os.PathLike,
    point_data: dict[str, np.ndarray] | None = None,
) -> None

Writes 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) -> None

Writes a .furca document.

ShapeModel.summary ​

python
ShapeModel.summary(self) -> str

Subjects, 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 | None

The 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.ndarray

The 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,
) -> Mesh

The 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') -> Mesh

A 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.ndarray

The 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) -> None

Writes a .furca document.

Vessel.summary ​

python
Vessel.summary(self) -> str

The 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) -> float

Smallest 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) -> None

Writes 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.

furca — parametric models of blood vessels.