Solar Rooftop Obstacle Simulator

A photoreal, location-accurate rooftop shading simulator. Pick a real site, choose a date and time, lay out a panel array of real-sized modules, drop in the things that actually cast shade on Indian rooftops — trees, neighbouring buildings, poles, water tanks, staircase rooms — and see exactly which panels fall into shade. Live, and as an irradiance-weighted annual analysis with a per-month chart and worst-case month.

It is shading-only by design (no kWh/energy yield). The sun is computed with the NOAA solar-position algorithm; shading is evaluated by per-panel raycasting. Single self-contained HTML file, no build step.

Built for India (and beyond)

India spans ~8°N (Kochi) to ~37°N (Srinagar), so the sun's height and path differ a lot across the country — and the winter (December) sun sits low in the south, which is usually the worst case an installer must check. This tool is tuned for that:

• 15 Indian city presets (Srinagar → Kochi) plus custom lat/long and "Use my location".
• A real seasonal sun path — the December worst-case and the annual figure both come from sampling the actual solar geometry for the chosen location.
• An optimal-tilt suggestion (tilt ≈ latitude, face south) appropriate for the site.
• A hazy daytime sky and satellite map that read like a real Indian rooftop survey.

It works anywhere on Earth — custom lat/long + UTC offset handle other regions and the southern hemisphere (the array then suggests facing north).

Features

• Location — city presets, custom lat/long + UTC offset, or 📍 Use my location (geolocation; also sets your timezone offset).
• Date & time — date and time sliders, plus ▶ Play day to sweep the shadows across the day; the sun, sun-path arc, and shading update live.
• Photoreal 3D scene — atmospheric sky, environment-mapped reflective panels, soft shadows, filmic tone-mapping; orbit/zoom, +/− zoom buttons, and a ☀ Sun path button to frame the full solar arc. A ground compass (N/E/S/W) and a live golden sun-path arc show the real solar geometry.
• Building — adjustable height (3–40 m, multi-storey) and orientation, with an on-roof facing arrow so you can see which way the array points against the compass, and a ☀ Face the sun button that snaps it to the optimal azimuth (south in India).
• Panel array (draw-a-zone) — draw a rectangular panel zone on the roof (✎ Draw zone), then drag it or its corner handles to move/resize; numeric width/depth/offset fields mirror it. The zone auto-fills with real-sized modules:
  • Module presets (e.g. Residential 440 W 1134×1762 mm, Commercial 550 W 1134×2279 mm) or custom width×height (mm).
  • Portrait/landscape toggle, adjustable module gap and edge setback.
  • Modules automatically flow around rooftop obstacles and stay inside the setback.
  • Live module count.
• Obstacles — add Tree / Building / Pole / Water tank / Staircase room (mumty); drag to position, resize by height, see the selected one's distance from the building; Load sample drops a realistic scene, Clear all resets.
• Import OSM buildings — pull the real neighbouring buildings from OpenStreetMap around the site (footprint size, rotation, and height where tagged) and drop them in as shading obstacles; optional, with graceful fallback when data is sparse.
• Shading analysis — live "panels shaded now", a green→red heatmap toggle, and Run annual analysis: per-month bar chart + worst month + an irradiance-weighted annual shading figure (midday shading counts more than dawn/dusk).
• Site map — a Leaflet satellite (Esri) / street (OSM) map of the exact site with the building footprint + panel zone + facing line drawn on it; click the map to set the location.

Running locally

The app is a single file, index.html, but it loads Three.js and Leaflet as ES modules, which browsers will not load over file://. Serve it over HTTP — any static server works:

# from the project root
python3 -m http.server 8080
# then open:  http://localhost:8080/

Other options: npx serve . or php -S localhost:8080.

Internet connection required: Three.js, its addons, and Leaflet load from CDNs (jsDelivr / unpkg), and the map uses Esri/OpenStreetMap tiles. If the 3D engine can't load, the page shows a connection hint.

Deploying to Vercel

Static page (index.html) plus one tiny serverless function — no build step, no env vars. HTTPS (which Vercel provides) enables Use my location.

npm i -g vercel   # if you don't have it
vercel            # preview deploy
vercel --prod     # production

Or import the repo at vercel.com/new — framework preset Other, no build command. The app is index.html, so it loads at the deployment's root URL by default. .vercelignore keeps the deploy lean (the dev src/, test/, and docs/ are excluded); vercel.json adds clean URLs and a couple of security headers.

api/overpass.js is a serverless proxy for the Import OSM buildings feature: the public Overpass API doesn't send CORS headers for browser requests, so the page calls this same-origin endpoint and it fetches Overpass server-side. Locally (plain static server) that route is absent and the app falls back to CORS-enabled Overpass mirrors, so OSM import still works in dev — just less reliably than the proxied production path.

Running the tests

The solar-geometry, shading-aggregation, and panel-packing math is covered by Node's built-in test runner (no dependencies to install):

npm test

Project layout

Path	What it is
index.html	The app — single self-contained file (the deliverable; served at /).
src/solar.mjs	Pure solar math: sunPosition (NOAA), daylight, sunDirection, clearSkyBeam.
src/analysis.mjs	Pure annual-shading aggregation (aggregateAnnual, irradiance-weighted).
src/layout.mjs	Pure panel packing (fillZone) with obstacle-skip.
test/*.test.mjs	Unit tests for the above.
docs/superpowers/specs/ · docs/superpowers/plans/	Design specs and implementation plans.

The pure math in src/*.mjs is embedded verbatim into the HTML (browsers can't import local modules over file:// without a build step). The copies are kept in sync, and a runtime self-test plus a numeric source-vs-embedded check guard against drift.

Accuracy notes

• Sun position uses the NOAA algorithm (~±0.01°) — validated against equinox/solstice geometry and both hemispheres; more than accurate enough for shading.
• Shading is geometric (per-panel raycasting against obstacles), the same approach used by tools like PVsyst and HelioScope.
• The annual figure is a beam-shading loss weighted by clear-sky irradiance — it reflects energy-relevant shading, not just hours. (It does not model clouds/weather.)