Skip to content

Positioning & Coordinate Systems

OpenSpace supports multiple Translation and Rotation types inside a node's Transform block. Choosing the right transform depends on whether your object is anchored to a planetary surface, orbiting Earth, following Keplerian elements, or driven by NAIF SPICE kernels.

Translation Comparison Matrix

Translation Type Coordinate System Primary Use Case External Files / APIs
StaticTranslation Cartesian [X, Y, Z] (meters) relative to Parent Deep-sky image planes, fixed galactic markers, offset sub-nodes None (hardcoded coordinates)
GlobeTranslation Geodetic Latitude, Longitude, Altitude Surface landmarks, ground stations, rovers, localized city overlays Parent RenderableGlobe
GPTranslation Earth-centered orbital elements (SGP4/SDP4) Active Earth satellites (ISS, Starlink, Hubble, weather sats) Celestrak OMM/TLE URL or local .txt/.json
KeplerTranslation Classical 6 orbital elements (Eccentricity, SemiMajorAxis, etc.) Asteroids, comets, exoplanets, simplified hypothetical orbits JPL Horizons osculating elements
SpiceTranslation High-precision n-body ephemeris Interplanetary spacecraft, moons, planets, custom mkspk trajectories NAIF .bsp + .tls kernels

Implementation Templates

Pins an object to exact geographic coordinates on any planet or moon with a RenderableGlobe:

Translation = {
    Type = "GlobeTranslation",
    Globe = "Earth",
    Latitude = 41.8781,     -- Decimal degrees (+North / -South)
    Longitude = -87.6298,   -- Decimal degrees (+East / -West)
    Altitude = 1000,        -- Meters above reference ellipsoid/DEM
    UseHeightmap = true     -- Snaps altitude relative to local terrain DEM
}

Propagates Earth-orbiting satellites in real time from Two-Line Element (TLE) or Orbit Mean-Elements Message (OMM) data:

Translation = {
    Type = "GPTranslation",
    TLEFile = asset.localResource("iss.tle"), -- Or synced Celestrak OMM file
    -- Optional: specify line/object index if file contains a constellation
}

Drives analytical two-body orbits from classical Keplerian parameters:

Translation = {
    Type = "KeplerTranslation",
    Eccentricity = 0.0167,
    SemiMajorAxis = 149598023, -- Kilometers
    Inclination = 0.00005,     -- Degrees
    AscendingNode = -11.26064, -- Degrees (Longitude of Ascending Node)
    ArgumentOfPeriapsis = 114.20783,
    MeanAnomaly = 358.617,
    Epoch = "2026 JAN 01 12:00:00",
    Period = 31558149.76       -- Orbital period in seconds
}

Places a node at a fixed meter offset from its Parent (for example, converting Right Ascension / Declination to Cartesian coordinates for a nebula or star cluster):

Translation = {
    Type = "StaticTranslation",
    Position = { 1.5e16, -2.3e16, 4.1e15 } -- { X, Y, Z } in meters
}

Celestrak Rate-Limiting Policy

If you configure HttpSynchronization to pull TLE/OMM files directly from Celestrak, do not repeatedly force-resync or restart OpenSpace in tight loops. Celestrak enforces automated 24-hour IP bans on clients that request identical TLE endpoints too frequently. Cache TLE files locally during testing.

Orientation & Billboard Rotation

To control how an object faces the camera or its parent planet, pair Translation with a Rotation block:

  • StaticRotation: Fixed Euler angles ({ Roll, Pitch, Yaw } in radians) or a 3×3 rotation matrix.
  • GlobeRotation: Aligns the node's local axes to local East-North-Up (ENU) surface coordinates on a planet—essential so surface 3D models sit upright on curved terrain rather than tilting sideways.
  • SpiceRotation: Drives spacecraft attitude (pointing solar panels or instruments) from NAIF C-kernels (.bc) and frame kernels (.tf).