Darksun Docs

Appearance

Reference Frames ​

Understanding which reference frame a vector lives in is essential when you combine force models, mission planning tools, and visual overlays. Darksun keeps the common frames explicit and provides helpers so you can move safely between them.

Global Inertial Frame (ECLIPJ2000) ​

  • Definition – Right-handed ecliptic frame aligned with the mean ecliptic and equinox of J2000. The +X axis points toward the mean vernal equinox, +Z is the ecliptic north pole, and +Y completes the triad (NASA SPICE Frames documentation; Ecliptic coordinate system).
  • Usage – Primary state integration, orbit caches, solar-system rendering, and export/import pipelines.
  • Transforms – All spacecraft and celestial states streamed from CelestialBodyProvider are resolved into this frame. Conversion utilities include:
    • CoordinateFrameService.toEcliptic() / fromEcliptic()
    • MathUtils.rotateToFrame(from: Matrix3, vector: PhysicsVector3)
          +Z (Ecliptic North)
          │
          │
          └─── +X (Vernal Equinox)
         /
       +Y (Completes right hand)

Body-Fixed Frames (Planet-Centered, Planet-Fixed) ​

  • Definition – Rotating frames tied to individual celestial bodies. +Z aligns with the spin axis, +X intersects the prime meridian, +Y completes the triad (NASA SPICE Frames & Coordinate Systems tutorial).
  • Usage – Groundtrack projections, surface collision tests, atmosphere sampling, and visual surface features.
  • Transforms – CoordinateFrameService.toBodyFixed(bodyName) applies the body’s rotation model, including precession, nutation, and secular drift when supplied in the registry. Inverse methods convert back to inertial.
  • Considerations – When you lift vectors back into ECLIPJ2000, include the body’s instantaneous angular velocity if you require correct Coriolis terms (for example, when modelling atmospheric drag with planet winds).

Local Orbital Frames (TNW / RTN) ​

  • Definition – Translating frames derived from a spacecraft orbit. The axes are:
    • T (Tangential) – Unit vector along instantaneous velocity.
    • N (Normal) – Unit vector along angular momentum (r × v).
    • W (Radial) – Points from the central body toward the spacecraft (T × N). (Alternate names: RTN, LVLH with similar orientation.)
  • Reference treatments include ESA’s SPENVIS guide to orbital coordinate transformations, which derives TNW/RTN conventions used for formation flying and maneuver planning (SPENVIS coordinate transformations).
  • Usage – Maneuver node authoring, burn analytics, formation flying overlays, delta-v budgeting.
  • Transforms – CoordinateTransforms.transformTNWToInertialWithPropagation and TNWFrameCalculator construct the rotation matrices from sampled position/velocity pairs. The resulting matrix T_TNW->ECI lets you map between TNW and ECLIPJ2000:
| e_T • |       | r̂_t |
| e_N • |   =   | ĥ  |
| e_W • |       | r̂_r |

where e_T, e_N, e_W form the matrix columns and r̂_r is the radial direction.

Instantaneous vs Propagated TNW ​

  • Instantaneous – Frame built from the current orbit state. Suitable for displaying manoeuvre vectors.
  • Propagated – Frame computed at the planned execution epoch by propagating forward. Used by the mission planner so burns stay aligned with the orbit at the burn time instead of drifting with current errors.

Barycentric & Multi-Body Frames ​

  • Definition – Frames centred on the barycentre of two or more bodies (e.g., Pluto–Charon). +Z aligns with the system’s angular momentum, +X points toward the secondary at epoch zero (NASA SPICE Dynamic Frames tutorial).
  • Usage – Propagator initialisation when both members exert significant gravity, specialist visualisation for binary systems.
  • Transforms – BarycentricUtils.resolveBarycentricFrame() returns the rotation/translation offsets. After solving, child body states are expressed in ECLIPJ2000 so downstream tools can remain unaware of the intermediate frame.

Sun-Pointing Frames ​

  • Definition – Utility frames aligned with the Sun vector relative to a spacecraft or body. +X points toward the Sun, +Y approximates along-track, +Z completes the triad (Solar radiation pressure).
  • Usage – Solar radiation pressure modelling, eclipse prediction, sun-angle visualisations.
  • Transforms – SolarRadiationPressureService.getSunFrame(spacecraftState) builds the matrix each integrator step; most consumers only need the primary unit vectors to evaluate incident angle.

Frame Selection Checklist ​

TaskRecommended FrameNotes
Long-term orbit propagationECLIPJ2000Use inertial frame to avoid fictitious forces.
Groundtrack / surface analysisBody-fixedKeeps latitude/longitude stable and eases terrain lookups.
Maneuver design and executionTNW propagated to burnAligns delta-v with prograde/normal/radial axes at execution time.
Binary system modellingBarycentricPrevents loss of precision from subtracting near-equal masses.
Solar array pointingSun-pointingSRP and thermal analyses rely on Sun incidence.

Working Safely Across Frames ​

  1. Label Vectors Explicitly – Variable names like velocityEci or forceBodyFixed prevent subtle bugs and improve TypeScript hints.
  2. Reuse Services – Prefer CoordinateFrameService, TNWFrameCalculator, and BarycentricUtils over ad-hoc math; the services apply all corrections (e.g., body polar motion, ephemeris interpolation).
  3. Snapshot Metadata – Physics worker snapshots include the source frame in their metadata. When creating tooling, read this flag before assuming an orientation.
  4. Testing – Unit tests in tests/services/orbitService.maneuverNodes.spec.ts and tests/physics/circularization.spec.ts demonstrate round-tripping between frames. Use them as templates when extending functionality.

Armed with these definitions and utilities, you can freely move between frames while keeping forces, manoeuvres, and visual overlays consistent throughout the simulation stack.

References ​

Built with VitePress

© 2025 Darksun