Room From Photos

CONFIG reference

• rot is the wall an item's back faces: 0 top, 90 right, 180 bottom, 270 left. The front is the side you use (the bed's foot, the drawers, the desk's chair side).
• rot takes any angle, not just the four walls. A piece given only w is round or square: d defaults to w.
• Door hinge is 'left' or 'right' as seen standing in the room facing that wall; swing is 'in' or 'out'. type: 'opening' is a closet or cased opening; clear sets the depth kept free in front of it (default 24″). An opening's label is a short noun ("Hall", "Closet"), because the checks use it in sentences: "Desk blocks the closet".
• Types: bed, crib, dresser, nightstand, desk (with chair), bookshelf, wardrobe, sofa, armchair, lounge (a bentwood cantilever chair; throw: true adds a sheepskin), chair (a side chair sized to its w, d and h), table (glass: true for a framed glass top, shelf: true for a lower shelf, round: true for a round top on splayed legs), rug, box, ottoman, petbed, stands (plant stands with pots), floorlamp (a tripod lamp; arc: 22 makes an arc lamp that hangs its shade 22″ out in front, so aim it with rot, and the checks flag a shade that reaches through a wall; shade = radius; an arc lamp's h is the arc's crown, and its shade hangs about a third of the reach below it), floorplant (w is the canopy's spread and h its top, and the pot scales from w; heads for a leafy tree, upright: true for spears, pole: true for a climber on a moss pole), art (a framed picture: mount = its bottom edge's height, print: 'landscape' | 'poster' | 'abstract' | 'mirror'), media (a console; tv = the screen's diagonal in inches; mount: 58 hangs just the TV on the wall at that height, with no floor footprint, drawn dashed in the plan), fireplace (a built-in: h is the mantel, face and faceH the firebox face, front the hearth kept clear, fw its width).
• Wall-mounted items (mount) have no floor footprint and hide while their wall is cut away in the dollhouse view.
• Windows take panes (the number of sashes; the default is one per 26″). Openings also take type: 'niche': shelves recessed into the wall between sill and head. ROOM.paneling: {walls: [edge indexes], name, color, plank: [min, max]} panels whole walls with random-width planks; edge i runs from outline[i] to outline[i+1], so a rectangle traced from the top-left is 0 top, 1 right, 2 bottom, 3 left. A built-in in fixed takes an id, which is the key its colours use in colors; its c is its centre and its rot works as for items.
• LIBRARY (optional) adds this room's own entries to the "Add a piece" catalogue: [{id: 'toys', name: 'Toy chest', type: 'box', w: 36, d: 18, h: 20}], each an item spec with an id and a name (variants work as on ITEMS, so "the new bed in three sizes" is one entry). group files it under seating, tables, storage, beds, lighting, plants, rugs or walls; without one it is listed first as "For this room". {base: false, entries: [...]} offers only these. The built-in catalogue covers each type in common sizes: a three-seat sofa and loveseat, armchair, lounge and dining chairs, an ottoman, coffee tables (rectangular, round, glass) and a side table, a media console, bookshelf, dresser, nightstand, wardrobe and desk, twin to king beds and a crib, tripod and arc lamps, a tree, a snake plant and a climber, 5 × 8 to 9 × 12 rugs, a pet bed, a wall TV and art. An added piece takes the palette's quietest swatches for its finishes, lands in the biggest clear square (a wall piece on the nearest wall, clear of its openings), is selected with the gizmo on it, and persists per option with its place, colours and variants under storageKey beside the older edits. Pieces taken out of an option wait in the library under "In this room". Thumbnails are the engine's own renders, made when the library opens and cached.
• variants: [{label: 'Yours'}, {label: 'Longer', w: 96}] on an item; an option picks one with variants: {sofa: 'Longer'}. LOOKS: [{name, colors}] replace the option's colours in one click; {} is the room as configured. Default clearances: dresser and wardrobe 36″ in front, desk 30″, bookshelf 24″, sofa 14″ (the usual reach to a coffee table); a bed needs one side with 20″ free. Override per item with front or side.
• Checks: things that run into a wall, overlap, or sit in a door swing; a blocked front, closet or bed side; tall things in front of a window; an arc lamp's shade through a wall or hanging into what's under it; open floor and the biggest clear square.
• python3 test.py <project-dir> audits the model against those checks and fails on any finding: every part stays over its footprint or a zone a check sees (an arc lamp's reach, a desk chair's front clearance, a hearth), stands on the floor (or its wall) joined to the rest, stays under its height, and every rod or tube ends on another part without passing through one. It also fails when the photo finishes don't load, when the page's load event waits for a photo or scan, when the photo view's light shifts as the room is re-captured, or when a piece loses its turn in the model after the ring, a nudge and the turn buttons. An expect.json beside a fixture's config.js pins what the panel says. Run it after any builder or finish change; tests/every-piece holds every type and flag.
• Colour: ROOM.walls, floor, trim, boards (board width in inches, 0 = none) and boardsDir ('x' or 'y'). On items, color is the body and color2 the second finish: bedding (bed), mattress (crib), legs (desk, table), cushions (sofa, armchair), cushion over a wood frame (lounge), shade over the stand (floorlamp), the pot (floorplant), the print (art), border (rug). Mattress and pillows stay soft white, and shelf books get muted colours of their own. LAYOUTS[i].colors overrides any of these for one option, as walls: 0x… or bed: [body, second]. look: 'white' opens on the white model.
• Finishes: TEXTURES names the folder of photo scans (default 'textures/'; false keeps the drawn finishes). textures/SOURCES.md lists each scan, its ambientCG source and the size one tile covers; swap in any greyscale scan under the same file name and set its size in SCANS in the engine. #debug&drawn shows the drawn finishes, for a before-and-after.
• Light: every lamp glows by default (a warm bulb inside any part a builder tags kind: 'shade'); ROOM.lamps: 0 turns them all off and 2 doubles them, and an item's glow: 0.5 scales its own. Every solid piece stands in a soft contact shadow; contact: 0 on an item removes it, 1 darkens it. Everything that dims or grades applies only through a photo's camera, never in the dollhouse: there, floors and paneling render a little less saturated than their swatch (15 % and 12 % toward grey), painted walls and trim take 70 % of the room's own bounce, and the capture itself sees the wood half as saturated, because wood under that warm bounce goes redder than a photo of it and an off-white wall beside it would tan where the photos show it white-grey; the view outside a window is lit 1.7× and hazed toward white, the way a camera exposed for the room sees it. A room with no window has no daylight in colour: give it a window, or its lamps carry the room.
• URL hash: #layout=2&view=sw|top&sel=bed&pane=plan&photo=1&look=white (layout and photo count from 1); add debug for the ROOM handle, and debug&frame=<id>&el=20 for a close-up of one piece or built-in (the visual sweep of tests/every-piece uses it). With debug, photo=N&bare draws that photo's camera alone, filling the window with no photo or UI, for a capture beside the photo; bench=8 writes frame costs into <pre id="bench"> (ROOM.bench(n) returns them: still, moving with the shadow map redrawn, env for the room-light capture, and draw calls); and exp, sun, win (window light), sky (the view's brightness), lamp, vig, wenv (how much of the captured room paint takes) and grey (how far the wood is greyed for the capture) override the photo view's light levels for tuning against photos (the defaults live in LIGHT in the engine; win and lamp also reach the dollhouse); lib opens the library, libadd=sofa3,art adds those catalogue entries, and libtest adds two, takes one out, and writes the stored state and the copy output to pre#libtest for a --dump-dom check.

Common mistakes

Gotchas

• Headless Chrome renders in software: slow, and fine for layout and the phone check but not for judging light. Use a visible browser on a real GPU for that; a hidden or background tab pauses its frame loop, and the loop is what applies a photo view's grading and captures the room's light. ROOM.snapPhoto applies both itself; for any other capture from a hidden tab, call ROOM.ev('applyLight(); captureEnv(); render3d()') first, or you'll compare studio light against the photo.
• Headless captures: "<Chrome>" --headless=new --user-data-dir=<scratch>/st-N --disable-gpu --use-angle=swiftshader --enable-unsafe-swiftshader --window-size=1440,900 --virtual-time-budget=5000 --screenshot=<png> <url>, one at a time with a timeout (e.g. perl -e 'alarm 45; exec @ARGV' …), then pkill -f "[u]ser-data-dir=<scratch>/st-N". The brackets stop pkill from matching and killing your own shell. file:// URLs work (add --allow-file-access-from-files or the textures fall back to drawn ones); give the phone harness's iframe an absolute file:// URL (a relative one came back ERR_FILE_NOT_FOUND). A capture with the library open takes a minute or more: its thumbnails render in software, so allow alarm 200. At phone width, headless SwiftShader never delivers a screenshot of the open library beside the model canvas (it does at desktop size), so capture the phone library over the plan (#debug&lib&pane=plan) or with nothumb, which skips the thumbnails. Chrome lingers after writing the file, so poll for it and kill rather than wait for exit; on a loaded machine the screenshot sometimes lands before the first frame as a 4 KB white page, so check the size and retry with a bigger budget. Software rendering is slow (a photo view with all passes takes 20–50 s) but its light is the same maths as a GPU's, so luminance measurements from it are valid; only the look needs a real GPU.
• Hosts that wrap the page in their own skeleton (claude.ai Artifacts do) want a copy without doctype, <html> and <body>: build.py --artifact writes one. Such hosts often pass only a bare #anchor, so make the defaults (view, the first option) the right opening state.
• claude.ai keeps an Artifact blank until the page's load event, and that event waits for every image started before it: a five-photo room's thumbnails and scans held one blank for 20–40 s. The engine starts its scans and thumbnails through afterLoad; start any new image the same way.
• Once a layout is chosen and something has to be built, the step-by-step build guide is the 3d-assembly-manual skill.