Files

125 lines
8.5 KiB
Markdown

# Map-true town and city renders for tabletop campaigns
An agent skill plus a small toolkit for turning a hand-drawn town map into photoreal, *geometrically consistent*
pictures: the first view from the road, the gate, an aerial of the market block, a shopfront, the taproom at
midnight when it is packed, the same street in a blizzard. Every picture of a place agrees with every other picture
of it, because they all descend from one 3D block model traced from your map.
Developed for a Norse-themed D&D campaign by Rick Falkvinge, with the agents that ran the render lanes. Shared so other
tables can use it with their own maps, their own renderer accounts and their own agent setups.
**See it in pictures:** [measured castle battlements](docs/walkthrough-royal-castle.md) ·
[an interior room](docs/walkthrough-interior-room.md) · [one sign across every angle](docs/walkthrough-sign-lock.md) ·
[a populated district sheet](docs/walkthrough-district-map.md)
## What it does
1. **Segments your map** into roofs, trees and water.
2. **Builds a 2.5D block model** of the town (footprints from the map, heights proposed by wealth zone, landmarks
modeled by hand with named dimensions, people as true-scale mannequins).
3. **Ray-marches a template plate per camera**: an untextured render from exactly where the final picture will be taken.
4. **Hands the plate to an image-edit model** ("re-surface IMAGE 1; move nothing") with a prompt built from blocks that
measurably held, plus material references from another camera.
5. **Gates the result against the plate**: drift, zoom, landmark fidelity, invented skyline structures, figure scale,
text and watermarks. Numbers, not vibes.
6. **Derives the matrices** every table needs: Day/Sunset/Night x Dry/Rain/Snow, three snow depths with route
clearance classes, and a population x time-of-day matrix for every venue with people in it.
7. **Sizes the whole effort by tier**: how likely is this place to come into focus at the table? That decides the
deliverables, the budget, which agent model runs it, and what the GM is asked to look at.
Before step 1, an optional **district-map stage** registers a district bitmap to the whole-city map, projects existing
pins, and fills unused template slots with explicitly PROPOSED T3/T4 establishments on real map buildings. It gives a
large city texture before every background doorway earns a render.
Why it works: words cannot carry an aspect ratio, a distance or a height, and a map given as a reference moves the
layout but not the shape. When the geometry arrives as pixels from the target camera, the renderer only has to paint
surface, and a correction is one edit to the model followed by a re-render of every camera.
## Requirements
- Python 3.10+, `pip install -r requirements.txt` (numpy, OpenCV, Pillow, requests). CPU only; a 2048x1152 plate takes
1-15 minutes on a many-core machine. No GPU needed.
- An image-edit API that accepts several reference images and a prompt and returns a 16:9 image. The method was built
and measured on one hosted model (`gpt-image-2.5-flare`, OpenAI-compatible `/images/edits`); what made it work was
that it treats the first image as the scene to re-surface and holds its layout, framing and figure positions well
enough to gate against. Anything with that property will do; see `scripts/adapters/README.md` for the adapter point.
- A map export at a known scale (meters per pixel). Calibrate on something of known size.
- An agent runtime that can read `SKILL.md` (OpenClaw, Claude Code, or any harness that loads AgentSkills), or a
patient human following it by hand.
## Quick start
```bash
pip install -r requirements.txt
python scripts/smoke_test.py # synthetic town: segment -> mass -> plates -> jobs -> gates, no API calls
cp examples/*.json my-town/ # citykit.json, views.json, scene.json, prompts.json; edit every value
export IMAGE_API_KEY=... # never in a file that goes into version control
cd scripts
python segment_map.py ../my-town/map.png --mpp 0.5 --out ../my-town/seg.npz --look ../my-town/look.jpg
python massing.py ../my-town/seg.npz --config ../my-town/citykit.json --out ../my-town/town.npz
python render_plate.py A_first_view C_gate_approach --config ../my-town/citykit.json
python build_jobs.py day --config ../my-town/citykit.json --prompts ../my-town/prompts.json --takes 3 --out ../my-town/jobs_day.json
python render_batch.py ../my-town/jobs_day.json --out ../my-town/out_day --start 4 --max 8
python gate.py ../my-town/out_day --config ../my-town/citykit.json
python cost.py ../my-town/out_day/results.jsonl --config ../my-town/citykit.json
```
Then pick, relight (sunset/night as light-only edits of the day pick), build the matrices with `matrix_jobs.py`, and
deliver per `references/naming.md`. `SKILL.md` is the ordered procedure with a completion criterion per step.
## A worked example (method only)
A capital of about 29,000 people on a whole-city map at 0.53 m/px. The party rides in from the west and nobody had a
picture of the valley road, a gate, or the first view of the city; every earlier overview had invented the city from
words (river on the wrong side, a cathedral, a metropolis).
- **Model:** 8,500 house pieces auto-massed from the bitmap in three wealth zones (turf-roofed outskirts, timber south,
stone-and-slate north); the castle traced from the map with proposed heights; the library at its canon dimensions;
the valley, the road beyond the map's edge and a timber toll gate all PROPOSED as named constants, because the map
draws no terrain and no gate.
- **Cameras:** a wide first view from a lookout knoll beside the road (the road itself ran in a cutting there), a long
lens and a telephoto from the same spot, the valley road at eye level, the gate approach at 52 m, through the gate at
13 m. Travelers, carts and a pack horse placed on the road as proxies.
- **Re-surface:** three to four takes per view, ~120 calls, 0 refusals.
- **Gates:** wide views held ECC scale 1.003-1.014 after a framing lock (the first round zoomed in 4-10 %); landmark
correlation 0.44-0.72, one take rejected at 0.16 for redrawing the castle as a palace; figures +5-13 % after the
eye-line clause (first round +25-28 %); sunset relights within 0.15 % scale and 1.8 px of their day pick after the
"this is the eastern sky, no glow" clause (two rounds had painted a sunset in the east).
- **Failures fixed in the model, not the prompt:** a false lake from a blurred river class; the road in a trench; the
gate's roof as a solid block; the toll bench standing on the road; a sun angle that put the gate in its own shadow.
- **Delivered:** 14 frames (7 views x day + sunset) with alternates, QC sheets, a README with 12 PROPOSED items each
carrying "if you rule otherwise, change X and re-render Y", and a Cost line.
## What to expect in cost
Measured in October 2026 on the hosted model used: about $0.06 per call with one reference and $0.09 with four, at
2048x1152 high quality. A tier-1 place (full matrix, rooms, population cells) runs 100-200 calls, $10-20; a tier-2 shop
20-40 calls; a tier-3 pub under $1. Volume is what costs: 54-cell matrices times takes times re-rolls. Over three weeks
of heavy use one campaign spent about $800 on 11,000 calls, 37 % of it on weather matrices. Every run writes a Cost
line so you can see where yours goes. The honest way to cut it is fewer takes and tighter candidate sets, not a weaker
renderer: the retakes and the review time cost more than the unit price.
The other cost is the GM's attention. The tier scheme exists to spend tokens and renders so that fewer, better frames
reach a human, and to put gated work straight into the campaign's canon folder with a one-line note instead of a
review pile.
## Layout
```
SKILL.md the procedure, for agents (and humans)
references/ pipeline, gates, prompting, matrices, effort tiers, naming, failure modes
docs/ illustrated map → model → plate → frame walkthroughs
scripts/ the toolkit (see SKILL.md "Reference"); smoke_test.py proves it end to end
scripts/adapters/ renderer adapter point
examples/ config, cameras, scene, prompts to copy and edit
```
## Status and license
The pipeline and gates are proven in use (hundreds of plates, thousands of renderer calls). The effort-tier scheme is
newly adopted and on trial; `references/effort-tiers.md` says what to evaluate. Contributions that add a renderer
adapter, a map-style segmentation preset, or measured gate bands for another model are welcome.
License: see `LICENSE`.