Calculation methodology

Scope and intended use

SunCarta is a planning tool for comparing direct sunlight and shade at a point or receiving surface. It is designed for homes, windows, balconies, gardens, photography, outdoor events and early solar screening. It is not a survey, legal solar-access determination, weather forecast or bankable photovoltaic yield model.

The interface separates deterministic solar geometry from uncertain scene geometry. Latitude, longitude, date, local time and time zone determine the sun. Buildings, walls, trees, orientation and room dimensions determine whether that sun reaches the selected place.

1. Solar position

The implementation follows the published NOAA solar-calculation form: fractional year estimates solar declination and the equation of time; true solar time then gives hour angle, zenith, altitude and azimuth. Azimuth is reported clockwise from true north.

Required inputs

Latitude, longitude, calendar date, wall-clock time and IANA time-zone offset.

Altitude

Angle of the sun above the geometric horizon. Below 0° is night for the simulator.

Azimuth

Horizontal direction toward the sun: 0° north, 90° east, 180° south and 270° west.

Sunrise and sunset

Calculated with a 90.833° zenith convention, approximating refraction and the apparent solar radius.

Reference: NOAA Global Monitoring Laboratory calculation details. Time-zone identifiers follow the IANA Time Zone Database.

2. Outdoor shadow projection

For level ground and a vertical obstacle of height h, the plan shadow length L is:

L = h ÷ tan(α)

Here α is solar altitude. The shadow bearing is the solar azimuth plus 180°. Buildings and walls use simplified plan footprints. A tree uses an elliptical crown shadow and an opacity control because foliage is neither rectangular nor fully opaque.

Near the horizon, mathematical shadow length approaches infinity. SunCarta caps the visible map projection so the interface remains usable and never presents that cap as a measured boundary.

3. Obstruction test

SunCarta estimates the bearing and distance from the receiving point to each obstacle. An obstacle blocks direct sun when both conditions hold:

• the sun’s altitude is lower than the angle from the point to the obstacle top; and
• the sun’s azimuth falls within the obstacle’s approximate angular width.

Obstacle width is converted to an angular span from the receiving point. Roof shape, terrain, transparent structures and small gaps require separate simplified scenarios rather than false precision.

4. Daily direct-sun duration

Daily duration is sampled every ten minutes. An outdoor point or horizontal garden surface counts a sample when the sun is above the horizon and no modeled obstacle blocks the ray. It is not constrained by a window bearing.

A vertical receiving plane, such as a window, facade or balcony, adds another condition: the sun must be in front of that plane. This distinction prevents outdoor sun hours from being understated by an unrelated orientation setting.

The sampling interval is suitable for screening and comparison, but a displayed duration should be read with roughly ten-minute granularity rather than as a survey-grade transition time.

5. Window and room sun reach

The room simulator first checks whether the sun is in front of the window plane. It then projects a simple beam from the window’s top edge toward a level floor and adjusts perpendicular reach for the difference between solar azimuth and window orientation.

This direct-beam model does not calculate diffuse daylight, visible-light transmission, reflections, curtains, deep reveals, glass coatings or complex overhangs. A room can remain bright while reported direct-beam reach is zero.

6. Location search and map context

Address search uses a same-origin Cloudflare Pages Function that validates the submitted query, requests a Photon-compatible geocoder, sanitizes the returned place fields and caches repeated normalized queries at the edge. Responses returned to the browser are explicitly marked not to be stored. Provider availability does not block the calculator: users can enter latitude and longitude, use browser geolocation or place the point directly on the map.

The basemap supplies geographic context. SunCarta does not infer or claim verified building heights from the visible footprint; obstacle dimensions remain explicit user inputs unless a future source is added with provenance and coverage checks.

7. Confidence and uncertainty

The interface labels confidence as input-dependent because it cannot verify a user’s measurements. Adding an obstacle does not by itself upgrade a result to medium or high confidence.

8. Verification status

Automated tests cover leap years, equinox behavior, a Mexico City summer day, wrapped compass angles, the relationship between solar altitude and shadow length, local clock formatting, the rule that sunlight cannot pass through the back of a window, and the separation between outdoor exposure and a vertical facing plane.

The static release gate also checks every sitemap URL for a generated HTML file, exact canonical, unique title and description, one H1, indexable robots state, complete social metadata and resolvable internal links. Field validation against measured shadow-transition times remains an evidence-building program rather than a hidden claim.

No page should claim centimetre- or minute-level real-world accuracy. If you find a reproducible mismatch, send coordinates, date, local time, time zone and verified geometry through the contact page.

Version history

1.1 · August 8, 2026

Separates outdoor and vertical-plane sun duration, adds the geocoding proxy and fallbacks, makes confidence explicitly input-dependent and introduces fail-closed static SEO checks.

1.0 · August 3, 2026

Initial public methodology for solar geometry, obstacle shadows, ten-minute duration sampling and room sun reach.