125 lines
8.5 KiB
Markdown
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`.
|