diff --git a/docs/technical_reference.md b/docs/technical_reference.md index d773100..70e5b2b 100644 --- a/docs/technical_reference.md +++ b/docs/technical_reference.md @@ -52,6 +52,16 @@ struct Vec3 { }; ``` +### Mat3 (physics.h) +```cpp +struct Mat3 { + double m00, m01, m02; + double m10, m11, m12; + double m20, m21, m22; +}; +``` +Row-major 3x3 matrix for 3D rotation operations. + ### CelestialBody (simulation.h) ```cpp struct CelestialBody { @@ -111,7 +121,7 @@ struct OrbitalElements { double argument_of_periapsis; }; ``` -**Note:** 3D orientation using `inclination`, `longitude_of_ascending_node`, and `argument_of_periapsis` is defined but not yet applied to orbital calculations (deferred implementation). +**Note:** 3D orientation is fully implemented using rotation matrices. The rotation sequence is z-x-z Euler angles: R_z(Ω) · R_x(i) · R_z(ω). All 3D parameters are applied in `orbital_elements_to_cartesian()`. ### Spacecraft (spacecraft.h) ```cpp @@ -184,8 +194,15 @@ struct OrbitTracker { double time_at_completion; int body_index; double min_time_days; + + // Orbital elements for 3D angle calculation + double inclination; + double longitude_of_ascending_node; + double argument_of_periapsis; + bool has_orbital_elements; }; ``` +**3D Support:** When `has_orbital_elements` is true, the tracker transforms 3D positions back to the orbital plane using the stored orbital elements before calculating the angle. This enables accurate period measurement for inclined orbits. ## Module Overview @@ -195,12 +212,24 @@ Vector math and gravity calculations. RK4 (Runge-Kutta 4th order) integration wi **Key functions:** - `rk4_step(Vec3* position, Vec3* velocity, double dt, double body_mass, double parent_mass)` - RK4 integration using position/velocity pointers - `evaluate_acceleration(Vec3 relative_pos, double body_mass, double parent_mass)` - computes gravitational acceleration from parent +- Matrix operations for 3D orbital orientation: + - `mat3_identity()` - returns identity matrix + - `mat3_multiply(Mat3 a, Mat3 b)` - matrix-matrix multiplication + - `mat3_multiply_vec3(Mat3 m, Vec3 v)` - matrix-vector multiplication + - `mat3_rotation_x(double angle)` - rotation about X axis + - `mat3_rotation_z(double angle)` - rotation about Z axis + - `mat3_rotation_orbital(double omega, double i, double Omega)` - combined z-x-z orbital rotation + +**Implementation:** +- Row-major 3x3 matrix format (different from raylib's column-major 4x4) +- Rotation matrices follow standard right-hand rule convention +- Combined orbital rotation: R_z(Ω) · R_x(i) · R_z(ω) for z-x-z Euler angles ### Orbital Mechanics (orbital_mechanics.cpp/h) -Keplerian orbital elements to Cartesian coordinate conversion. Supports all orbit types with planar orbits (3D orientation deferred). +Keplerian orbital elements to Cartesian coordinate conversion. Supports all orbit types with full 3D orientation using rotation matrices. **Key functions:** -- `orbital_elements_to_cartesian(OrbitalElements elements, double parent_mass, Vec3* out_position, Vec3* out_velocity)` - converts Keplerian elements to local position/velocity +- `orbital_elements_to_cartesian(OrbitalElements elements, double parent_mass, Vec3* out_position, Vec3* out_velocity)` - converts Keplerian elements to local position/velocity with 3D orientation **Implementation:** - Circular orbits (e=0): Position on circle, velocity from vis-viva equation @@ -209,7 +238,7 @@ Keplerian orbital elements to Cartesian coordinate conversion. Supports all orbi - Hyperbolic orbits (e>1): Same as elliptical with negative semi_major_axis - All elements use SI units (meters, radians) - `true_anomaly = 0` is at periapsis (closest approach) -- 3D orientation (inclination, RAAN, argument of periapsis) defined but not yet applied (deferred) +- 3D orientation: applies z-x-z Euler rotations (R_z(Ω) · R_x(i) · R_z(ω)) to position and velocity vectors ### Simulation (simulation.cpp/h) Simulation state management and updates. SOI detection using Hill sphere: `r_soi = a * (m/M)^(2/5)`.