Skip to content

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 residual

Resolutions ​

Sizes (centerline.size, centerline.offset_bins, wall.tau_size) are either a fixed integer or a rule proportional to the aspect ratio L/r¯ of the vessel (length over mean radius):

n=clamp(round(per_radius⋅L/r¯)+offset, min, max).

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 ​

ParameterMeaning
inletWhich boundary is the inlet. largest matches arterial flow; use smallest for veins or nearest to choose by position.
caps.label_arraysCell arrays whose non-zero values mark cap triangles.
caps.face_arrays, caps.face_flatnessCell 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_fractionPlanar 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.sizeControl points of the centerline.
centerline.level_setsHarmonic level sets whose centroids the centerline fits.
centerline.stiffnessCut-off length in mean radii: the centerline ignores features shorter than this.
centerline.penalty_orderOrder 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_sectorsCross-section bins in which the centring diagnostic is measured, and the angular sectors each must cover.
frame.samplesSteps of the frame table; stored in the encoding.
frame.referenceDirection of θ=0 at the inlet (and, on average, of φ=0).
frame.straight_toleranceBelow this fraction of the length, the default reference direction is considered undefined (straight centerline) and a coordinate axis is used.
frame.sectionsOrientation 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_orderSmoothing 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_samplesPoints [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_sizeCoefficients of the wall along and around the vessel.
wall.smoothingSmoothing of the wall fit.
wall.correctionsParameter 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.angleThe 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.knotsLongitudinal knot placement: uniform, or adaptive with a strength in [0,1) (share of knots placed by wall curvature) and samples_per_span (resolution of the curvature profile). See Adaptive knots.
ends.modeboundary: the wall domain just contains every vertex. centroid: the wall ends at the boundary centroids and vertices beyond are ignored. See Ends.
ends.axial_toleranceVertices farther than this (× mean radius) outside the wall domain are excluded from fits.
junctions.continuationAt 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_residualAt 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.clearanceRings 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.windowLength, in parent radii, of the stretch before an apex over which the parent fades out and its children fade in.
junctions.smoothnessWidth ε of the smooth union of the branches, relative to each branch's radius: the scale on which the creases where branch walls meet are rounded.
junctions.coverageAt a junction, a wall spans the sections where at least this fraction of the angular sectors hold its own data.
junctions.extensionHow far, in its radii, a branch is carried beyond its data into a junction (as its end section).
junctions.harmonic_residualWith 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_subjectsIn 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.enabledWhether saccular lobes (dead ends of the flow, such as aneurysm sacs) are sought.
lobes.stagnationVertices where the flow passes at most this fraction as strongly as across the rest of their level are stagnant.
lobes.min_areaA connected stagnant region is the core of a lobe when its area is at least this many times πr¯2, with r¯ the mean radius of the inlet and outlets.
lobes.sphere_toleranceA lobe spans its core and the wall around it within this fraction of the radius of the sphere that best fits the core.
lobes.degreeDegree of the spherical harmonics of a lobe's wall ((L+1)2 coefficients).
lobes.tube_residualAn 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.toleranceThe 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 θ=0 points from c(0) towards the arc-length centroid of the centerline, projected onto the inlet normal plane, i.e. "into the bend". This is invariant to rigid motions of the input. For a (nearly) straight centerline that direction is undefined, and the coordinate axis least aligned with the inlet tangent is used instead; set frame.reference to make the choice explicit.

furca — parametric models of blood vessels.