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.
Where:
is the satellite's position from Earth's centre (m) is the unit vector toward the Sun is Earth's equatorial radius, 6 378 137 m (WGS 84)
Units
- Inputs:
randsunin m, from Earth's centre, on the same axes: SGP4's TEME from propagate, andsunPositionfrom@interstellar-tools/equations. - Output:
truein 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
| 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
boolean
true if the satellite is in the shadow.
Throws
- If
rorsunis not three finite numbers. - If
sunis 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