Skip to content

Documentation / @interstellar-tools/maps / hillshadeAt

Function: hillshadeAt() ​

ts
function hillshadeAt(
  slope: Radians,
  aspect: Radians,
  sunAzimuth: Radians,
  sunElevation: Radians
): number;

Defined in: terrain/hillshade.ts:93

Compute the hillshade of a patch of terrain: how brightly the Sun lights it, from its slope and aspect.

cos⁡i=sin⁡αcos⁡s+cos⁡αsin⁡scos⁡(ψ−A),hillshade=max(0,cos⁡i)

Where:

  • s is the slope and A the aspect, clockwise from north (rad), from slopeAt and aspectAt
  • ψ is the Sun's azimuth, clockwise from north, and α its elevation above the horizon (rad)
  • i is the angle between the Sun and the ground's normal: the incidence angle

Units

  • Inputs: all angles in radians.
  • Output: brightness in [0, 1]: 1 facing the Sun squarely, 0 facing away from it.

Notes

  • It's lambertReflectance for the ground's normal: what shaded relief maps show. Level ground gets sin⁡α; a slope facing the Sun gets more, one facing away less.
  • The Sun's azimuth uses the same convention as the aspect, so a slope faces the Sun when ψ=A.
  • Only the patch's own orientation counts: it doesn't know about shadows cast by other terrain, such as a crater's rim. A slope can be lit while the Sun is below the horizon, if it faces it steeply enough.
  • Level ground has no aspect: with slope 0, aspect is ignored and may be NaN. A NaN slope, from the edge of a grid or a missing cell, gives NaN.
In practiceApollo 11, morning at Tranquility Base

0.19

Level ground, with the Sun 10.8° above the eastern horizon

A 10° slope facing the Sun was almost twice as bright, 0.36, and one facing away almost black, 0.01. That contrast is why Apollo landings came in with the Sun low behind them: craters and boulders stood out.

ts
const sun = toRad(10.8);
const east = toRad(90);
hillshadeAt(0 as Radians, NaN as Radians, east, sun); // ≈ 0.19
hillshadeAt(toRad(10), east, east, sun); // ≈ 0.36
hillshadeAt(toRad(10), toRad(270), east, sun); // ≈ 0.01

Parameters ​

ParameterTypeDescription
slopeRadiansSlope s in radians (in [0, π/2], or NaN).
aspectRadiansAspect A in radians, clockwise from north (finite; ignored when slope is 0).
sunAzimuthRadiansSun's azimuth ψ in radians, clockwise from north (finite).
sunElevationRadiansSun's elevation α above the horizon in radians (in [−π/2, π/2]).

Returns ​

number

The hillshade in [0, 1], or NaN for a NaN slope.

Throws ​

  • If sunAzimuth, sunElevation or a sloping cell's aspect is not finite, or slope is infinite.
  • If slope is outside [0, π/2], or sunElevation outside [−π/2, π/2].

Example ​

ts
import type { Radians } from '@interstellar-tools/types';

// A 30° slope facing south, the Sun 45° up in the south
hillshadeAt(
  (Math.PI / 6) as Radians,
  Math.PI as Radians,
  Math.PI as Radians,
  (Math.PI / 4) as Radians
); // sin 75° ≈ 0.97

See ​