Skip to content

Documentation / @interstellar-tools/tracking / groundTrack

Function: groundTrack() ​

ts
function groundTrack(
  elements: MeanElementsInterface,
  from: Date,
  to: Date,
  step?: number
): GeodeticCoordinatesInterface[][];

Defined in: satellites/ground-track.ts:69

The ground track of a satellite: the points on the ground directly below it over time, ready to draw on a flat map.

Steps subSatellitePoint from from to to, and splits the track where it crosses the antimeridian, ±180°: each segment ends at the edge of the map, and the next starts at the other edge, at the latitude where the track crosses it. A renderer then never draws a line across the whole map.

Notes

  • Westward drift. Each orbit's track lies west of the one before, by the angle Earth turns in an orbit: about 23° for the ISS.
  • A geostationary satellite's track is a point, or a small figure eight if its orbit is a little inclined.
  • Each point's h is the satellite's height above the WGS 84 ellipsoid.
  • Pick the step to suit the map: a minute draws a smooth track for a low orbit. The track is linear between points, so a step much longer than a few minutes cuts corners.

Parameters ​

ParameterTypeDefault valueDescription
elementsMeanElementsInterfaceundefinedThe mean elements, from parseTle or parseOmm.
fromDateundefinedStart of the track, as a Date.
toDateundefinedEnd of the track, as a Date after from.
step?number60Time between points in s (finite, > 0): 60 by default.

Returns ​

GeodeticCoordinatesInterface[][]

The track, as segments of points: geodetic latitude phi and longitude lambda in radians, longitude in (-π, π], and height h in m.

Throws ​

  • If from or to is not a valid Date, step is not a finite number, or a value of elements is not a finite number.
  • If to is not after from, step <= 0, the track would have more than a million points, or SGP4 fails along it, as in propagate.

Example ​

ts
const now = new Date();
const later = new Date(now.getTime() + 92 * 60_000); // one ISS orbit

for (const segment of groundTrack(iss, now, later))
  drawLine(segment.map(({ phi, lambda }) => [toDeg(lambda), toDeg(phi)]));

See ​