Skip to content

Add tests that define & prove our calibration math#1768

Draft
ButterscotchV wants to merge 2 commits intomainfrom
bscotch/reset-proof-tests
Draft

Add tests that define & prove our calibration math#1768
ButterscotchV wants to merge 2 commits intomainfrom
bscotch/reset-proof-tests

Conversation

@ButterscotchV
Copy link
Copy Markdown
Member

@ButterscotchV ButterscotchV commented Mar 1, 2026

Terminology

  • Heading correction (hC): The offset in heading (yaw) between the tracker's world reference and the headset's world reference
  • Attitude alignment (aA): The offset in attitude (pitch+roll) between the tracker's local reference and the bone's local reference
  • Heading alignment (hA): The offset in heading (yaw) between the tracker's local reference and the bone's local reference

In essence: Correction gives us the tracker's absolute orientation in the world, alignment translates the orientation to represent a fixed mounting on a rigidbody (limb).

Description

These tests added prove these five essential rules that define our calibration equation:

  1. Heading correction may be applied at any time as long as it is on the left side of the orientation
  2. Applying heading correction does not affect attitude calculation
  3. The order that you apply attitude and heading alignment does matter (basic quaternion business, but nice to show)
  4. By applying the inverse of the heading alignment as a heading correction, we can make the two variables independent
  5. If we want to modify heading alignment independently, we must perform it after attitude alignment

or in a more user relatable context:

  1. Yaw reset can be applied at any time in the math with no negative effects
  2. Yaw reset doesn't affect full reset calculation (continuation of 1)
  3. The order of applying full reset vs. mounting reset matters
  4. We can change mounting reset whenever and not mess up yaw reset
  5. Mounting reset must be applied after full reset, otherwise your full reset gets weird

These tests are purely for reference purposes and may be disabled if they cause significant slowdowns in test runs. No code has been implemented otherwise, but this lays the groundwork for development based on proven principles and basic concepts which may be built upon to create tests for our "reset" implementation. This should also serve as a reference for new contributors to learn how calibration works and the limitations of the math, and to reduce wasted time investigating bugs related to "reset" math when one of our basic rules can explicitly prove the behaviour even if the system itself is not tested.

tl;dr: People don't really understand quaternions, let's just show what works, how it works, and why it works.

This should also be extended to acceleration alignment at some point, though that is much easier to comprehend.

WIP

  • Comments could use some reconsideration
  • Terminology should be documented in the code
  • Basic example(s) of how these concepts may be applied to calculate the required "session calibrations"
  • Describe the dependencies of variables and how we manipulate the chain
  • Implement static body frame pitch/roll offsets (ex. t-pose reset)

@ButterscotchV ButterscotchV self-assigned this Mar 1, 2026
@ButterscotchV ButterscotchV added Difficulty: Math Heavy For something that requires some non-trivial math Priority: Normal The default priority Area: Server Related to the server labels Mar 1, 2026
@ButterscotchV ButterscotchV force-pushed the bscotch/reset-proof-tests branch from fbecabf to 6478e12 Compare March 1, 2026 11:03
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Area: Server Related to the server Difficulty: Math Heavy For something that requires some non-trivial math Priority: Normal The default priority

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant