Calculation methodology

Solar geometry and civil time

SunCarta uses Astronomy Engine 2.1.19, under the MIT license, locally in the browser. Position uses a UTC instant, north-positive latitude and east-positive longitude at a sea-level astronomical observer. Azimuth is clockwise from true north: north 0°, east 90°, south 180°, west 270°. Elevation is the topocentric solar centre without atmospheric refraction. Near the zenith and geographic poles, azimuth is poorly conditioned.

Valid local dates span 1900–2100. Coordinates select an IANA time zone; the runtime time-zone database supplies historical and future civil rules. A repeated DST hour offers two instants. A nonexistent clock time moves forward by the gap, with the adjustment reported. Civil days are integrated over their actual UTC membership intervals, including 23-hour, 25-hour and historically skipped dates. Future government time-zone changes cannot be predicted by today’s database.

Events and open-horizon daylight

Sunrise and sunset use the standard upper-limb horizon convention: 34 arcminutes of atmospheric refraction plus the solar angular radius at that instant. This is approximately −0.833° centre altitude. Terrain, weather and observer elevation do not change these standard event times. Solar noon is the meridian transit, not necessarily 12:00 local time.

Civil, nautical and astronomical twilight use geometric centre elevations of −6°, −12° and −18°. Golden windows use −4° to +6° while rising and +6° to −4° while setting. These are geometric conventions, not promises of photographic color. Polar or transition days can lack individual events; daylight is integrated over real elapsed intervals rather than subtracting wall-clock labels.

Season shortcuts solve solar-longitude events for the chosen year. The Annual light heatmap samples elevation hourly against dates with an open horizon. It does not represent annual garden exposure or cloud-filtered sunshine.

Shadow length and modeled obstructions

Level-ground shadow length = height ÷ tan(solar elevation)

For positive geometric elevation, numeric shadow length is uncapped and its bearing is opposite the Sun. The map clips its visible projection at 100 km. Extreme near-horizon lengths exceed the practical validity of a level plane: curvature, slope and refraction are excluded.

Building, Wall and Tree labels use finite opaque vertical screens with height, width, position and rotation. Rotation is the screen’s normal clockwise from true north. They are not volumetric buildings or leaf-transmission models. A zero-opacity imported screen is ignored; positive opacity does not simulate partial sunlight. The default scene contains no obstacles.

Receiver height and obstacle height must share the same ground reference. A manually entered horizon interpolates between azimuth/elevation points and can block the modeled ray. It does not alter standard sunrise/set or the open-horizon Annual light heatmap. Optional Context imports add a coarse sampled terrain horizon and available OpenStreetMap building heights. Tagged heights and storey estimates are labeled separately. Missing data is unknown; no vegetation layer is inferred. See Data sources for sampling distances, coverage and attribution.

Direct-sun duration

Imported terrain is sampled every 5° at 100, 250, 500, 1,000, 2,000, 3,000, 5,000, 8,000 and 12,000 m. Each bearing retains the greatest positive angle after observer height and geometric Earth curvature; atmospheric refraction is excluded. Nearest-pixel elevation and finite sampling can miss ridges. The profile is cleared when the observer moves; changing observer height clears a terrain-derived profile so it can be reloaded.

The selected civil day is divided into real elapsed intervals of at most two minutes, evaluated at their midpoints. A horizontal outdoor point counts when the geometric solar centre clears the modeled horizon and screens. A vertical facade adds the requirement that the Sun is in front of its facing plane. Short last intervals are weighted by their actual duration.

This is modeled direct sun under declared geometry. It is not observed sunshine, irradiance or plant performance. Small gaps and shadow transitions can fall between samples. Clear-sky geometric direct sun can differ from standard open-horizon daylight because their horizon conventions differ.

Window and room reach

For a clear front-facing ray, perpendicular reach = (sill height + window height) ÷ tan(elevation) × cos(direction difference). The schematic caps reach at 8 m. Window width is retained as an input but does not change that one-dimensional equation. Glazing, reflections, curtains, reveals and horizontal overhangs are excluded. Zero direct sun does not imply a dark room.

Alignment search and saved scenes

Alignment uses a target azimuth/elevation and tolerance of 0.25°, 0.5°, 1° or 3°. It scans ten-minute candidates and refines local minima with a local angular approximation. A target pin provides bearing, not terrain visibility. Inspect each candidate; the search is not a completeness proof. Each match also includes the contiguous interval around the closest instant that stays within tolerance. Boundaries are refined to 0.1 seconds and clipped to the requested civil-date range. These geometric windows exclude terrain, obstacles and weather.

Up to 40 named scenes can remain in this browser. JSON and scene links preserve location, instant and modeled assumptions; they contain precise coordinates and obstacle data when you choose to share. CSV, SVG and calendar exports are calculated outputs, not measured records. Changing the date never reconstructs historical buildings, leaves or clouds.

Independent checks and their limits

Seventy-two airless topocentric comparisons against JPL Horizons DE441 cover eight locations and nine dates per site from 1900–2100. The largest observed azimuth/elevation component difference was 0.001387°, within a 0.05° regression threshold. These sampled results are not a universal accuracy bound.

Thirteen USNO civil-day fixtures supply 21 numeric sunrise/set comparisons: the largest residual against minute-rounded values was 0.5168 minutes, within a one-minute test limit. Four 2026 season events use a two-minute tolerance; the largest observed difference was 60.316 seconds. Computational agreement does not establish observed sunrise accuracy through variable atmosphere or a real skyline.

References: JPL Horizons conventions, USNO daily events, USNO seasons and IANA time zones. Source responses and query URLs are retained in the release test fixtures.

Use and uncertainty

Use SunCarta for planning and comparisons with measured or clearly estimated inputs. It does not provide a survey, legal solar-access determination, weather forecast or energy-yield model. Validate the decisive obstacle on site. Read the source register or download the machine-readable methodology. Report reproducible mismatches with coordinates, UTC instant, time zone and declared geometry through the contact page.