Skip to content

Documentation / @interstellar-tools/tracking / isInEarthShadow

Function: isInEarthShadow() ​

ts
function isInEarthShadow(r: Vector3DTupleType, sun: Vector3DTupleType): boolean;

Defined in: satellites/shadow.ts:62

Whether a satellite is in Earth's shadow, taking the shadow as a cylinder as wide as Earth, straight back from the Sun. It's the usual quick test for whether a satellite is lit.

r⋅s^<0and‖r−(r⋅s^)s^‖<R⊕

Where:

  • r is the satellite's position from Earth's centre (m)
  • s^ is the unit vector toward the Sun
  • R⊕ is Earth's equatorial radius, 6 378 137 m (WGS 84)

Units

  • Inputs: r and sun in m, from Earth's centre, on the same axes: SGP4's TEME from propagate, and sunPosition from @interstellar-tools/equations.
  • Output: true in the shadow.

Notes

  • The real shadow narrows into a cone, the umbra, inside a widening penumbra. The cylinder lies between the two, so it puts the start and end of an eclipse a few seconds out for a low orbit. earthShadow tells umbra and penumbra apart.
  • Earth's atmosphere and flattening shift the edge by a few kilometres, about a second for the ISS.

Parameters ​

ParameterTypeDescription
rVector3DTupleTypeThe satellite's position in m, from Earth's centre.
sunVector3DTupleTypeThe Sun's position in m, from Earth's centre, on the same axes.

Returns ​

boolean

true if the satellite is in the shadow.

Throws ​

  • If r or sun is not three finite numbers.
  • If sun is at Earth's centre.

Example ​

ts
const date = new Date('2026-11-04T12:00:00Z');

isInEarthShadow(propagate(iss, date).r, sunPosition(date).r); // true in eclipse

See ​

earthShadow