curvature

curvature — polyline field sampling + frame continuity

Purpose

Pure-math polyline helpers for the guidance tower: closest-point projection, linear field
interpolation with local smoothing, and SO(3) frame-sequence sign-continuity enforcement.
No config or mesh dependencies — just NumPy plus a few geometry casts.

Role in the system

• Stateless support library; consumes only geometry (as_flat3, as_mat3, interpolate_linear)
  and utils/infra (Package).
• base_guidance calls enforce_frame_sequence_continuity to de-flip the per-window base frames.
• com_guidance calls closest_point_on_segment_polyline to project the CoM onto the orbit polyline.
• guidance/guidance_rollout calls sample_polyline_window to read position/tangent/curvature at a
  fractional progress index.
• The smooth analytic path uses the closed-form orbit sampler in orbit instead; these helpers serve
  the indexed/polyline access pattern.

Inputs / Outputs

• In: polyline arrays of 3-vectors (p_cd, v_cd, kappa_cd), a query point or fractional
  progress, and lists of frames (matrices or quaternions, cast via as_mat3).
• Out: Package records — (i0, i1, alpha, p_near) for projection, (p, v, kappa) for a window
  sample — or plain NumPy vectors / lists of SO(3) matrices.

Key functions

• sample_polyline_window — position + tangent + smoothed curvature at progress — utils/curvature.py:87
• closest_point_on_segment_polyline — nearest segment projection (i0, i1, alpha, p_near) — utils/curvature.py:47
• enforce_frame_sequence_continuity — sign-align consecutive SO(3) frames (xy-flip) — utils/curvature.py:7
• path_tangent_from_positions — central-difference tangent, alpha-blended — utils/curvature.py:29
• smooth_vector_field — window-average then blend (curvature de-ripple) — utils/curvature.py:115

Pseudocode (sample a window)

u      = clip(progress, 0, n-1)        # fractional index into the polyline
i0, i1 = floor(u), i0+1                # bracketing samples
alpha  = u - i0
p      = lerp(p_cd[i0], p_cd[i1], alpha)
v      = central-difference tangent at i0,i1, blended by alpha
kappa  = window-average kappa_cd around i0,i1 (radius=1), blended  # de-ripple at segment crossings

Related

geometry · base_guidance · com_guidance · orbit · terminology