SGP4 Orbit Propagation: TLE and Element-Based Methods

IRBEM includes the SGP4 (Simplified General Perturbation-4) orbit propagator for NORAD two-line element (TLE) sets. Two entry points are provided: SGP4_TLE propagates TLE files obtained from external sources, while SGP4_ELE computes orbit coordinates directly from a set of orbital elements without requiring a TLE file. A utility routine RV2COE converts position/velocity state vectors to classical orbital elements.

Unlike the original SGP4 implementation, IRBEM’s version accepts start time, stop time, and time step in seconds rather than minutes. This was chosen for convenience.

SGP4_TLE

SGP4_TLE propagates NORAD two-line elements from a file and writes the resulting spacecraft position time series to an output file. TLE sets can be obtained from http://celestrak.com/.

On Unix/Linux systems, TLE files downloaded from NORAD must be converted from DOS (CRLF) to Unix (LF) line endings before use:

dos2unix file.tle newfile.tle

Some TLE files contain errors such as elements from a different satellite or repeated entries. IRBEM’s SGP4 function implements no filters for these issues — inspect your TLE files before use.

Parameters

runtype

integer

required

Controls the start and stop time source:

Value	Behaviour
`0`	Start and stop times are read from the TLE file itself
`1`	Start and stop times are supplied by the user via `startsfe` and `stopsfe`

startsfe

double

required

Start time as seconds from the epoch of each TLE. May be negative. Ignored when runtype = 0.

stopsfe

double

required

Stop time as seconds from the epoch of each TLE. May be negative. Ignored when runtype = 0.

deltasec

double

required

Propagation time step in seconds.

InFileByte

byte array

required

Path and filename of the input TLE file, encoded as a byte array.

strlenIn

integer

required

Length of the InFileByte string.

OutFileByte

byte array

required

Path and filename for the output file, encoded as a byte array.

strlenOut

integer

required

Length of the OutFileByte string.

Output

The output file contains 6 space-delimited columns per propagated time step:

Column	Quantity	Format / Units
1	Date	dd/mm/yyyy
2	Time	hh:mm:ss
3	Decimal year	—
4	Altitude	km
5	Latitude	degrees
6	East longitude	degrees

Call Sequences

! runtype = 1: propagate with user-specified times, 60-second steps
CALL sgp4_tle1(1, 0.0d0, 86400.0d0, 60.0d0, InFileByte, strlenIn, OutFileByte, strlenOut)

! runtype = 0: use start/stop times from the TLE file
CALL sgp4_tle1(0, 0.0d0, 0.0d0, 60.0d0, InFileByte, strlenIn, OutFileByte, strlenOut)

The MATLAB wrapper automatically computes runtype, strlenIn, OutFileByte, and strlenOut. By default it writes to a temporary file (onera_desp_lib_sgp4_tle.tmp), reads the results back into a MATLAB structure, and deletes the temporary file. To retain the output as a text file for very long TLE runs, call onera_desp_lib_sgp4_tle(InFile, OutFile).

SGP4_ELE

SGP4_ELE propagates an orbit defined by orbital elements rather than a TLE file and returns the spacecraft positions as arrays in the user-selected output coordinate system.

Parameters

sysaxesOUT

integer

required

Key for the output coordinate system. See the coordinate systems reference.

year

integer

required

Year of the start epoch.

month

integer

required

Month of the start epoch.

day

integer

required

Day of the start epoch.

hour

integer

required

Hour of the start epoch.

minute

integer

required

Minute of the start epoch.

seconds

integer

required

Seconds of the start epoch.

e1 – e6

double

required

Six orbital elements. Their meaning depends on the options array:

`options(1)`	Type	e1	e2	e3	e4	e5	e6
`1`	ONERA	inclination (deg)	perigee altitude (km)	apogee altitude (km)	RAAN (deg)	arg/lon of perigee (deg)	anomaly/latitude/longitude
`2`	Classical	semimajor axis (Re)	eccentricity	inclination (deg)	RAAN (deg)	arg/lon of perigee (deg)	anomaly
`3`	RV	xGEI (km)	yGEI (km)	zGEI (km)	VxGEI (km/s)	VyGEI (km/s)	VzGEI (km/s)
`4`	Solar	inclination (deg)	perigee altitude (km)	apogee altitude (km)	LT of apogee (h)	LT of max inclination (h)	anomaly
`5`	Mean	mean motion (rev/day)	eccentricity	inclination (deg)	RAAN (deg)	arg/lon of perigee (deg)	anomaly

options

integer[5]

required

Element type specifiers:

options(1): orbital element set type (1–5, see table above)
options(2): 1 = argument of perigee, 2 = longitude of perigee (for types 1, 2, 5)
options(3): 1 = time since perigee passage (s), 2 = true anomaly (deg), 3 = argument of latitude (deg), 4 = true longitude (deg), 5 = mean anomaly (deg)

startsfe

double

required

Start time from the provided epoch in seconds. May be negative.

stopsfe

double

required

Stop time from the provided epoch in seconds. May be negative.

deltasec

double

required

Propagation step time in seconds.

Output

OUTyear

integer[NTIME_MAX]

Year for each orbital position.

OUTdoy

integer[NTIME_MAX]

Day of year for each orbital position.

double[NTIME_MAX]

Time of day in seconds for each position.

double[NTIME_MAX]

First coordinate in sysaxesOUT.

double[NTIME_MAX]

Second coordinate in sysaxesOUT.

double[NTIME_MAX]

Third coordinate in sysaxesOUT.

Call Sequences

CALL sgp4_ele1(sysaxesOUT, year, month, day, hour, minute, sec, &
    e1, e2, e3, e4, e5, e6, options, startsfe, stopsfe, deltasec, &
    OUTyear, OUTdoy, UT, X1, X2, X3)

RV2COE — State Vector to Orbital Elements

RV2COE converts a position and velocity vector in GEI coordinates to the classical set of orbital elements. It is included in the IRBEM SGP4 distribution.

Parameters

double[3]

required

Position vector in GEI (km).

double[3]

required

Velocity vector in GEI (km/s).

Output

double

Semilatus rectum (km).

double

Semimajor axis (km).

ecc

double

Eccentricity.

incl

double

Inclination (rad).

omega

double

Longitude of ascending node (rad).

argp

double

Argument of perigee (rad).

double

True anomaly (rad).

double

Mean anomaly (rad).

argLat

double

Argument of latitude (rad).

lamTrue

double

True longitude (rad).

lonPer

double

Longitude of periapsis (rad).

Call Sequences

CALL rv2coe(R, V, P, A, Ecc, Incl, Omega, Argp, Nu, M, ArgLat, LamTrue, LonPer)

Typical Workflow

The following example illustrates a complete TLE propagation and the equivalent element-based propagation.

! --- SGP4_TLE: propagate 1 day starting from TLE epoch, 60-second steps ---
integer :: lenIn, lenOut
character(len=256) :: InFile, OutFile

InFile  = '/data/tles/noaa18.tle'
OutFile = '/data/output/noaa18_orbit.txt'
lenIn   = len_trim(InFile)
lenOut  = len_trim(OutFile)

CALL sgp4_tle1(1, 0.0d0, 86400.0d0, 60.0d0, &
    InFile, lenIn, OutFile, lenOut)

% --- MATLAB: propagate TLE and obtain a structure ---
pos = onera_desp_lib_sgp4_tle('noaa18.tle');
% pos.Bdate  — [dd mm yyyy] date columns
% pos.Btime  — [hh mm ss]  time columns
% pos.alt    — altitude (km)
% pos.lati   — latitude (deg)
% pos.longi  — East longitude (deg)

% --- Element-based propagation: ISS-like orbit, GEO output ---
% ONERA elements: incl=51.6 deg, hp=410 km, ha=415 km, RAAN=0, argp=0, M=0
e = [51.6, 410, 415, 0, 0, 0];
startdate = datenum(2024, 6, 1,  0, 0, 0);
enddate   = datenum(2024, 6, 1, 12, 0, 0);
pos = onera_desp_lib_sgp4_ele(e, startdate, enddate, 60, 1); % sysaxesOUT=1 (GEO)

Overview

Magnetic Coordinates

Coordinate Transformations

Models

Utilities

SGP4 Orbit Propagation: TLE and Element-Based Methods

SGP4_TLE

Parameters

Output

Call Sequences

SGP4_ELE

Parameters

Output

Call Sequences

RV2COE — State Vector to Orbital Elements

Parameters

Output

Call Sequences

Typical Workflow

Build docs developers (and LLMs) love

Overview

Magnetic Coordinates

Coordinate Transformations

Models

Utilities

Documentation Index

​SGP4_TLE

​Parameters

​Output

​Call Sequences

​SGP4_ELE

​Parameters

​Output

​Call Sequences

​RV2COE — State Vector to Orbital Elements

​Parameters

​Output

​Call Sequences

​Typical Workflow

Build docs developers (and LLMs) love

SGP4_TLE

Parameters

Output

Call Sequences

SGP4_ELE

Parameters

Output

Call Sequences

RV2COE — State Vector to Orbital Elements

Parameters

Output

Call Sequences

Typical Workflow