Sgp4Ex

Sgp4Ex is an Elixir NIF wrapper for the SGP4 source code available at https://celestrak.org/publications/AIAA/2006-6753/ - it allows propagation of Two-Line Element sets (TLEs) to get TEME state vectors describing the position/velocity of satellites.

Features

• High-accuracy SGP4 propagation using the official C++ implementation
• Forgiving TLE parser that handles common data issues
• TEME to geodetic coordinate conversion (latitude/longitude/altitude)
• Sub-meter accuracy at epoch, maintains excellent accuracy for typical propagation periods

Installation

Sgp4Ex can be installed by adding it to mix.exs:

def deps do
  [
    {:sgp4_ex, "~> 0.2.0"}
  ]
end

Usage

Basic TLE Propagation

# Parse a TLE
line1 = "1 25544U 98067A   21275.54791667  .00001264  00000-0  39629-5 0  9993"
line2 = "2 25544  51.6456  23.4367 0001234  45.6789 314.3210 15.48999999    12"
{:ok, tle} = Sgp4Ex.parse_tle(line1, line2)

# Propagate to a specific time
epoch = ~U[2021-10-02T14:00:00Z]
{:ok, teme_state} = Sgp4Ex.propagate_tle_to_epoch(tle, epoch)

# Get position and velocity in TEME frame (km and km/s)
{x, y, z} = teme_state.position
{vx, vy, vz} = teme_state.velocity

Geodetic Coordinates

# Get latitude, longitude, and altitude
{:ok, geo} = Sgp4Ex.propagate_to_geodetic(tle, epoch)
IO.puts("Latitude: #{geo.latitude}°")
IO.puts("Longitude: #{geo.longitude}°")
IO.puts("Altitude: #{geo.altitude_km} km")

Forgiving TLE Parser

The TLE parser automatically handles common data issues:

• Trailing whitespace and backslashes
• Truncated checksums
• Leading dots in floats (.123 → 0.123)
• Spaces in numeric fields

Technical Details

Coordinate Systems

• TEME (True Equator Mean Equinox): Output frame from SGP4
• ECEF (Earth-Centered Earth-Fixed): Intermediate frame for geodetic conversion
• Geodetic: WGS84 latitude, longitude, and altitude

The implementation uses the classical IAU 1982 model for Greenwich Mean Sidereal Time (GMST). This differs from modern implementations like Skyfield by approximately 0.536° in longitude due to the Equation of the Equinoxes (the difference between mean and apparent sidereal time).

Build Requirements

• Erlang/OTP with NIF support
• C++ compiler
• Make

The build process is handled automatically by the custom Mix task.

License

This project is licensed under the same terms as the original SGP4 source code.