docs: Camera context (auto-exposure) + ADR 0010 zero-match recovery consolidation#467
Open
brickbots wants to merge 2 commits into
Open
docs: Camera context (auto-exposure) + ADR 0010 zero-match recovery consolidation#467brickbots wants to merge 2 commits into
brickbots wants to merge 2 commits into
Conversation
…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]>
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. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Output of a
grill-with-docssession 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 themode/SNR/sweep/zero-starambiguities.docs/ax/camera.md— architecture deep-dive: feedback data flow (Matchespublished 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, theZeroStarHandlerplugin seam,set_ae_handler, the Experimental "AE Algo" menu, and theauto_exposure_zero_star_handlerconfig key.Updated
CONTEXT-MAP.md— registers the Camera context; adds Positioning → Camera (Matchesfeedback) 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 byExposureSNRController.update(..., noise_floor=...); the previously documentedauto_exposure.SNR_target_offset()never existed.Notes
🤖 Generated with Claude Code