Documentation / @interstellar-tools/tracking / earthShadow
Function: earthShadow()
ts
function earthShadow(r: Vector3DTupleType, sun: Vector3DTupleType): ShadowType;Defined in: satellites/shadow.ts:135
Where a satellite is relative to Earth's shadow: in sunlight, in the penumbra where Earth covers part of the Sun, or in the umbra where it covers all of it.
Compares the apparent radii of the Sun and of Earth, seen from the satellite, with the angle between them:
The satellite is sunlit if
Where:
, are the satellite's and the Sun's positions from Earth's centre (m) is the Sun's radius, 695 700 km (IAU 2015 B3) is Earth's equatorial radius, 6 378 137 m (WGS 84)
Units
- Inputs:
randsunin m, from Earth's centre, on the same axes. - Output:
'sunlit','penumbra'or'umbra': see ShadowType.
Notes
- Earth is taken as a sphere without an atmosphere, as in isInEarthShadow. Refraction through the atmosphere lights the umbra a deep red; a satellite there is dark to the eye and its solar panels.
- A low satellite crosses the penumbra in about 10 s; Earth's umbra ends about 1.4 million km away, past which the satellite would see Earth pass across the Sun, in the penumbra.
Parameters
| Parameter | Type | Description |
|---|---|---|
r | Vector3DTupleType | The satellite's position in m, from Earth's centre. |
sun | Vector3DTupleType | The Sun's position in m, from Earth's centre, on the same axes. |
Returns
'sunlit', 'penumbra' or 'umbra'.
Throws
- If
rorsunis not three finite numbers. - If
ris within Earth's equatorial radius of its centre, orsunis at Earth's centre.
Example
ts
const date = new Date('2026-11-04T12:00:00Z');
earthShadow(propagate(iss, date).r, sunPosition(date).r); // 'sunlit', 'penumbra' or 'umbra'