# SunGlare Atlas · 全球道路太阳眩光研究所

An open research prototype for reproducible analysis of the *geometric potential* for low-angle direct sun on road travel directions, with a global astronomical overview and a distinct real-road evidence layer. The public site does not display any personal author name.

The central question is: *What proportion of road directions align with low-altitude sunlight, for how long each year, in which months and hours, and how much vehicle travel might overlap these windows?*

This application intentionally does **not** predict Tesla/FSD or other vehicle-system failures. It also does **not** claim to have computed a measured global glare percentage.

## Use it

1. Start at the global map. Compare latitude-dependent solar geometry over Natural Earth land outlines, change year and sun-angle conditions, and click one of twenty cross-continental reference locations. The map and location percentage refer to **equally weighted hypothetical travel directions**, not actual road inventory.
2. Below the global map, select a location and examine a small sample of actual road geometry. The urban sample tool offers Windsor, Toronto, Detroit, Phoenix, Lisbon, Reykjavík, Singapore, Melbourne and additional global reference locations.
3. Click **获取 OSM 真实道路** to fetch a small OpenStreetMap area via a public Overpass service. The square's half-width is 1–5 km in each axis, and returned ways are clipped to that square. These third-party servers can be rate-limited or unavailable. Alternatively, import an **Overpass JSON** with `way` elements including `geometry` and `tags`, or a **GeoJSON FeatureCollection** with `highway` and ideally `oneway`, `name`, `osm_id` properties.
4. Adjust the sun-altitude limit (default 15°), maximum bearing difference (default 20°), and high-exposure threshold (default 30 annual hours per directed segment).
5. Read the high-exposure road share, mean modeled exposure hours, commuting-hour exposure, month/hour patterns, map, and roadway contribution ranking. Download the computed segments as a CSV.
6. For traffic results, upload `way_id,aadt` CSV matched to the same OpenStreetMap `way` identifiers. Alternatively activate the clearly labeled **hypothetical road-class scenario**; it is not an observed traffic figure.

Run locally with `npm run serve`, visit `http://localhost:4173`. Run tests using `npm test` and syntax checks with `npm run check`. No build pipeline, server database, or API key required.

## Exact metric definitions

### Global world-map quantities

The global chart uses Natural Earth land polygons for geographic orientation and independent astronomical computation at 10° latitude-band centers (longitude 0°, UTC reference), plus 20 named geographic reference points in all populated continents. It does **not** use observed or estimated road kilometers to weight the world map. For each latitude or reference location, compute 360 equally likely travel bearings (one-degree increments). The displayed **directional orientation share** equals the percentage of those 360 bearings with annual modeled low-angle direct-sun alignment hours exceeding the chosen threshold. The eastbound, westbound, and mean-hour map modes are similarly astronomical. This is an explicitly hypothetical orientation-uniform baseline; changing road-orientation distributions, local street geometry, land weighting, weather, or traffic changes the real-world answer. Reference locations are illustrative, not a probability sample of all roads.

Land boundaries: [Natural Earth 1:110m land](https://github.com/nvkelso/natural-earth-vector/blob/master/geojson/ne_110m_land.geojson), public-domain license and [terms](https://www.naturalearthdata.com/about/terms-of-use/).

### Regional measured road geometry and modeled exposure

The calculation is for *directed* road kilometers, because sun alignment differs by travel direction. A bidirectional physical road segment of length `L` is represented by two directed segments, each of length `L`; a correctly tagged one-way segment has one direction. Distances are measured along OSM polylines using the haversine formula. These are not lane-kilometers, passenger trips, or a length-weighted inventory of all the world's roads.

At 20-minute intervals for the selected local calendar year, the independently implemented astronomical engine gives solar altitude `h(t)` and azimuth `a(t)` near the city's geographic center. For segment heading `b`, an interval qualifies if:

```
0° < h(t) ≤ altitude_limit
and circular_angular_difference(a(t), b) ≤ alignment_limit
```

Each interval contributes 1/3 hour. These solar alignments are **possible low-angle direct-sun exposures under a clear unobstructed horizon**, not observed glare incidents. The method excludes observer eye height, windshield geometry, slope, terrain, buildings, trees, weather, atmospheric brightness, and individual susceptibility. Sub-city variation in solar geometry is approximated with the city center and should be revised for global tile processing.

- **Annual exposure hours per directed road segment:** Sum of qualifying 20-minute intervals in the local year.
- **High-exposure road share (%):** `100 × sum(length of directed segments where annual hours ≥ user threshold) / sum(length of all included directed segments)`.
- **Mean annual hours per directed road km:** `sum(length × annual hours) / sum(length)`.
- **Commuting hours:** The same calculation restricted to **07:00–09:59** and **16:00–18:59** local clock time. These are fixed illustrative windows, not observed traffic peak times.
- **Monthly and hourly charts:** Length-weighted means of qualifying hours across the analysis area's directed road inventory.
- **Traffic weighted exposure (vehicle-km/year, modeled):** `sum(directed AADT × directed length in km × annual exposure hours / 24)` over roads covered by the selected traffic source. It assumes a *uniform 24-hour vehicle arrival rate*; real hourly counts can dramatically change results.
- **Traffic weighted exposure share (%):** `100 × sum(AADT_directed × km × hours/24) / sum(AADT_directed × km × days_in_year)` for roads with matching traffic data only. Leap years use 366 days.

**Important:** The output `trafficCoverage` is road-length coverage, not traffic-volume coverage. When a measured AADT file covers 40% of directed roads, its weighted proportion represents **only the matched subset** and must not be presented as the share for the whole city or the world. For bidirectional ways, total two-way AADT is divided equally between directions; the true direction split needs independent measurements. The scenario supplies artificial AADT values by OSM road class, never substitute it for measurements.

## What it would take to publish a global road share

The current website is an honest **regional prototype**, not a planet-scale computation. A defensible global estimate requires an offline data pipeline:

1. Fix a road universe, reference date, driving eligibility, and treatment of missing/uneven OSM coverage.
2. Process a dated global OpenStreetMap planet extract in geographical tiles. Keep `way_id`, coordinates, road class, legal direction, segment distance, lat/lon; avoid double counting tiled intersections.
3. Compute solar tracks at geographically appropriate positions, road bearings, local time zones, and uncertainty ranges across several sun-angle thresholds. Include road grades, mountain skylines and built-environment occlusion as separate stages.
4. Aggregate worldwide and by country, latitude belt, season, road class, and hour. Include both **physical road share** and **directed-road-km share** with explicit denominators. Quantify OSM selection/coverage bias.
5. To estimate actual exposed conditions, integrate verified historical cloud/visibility records and geographic obstruction data. Report uncertainty rather than interpreting geometry-only windows as observed events.
6. Overlay licensed road-level AADT and preferably hourly directional traffic counts, document matching coverage, then report vehicle-km/year at risk and a rank of potentially affected corridors. Never count AADT gaps as zero.
7. Archive inputs and reproducible processing code; perform sensitivity and external validation against measured sun-glare reports if available.

**Global percentage and true annual number of affected vehicles: not yet computed.** No site claim should imply otherwise.

## Limitations and provenance

- **Road data:** [OpenStreetMap](https://www.openstreetmap.org/copyright) contributors, licensed ODbL. Public [Overpass API](https://wiki.openstreetmap.org/wiki/Overpass_API) services should only be used for small reasonable queries; global runs should use official extracts or dedicated infrastructure.
- **Astronomical reference:** [NREL Solar Position Algorithm](https://midcdmz.nlr.gov/spa/). Sun-coordinate calculations here are independently coded standard approximate relationships, rather than copied from the restricted SPA implementation.
- **Prior academic work:** [Solar Glare Vulnerability Analysis of Urban Road Networks—A Methodology (2019)](https://doi.org/10.3390/en12244779), which notes the importance of road travel heading and grade alongside solar position.
- **AADT:** Provided by user as a distinct input with their own traffic provider's reuse permissions. The internal road-class values are hypothetical examples only.
- **Reproducibility:** `engine.js` is a pure JavaScript model module, `tests/engine.test.mjs` includes astronomical and road-direction sanity tests. Future scientific use should add independent high-accuracy ephemeris comparison, regional bias assessment, and measured-validation datasets before publication.

Do not cite this prototype as an empirical estimate of the planet's observed solar-glare rate.