Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/PRBEM/IRBEM/llms.txt

Use this file to discover all available pages before exploring further.

IRBEM supports 15 coordinate systems for specifying spacecraft positions and for transforming vectors between frames. The sysaxes integer key selects the coordinate system for input positions passed to most IRBEM routines, and is also used as the sysaxesIn / sysaxesOut arguments to the Coords.transform() function in the Python wrapper.

​
Coordinate System Reference Table

KeyNameDescription
0GDZGeodetic: altitude (km), latitude (deg), East longitude (deg) — uses the WGS84 reference ellipsoid
1GEOGeocentric geographic cartesian (Re) — Earth-Centered Earth-Fixed; X in equatorial plane at prime meridian, Z toward True North
2GSMGeocentric Solar Magnetospheric cartesian (Re) — X points sunward; X–Z plane contains Earth’s dipole axis (positive North)
3GSEGeocentric Solar Ecliptic cartesian (Re) — X points sunward; Y in ecliptic plane pointing anti-orbit; Z toward ecliptic pole
4SMSolar Magnetic cartesian (Re) — Z aligned with centered dipole axis (positive North); Y perpendicular to Sun–Earth line and dipole axis
5GEIGeocentric Equatorial Inertial cartesian (Re) — X toward equinox of date; Z parallel to instantaneous Earth rotation axis
6MAGGeomagnetic cartesian (Re) — Z parallel to centered dipole axis (positive North); Y at 90° east of dipole meridian in the equatorial plane
7SPHGEO in spherical (Re, lat deg, East lon deg) — geocentric geographic coordinates expressed in spherical instead of Cartesian
8RLLGeodetic spherical (Re, lat deg, East lon deg) — radial distance instead of altitude, but latitude remains geodetic (not geocentric)
9HEEHeliocentric Earth Ecliptic cartesian (Re) — origin at solar center; X toward Earth; Z perpendicular to Earth’s orbital plane (positive North)
10HAEHeliocentric Aries Ecliptic cartesian (Re) — origin at solar center; Z perpendicular to Earth’s orbital plane (positive North); X toward equinox of date
11HEEQHeliocentric Earth Equatorial cartesian (Re) — origin at solar center; Z parallel to Sun’s rotation axis (positive North); X toward intersection of solar equator and central meridian as seen from Earth
12TODTrue of Date (cartesian, Re) — same as GEI; uses true equator and equinox of date; included for legacy support
13J2000GEI at J2000 (cartesian, Re) — X aligned with mean equinox at J2000; Z parallel to mean rotation axis at J2000 (corrects for precession, not nutation)
14TEMETrue Equator Mean Equinox (cartesian, Re) — inertial system used by the SGP4 orbit propagator

​
Axis Orientations in Detail

​
Near-Earth Systems (GDZ, GEO, GSM, GSE, SM, GEI, MAG, SPH, RLL)

GDZ (key 0) stores positions as (altitude, latitude, longitude) tuples — not Cartesian. Altitude is measured above the WGS84 ellipsoid in kilometres; latitude is geodetic. This is the default sysaxes value in the Python wrapper and is the natural format for satellite tracking data. GEO (key 1) is Cartesian and Earth-fixed (rotates with the Earth). X lies at the intersection of the equatorial plane and the prime meridian (Greenwich). Z points toward the geographic North Pole. GSM (key 2) is the workhorse system for magnetospheric physics. X always points from Earth toward the Sun. The X–Z plane is tilted to contain the dipole axis, so the magnetospheric equatorial plane is not the same as the geographic equator. GSE (key 3) also has X pointing sunward, but the Y and Z axes are defined by the ecliptic plane rather than the dipole orientation. It is preferred for solar wind and IMF analyses. SM (key 4) is similar to GSM but rotated about Y so that Z is strictly aligned with the dipole axis. X in SM is therefore not exactly along the Sun–Earth line. GEI (key 5) is a quasi-inertial frame: axes are fixed to the true equator and equinox of date, so they precess slowly. Also returned as TOD (key 12) for legacy compatibility. MAG (key 6) is the geomagnetic system whose Z axis is the centered-dipole axis. It is useful for expressing pitch-angle distributions and magnetic latitude. SPH (key 7) expresses the same geographic frame as GEO but in spherical coordinates: (r, geocentric latitude, East longitude). Note that latitude here is geocentric, not geodetic. RLL (key 8) is the spherical counterpart of GDZ: (r, geodetic latitude, East longitude). The latitude is geodetic and therefore is not interchangeable with SPH despite similar appearance.

​
Heliocentric Systems (HEE, HAE, HEEQ)

These systems have their origin at the solar center and use Earth-radius (Re) as the distance unit. They are useful for solar wind propagation delay calculations and inner-heliosphere analyses. HEE (key 9) rotates with the Earth–Sun line; HAE (key 10) and HEEQ (key 11) are inertial or slowly varying.

​
Inertial Reference Systems (TOD, J2000, TEME)

Four geocentric equatorial inertial systems are in widespread use: J2000, MOD (Mean of Date), TOD, and TEME. IRBEM defines its geophysical coordinate systems (GSE, GSM, SM, etc.) relative to TOD. Correcting J2000 for precession gives MOD, and then correcting for nutation gives TOD (identical to IRBEM’s GEI).
TEME (key 14) is the coordinate system output by the SGP4 two-line element propagator. If you are computing positions from TLE data you should use sysaxes=14 for input and then transform to your preferred working frame.

​
Python Usage

In the MagFields class, sysaxes is set at construction time and applies to all subsequent calls: 
from IRBEM import MagFields

# GDZ input: (altitude km, latitude deg, East longitude deg)
model = MagFields(kext='T96', sysaxes=0)

X = {
    'dateTime': '2020-06-01T12:00:00',
    'x1': 550.0,   # altitude (km)  — GDZ
    'x2': 45.0,    # latitude (deg)
    'x3': 10.0,    # East longitude (deg)
}
For coordinate transformations, pass system names as strings to Coords.transform(): 
import datetime
import numpy as np
from IRBEM import Coords

c = Coords()

t = datetime.datetime(2020, 6, 1, 12, 0, 0)
pos_geo = np.array([[3.0, 1.5, 2.0]])  # GEO cartesian, Re

# Transform GEO → GSM
pos_gsm = c.transform(t, pos_geo, 'GEO', 'GSM')
print(pos_gsm)
String keys accepted by Coords.transform(): 'GDZ', 'GEO', 'GSM', 'GSE', 'SM', 'GEI', 'MAG', 'SPH', 'RLL'. Integer keys (0–14) are also accepted.
GDZ vs SPH: GDZ (key 0) uses geodetic latitude (WGS84 ellipsoid-referenced), while SPH (key 7) uses geocentric latitude. These differ by up to ~0.19° and the two formats are not interchangeable, even though both express positions as (distance/altitude, latitude, longitude).
When working with satellite data in the common altitude/latitude/longitude format, use sysaxes=0 (GDZ). This is also the default in the Python MagFields constructor, so you can omit the sysaxes keyword unless you need a different system.

Build docs developers (and LLMs) love

Get started for freeTalk to us