Add tests that define & prove our calibration math #35

New Issue

MrUnknownDE · 2026-04-05T17:54:00+02:00

MrUnknownDE commented

2026-04-05 17:54:00 +02:00

Originally created by @ButterscotchV on 3/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:

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

or in a more user relatable context:

Yaw reset can be applied at any time in the math with no negative effects
Yaw reset doesn't affect full reset calculation (continuation of 1)
The order of applying full reset vs. mounting reset matters
We can change mounting reset whenever and not mess up yaw reset
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)

*Originally created by @ButterscotchV on 3/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)

MrUnknownDE added the Priority: Normal Difficulty: Math Heavy Area: Server Priority: Normal Area: Server Area: Server Area: Server Area: Server Area: Server Area: Server Area: Server Area: Server Area: Server Area: Server Area: Server Area: Server Area: Server Area: Server Area: Server Area: Server Area: Server Area: Server labels 2026-04-05 17:54:02 +02:00

Sign in to join this conversation.

Branches Tags

main

aed/grammar-police

battery-0

bscotch/server-rewrite-temp

hannah/steam

pontoon

hannah/keybinds

server-rewrite

bscotch/accel-mount

dependabot/github_actions/gradle/actions-6

dependabot/github_actions/pnpm/action-setup-5

dependabot/github_actions/actions/upload-artifact-7

dependabot/github_actions/actions/download-artifact-8

FloorClipSteamLinkInteractionFix

sapphire/trim-vrm-json

llelievr/trackers-udp-tests

sapphire/linux-bridge-kotlin

sapphire/linux-vrchat-compatdata-path

smol-sleep-state

sapphire/stay-aligned-setup-no-step-skip

sapphire/steamvr-hands-warning

sapphire/proportions-import-skeleton-request

sapphire/bone-mask-update

llelievr/settings-profiles

bscotch/proguard

bscotch/bvh-fix

mitten

bscotch/reset-proof-tests

hannah/install-from-server

smol-buttons

TheButlah-patch-1

sapphire/update-solarxr

sapphire/kotlin-flatbuffers

csv-data-export

feat_flashmode

bscotch/remove-drift-compensation

llelievr/kotlin-config

bscotch/fix-osc-duplication

llelievr/keep-battery-value

rest-calibration-support

tracker-graph

fingertracking

update-eslint

tauri-android

hide-new-resets

height-config

snap-serial

feat/new-updater

support-inches

vrc-fix-ik-key

llelievr/3dmodel-preview

accel-mapping-fixes

llelievr/manual-proportions-rework

llelievr/put-automatic-steamvr-tracker-assigment-first

llelievr/remove-manual-mounting-onboarding

onboarding-usage-step

oldflex

motion-compensation

kotlin-warnings-fix

accessories

tpose

foxvr

No Label Area: Server Area: Server Area: Server Area: Server Area: Server Area: Server Area: Server Area: Server Area: Server Area: Server Area: Server Area: Server Area: Server Area: Server Area: Server Area: Server Area: Server Area: Server Area: Server Difficulty: Math Heavy Priority: Normal Priority: Normal

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: github/SlimeVR-Server#35