Refactor Solver/Integrator flow to use dataclasses, combine camera/aligned position estimates into ImuDeadReckoning

[brickbots]

Summary

Reworks the Positioning data path (solver.py → integrator.py → consumers) off the legacy solved dict and onto typed dataclasses, then sharpens the boundaries between the solver, the integrator, and the IMU dead-reckoner. The change lands in three layers:

Reviewers

There is a lot of stuff here, but the main areas for input are the shape of the dataclasses in PiFinder/types/positioning.py and the flow of data from solver.py->integrator.py.

1. Dataclass migration — kill the solved dict (220a6484)

End-to-end adoption of the dataclasses in PiFinder/types/positioning.py:

• PointingEstimate replaces the solved dict everywhere. Pointing is modelled as a 2 × 2 matrix — two axes (camera, aligned) × two states (solve, estimate) — reached as pointing.<axis>.<state>.<RA|Dec|Roll>.
• The integrator owns the long-lived PointingEstimate; its solve cells survive failed plate-solves so IMU dead-reckoning keeps producing aligned estimates.
• shared_state.solution() / set_solution() carry PointingEstimate and default to an empty instance, so all ~15 consumers (UI, server, pos_server, nearby, …) read through the access shape without None checks.
• Alignment queues carry typed commands/responses (AlignOnRaDec / AlignCancel / ReloadSqmCalibration, AlignedResult), dispatched via isinstance().
• Rename solve_pixel → target_pixel across code, default_config.json, and shared_state. No config-migration logic — users re-align to write the new key.
• Deletes dead code (solver_main.py, get_initialized_solved_dict(), the legacy dict bridge methods).
• Adds matched_centroids / matched_stars to PointingEstimate so the SQM calibration UI can replay SQM from cached published solutions.

2. Collapse the two-axis IDR into one dual-axis instance (9a2ee904)

• ImuDeadReckoning now handles both axes in one instance. solve(camera, aligned, q_x2imu) captures the static q_cam2aligned alongside the drifting q_eq2x; predict() composes the camera prediction with q_cam2aligned and returns both as a (camera, aligned) tuple. reset() clears both.
• integrator.py drops the idr_camera / idr_aligned pair for a single idr.
• The IDR stays a pure math primitive: RaDecRoll in, RaDecRoll out — no import from PiFinder.types.positioning.
• imu_dead_reckoning_legacy.py is retained in-tree as the equivalence reference until we're comfortable removing it in a follow-up.

3. Split the solver→integrator message into a SolveResult DTO (913e5d08)

The migration in (1) had the solver build the same PointingEstimate the integrator owns and publishes — forcing it to set estimate == solve cells and emit a hollow PointingEstimate on failure. This layer separates the wire message from the published aggregate:

• New SolveResult = SuccessfulSolve | FailedSolve, a typed DTO on solver_queue. The integrator dispatches via isinstance() and is the sole builder/owner of PointingEstimate.
• SuccessfulSolve carries flat per-axis Pointings (no solve/estimate split — the solver never IMU-progresses) plus a single solve_time; the integrator fans these into both cells and assigns solve_time / cam_solve_time.
• The inline failed-solve branch is promoted to _apply_failed_solve so tests exercise the real integrator path.
• Rationale captured in ADR-0003; vocabulary added to positioning/CONTEXT.md.

Also in this layer: silence a spurious invalid value encountered in isnan RuntimeWarning — np.isnan() on the IDR's NaN-quaternion sentinel tripped numpy's FP-invalid flag. Replaced with a per-component math.isnan helper (_quat_has_nan), clearing all 25 unit-test warnings.

Docs (fb92dcd0 + this work)

docs/ax/positioning.md and docs/ax/positioning/CONTEXT.md updated to the new vocabulary; ADR-0003 added. The canonical glossary (CONTEXT.md) and the vocabulary decision (ADR-0001) remain authoritative for terms.

Test plan

• nox -s lint type_hints smoke_tests unit_tests — all green (214 unit tests pass; 219 unit + smoke), 0 warnings.
• Run on hardware: confirm dead-reckoning continues across failed solves and the aligned-axis offset is preserved under IMU motion.
• Run alignment flow: confirm the IDR picks up the alignment offset on the next solve and pointing.aligned.estimate reflects it.

Additional Notes for reviewers

• imu_dead_reckoning_legacy.py is intentionally retained as the equivalence-test reference; removal is a planned follow-up.
• A stale handoff.md scratch doc that had slipped into the branch was removed in this PR.

🤖 Generated with Claude Code

[brickbots]

@TakKanekoGit Here's a partially simplified ImuDeadReckoning class + a whole lot of refactoring around it to make the solver->integrator flow much more understandable. Hopefully this overall simplification helps everyone, but it's a ton to review.

I'm pretty sure about everything but the math in ImuDeadReckoning - Looking at the changes is a bit hard to follow, but the class is pretty small now. I think I preserved the camera center to alignment point logic/math properly and apply it correctly, but I'm still very much not across the quaternion transform maths.

What should be happening is that all the estimation is being done from a camera_center basis (the camera pointing), the delta between the camera and aligned solves is computed every time there is a new image solve, and the aligned estimate is derived from the camera estimate not calculated from scratch which should help with the missing roll from Tetra3 for the target_pixel solution.

Whew! I'm going to test this under the stars to verify this all, but I think it should work 🤞

[TakKanekoGit]

It's a big change! I've just started the review but must dash off. I'll hopefully have time tomorrow (sorry about that).

Good luck with the star testing! Have you tested it in demo mode? I often managed to catch errors with ImuDeadReckoning() using the demo mode.

[brickbots]

@mrosseel This is a pretty big change in the data models flowing through the solver->integrator and then used by the rest of the system. It will definitely impact you telemetry work, so wanted to flag you here so you could have a heads up and provide any input. Hoping to merge this soon so avoid creating more potential conflicts with new code 👍

[brickbots]

Just tested this briefly under the stars... It seems to work just like the current code in main, which is nice.

Both this branch and main are just AWESOME. Fast, smooth chart updates, works regardless of what weird angle I put the PiFinder in, just amazing work @TakKanekoGit

I did find one bug in this version that I'll fix up. It sometimes reverts to saying 'no solve' even though it's had one and was updating it with the IMU. I'm sure it's something simple leaking through, maybe related to the derivation of the solve_state when the solution is updated 🤷‍♂️

[TakKanekoGit]

Hi @brickbots. This looks fantastic. Very nice. The algorithm looks all fine. I've added a few very minor comments.

[brickbots]

@TakKanekoGit Thank you for the second round of review. I've committed all my updates so please take a look and resolve or add new comments to the conversations.

I've not tested the "no solve" bug fix under the stars yet. I'm on a work trip until Friday so that will have to wait for me, but anyone who wants pull this branch and test is very welcome!

[mrosseel]

@mrosseel This is a pretty big change in the data models flowing through the solver->integrator and then used by the rest of the system. It will definitely impact you telemetry work, so wanted to flag you here so you could have a heads up and provide any input. Hoping to merge this soon so avoid creating more potential conflicts with new code 👍

probably best if I wait to see what comes out of it and then merge with telemetry branch, which should be up to date with main as of now.

[mrosseel]

Hi, telemetry branch has the fix and should be up to date with main

…

On Tue, 26 May 2026, 19:37 Tak Kaneko, ***@***.***> wrote: ***@***.**** commented on this pull request. ------------------------------ In python/PiFinder/integrator.py <#429 (comment)>: > - # Set up dead-reckoning tracking by the IMU: - imu_dead_reckoning = ImuDeadReckoning(cfg.get_option("screen_direction")) - # imu_dead_reckoning.set_cam2scope_alignment(q_scope2cam) # TODO: Enable when q_scope2cam is available from alignment + # Single IMU dead-reckoner handling both axes. Seeded with the + # (camera, aligned) pair at each successful plate-solve. + idr = ImuDeadReckoning(screen_direction) Hi @brickbots <https://github.com/brickbots> -- I have a function to estimate this (q_imu2cam) but I paused it until the issue with the invalid solves are fixed and I can record some new telemetry data (perhaps this PR might even fix it?). @mrosseel <https://github.com/mrosseel> has the details on the root cause. Hopefully, we'll be able to include it with the next release. — Reply to this email directly, view it on GitHub <#429?email_source=notifications&email_token=AALFXXX4ZXLLOJ7HGQMLP3D44XI7FA5CNFSNUABKM5UWIORPF5TWS5BNNB2WEL2QOVWGYUTFOF2WK43UKJSXM2LFO4XTIMZWGYYDQMZVGA22M4TFMFZW63VHNVSW45DJN5XKKZLWMVXHJLDGN5XXIZLSL5RWY2LDNM#discussion_r3305707765>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AALFXXVFAOIL7F47IIV3HX344XI7FAVCNFSM6AAAAACZKB5HXCVHI2DSMVQWIX3LMV43YUDVNRWFEZLROVSXG5CSMV3GSZLXHM2DGNRWGA4DGNJQGU> . Triage notifications on the go with GitHub Mobile for iOS <https://apps.apple.com/app/apple-store/id1477376905?ct=notification-email&mt=8&pt=524675> or Android <https://play.google.com/store/apps/details?id=com.github.android&referrer=utm_campaign%3Dnotification-email%26utm_medium%3Demail%26utm_source%3Dgithub>. You are receiving this because you were mentioned.Message ID: ***@***.***>

[TakKanekoGit]

@mrosseel This is a pretty big change in the data models flowing through the solver->integrator and then used by the rest of the system. It will definitely impact you telemetry work, so wanted to flag you here so you could have a heads up and provide any input. Hoping to merge this soon so avoid creating more potential conflicts with new code 👍

probably best if I wait to see what comes out of it and then merge with telemetry branch, which should be up to date with main as of now.

@mrosseel -- Just to let you know, I'm working on changes to imu_pi.py to use gyro measurements directly which will probably conflict with your telemetry PR. I'll probably need your help to fix the merge conflicts when we get to it.