Files

8.6 KiB

name, description, license
name description license
dnd-city-visualization Render map-true towns, cities, approaches, establishments and their weather/population matrices for a tabletop campaign: 3D block model from the map, template plates per camera, re-surface with an image-edit model, gate, deliver by effort tier. Use when a GM asks for a view of a mapped place, a first view from the road, an aerial, a gate, a shopfront, a tavern at a given hour, or a weather matrix. see LICENSE

City render workflow

The method: geometry arrives as pixels, never as words. Trace the map into a block model, ray-march a template plate per camera, hand the plate to an image-edit model as IMAGE 1 with "re-surface this; move nothing", then gate the frame against the plate. A correction is one edit to the model and a re-render of every camera. Details in references/pipeline.md; run scripts/smoke_test.py once to see every tool work on a synthetic town.

Before you start

  • Read references/effort-tiers.md and assign the place a tier (= the chance it comes into focus at the table). The tier fixes the deliverables, the budget and the matrix sizes. Never exceed the tier's ceiling without the GM.
  • Copy examples/citykit.example.json, views.example.json, scene.example.json, prompts.example.json next to the map and fill every value. Credentials only in the environment (IMAGE_API_KEY, IMAGE_API_BASE).
  • Write down what is canon (on the map) and what you are about to PROPOSE (terrain, heights, walls, gates, the hour).
  • Check the lane folder for a fresh REPORT.md: the same brief dispatched twice is re-verified, never re-rendered.
  • Done when: config files exist, the tier and budget are in the brief, and REPORT.md exists with a Problem line.

Steps

  1. Build district sheets when the city needs them. Register each district bitmap to the whole-city map from several roof patches; record the scale, translation and residuals; project established pins through that transform. Fill unused template slots only with clearly PROPOSED establishments sited on real unoccupied roofs, each with a name, tagline, wealth tier and effort tier. Never move a pin to escape the template veil. Most padded places are T3/T4 until play promotes them. Route leaders without crossings or legend hits; see docs/walkthrough-district-map.md and references/pipeline.md section 0.5. Done when: registration is measured, canon and proposals are visually distinct, every pin is map-sited, label routing passes, and the companion table carries both tier types.
  2. Segment the map. segment_map.py MAP --mpp M --out seg.npz --look look.jpg. Eyeball look.jpg. Done when: roofs, trees and water are right where you will put a camera; false trees removed.
  3. Mass the town. massing.py seg.npz --config citykit.json --out town.npz. Heights come from wealth zones (proposed); hand-modeled landmarks are cut out and rebuilt in scene.json with every dimension named. Done when: separate houses are separate cells, no slivers, landmarks have their canon dimensions.
  4. Place cameras and proxies. Cameras in views.json: eye-level views at ground + 1.65 m with a lens shift instead of pitch; the camera that presents the defining feature; found from the heightfield, never by eye. Proxies (1.60-1.80 m, carts, animals) in the scene, 10 m or more from an eye-level camera, off the frame edge. Done when: every view has a visibility list (what it sees, what is occluded) written for step 5.
  5. Render plates. render_plate.py V1 V2 --config citykit.json (parallel processes; 1-15 min each at 2048). Gate the plate against the map's checkable facts (references/gates.md section 0) and fix the model, not the prompt. Done when: every plate passes its facts by eye and the untextured plate shows no artifact.
  6. Write the prompts. Fill prompts.json per references/prompting.md: resurface premise, per-view intro / keep / FRAMING LOCK with measured band positions, the people block, the eye-line clause for eye-level views, the setting and town blocks (with the big things the model invents for a town of this kind, negated), the light with the sun relative to the camera, no-modern and no-text. Material references from a different camera than the plate. Done when: build_jobs.py day --config citykit.json --prompts prompts.json --takes 3 --out jobs_day.json writes the jobs and you have read jobs_day_PROMPTS.md for contradictions.
  7. Re-surface. render_batch.py jobs_day.json --out out_day --start 4 --max 8. Three to four takes per view. Done when: out_day/calibration.md reports the run and no quota or refusal stopped it (a refusal stops the lane; report it, do not switch renderers).
  8. Gate and pick. gate.py out_day --config citykit.json, then qc_sheet.py. Reject reframes (ECC scale off 1, shifts beyond a few px), low landmark correlation, any invented skyline structure on wide views, figures off their brackets, anything in the corner sweep. Pick one plus an alternate per view into picks.json. Done when: every pick has its gate numbers in REPORT.md and the plate-vs-pick sheet exists.
  9. Relight. build_jobs.py relight --light sunset V=out_day/V_day_t2.png ... --out jobs_sunset.json, render, gate with --keepers. Sunset, night and morning are light-only edits of the day pick; the sky in frame is named (east or west). Done when: relights register to their day pick within 0.2 % scale and 2 px.
  10. Matrices (tier 1 and 2). matrix_jobs.py weather --tier T V=keeper ... for Day/Sunset/Night x Dry/Rain/ Snow (light) and any storm or deep-snow cells; matrix_jobs.py population --tier T V=empty_master ... for every venue with people. Chained cells (Sunset/Night of a weather) get their reference after the Day cell is picked. Gate storms on the wall band, deep snow above the snow line, route clearance by class (references/matrices.md). Done when: the matrix is complete for the tier, each cell's gate rung is recorded, fixed cells are disclosed.
  11. Character pass (several exteriors on one wealth rung). Thumbnail the batch; if the houses are interchangeable, one-change edits adding each house's emblem sign and visible trade, gated against their own source. Done when: the contact sheet reads as different places.
  12. Deliver. Canon file names per references/naming.md; picks plus alternates; the QC sheets; a README for the GM (what to show when, PROPOSED items with "if you rule otherwise", open questions, known flaws). Gated work goes straight to canon with a one-line note; a human review entry only for a story-critical face, a permanent bake, or on request. Verify by fetching back and hashing. Done when: REPORT.md has Problem, two Whys, what was built, picks with numbers, failures and fixes, PROPOSED, open questions, limits, Cost (cost.py), and the re-render chain; the hand-off is its path and one headline line.

Non-negotiables

  • Fix geometry in the model, never by wording. The renderer photographs the plate's mistakes as faithfully as its truths.
  • Per camera, from a visibility list; occluded features disowned positively.
  • Overviews and wide aerials are gated for invented large buildings against the model's landmark list.
  • Figures are proxies in the plate, gated by brackets (+-25 %).
  • Signs are emblems, never lettering; a corner and edge sweep on every frame.
  • Never re-export the map to fix a fit; move a pin or reuse an existing building.
  • Every run reports its Cost. Cut spend by volume, never by switching to a weaker renderer.
  • Play promotes a place's tier; never demote; nothing rendered is deleted, superseded files are moved aside.

Reference

  • references/pipeline.md — the method step by step, with the measured reasons.
  • references/gates.md — every gate, its bands, and what it is blind to.
  • references/prompting.md — prompt blocks, framing locks, scale by relation, wealth-tier vocabulary, glass.
  • references/matrices.md — the 9-square, snow levels and route clearance, foliage, population x time, matrix traps.
  • references/effort-tiers.md — tiers, deliverables, budgets, model-cost tiering, delivery policy (on trial).
  • references/naming.md — file and folder names, the report shape.
  • references/failure-modes.md — symptom, cause, fix, one line each.
  • docs/ — illustrated castle, interior, sign-lock, and district-sheet walkthroughs.
  • scripts/ — segment_map.py, massing.py, scene_solids.py, render_plate.py, build_jobs.py, render_batch.py (+ adapters/), gate.py, qc_sheet.py, matrix_jobs.py, cost.py, smoke_test.py.