GNC/guidance/guidance_classes.py — mode taxonomy & guidance records

Vocabulary of the guidance tower: four mode enums and three typed pose records. No control logic — just the typed payloads that flow through ee_guidance.

GuidanceMode — four-state EE state machine

GuidanceMode∈{INITIAL,FALLBACK,HOLD,TARGETING}⊂Z≥0\text{GuidanceMode} \in \{\text{INITIAL}, \text{FALLBACK}, \text{HOLD}, \text{TARGETING}\} \subset \mathbb{Z}_{\ge 0}

Ordinal indexes the plot-band colour; the ordering is not a priority ring.

State transitions (ANCHOR path)

INITIAL→startup complete{TARGETINGcandidate acceptedFALLBACKno viable candidate\text{INITIAL} \xrightarrow{\text{startup complete}} \begin{cases} \text{TARGETING} & \text{candidate accepted} \\ \text{FALLBACK} & \text{no viable candidate} \end{cases}

TARGETING→1 stepHOLD\text{TARGETING} \xrightarrow{\text{1 step}} \text{HOLD}

HOLD→update dueTARGETING\text{HOLD} \xrightarrow{\text{update due}} \text{TARGETING}

TARGETING fires for exactly one step then latches back to HOLD. The EE tracks in HOLD.

OrbitPathMode — routing fork

OrbitPathMode∈{POSE,ANCHOR}\text{OrbitPathMode} \in \{\text{POSE}, \text{ANCHOR}\}

POSE:ped=pc−rcamr^,zed=r^(5.7)\text{POSE:}\quad \bm p_{ed} = \bm p_c - r_{\mathrm{cam}}\hat{\bm r},\qquad \bm z_{ed} = \hat{\bm r} \tag{5.7}

In POSE mode the scorer, HOLD, TARGETING, and FALLBACK are inert; only INITIAL then the deterministic schedule run.

ANCHOR retains the full four-mode machine.

CameraPose record

Desired EE camera pose emitted by the state machine each step:

CameraPose=(pe,ze,Re)∈R3×S2×SO(3)\text{CameraPose} = \bigl(\bm p_e, \bm z_e, \bm R_e\bigr) \in \mathbb{R}^3 \times S^2 \times \mathrm{SO}(3)

Construction contract: if Re\bm R_e is supplied then ze←Re[:,2]\bm z_e \leftarrow \bm R_e[:,2]; otherwise ze\bm z_e is unit-normalised on init.

SurfaceTarget & Selection records

Target point on the inspected surface:

SurfaceTarget=(x,n^,idx),n^∈S2\text{SurfaceTarget} = \bigl(\bm x, \hat{\bm n}, \text{idx}\bigr),\qquad \hat{\bm n} \in S^2

The scorer packs the winner into:

Selection=(SurfaceTarget,CameraPose,stotal,pce)\text{Selection} = \bigl(\text{SurfaceTarget}, \text{CameraPose}, s_{\text{total}}, \bm p_{ce}\bigr)

pce\bm p_{ce} is the CoM-relative EE offset latched at the end of each TARGETING step.

ScoringMode — candidate combination rule

ScoringMode∈{MEAN,PRODUCT,EXPONENTIAL,WEIGHTED}\text{ScoringMode} \in \{\text{MEAN}, \text{PRODUCT}, \text{EXPONENTIAL}, \text{WEIGHTED}\}

Validated at construction from the YAML key scoring.mode; an unrecognised string raises immediately (StrEnum fail-loud contract).

Active in ANCHOR only — inert in POSE.