Module fit 

Polyline → Catmull-Rom fitting.

Reduces a dense streamline to a sparse set of control points whose Catmull-Rom interpolation reproduces the input within a user-specified Hausdorff tolerance. Useful for editor tools (which want few sculptable control points) and for compressing dense atlas tractograms.

The algorithm:

1. Start with the two endpoints as kept control points.
2. For each segment between consecutive kept points, tessellate the Catmull-Rom curve, then walk the interior input vertices in that segment and find the one whose perpendicular distance to the tessellated polyline is largest.
3. If any segment’s worst vertex is farther than epsilon_mm, add the worst vertex from each violating segment as a new kept point and iterate. Adding many points per iteration converges in O(log n) passes for smooth curves while staying stable on degenerate inputs.
4. Stop when no segment’s worst error exceeds the tolerance.

Distances are computed as squared distances throughout (no sqrt in the hot loop) and the per-segment tessellation buffer is reused across iterations so the working set stays compact.

Endpoint convention

Both endpoints of every input streamline are always retained, matching how trxviz-draw and most editor UIs treat streamline terminations (cortical/sub-cortical anchors are anatomically meaningful).

Coordinate units

epsilon_mm matches the units of points, which in TRX is RAS+ mm.

Structs

FittedMarker

Schema for the FITTED_MARKER_KEY payload. Stable across releases of this crate; consumers should treat unknown fields as ignorable.

SimplifyOptions

SimplifyStats

Constants

FITTED_MARKER_KEY

JSON key written under Tractogram::extra_mut to mark a tractogram as already Catmull-Rom-fitted.

MIN_KEPT_POINTS

Endpoints are always kept, so the minimum output size is 2 — even when the input has fewer points the function returns the input unchanged.

Functions

fit_catmull_rom_indices

Fit a Catmull-Rom curve through a sparse subset of points such that the curve stays within epsilon_mm of every input vertex. Returns the retained input indices in ascending order.

sample_catmull_rom

Sample a Catmull-Rom curve through cps with samples_per_segment evenly-spaced parameter steps per segment. The first CP appears once at the start; each subsequent segment contributes samples_per_segment points (so the final CP appears once at the end). Returns owned points.

sample_catmull_rom_into

Sample a Catmull-Rom curve into a caller-provided buffer. The buffer is cleared first; capacity is reused. Useful in tight loops to avoid per-call allocations.

simplify_streamline

Convenience: return the simplified streamline as owned positions.

simplify_tractogram

Build a new Tractogram from input with each streamline simplified to a Catmull-Rom-fittable control polygon. Preserves the source header (so spatial metadata round-trips) and writes the FITTED_MARKER_KEY marker.