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.
Where:
is the slope and 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) 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
; 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
. - 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
slope0,aspectis ignored and may beNaN. ANaNslope, from the edge of a grid or a missing cell, givesNaN.
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.01Parameters
| Parameter | Type | Description |
|---|---|---|
slope | Radians | Slope NaN). |
aspect | Radians | Aspect slope is 0). |
sunAzimuth | Radians | Sun's azimuth |
sunElevation | Radians | Sun's elevation |
Returns
number
The hillshade in [0, 1], or NaN for a NaN slope.
Throws
- If
sunAzimuth,sunElevationor a sloping cell'saspectis not finite, orslopeis infinite. - If
slopeis outside [0, π/2], orsunElevationoutside [−π/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.97See
- hillshadeGrid
- lambertReflectance
- https://doi.org/10.1109/PROC.1981.11918 Horn (1981), Hill shading and the reflectance map