Skip to content

docs: Camera context (auto-exposure) + ADR 0010 zero-match recovery consolidation#467

Open
brickbots wants to merge 2 commits into
mainfrom
worktree-camera-context-docs
Open

docs: Camera context (auto-exposure) + ADR 0010 zero-match recovery consolidation#467
brickbots wants to merge 2 commits into
mainfrom
worktree-camera-context-docs

Conversation

@brickbots

@brickbots brickbots commented Jun 11, 2026

Copy link
Copy Markdown
Owner

Summary

Output of a grill-with-docs session preparing for the zero-star-handler consolidation. Creates the Camera bounded context (exposure control in the camera process), records the consolidation decision as ADR 0010, and fixes terminology drift in the SQM docs.

New

  • docs/ax/camera/CONTEXT.md — glossary: the three exposure regimes (solver-driven AE / native AE / manual), the two controllers (match-count, background), zero-match recovery and the recovery ladder; flags the mode/SNR/sweep/zero-star ambiguities.
  • docs/ax/camera.md — architecture deep-dive: feedback data flow (Matches published on every solve attempt → controller → set_camera_config), regime transitions (daytime-align handoff, manual-nudge override), controller behavior, recovery semantics, the diagnostic exposure sweep capture, and gotchas — including the deliberately open question of whether the shipped default regime should stay manual 0.4 s.
  • docs/adr/0010-zero-match-recovery-single-ladder.md — the decision: recovery's scope is badly-wrong exposure only (not defocus / transients / solver-side failures); keep the Sweep ladder ordering floored at 200 ms[400, 800, 1000, 200] ms (below 200 ms a frame is unlikely to pick up enough stars to solve; the floor bounds recovery's blind search only — the match-count controller's feedback clamp still reaches 25 ms); retire Exponential, Reset, and Histogram, the ZeroStarHandler plugin seam, set_ae_handler, the Experimental "AE Algo" menu, and the auto_exposure_zero_star_handler config key.

Updated

  • CONTEXT-MAP.md — registers the Camera context; adds Positioning → Camera (Matches feedback) and rewords SQM → Camera to the background-controller terminology.
  • docs/ax/sqm.md, docs/ax/sqm/CONTEXT.md — drift fix: the noise floor is consumed by ExposureSNRController.update(..., noise_floor=...); the previously documented auto_exposure.SNR_target_offset() never existed.

Notes

  • Docs only — no code changes. The consolidation itself (deleting the three strategies, menu, and config key, and applying the 200 ms ladder floor) is a follow-up implementation PR that executes ADR 0010.

🤖 Generated with Claude Code

brickbots and others added 2 commits June 11, 2026 16:58
…ry consolidation

Create the Camera bounded context covering exposure control in the
camera process:

- docs/ax/camera/CONTEXT.md — glossary: exposure regimes (solver-driven /
  native / manual), match-count and background controllers, zero-match
  recovery, recovery ladder; flags the mode/SNR/sweep/zero-star
  ambiguities.
- docs/ax/camera.md — architecture deep-dive: feedback data flow, regime
  transitions, controller details, recovery semantics, diagnostic
  exposure sweep capture, gotchas (incl. the open question of the
  shipped default regime).
- docs/adr/0010-zero-match-recovery-single-ladder.md — decision: scope
  recovery to badly-wrong exposure only; keep the Sweep ladder, retire
  Exponential/Reset/Histogram strategies, the ZeroStarHandler plugin
  seam, the "AE Algo" menu, and the auto_exposure_zero_star_handler
  config key.
- CONTEXT-MAP.md — register the Camera context; split the SQM→Camera
  relationship and add Positioning→Camera (Matches feedback).
- docs/ax/sqm* — fix drift: the noise floor is consumed by
  ExposureSNRController.update(), not the nonexistent
  auto_exposure.SNR_target_offset(); align terminology with the new
  background-controller naming.

Co-Authored-By: Claude Fable 5 <[email protected]>
Below 200 ms a frame is unlikely to pick up enough stars to solve, even
under a bright sky, so the legacy short rungs (100/50/25 ms) only spent
solve attempts where solving was improbable. Decided ladder:
[400, 800, 1000, 200] ms. The floor bounds recovery's blind search only;
the match-count controller's feedback clamp still reaches 25 ms.

Co-Authored-By: Claude Fable 5 <[email protected]>
@brickbots brickbots requested a review from mrosseel June 12, 2026 02:22
@brickbots

Copy link
Copy Markdown
Owner Author

Hi @mrosseel! I'm aiming to remove the options for auto-exposure algo, locking in the sweep as the method, and bracketing this between 200 and 1000ms. This PR is to add documentation about the AE feature and also an Architectural Decision Record (ADR) about the selection of the specific AE algo and the ranges.

If you have any concerns, objections or thoughts, let me know. Otherwise I'll merge this and followup with the code changes to make AE the default, remove the config option and narrow the sweep along with some light refactoring to make some of the concepts and variables consistent and non overlapping with some other parts of the code as described in the camera/CONTEXT.md doc.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant