Appearance
Encoder parameters
Every quantity that shapes the result is a parameter. All are optional; a TOML file passed with furca encode --params FILE may set any subset, and command line flags take precedence. The parameters actually used are stored in each .furca document.
The complete set, with defaults:
toml
inlet = "largest" # "largest", "smallest" or { nearest = [x, y, z] }
[caps] # only used for closed surfaces
label_arrays = ["CapID", "capid", "cap_id"]
face_arrays = ["ModelFaceID"] # faces of the model: the flat ones are the caps
face_flatness = 0.99
angle_tolerance = 1.0 # degrees
min_area_fraction = 0.005
[centerline]
size = { per_radius = 1.5, offset = 4, min = 8, max = 128 } # or an integer
level_sets = 128
stiffness = 0.5 # cut-off length, in mean radii
penalty_order = 3 # derivative penalized: 2 = bending energy, 3 = curvature variation
offset_bins = { per_radius = 2.0, offset = 0, min = 16, max = 256 }
offset_sectors = 16
[frame]
samples = 4096
# reference = [0.0, 1.0, 0.0] # default: towards the centerline centroid
straight_tolerance = 1e-3
sections = "harmonic" # or "normal"
tilt_stiffness = 0.3 # cut-off length of the section tilt, in mean radii
tilt_penalty_order = 3
fold_samples = [1024, 96] # τ × φ points where the fold of the encoded wall is checked
[wall]
tau_size = { per_radius = 3.0, offset = 3, min = 8, max = 192 } # or an integer
theta_size = 24
smoothing = "auto"
knots = { mode = "adaptive", strength = 0.5, samples_per_span = 16 } # or { mode = "uniform" }
corrections = 1 # parameter corrections of the harmonic angle
angle = "harmonic" # or "polar": a radius function, for star-shaped sections
[ends]
mode = "boundary" # or "centroid"
axial_tolerance = 1e-3 # × mean radius
[junctions] # only used for branched vessels
continuation = 1.2 # a child this many times wider than the others continues its parent
trunk_residual = 0.5 # closer in width: a trunk if its RMS residual is this fraction of a bifurcation's
clearance = 1.0 # ring radii between a dividing branch's rings and the apex
window = 1.0 # parent radii over which branches fade in and out
smoothness = 0.1 # blend of the smooth union, × each branch's radius
coverage = 0.75 # fraction of angular sectors with data where a wall still spans
extension = 2.0 # branch radii a branch is carried beyond its data
harmonic_residual = 0.5 # a branch takes its harmonic angle if that leaves this fraction of the polar residual
harmonic_subjects = 0.5 # in a cohort: fraction of the subjects that must choose it
sweeps = 50 # sweeps of the joint fit, at most
tolerance = 1e-4 # relative decrease of the misfit that ends the joint fit
[lobes] # saccular lobes
enabled = true
stagnation = 0.3 # stagnant where the flow is below this fraction of its level's
min_area = 1.0 # × π r̄² of the inlet and outlets
sphere_tolerance = 0.2 # growth around the sphere of the core, × its radius
degree = 12 # spherical harmonics
tube_residual = 0.5 # an unbranched vessel keeps its lobes if they leave this fraction of the tube's RMS residualResolutions
Sizes (centerline.size, centerline.offset_bins, wall.tau_size) are either a fixed integer or a rule proportional to the aspect ratio
Because fits are penalized and the penalty strength is chosen automatically (see P-splines), resolutions can be generous: extra coefficients cost storage but do not cause oscillations. For population studies, fix centerline.size, wall.tau_size and wall.theta_size so that every subject has a feature vector of the same length.
wall.theta_size sets the angular detail. On the real segments of the validation, 16 coefficients leave errors up to 1.5% of the radius, 24 (the default) below 0.5%, and 32 reach the accuracy floor (about 0.1% at most). Sections that are not star-shaped are longer for their area and need more: 48 or more for crescents and curled lobes (see Sections that are not star-shaped).
Reference
| Parameter | Meaning |
|---|---|
inlet | Which boundary is the inlet. largest matches arterial flow; use smallest for veins or nearest to choose by position. |
caps.label_arrays | Cell arrays whose non-zero values mark cap triangles. |
caps.face_arrays, caps.face_flatness | Cell arrays that split the surface into the faces of its model (as SimVascular's ModelFaceID), tried when no label array exists: the faces whose triangles' area vectors sum to at least face_flatness of their area (one for a plane, near zero for a tube wall) are the caps, however small. |
caps.angle_tolerance, caps.min_area_fraction | Planar cap detection, used when neither a label array nor a face array marks the caps: maximal normal deviation within a cap and minimal cap area relative to the surface. |
centerline.size | Control points of the centerline. |
centerline.level_sets | Harmonic level sets whose centroids the centerline fits. |
centerline.stiffness | Cut-off length in mean radii: the centerline ignores features shorter than this. |
centerline.penalty_order | Order of the derivative whose energy smooths the centerline and the section tilt. 3 (default) does not pull the curve straight at the ends or inside bends; 2 is the classical bending energy. |
centerline.offset_bins, centerline.offset_sectors | Cross-section bins in which the centring diagnostic is measured, and the angular sectors each must cover. |
frame.samples | Steps of the frame table; stored in the encoding. |
frame.reference | Direction of |
frame.straight_tolerance | Below this fraction of the length, the default reference direction is considered undefined (straight centerline) and a coordinate axis is used. |
frame.sections | Orientation of the cross-sections: harmonic (planes of the harmonic level rings, valid in tight bends) or normal (perpendicular to the centerline). See Vessel coordinates. |
frame.tilt_stiffness, frame.tilt_penalty_order | Smoothing of the tilt of harmonic sections: cut-off length in mean radii and penalty order. Shorter than the centerline's, so that the sections stay close to the planes of the rings. |
frame.fold_samples | Points [n_τ, n_φ] of the encoded wall where the fold of the coordinates is evaluated (max_fold in the diagnostics; below one, the reconstruction cannot fold). |
wall.tau_size, wall.theta_size | Coefficients of the wall along and around the vessel. |
wall.smoothing | Smoothing of the wall fit. |
wall.corrections | Parameter corrections: refits in which every vertex takes the angle of its nearest point on the previous fit, which removes the noise of the discrete harmonic angle. 0 fits the angles of the vertices as they are. |
wall.angle | The angle the sections are parametrized by: harmonic (the harmonic angle, sections of any shape) or polar (the polar angle about the centerline with no tangential component: the wall is a radius function, which needs star-shaped sections and reproduces the model before the harmonic angle). In a branched vessel, harmonic lets each branch choose (junctions.harmonic_residual) and polar keeps the polar angle in all. |
wall.knots | Longitudinal knot placement: uniform, or adaptive with a strength in samples_per_span (resolution of the curvature profile). See Adaptive knots. |
ends.mode | boundary: the wall domain just contains every vertex. centroid: the wall ends at the boundary centroids and vertices beyond are ignored. See Ends. |
ends.axial_tolerance | Vertices farther than this (× mean radius) outside the wall domain are excluded from fits. |
junctions.continuation | At a junction, the widest child continues its parent as one branch (a trunk with side branches) if it is this many times wider than every other child. Closer in width, the junction is fitted both as a trunk and as a bifurcation (the parent ends and its children start), and trunk_residual decides. See Branched vessels. |
junctions.trunk_residual | At a junction whose children are close in width, the trunk is chosen over the bifurcation when its RMS residual is at most this fraction of the bifurcation's. |
junctions.clearance | Rings of a branch whose plane passes closer to the apex where it divides than this many ring radii are left out of its centerline. |
junctions.window | Length, in parent radii, of the stretch before an apex over which the parent fades out and its children fade in. |
junctions.smoothness | Width |
junctions.coverage | At a junction, a wall spans the sections where at least this fraction of the angular sectors hold its own data. |
junctions.extension | How far, in its radii, a branch is carried beyond its data into a junction (as its end section). |
junctions.harmonic_residual | With wall.angle = "harmonic", a branch is parametrized by its own harmonic angle, rather than by its polar angle, when that fits its data with at most this fraction of the RMS residual. See Branches that are not star-shaped. |
junctions.harmonic_subjects | In a cohort, a branch is parametrized by its harmonic angle in every subject when at least this fraction of the subjects, encoded alone, chose it, and by its polar angle in all of them otherwise. |
lobes.enabled | Whether saccular lobes (dead ends of the flow, such as aneurysm sacs) are sought. |
lobes.stagnation | Vertices where the flow passes at most this fraction as strongly as across the rest of their level are stagnant. |
lobes.min_area | A connected stagnant region is the core of a lobe when its area is at least this many times |
lobes.sphere_tolerance | A lobe spans its core and the wall around it within this fraction of the radius of the sphere that best fits the core. |
lobes.degree | Degree of the spherical harmonics of a lobe's wall ( |
lobes.tube_residual | An unbranched vessel with lobes is encoded as a tube and as one branch with its lobes; the lobes are kept when they leave at most this fraction of the tube's RMS residual (see Unbranched vessels). |
junctions.sweeps, junctions.tolerance | The joint fit of all walls: at most this many sweeps over the branches, ending when one decreases the misfit by less than this fraction. |
Angular reference
By default frame.reference to make the choice explicit.