# Matrix Implementation Plan - 3D Orbital Rotations

## Objective
Implement 3x3 rotation matrices in the physics module to support 3D orbital element orientation (inclination, RAAN, argument of periapsis).

## Background
Currently `orbital_elements_to_cartesian()` only produces 2D orbits (z=0). To support inclined orbits like Molniya, we need to apply rotation matrices to transform 2D orbital plane coordinates into 3D space.

## Rotation Sequence (z-x-z Euler angles)
```
r_final = R_z(Ω) · R_x(i) · R_z(ω) · r_orbital_plane
v_final = R_z(Ω) · R_x(i) · R_z(ω) · v_orbital_plane
```
Where:
- ω (omega) = argument of periapsis
- i = inclination
- Ω (Omega) = longitude of ascending node

## Implementation

### 1. Data Structure (physics.h)
```cpp
struct Mat3 {
    double m00, m01, m02;  // Row 0
    double m10, m11, m12;  // Row 1
    double m20, m21, m22;  // Row 2
};
```
**Format**: Row-major 3x3 matrix (different from raylib's column-major 4x4)

### 2. Functions to Implement (physics.h/cpp)

#### Core Matrix Operations
- `mat3_identity()` - Returns identity matrix
- `mat3_multiply(Mat3 a, Mat3 b)` - Matrix-matrix multiplication
- `mat3_multiply_vec3(Mat3 m, Vec3 v)` - Matrix-vector multiplication

#### Rotation Matrices
- `mat3_rotation_x(double angle)` - Rotation about X axis (for inclination)
- `mat3_rotation_z(double angle)` - Rotation about Z axis (for ω and Ω)

#### Convenience Function
- `mat3_rotation_orbital(double omega, double i, double Omega)` - Combined rotation

### 3. Test Plan (test_integration.cpp)

#### Basic Operations
- Identity matrix multiplication
- Matrix-vector multiplication
- Matrix-matrix multiplication

#### Edge Cases for Rotations
- Identity (0° rotation)
- 180° rotation (π radians) - coordinate flip
- 360° rotation (2π radians) - should equal identity
- Negative angles (-90° = 270°)
- Very small angles (numerical stability)
- Combined rotations that cancel (+90° then -90°)

#### Validation Tests
- Orthogonality: R^T · R = I
- Determinant = 1 (proper rotation)

### 4. Integration (Future Session)
After matrix implementation, modify `orbital_elements_to_cartesian()` to:
1. Generate 2D position/velocity in orbital plane
2. Apply combined rotation matrix
3. Return 3D coordinates

## References
- docs/planning/molniya-orbit-test-plan.md
- src/orbital_mechanics.cpp (orbital_elements_to_cartesian)
- Standard orbital mechanics: Keplerian to Cartesian conversion

## Date
Created: 2026-01-28