claudes_game/docs/planning/orbit-tracker-3d-fix-plan.md

OrbitTracker 3D Fix Plan

Problem

update_orbit_tracker() only uses atan2(y, x) which calculates the angle in the x-y plane. For 3D inclined orbits, this doesn't track the true orbital angular position because:

1. The spacecraft moves in an inclined orbital plane (not the x-y plane)
2. The x-y projection doesn't represent the true angular progress around the orbit

Current Implementation (Failing)

Vec3 relative_pos = vec3_sub(body->global_position, parent->global_position);
double current_angle = atan2(relative_pos.y, relative_pos.x);  // Only works for 2D orbits in x-y plane

Solution

Track the orbital angular position by projecting the 3D position onto the orbital plane and calculating the true anomaly.

Implementation Approach

Option 1: Store Orbital Plane Normal (Recommended)

Add fields to OrbitTracker to store the orbital plane orientation:

• Vec3 orbital_plane_normal - Normal vector to the orbital plane
• Vec3 reference_direction - Reference direction in the orbital plane (periapsis direction)

Calculation steps:

1. Compute orbital plane normal from inclination (i) and RAAN (Ω):

   n_x = sin(i) * sin(Ω)
   n_y = -sin(i) * cos(Ω)
   n_z = cos(i)
   

2. Compute periapsis direction in 3D space:

   R_z(Ω) · R_x(i) · R_z(ω) transforms (1, 0, 0) to periapsis direction
   

3. Project position onto orbital plane and calculate angle from periapsis

Option 2: Use Existing Rotation Matrix

Reuse mat3_rotation_orbital() to transform position back to orbital plane coordinates:

1. Apply inverse rotation: R_orbital^T · r_3D = r_orbital_plane
2. Calculate angle in orbital plane: atan2(y_orbital, x_orbital)

This is simpler and reuses existing code.

Changes Required

test_utilities.h

• Add double inclination field to OrbitTracker struct
• Add double longitude_of_ascending_node field
• Add double argument_of_periapsis field

test_utilities.cpp

• Modify create_orbit_tracker_with_min_time() to accept orbital elements
• Modify update_orbit_tracker() to:
  1. Build inverse rotation matrix from stored orbital elements
  2. Transform 3D position back to orbital plane
  3. Calculate angle in orbital plane

test_inclined_orbits.cpp

• Update create_orbit_tracker_with_min_time() calls to pass orbital elements

Test

• Molniya orbital period test should pass (12 hours ± tolerance)
• All other orbit tests should continue to pass

Notes

• Backward compatibility: Planar orbits (i=0) should work exactly as before
• The inverse rotation is just the transpose of the rotation matrix (orthogonal)
• Performance: Minimal impact, only called during tests

Files to Modify

1. src/test_utilities.h - Add orbital element fields to OrbitTracker
2. src/test_utilities.cpp - Implement 3D angle calculation
3. tests/test_inclined_orbits.cpp - Update tracker creation calls
4. tests/test_orbital_period.cpp - May need updates if using tracker
5. tests/test_moon_orbits.cpp - May need updates if using tracker