ee_guidance

ee_guidance — EE target selection, POSE path, and the GuidanceMode state machine

Purpose

Picks one raw EE camera pose per step through the GuidanceMode machine
(INITIAL → HOLD/TARGETING/FALLBACK), finalizes it through smoothing + reach limiting, and (via the
controller) marks FOV coverage. The top of the guidance tower: it owns the camera schedule and the
EE feedforward twist (analytic or finite-difference).

Role in the system

• extends base_guidance (BaseGuidance → com_guidance COMGuidance) — the deep guidance chain.
• Called by breve_controller each step via add_ee_goal (live) / sample_guidance_goal (rollout);
  share_motion_cache wires the controller’s motion cache in.
• Feeds the EE twist to breve_controller (derate_twist_by_gamma, analytic_desired_nu_e_feedforward).
• Supported by analytic_feedforward (closed-form twist), target_finder (mesh, ANCHOR scorer, FOV
  marking), and guidance_classes (CameraPose/SurfaceTarget/Selection, GuidanceMode/OrbitPathMode).
• Guidance-without-dynamics path: guidance_rollout drives it through fake_kinematics.

Inputs / Outputs

• In: State (q, v → forward kinematics) or Desired (rollout), the previous Desired, the step index,
  config (targeting / trajectory / orbit-path), and s_min_G for the derate ramp.
• Out: a finalized Desired with EE pose (p_e, R_e, z_e); the desired EE twist nu_e; and the
  per-step guidance/inspection/diagnostics log Package.

Key methods

• set_ee_target — branch owner; selects one raw pose per step across all modes — GNC/guidance/ee_guidance.py:699
• orbit_path_pose — deterministic POSE pose: aim at x_surf(s_aim) from the standoff radius — :684
• _aim_arclength — the aim clock s_aim (progress-synced or open-loop; floor/lead knobs) — :670
• consistent_finalize_pose — filter → reach-limit → commit → write onto Desired (one finalizer) — :792
• filter_camera_pose — first-order smooth + rate-limit of position and pointing axis — :812
• guidanceModeINITIAL / guidanceModeHOLD / guidanceModeTARGETING / guidanceModeFALLBACK — the four mode poses — :346 / :469 / :498 / :451
• update_due / accept_target — reselect cadence + score-margin acceptance (ANCHOR only) — :405 / :562
• analytic_desired_nu_e_feedforward — closed-form EE twist + reduced derivative (POSE only) — :267
• derate_twist_by_gamma — scale the commanded EE twist by γ(s_min_G) — :219

Footguns

POSE is the adopted default — the scorer is INERT

In POSE mode the camera pose is scheduled by orbit_path_pose (the analytic path), so the
EETargetFinder scorer never runs. In ANCHOR mode the anchor is a CoM-orbit vantage point, NOT
x_surf — placing candidate cameras at x_surf would put them inside the target surface.
Both modes require orbit_path; CHAIN_12 removed the pathless reactive flow. (GNC/INSIGHTS.md [guidance])

Analytic feedforward is POSE-only

analytic_ff_applicable() is True iff orbit_path_mode is POSE. The closed form assumes the look
axis z_ed = u from x_surf(s_aim) and v_des = const, s̈ = 0. ANCHOR falls back to finite-difference
(desired_nu_e_feedforward_consistent) because the scorer picks a different aim point. (GNC/INSIGHTS.md [math])

Latched INITIAL offsets persist until reset

default_selection.p_ce and default_R_be0 are latched on the first INITIAL call from the real EE
pose; only reset_runtime_state clears them. The aim-clock state _s_aim_prev inits to None, so the
floor branch is a no-op on the first _aim_arclength call. (GNC/INSIGHTS.md [footgun])

derate_twist_by_gamma uses measured-state γ

The EE-twist derate scales the commanded twist by γ(s_min_G) (the same conditioning ramp), applied
to the FF output so the analytic FF stays reference-only pure. Speed-derate is the rejected A/B variant —
the endorsed mechanism is impedance (gain) derate in breve_controller. (GNC/INSIGHTS.md [derate])

Pseudocode (one guidance step)

add_ee_goal(st, des_base, step_idx):
  default_pose, mode = guidanceModeINITIAL(st)        # latched p_ce / R_be0 hold
  if aim_during_initial and 1 <= step < startup:      # CHAIN_4: aim along path during INITIAL
      raw = orbit_path_pose(st, mode=INITIAL)
  elif not enabled or still in INITIAL window:
      raw = default_pose
  elif POSE mode:
      raw = orbit_path_pose(st)                        # x_surf(s_aim) at standoff; scorer INERT
  else:                                                # ANCHOR: scorer with path vantage
      if not update_due: raw = exit_hold(st)
      else: choose_goal → clamp → rescore → accept_target → exit_{targeting|fallback|hold}
  return consistent_finalize_pose(st, des, raw):
      filter_camera_pose  (low-pass + per-step rate/slew clamp)
      enforce_reach_limit (clamp |p_ce| <= r_reach)
      commit + write (p_e, R_e, z_e) onto Desired

Equations & references

Key equations mirrored from current_sota — the math source of truth; see there for derivations.

Standoff pose construction (POSE mode) — §5.4, eq (5.7):

$${\mathbf{p}}_{ed}={\mathbf{p}}_c+r_{\mathrm{cam}}\hat{\mathbf{r}},{\mathbf{z}}_{ed}=\hat{\mathbf{r}}$$

World-frame desired twist — §5.5, eq (5.14):

$${\mathbf{\nu }}_{ed}=\left[\begin{array}{c}{\dot{\mathbf{p}}}_{ed}\\ {\mathbf{\omega }}_{ed}\end{array}\right]=\left[\begin{array}{c}{\mathbf{v}}_{cd}+r_{\mathrm{cam}}\dot{\hat{\mathbf{r}}}\\ \hat{\mathbf{r}}\times \dot{\hat{\mathbf{r}}}\end{array}\right]$$

Circumcentroidal ($\oplus$) conversion — §5.6, eq (5.17):

$${\mathbf{\nu }}_{ed}^{\oplus }={\mathbf{\nu }}_{ed}^{\mathrm{local}}-{\mathbf{G}}_{v_c}{\mathbf{v}}_{cd}+{\mathbf{G}}_{{\omega }_b}{\mathbf{\omega }}_{bd}$$

References:

• POSE-mode orbit-path guidance + the aim clock: current_sota (project guidance section).
• Analytic desired twist (§5.8–5.18) is computed in analytic_feedforward and invoked here.

Related

base_guidance · com_guidance · analytic_feedforward · target_finder · guidance_classes · guidance_rollout · breve_controller · terminology · ee_feedforward · target_finding_coverage · guidance_modes