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 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 · an interior room · one sign across every angle · a populated district sheet
What it does
- Segments your map into roofs, trees and water.
- 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).
- Ray-marches a template plate per camera: an untextured render from exactly where the final picture will be taken.
- 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.
- Gates the result against the plate: drift, zoom, landmark fidelity, invented skyline structures, figure scale, text and watermarks. Numbers, not vibes.
- 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.
- 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; seescripts/adapters/README.mdfor 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
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.