Environment · interface

CelestialSite

Where in the world, and when in the year, the sky is being sampled.

Explained in Sky and atmosphere.

interface CelestialSite
import type { CelestialSite } from '@driftengine/core';

In depth

A site rather than a latitude alone, because latitude and season are one question: the sun's altitude is a function of the declination and the latitude, and a model with one and not the other is wrong in a way that only shows up six months later.

Properties

NameTypeDescription
latitudeDegreadonlynumberDegrees north of the equator, −90 to 90. Clamped rather than refused, because a value past a pole is a caller's arithmetic overshooting rather than a request for something impossible.
longitudeDegreadonlyoptionalnumberDegrees east of Greenwich, −180 to 180, or absent.
More

Naming this or utcOffsetHours changes what the timestamp means: it stops being read through the host machine's time zone and becomes a plain UTC instant, from which this site's own hour is derived. See celestialStateAt. Not clamped, because a longitude is an angle and a value past the antimeridian means the place a turn around says it does.

Alone, it also stands in for the zone: a place is assumed to keep the time of its own meridian, which is exact solar time and differs from a real zone by up to half an hour.

utcOffsetHoursreadonlyoptionalnumberHours this site's wall clock runs ahead of UTC — 2 for Italy in summer — or absent.
More

The other half of the pair above, and the same switch: naming it makes the timestamp a UTC instant. It is what turns that instant into the site's calendar day, which is the one thing a longitude cannot do; with longitudeDeg beside it the sun also stops sitting at the zone's centre and moves to the place's real meridian, up to half an hour either way.

Daylight saving is the caller's, because a zone's offset is a function of the date and of legislation, and an engine that shipped a table of it would ship a table that expires.

dayOfYearreadonlyoptionalnumberDay of the year, 1 to 365, or absent to take it from the timestamp.
More

Present because a world may run on a calendar of its own — a game whose year is forty days still wants a season — and taking it from the timestamp would tie that to the wall clock.

obliquityDegreadonlyoptionalnumberThe planet's axial tilt in degrees. Earth's 23.44 by default.
More

Zero is a world with no seasons at all, where the sun's arc is the same every day and depends on latitude alone; larger values are a world with sharper ones. It is here because it costs one multiply and because a stylised world is exactly the consumer this engine has.