Technical Info

Technical notes about the astronomy data, calculations, validation, references, and known limits behind Darkness Calendar.

Technical overview

Darkness Calendar calculates each night in the browser instead of downloading a ready-made table. The astronomy comes from Astronomy Engine, which can compute Sun, Moon, and planet positions and search for events such as rise, set, transit, and specified altitude crossings. The app supplies the selected coordinates, elevation, time zone, and observing-night date, then reshapes those results into the Darkness Chart: twilight boundaries, event times, moonlit periods, Moon phase and illumination, planet visibility, dark-hour totals, and the shaded bands that make a night readable at a glance. The same calculation path is checked against independent public references so the displayed numbers are not trusted simply because the chart looks plausible.

How the night is calculated

Darkness Calendar starts with a geographical location, using latitude, longitude, elevation, and an IANA time zone such as Europe/Stockholm. The time zone is just as important, because the chart is organized around local nights, not UTC dates. A row in the Darkness Chart runs from 14:00 local time to 10:00 the following local morning, with midnight in the middle. Astronomy Engine gives the app astronomical instants; Darkness Calendar decides how those instants belong to the night.

Astronomy Engine is the low-level calculation source. It is not an online lookup service and the app does not fetch daily ephemeris tables. The package contains mathematical models that can return the apparent position of the Sun, Moon, and planets for a given observer and time. It can also search for useful event times: when a body rises or sets, when the Sun crosses a requested altitude, and when a planet crosses the local meridian. Darkness Calendar uses those searches for sunrise, sunset, moonrise, moonset, civil, nautical, and astronomical twilight, and optional planet rise, transit, and set times.

Twilight is handled as a Sun-altitude crossing. Civil twilight uses the Sun center at -6 degrees, nautical twilight at -12 degrees, and astronomical twilight at -18 degrees. That is different from sunrise and sunset, which are horizon events for the visible solar disc and include the rise/set conventions applied by the underlying engine. The distinction matters because a twilight time and a rise/set time are not just two labels for the same calculation. If the Sun never reaches -18 degrees below the horizon on a high-latitude summer night, the app leaves astronomical dusk and dawn missing.

Intervals and visual layers

The event times shown in the tables are only part of the result. The app's primary use is in visualizing darkness intervals such as astronomical darkness, which is the interval where the Sun is below -18 degrees. Moon visibility is the interval where the Moon is above the horizon at any time between sunset and sunrise. Moon-free astronomical darkness is calculated by subtracting Moon-visible intervals from astronomical-darkness intervals. The Effective Darkness Window uses the same kind of interval arithmetic, either from the default astronomical-night window or from the user's custom window markers, and then removes the parts where the Moon is visible.

The Moon display combines exact boundaries with visual approximation. The app calculates Moon illumination near local midnight for the selected observing night, then uses neighboring nights to decide whether the displayed phase is waxing or waning. For the Darkness Chart shading, the app calculates Sun and Moon altitude at regular points across the night. Those points are not event times. They are a rendering aid used to vary the strength of the translucent Moon overlay according to Moon altitude and illumination phase. As a technical detail, the left and right edges of that overlay are still clipped to the actual Moon visibility intervals, so the shaded area should start and end at moonrise or moonset rather than at the nearest visual calculation point. This ensures that the edges of the Moon shades on the chart are very accurate.

Daylight and twilight bands come from Sun altitude. Moon shading estimates the relative visual influence of the Moon from altitude and illuminated fraction. Darkness-window highlights come from interval calculations. Keeping those jobs separate is important: visual layers can be smooth and useful, but totals and event boundaries should come from event searches and interval math, which are much more accurate.

Planet support follows the same model. When enabled, the app asks Astronomy Engine for rise, transit, and set events for the selected planets and calculates above-horizon intervals. The chart can then show whether a planet is up during the night and where its event lines fall. This is meant for planning visibility during darkness.

Validation

Validation of the software is layered. First, Astronomy Engine has its own upstream validation against established ephemeris references. Darkness Calendar does not try to reproduce the full celestial-mechanics validation of that library. Instead, it validates the app's use of the library: local date handling, time-zone conversion, daylight-saving boundaries, high-latitude nights with missing astronomical twilight, Moon rise/set behavior around row edges, Moon illumination, and a planet example. The checked reference values are stored with the project so the validation can run repeatably without depending on a live web page.

The external comparison sources are deliberately varied. Timeanddate.com is used for public Sun and Moon event pages, Sunrise-Sunset.org for coordinate-based Sun and twilight values, and In-The-Sky.org for Moon and planet-oriented reference values. Agreement is required across different locations, seasons, event types, daylight-saving cases, missing-event cases, and independent sources. It also catches the bugs most likely to affect this application: wrong local date, wrong row boundary, wrong time-zone offset, using a visual approximation as an exact total, or clipping one chart layer differently from another.

Some differences from other sites are still expected. Public calculators may use a city-center coordinate rather than the exact observing site, different elevation, different refraction assumptions, different rounding, or a different convention for lunar illumination. Moon rise and set are especially sensitive because the Moon is close, fast moving, and affected by parallax and horizon assumptions. Near the horizon, real atmospheric refraction can move an apparent event by minutes. A tree line, hill, roof, or mountain ridge can move the practical observing time by much more than that.

What the app does not calculate is also important. It does not know the local horizon profile. It does not predict measured sky brightness in magnitudes per square arcsecond. The correct way to read the output is therefore practical rather than absolute: the event times are mathematically grounded and checked against external references, the darkness totals are interval-derived, the chart shading is a visual guide, and the largest real-world errors will usually come from horizon, atmosphere, and sky conditions rather than from the ephemeris calculation itself.

Licenses and attribution

Darkness Calendar is built on freely available browser packages and public media assets. The astronomy calculations use Astronomy Engine under the MIT license, and the offline coordinate-to-time-zone lookup uses @photostructure/tz-lookup under CC0. The build and test tooling uses common open-source licenses such as MIT, Apache-2.0, BSD-3-Clause, ISC, and MPL-2.0.

The Moon texture used in the Moon phase display comes from NASA's Scientific Visualization Studio CGI Moon Kit, based on Lunar Reconnaissance Orbiter data products. NASA media guidelines generally allow informational web use of NASA imagery and texture maps, with NASA acknowledged as the source and without implying NASA endorsement.

The location picker world map is based on the Wikimedia Commons equirectangular blank world map, published under the Creative Commons CC0 public-domain dedication. The small validation reference values in the project are factual event-time checks captured from public astronomy references and are used only to verify the app's calculations, not as a reusable data set.

References