Sunspill

Set up your own room in a few minutes, then see where the sun lands on its floor, by the hour and the season.

English | zh-TW | zh-CN | ja | ko | es | fr | de | pt-BR

Open the live demo  |  free, no login, opens offline after the first visit
_{Made for a phone. Seven steps and a few minutes get you from an address to your own room. Your room stays in your browser. The last one you edited is kept on your device, along with any you name and save. Address search, the map and building outlines ask public OpenStreetMap servers, and only after you say yes to each one.}

No rendering, no AR. The patch on your floor is an exact polygon, and you can check it against a ray tracer.

Press Set up my room. Seven steps, a Back and a Next button, a few minutes on a phone.

1. Where. Type an address or drop a pin on the OpenStreetMap map. The latitude, longitude and time zone fill themselves in. An address written the Taiwanese way, with a house number and a floor, works. When OpenStreetMap lacks the number, you get the street and a note to drop a pin on your building.
2. The room. Start from a studio suite, bedroom, living room or home office (the sizes follow typical Taiwanese flats, so correct them), or trace your own floor plan or listing photo with a two point scale. Set the floor number.
3. Windows and doors. Real dimensions along the walls, snapping to the wall ends, the middle and each other, balconies with a railing, eaves and doors.
4. Which way it faces. Turn the room over the outline of your building on the map, or hold the phone against the window and read its compass with the magnetic declination added. North is always on screen.
5. What stands around it. Neighbouring buildings and their heights load from OpenStreetMap. A height that OpenStreetMap lacks is guessed from the nearest buildings that have one, marked, and you can edit it. Add buildings and trees by hand. A clock on the map shows where the sun is and outlines the buildings that shade a window at that time.
6. Furniture. Place, drag and turn beds, desks, sofas, shelves and plants, and see the sun land on them.
7. Check against the real sun. Mark where the sun really was on the floor at a time you saw it, or lay a photo of the floor under the plan. Sunspill shows how far the model is off and can fit the facing and the window to your marks.

The same bedroom in Taipei at 16:30 on 15 July. Turn the window from west to east and the afternoon sun is gone.

West window	East window
4 h 28 min of direct sun a day after 14:00	0 min

_{Average per day over 40 sample days from June to September (every third day), clear sky, direct sun only, from the Afternoon sun check in the Results tab. The rule is printed in the app.}

West sun is a standing worry for people who rent in Taiwan, and a listing photo can't show what it will do in your room.

A compass app gives you an angle. A map shadow tool draws the buildings in the street. Neither shows the patch of light on the floor of the room you're about to sign for. Sunspill does. You describe the room, the window and what stands outside, pick a place and a date, and the patch moves as you drag the clock. The same engine answers the other light questions: how many hours a desk or a plant gets, and which corner is best.

West bedroom, 15 July, 16:30

Same room, 21 December

South room, noon in winter

East bedroom, summer morning

New in 0.2.3: a Taiwanese address with a house number and a floor is found, a building load survives pressing Next, a plain note says when the public servers are busy, and the Overpass server that refused every browser is replaced.

New in 0.2.2: buildings that OpenStreetMap draws in several parts now load, a missing height is guessed from the buildings next to it, rooms can be saved by name, the drawing tells a screen reader what the keys do, and the room step shows the floor area, in ping on the Traditional Chinese page.

New in 0.2: a guided setup for a phone, address search and a map pin, the phone compass with declination, neighbouring buildings and trees from OpenStreetMap, balconies, doors, floors and turned furniture, tracing a floor plan, and a check against the sun you saw.

• Draw the room. Size, wall thickness, up to four windows with a shade, a balcony and a rail, up to three doors, the floor number and furniture you can turn.
• Scrub any day. Pick a city, an address, your location or a latitude and longitude. The clock, the sun path and the patch follow, and daylight saving is handled.
• See what shades it. Buildings from OpenStreetMap with their heights, trees, and your own balcony and eave. Switch any of them off to see what it costs in hours of sun.
• See the hours. The sun hours map colours the floor, or a surface at a height you set, by the hours of direct sun per day for a day, a month, a year or a range of months. Hover for the number.
• Check the afternoon. A printed rule: the minutes after a time you choose when direct sun reaches the floor or a wall, averaged over the months you choose.
• Find a spot for a plant. Full sun, partial sun or low light, for a 30 cm footprint, ranked, at least 60 cm apart.
• Compare with reality. Mark the patch you saw, see the overlap and the offset in centimetres, and fit the direction.
• Keep several rooms. Name a room and keep up to twelve in this browser, to flip between flats.
• Share it. A link that holds the whole room, a PNG card, a GIF, or the room as a JSON file. One switch rounds the place to whole degrees and drops the names from all of them.
• Use it anywhere. Nine languages, light and dark themes, keyboard and touch, undo and redo, offline after the first visit.

Sun elevation is within 0.007 degrees of the NREL reference. Against pvlib and shapely there were 0 disagreements in 54,000 probe points (4,036 lit, 1,275 of them dark only because a building, a tree or a balcony rail shades the window).

Every piece of the geometry is checked against an independent reference, from the sun (pvlib, NREL SPA) and the shadows (a ray tracer and shapely) to the magnetic declination (pygeomag), the map offsets (pyproj) and the photo flattening (OpenCV). node scripts/validate.mjs reproduces it, and docs/VALIDATION.md lists the choices that aren't checked.

The checks can't tell you how close your inputs are to the real room. Sunspill hasn't been compared with a photograph of a real room yet, so it has a check mode that compares the model with the sun you saw. docs/ACCURACY.md says how far each wrong input moves the patch. The direction of the window and the height of the building across the street matter most. A height that OpenStreetMap lacks is guessed from the nearest buildings that have one. Left out one at a time on five stretches of Taipei, that guess was off by a middle factor of 1.2 to 1.3, against 1.7 to 5.7 for a fixed nine metres.

Your room, the pictures you trace and the marks you make never leave your browser, and neither do the rooms you save by name. There's no account, no analytics and no cookie. Three optional services talk to public OpenStreetMap servers (the building outlines may come from one of three Overpass servers run by others). Each is off until you allow it, and the page says what it sends first:

You can switch each one off again under "Online services". The page's Content Security Policy names those five hosts and the page's own address, and no others, and the browser tests check it. The quick check also reads static files of past deals (the Ministry of the Interior's 實價登錄) from the page's own address. See docs/PRIVACY.md.

git clone https://github.com/Arthur031221/Sunspill.git
cd Sunspill
npm ci
npm run build
npx --yes serve dist

npm install github:Arthur031221/Sunspill

import { defaultScene, sunAt, scenePatches, totalArea } from 'sunspill'

const scene = defaultScene()                       // a west facing bedroom in Taipei
const sun = sunAt(scene.place, 7, 15, 16 * 60 + 30) // 16:30 on 15 July
const { floor } = scenePatches(scene, { azimuth: sun.azimuth, elevation: sun.elevation })
console.log(`${totalArea(floor).toFixed(1)} square metres of floor in sun`)

The sun position follows the NOAA equations. A window opening is trimmed by the wall thickness and the shadows of the eave, the balcony rail, and every building and tree outside, which leaves a few convex pieces. Each piece is carried along the sun rays onto the floor and walls and clipped there. A building outline of any shape is cut into convex prisms first, and the shadow of a prism on the window is the hull of its corners carried along the rays. The room is convex, so a ray that gets in meets the boundary once and nothing inside can block it. docs/ARCHITECTURE.md has the details.

What it leaves out is listed on the page and on every picture it exports: clear sky and direct sun only, no reflections, no furniture shadows, one box shaped room, buildings as flat topped prisms and trees as solid shade. Beams almost parallel to a wall are ignored. If you can photograph a room under a sun you can date, please send a real room report.

Usage | Privacy | Past deals data | Accuracy | Validation | Install | Config and file format | Library API | Architecture | Contributing | Changelog

L shaped rooms. Vertical fins and blinds. Shadows from furniture. A comparison with photographed rooms. Leaf-off seasons for trees. Tests on Safari and a real iPhone. Published npm package.

SunCalc gives sun angles as a library. Sunspill uses its own NOAA implementation, checked against NREL. building-sunlight-simulator shows building shadows for housing estates. The Flat Sun and Shade Simulator covers flats in Singapore. Sunspill is for the inside of one room, anywhere, with the code open.

MIT. The Fraunces font is embedded under the SIL Open Font License. Map pictures, building outlines and address search come from OpenStreetMap contributors and are under the Open Database License. The time zone table is @photostructure/tz-lookup (CC0) and the magnetic field model is the World Magnetic Model 2025 (public domain). See THIRD_PARTY.md.

Assisted by Claude/Codex.