PyCenterline

class multimodars.PyCenterline(points)

Bases: object

Python representation of a vessel centerline.

points

Ordered list of centerline points.

Type:: list of PyCenterlinePoint

branch_start_indices

Index into points where each branch begins. Entry 0 is always 0 (the main vessel); subsequent entries mark the start of side branches. Read-only — recomputed by calculate_branches.

Type:: list of int

Examples

>>> centerline = PyCenterline(points=[p1, p2, p3])

calculate_branches(spacing_tolerance=1.0)

Detect branches by spatial proximity and return a new centerline with branch_id assigned on every point.

Points whose mutual distance is ≤ spacing_tolerance × median_nn_spacing are considered spatially consecutive regardless of their original array order. The largest connected group becomes branch 0 (main vessel); further groups are numbered by descending size.

Parameters:: spacing_tolerance (float) – Multiplier on the median nearest-neighbour spacing used as the adjacency threshold. 1.5 is a reasonable starting value; increase it if branches are incorrectly split, decrease it if distinct branches are incorrectly merged.
Returns:: New centerline with branch_id set on every point and branch_start_indices populated.
Return type:: PyCenterline

Examples

>>> cl = centerline.calculate_branches(1.5)
>>> main = [p for p in cl.points if p.branch_id == 0]

check_centerline()

Normalise branch ordering so that downstream processing is consistent.

Branch 0 – the point with the highest z-coordinate is moved to index 0 (the whole branch is reversed if necessary).
Side branches – the endpoint closest to branch 0 becomes index 0 (the branch is reversed if necessary).

Returns:: New centerline with all branches in canonical order.
Return type:: PyCenterline

find_sharp_angles(branch_id, cos_threshold)

Return local positions (0-indexed within the branch) of interior points where the opening angle is sharper than cos_threshold.

Parameters:

branch_id (int) – Branch to inspect (0 = main vessel).
cos_threshold (float) – Cosine of the opening angle above which a point is considered sharp. Use 0.0 for < 90°, 0.5 for < 60°, 0.866 for < 30°, etc.

Returns:

Local positions within the branch where sharp angles were found.

Return type:

list[int]

static from_contour_points(contour_points)

Build a centerline from a flat list of PyContourPoint objects.

Parameters:: contour_points (list of PyContourPoint) – Ordered sequence of contour points.
Returns:: Centerline constructed from the provided points.
Return type:: PyCenterline

Examples

>>> pts = [PyContourPoint(...), PyContourPoint(...), ...]
>>> cl = PyCenterline.from_contour_points(pts)

get_branch(branch_id)

Return a new centerline containing only the points of one branch.

All retained points are reassigned to branch_id = 0 and branch_start_indices is reset to [0].

Parameters:: branch_id (int) – Branch to extract.
Returns:: Single-branch centerline with the requested points.
Return type:: PyCenterline
Raises:: ValueError – If branch_id does not exist in this centerline.

merge_branches(branch_id_a, branch_id_b)

Merge two branches and return the updated centerline.

Segments are joined at the closest endpoint pair. If either branch is the main branch (id 0) the merged result becomes branch 0.

Parameters:

branch_id_a (int)
branch_id_b (int)

Returns:

New centerline with the two branches merged and all IDs reassigned.

Return type:

PyCenterline

points_as_tuples()

split_branch(branch_id, local_pos)

Split a branch at a local position and return the updated centerline.

Both resulting segments include the split point. When splitting the main branch (branch_id=0) the longer segment stays as branch 0; for side branches the first segment keeps its slot and the second is appended.

Parameters:

branch_id (int) – Branch to split.
local_pos (int) – 0-indexed position within the branch (as returned by find_sharp_angles).

Returns:

New centerline with the branch split and all IDs reassigned.

Return type:

PyCenterline