> ## Documentation Index
> Fetch the complete documentation index at: https://docs.valar.space/llms.txt
> Use this file to discover all available pages before exploring further.

# Reference Frames

> Understanding coordinate reference frames in VALAR

> For the complete documentation index, see [llms.txt](/llms.txt).

Reference frames are coordinate systems used to describe positions and velocities of spacecraft. VALAR supports a comprehensive set of reference frames for orbital mechanics, allowing seamless transformations between celestial (inertial), Earth-fixed, and local frames.

## Frame Tree Architecture

VALAR models reference frames as a **tree structure** with a single root. Each child frame has a time-dependent or fixed transform to its parent frame. By composing these transforms, you can convert coordinates from any frame to any other frame.

The **root frame** is **GCRF** (Geocentric Celestial Reference Frame), an inertial frame aligned to the ICRF axes at Earth's center.

**Typical workflow:**

1. Propagate orbits in a **celestial/inertial frame** (e.g., GCRF, EME2000)
2. Convert to an **Earth-fixed frame** (e.g., ITRF) for ground tracks and visibility
3. Use **local frames** for ground stations (topocentric) or relative motion (LOF)

***

## Celestial / Inertial Frames (ECI)

### GCRF (Geocentric Celestial Reference Frame)

**Recommended celestial frame for most purposes.** GCRF is the IERS inertial reference frame and serves as the root of the frame tree. It's aligned with the ICRF axes and centered at Earth's geocenter.

* **Use for:** Orbit propagation, ephemeris generation, high-precision applications
* **Origin:** Earth's center of mass
* **Orientation:** ICRF-aligned (J2000.0 epoch)

### EME2000 (Earth Mean Equator 2000)

Also known as **J2000**, this is the mean equator and equinox at the J2000.0 epoch. Widely used for legacy compatibility and interoperability with older systems.

* **Use for:** Legacy interfaces, CCSDS file formats (OPM, OEM)
* **Origin:** Earth's center of mass
* **Orientation:** Mean equator and equinox at J2000.0

### ICRF (International Celestial Reference Frame)

Solar-system barycentric frame aligned with GCRF. Useful for deep-space missions and interplanetary trajectories.

* **Use for:** Interplanetary missions, solar system dynamics
* **Origin:** Solar system barycenter
* **Orientation:** Aligned with GCRF

### Intermediate Frames (Internal Use)

VALAR uses intermediate frames internally for accurate transformations following IAU 2006/2000 paradigm:

* **CIRF** (Celestial Intermediate Reference Frame): X-axis along Celestial Intermediate Origin (CIO), Z-axis along Celestial Intermediate Pole (CIP)
* **TIRF** (Terrestrial Intermediate Reference Frame): CIRF with Earth Rotation Angle applied, including tidal effects

<Info>
  You rarely need to use CIRF/TIRF directly. They're part of the transformation chain between celestial and terrestrial frames.
</Info>

***

## Earth-Fixed Frames (ECEF)

### ITRF (International Terrestrial Reference Frame)

**Recommended Earth-fixed frame.** ITRF rotates with Earth and includes polar motion corrections from IERS Earth Orientation Parameters (EOP).

VALAR supports multiple ITRF versions:

* **ITRF2020** (latest)
* **ITRF2014**
* **ITRF2008**
* **ITRF2005**

**Use for:**

* Ground station coordinates
* Ground track visualization
* Visibility and access calculations
* Geographic mapping

**IERS Conventions:** VALAR supports IERS 1996, 2003, and 2010 conventions. Choose the convention that matches your accuracy requirements:

* **IERS 2010:** Most accurate, recommended for new applications
* **IERS 2003:** Widely used, good balance of accuracy and compatibility
* **IERS 1996:** Legacy convention, use only for compatibility

<Warning>
  For high-precision applications requiring specific ITRF versions (e.g., centimeter-level geodesy), ensure EOP data is properly loaded and not using simplified models.
</Warning>

***

## Legacy Equinox-Based Frames

These frames exist for compatibility with older systems and are **deprecated by IERS**:

* **MOD** (Mean of Date)
* **TOD** (True of Date)
* **GTOD** (Greenwich True of Date)
* **Veis1950**

<Warning>
  Use legacy frames only when required for interoperability with systems that explicitly expect them. For new applications, use GCRF and ITRF instead.
</Warning>

***

## TEME Frame (TLE/SGP4 Special Case)

### TEME (True Equator, Mean Equinox)

TEME is **not a well-standardized frame** and should be avoided for general analysis. It exists primarily to support **TLE (Two-Line Element) and SGP4** propagation.

**Best practice:** If working with TLE data from external sources, convert from TEME to GCRF or ITRF as soon as possible after SGP4 propagation.

TEME is primarily encountered when processing public catalog data (Space-Track, CelesTrak). For operational use, state vectors should be converted to standard reference frames like GCRF or ITRF.

***

## Ground Station Frames

### Topocentric Frame (ENU)

Local **East-North-Up** (ENU) frame at a geodetic point on Earth's surface. This is the standard frame for ground stations, antennas, and measurement modeling.

**Components:**

* **E (East):** Tangent to Earth's surface, pointing east
* **N (North):** Tangent to Earth's surface, pointing north
* **U (Up):** Normal to reference ellipsoid, pointing away from Earth

**Use for:**

* Ground station modeling
* Antenna pointing
* Azimuth-Elevation calculations
* Line-of-sight visibility

***

## Local Orbital Frames (LOF)

Local Orbital Frames are moving frames tied to a spacecraft's orbital state, useful for relative motion analysis and pointing control.

### Common LOF Types

| Frame    | Description                      | X-Axis                   | Y-Axis       | Z-Axis               |
| -------- | -------------------------------- | ------------------------ | ------------ | -------------------- |
| **LVLH** | Local Vertical Local Horizontal  | Velocity direction       | Orbit normal | Nadir (toward Earth) |
| **QSW**  | Along-track, Cross-track, Normal | Along-track              | Cross-track  | Normal               |
| **RTN**  | Radial, Tangential, Normal       | Radial (away from Earth) | Along-track  | Normal               |
| **TNW**  | Tangential, Normal, Cross-track  | Along-track              | Normal       | Cross-track          |
| **VNC**  | Velocity, Normal, Co-normal      | Velocity                 | Normal       | Co-normal            |

### Inertial Variants

Each LOF type has an **"\_INERTIAL"** variant that maintains the orientation from the reference epoch:

* `LVLH_INERTIAL`
* `QSW_INERTIAL`
* `RTN_INERTIAL`
* `TNW_INERTIAL`
* `VNC_INERTIAL`

<Warning>
  **LOF naming is not universally standardized.** Always verify the frame definition matches your interface requirements. VALAR's LVLH follows the Vallado/STK convention. For CCSDS RTN compliance, check whether a quasi-inertial variant is expected.
</Warning>

**Use for:**

* Relative guidance and control
* Formation flying
* Rendezvous and proximity operations
* Thrust direction specification
* Payload pointing

***

## Planetary and Body Frames

VALAR supports body-centered inertial and body-fixed frames for major solar system bodies, aligned to IAU pole and prime meridian definitions:

* **Moon** (EME, IAU Moon)
* **Mars** (IAU Mars)
* **Jupiter, Saturn, etc.**

**Use for:**

* Interplanetary missions
* Moon and Mars operations
* Multi-body dynamics

***

## IERS Conventions and EOP Data

Transformations between celestial and terrestrial frames depend on:

1. **IERS Conventions**: Models for precession, nutation, polar motion, and tidal effects
2. **EOP (Earth Orientation Parameters)**: Observed variations in Earth's rotation and orientation

### IERS Convention Selection

| Convention | Accuracy | Use Case                           |
| ---------- | -------- | ---------------------------------- |
| IERS 2010  | Highest  | Modern high-precision applications |
| IERS 2003  | High     | General operational use            |
| IERS 1996  | Moderate | Legacy compatibility               |

### EOP Data Sources

VALAR automatically fetches and updates EOP data from IERS. For offline or restricted environments, EOP files can be manually loaded.

***

## Common Use Cases

### Orbit Propagation (LEO/GEO)

* **Propagate in:** GCRF or EME2000
* **Convert to:** ITRF for ground tracks and visibility

### Ground Station Measurements

* **Station frame:** Topocentric (ENU) over ITRF
* **Measurement types:** Azimuth, Elevation, Range, Range-rate

### Relative Motion (Formation Flying)

* **Choose LOF:** Based on control law (LVLH, QSW, RTN, TNW, VNC)
* **Document choice:** In interface control documents

### Maneuver Planning

* **Define burns in:** RTN (radial-tangential-normal) or LOF matching thruster orientation
* **Export in:** OCM files with specified reference frame

***

## Frame Selection Guide

| Task                       | Recommended Frame            | Alternative |
| -------------------------- | ---------------------------- | ----------- |
| Orbit propagation          | GCRF                         | EME2000     |
| State vector storage       | GCRF                         | EME2000     |
| Ground track visualization | ITRF                         | -           |
| Ground station coordinates | ITRF (specific version)      | -           |
| Maneuver planning          | RTN or spacecraft LOF        | LVLH        |
| Conjunction analysis       | GCRF                         | EME2000     |
| Ephemeris export (OEM)     | GCRF or EME2000              | ITRF        |
| Relative guidance          | LVLH or mission-specific LOF | QSW, RTN    |

***

## Practical Tips

### Frame Selection

1. **Default to GCRF** for celestial work and **ITRF** for Earth-fixed work unless a legacy interface requires otherwise
2. **Document your LOF definition** in interface control documents. Industry definitions differ.
3. **Avoid TEME** as an analysis frame; treat it as a TLE ingestion format only

### High-Precision Applications

4. If you need a specific ITRF version (e.g., ITRF2020) for centimeter-level geodesy, ensure full EOP is loaded
5. Choose IERS 2010 conventions for the highest accuracy
6. Verify EOP data is current (\< 1 week old for best results)

### Legacy System Integration

7. Use EME2000/J2000 when interfaces explicitly require it
8. Convert to recommended frames (GCRF/ITRF) as soon as possible for internal calculations
9. Only use MOD/TOD/GTOD for systems that cannot accept modern frames

### File Format Compatibility

10. **CCSDS formats** (OPM, OEM, OCM) typically use EME2000 or GCRF
11. **TLE files** use TEME frame with SGP4/SDP4 propagators
12. **CDM files** specify their frame explicitly; verify before ingesting

***

## Frame Transformations in VALAR

VALAR automatically handles frame transformations throughout the platform:

* **State Vector Import:** Specify source frame (GCRF, EME2000, ITRF, etc.)
* **Orbit Propagation:** Choose propagation frame (defaults to GCRF)
* **Ephemeris Generation:** Select output frame for OEM export
* **Ground Track Visualization:** Automatic GCRF → ITRF transformation
* **Maneuver Planning:** Define burns in LOF or inertial frames

All transformations account for:

* Time-varying Earth orientation (polar motion, UT1-UTC)
* Precession and nutation
* Tidal effects (when using IERS 2003/2010 conventions)
* Frame-specific corrections per IERS standards

***

## Technical References

VALAR's reference frame implementation is built on industry-standard astrodynamics models, following:

* **IERS Conventions** (2010, 2003, 1996)
* **IAU 2006/2000** precession-nutation model
* **CCSDS Navigation Data Messages** standards
* **Vallado's** *Fundamentals of Astrodynamics and Applications*

For detailed mathematical formulations, consult the IERS Conventions documentation and CCSDS standards.