procedural-realism
Make photographic-style images with pure code and physics, no generative image model. Ray-marched terrain of any real mountain with physical sky, haze, shadows, snow, mist and clouds; mirror lakes; forests and villages; blue hour with a lit city or a moonlit starry night; sunset timelapse videos along the real sun path. A from-scratch path tracer renders JSON still lifes (glass, prisms with rainbow caustics, copper, fruit). A painterly finisher turns any image, including an uploaded photo, into oil, impasto, gouache, watercolour or ink. Use whenever someone wants a realistic or "CGI" render made from code, a photoreal landscape of a real place, a 3D still life without Blender, a painting of a render or photo, or an image path traced or ray traced from scratch with "no AI image". Not for help with other renderers (Blender, Cycles, Unreal), explaining rendering in words, photo filters or real-paint advice. For line-art, contour, riso or woodcut styles, use procedural-terrain-art.
- License 许可
- Apache-2.0
- 最近更新
- 2026-10-31
- Stars
- ★ 12
- Forks
- 1
01 前言 Front Matter
- name
- procedural-realism
- license
- Apache-2.0
- metadata
- { "version": "1.2.0", "homepage": "https://dogum.github.io/procedural-art/" }
- description
- Make photographic-style images with pure code and physics, no generative image model. Ray-marched terrain of any real mountain with physical sky, haze, shadows, snow, mist and clouds; mirror lakes; forests and villages; blue hour with a lit city or a moonlit starry night; sunset timelapse videos along the real sun path. A from-scratch path tracer renders JSON still lifes (glass, prisms with rainbow caustics, copper, fruit). A painterly finisher turns any image, including an uploaded photo, into oil, impasto, gouache, watercolour or ink. Use whenever someone wants a realistic or "CGI" render made from code, a photoreal landscape of a real place, a 3D still life without Blender, a painting of a render or photo, or an image path traced or ray traced from scratch with "no AI image". Not for help with other renderers (Blender, Cycles, Unreal), explaining rendering in words, photo filters or real-paint advice. For line-art, contour, riso or woodcut styles, use procedural-terrain-art.
02 资源文件 23
- 参考文档evals/evals.json4.5 KB
- 资产文件evals/files/mountain_photo.jpg66.5 KB
- 参考文档evals/trigger_evals.json2.3 KB
- 参考文档references/lessons.md12.5 KB
- 参考文档references/painting.md9.8 KB
- 参考文档references/scenes.md8.3 KB
- 参考文档references/terrain_features.md20.7 KB
- 参考文档scenes/pomegranate.json4.6 KB
- 参考文档scenes/prism_and_crystal.json3.2 KB
- 参考文档scenes/wine_and_marbles.json3.9 KB
- 脚本scripts/dem.py5.0 KB
- 脚本scripts/osm_roads.py18.0 KB
- 脚本scripts/paint_compare.py1.6 KB
- 脚本scripts/paint_media.py5.3 KB
- 脚本scripts/paint_strokes.py17.7 KB
- 脚本scripts/paint_wash.py27.4 KB
- 脚本scripts/paint.py22.2 KB
- 脚本scripts/pathtracer.py65.1 KB
- 脚本scripts/pbr_terrain.py62.9 KB
- 脚本scripts/post_pathtrace.py7.1 KB
- 脚本scripts/post_terrain.py12.7 KB
- 脚本scripts/terrain_near.py135.2 KB
- 脚本scripts/timelapse.py13.3 KB
03 SKILL.md 正文
Procedural realism
Four tools, numpy/scipy/pillow only, that push how close pure math gets to a photograph or a painting:
| Tool | Best at | Time on 1 CPU |
|---|---|---|
scripts/pbr_terrain.py (+ post_terrain.py) |
Real mountains from real elevation data: atmosphere, golden light, shadows, snow, mist, clouds; optional lake reflections, trees and villages, blue hour with city lights along real streets (OpenStreetMap), moonlit night | 7 s at 600×200 · ~2.5 min at 3000×1000 plain · 5–13 min with water, trees or a city |
scripts/timelapse.py |
Sun-angle video (golden hour to night) along the real solar path for a date and place, every frame rendered so shadows slide | ~15 s per 600×200 frame, ~50 s at 1200×400, one core each; frames render 4 at a time (--jobs), so a 20 s clip (480 frames) ≈ 2 h at 1200×400 on 4 cores, 6 h on one |
scripts/pathtracer.py (+ post_pathtrace.py) |
Tabletop scenes from a JSON file: glass, liquids, metal, glossy fruit, soft or hard light, caustics (photon map), rainbow dispersion, depth of field | ~3 s per pass at 900×300; 30–70 s per pass at 2400×800; 60–80 adaptive spp (about an hour) for a clean final |
scripts/paint.py |
Any image (a render from above, or a photo the user uploads) as oil, impasto, gouache, watercolour or ink | 10–60 s at 3000×1000 |
Requirements: Python 3 with numpy, scipy and pillow; ffmpeg for timelapses. The terrain renderer needs network access to AWS Terrain Tiles for elevation data, and with --city to the OpenStreetMap Overpass API for streets (scripts/osm_roads.py; cached in --work/osm, with a synthetic street grid when it can't be reached).
Work in a writable folder (for example the session's outputs folder) and call the scripts by path: the installed skill folder may be read-only, and every script writes only to --work, --out and the current folder. In the commands below SK is this skill's folder (the one containing this file) and S=$SK/scripts.
If the user wants stylized or graphic output instead (line engravings, contour maps, risograph prints, woodcuts), that is the procedural-terrain-art skill.
Terrain: workflow
SK=/path/to/procedural-realism; S=$SK/scripts # run from a writable folder
ARARAT="--peak 39.7019,44.2986 --from 40.1792,44.4991 --second 39.6517,44.4011 --work work/ararat"
python $S/pbr_terrain.py $ARARAT --size 600x200 && \
python $S/post_terrain.py --bands work/ararat/bands_600x200 --out draft.png # draft: fetch + ~7 s
# final, in row chunks that each fit a time-limited shell (rows already on disk are skipped)
python $S/pbr_terrain.py $ARARAT --size 3000x1000 --rows 0:500
python $S/pbr_terrain.py $ARARAT --size 3000x1000 --rows 500:1000 && \
python $S/post_terrain.py --bands work/ararat/bands_3000x1000 --out final.png
- Where:
--peakis the summit and--fromis where the famous view is taken. Look both up; don't guess. The camera auto-backs along that line of sight until the mountain spans about 5° of view, which gives the telephoto "mountain from the city" look. Override with--cam-offset(km toward the peak; 0 = stand at--from). - Two peaks:
--second lat,lonframes two peaks together, for example Ararat and Lesser Ararat. - Light: this matters most. By default the sun lights the faces the camera sees, at 10° elevation (golden hour). Backlit mountains read as flat grey shapes. Tune with
--sun-azand--sun-el, or--time day|golden|blue|night. - Air:
--hazesets dust (0.1 crisp, 1+ dusty),--airsets how blue distant things get, and--mistsets the valley mist density (0 turns it off; above about 6 it becomes a flat featureless sheet). - Snow:
--snowlinein metres. The default is 68% of the way up. - Framing:
--layout right|center|left,--hfov,--pitch,--horizon F(true horizon at fraction F from the top),--cam-height(km above ground). If foreground ridges hide the base, that is real geography. Raise--cam-height, change--cam-offset, or keep it: framing between dark ridges often looks better. - Variants:
--tag NAMEgives a variant its own band folder (bands_WxH_NAME). Resuming a folder with different pixel-affecting flags stops with a message instead of mixing two pictures, andpost_terrain.pythen refuses that folder too, so a chained&&block can't save the old picture under a new name. Chunks can have any row range: missing rows are found and filled on the next run, and post refuses a folder with missing rows. - Check: each run prints the peak elevation it found. Compare it with the real value to catch wrong coordinates (tiles clip sharp summits a little: Fuji comes out at 3742 m, real 3776 m).
Lakes, forests, villages, night, timelapse
All off by default. Full flag list, recipes for every showcase, tuning notes and the pitfalls of each feature: references/terrain_features.md (read it before using any of these).
- Water:
--water-level autoturns a lake near the camera into water that reflects terrain, sky and cloud;--waves 0.1is a calm morning mirror. Stand on the water:--cam-offset 0 --cam-height 0.004 --horizon 0.5.autoonly accepts a basin that is level in the elevation data; on a dry plain it prints why and renders without water. For a lake it can't find, or the sea, give--water-level <metres> --water-seed lat,lon. - Near field:
--trees 0.8 --villages 0.6 --near-km 5adds trees, orchard and poplar rows, houses with pitched roofs, and field walls and fences, reflected in water. They only read with a low camera (--cam-height 0.03or less). Standing in a field (--cam-height 0.003), trees and houses from about 40 m hold up at 3000 px; add--sky physicaland post with--exposure 0.6.--biome temperate --treeline 2400for green mountains. - Twilight and night:
--time blueor--sun-el -4switches to the physical sky (Earth shadow, Belt of Venus, alpenglow).--city 0.8lights a city along its real streets from OpenStreetMap: lamps by road class (white LED on avenues, orange sodium on side streets), car light streaks (--traffic,--shutter), lit windows in the buildings that front a street, dark parks and fields. Road data © OpenStreetMap contributors (ODbL). The first run fetches the roads; public Overpass mirrors can take several minutes for a city, and--streets gridskips them. Post with--exposure "auto*0.3": at blue hour post keys the exposure on the sky and sets the white balance to 4800 K.--near-lamps 16 --aperture 40adds out-of-focus lamps.--time nightgives a moonlit night with point stars, and post picks a night exposure by itself;--moon 0is starlight only. A city reads best at blue hour; under--time nightit dominates the frame. - Clouds:
--cloud-model msgives the lenticular multiple scattering and a silver lining.
Fuji mirrored in Lake Kawaguchi, the recipe of the showcase final (water makes a view about 4× slower than a dry one; the 3000×1000 final with trees took 12 min):
FUJI="--peak 35.3606,138.7274 --from 35.5215,138.7460 --cam-offset 0 --cam-height 0.004 --hfov 68 --layout center \
--horizon 0.5 --water-level auto --waves 0.12 --base 900 --mist 1.0 --haze 0.15 --biome temperate \
--treeline 2400 --snowline 2900 --trees 0.8 --villages 0.6 --near-km 5 --cloud-model ms --work work/fuji"
python $S/pbr_terrain.py $FUJI --size 900x300 && \
python $S/post_terrain.py --bands work/fuji/bands_900x300 --out fuji_lake_draft.png
Sunset timelapse over Yerevan (real sun path for 20 April, 18:40–20:40 local, 20 s at 24 fps; every frame is rendered at its own sun position, so shadows slide; everything after -- goes to pbr_terrain.py; rerun to resume). Draft a few seconds at 600×200 first (--start 19:26 --end 19:56 --frames 121 covers sunset):
python $S/timelapse.py --work work/tl --out ararat_sunset.mp4 --frames 480 --size 1200x400 \
--date 2026-04-20 --utc-offset 4 --start 18:40 --end 20:40 -- \
--peak 39.7019,44.2986 --from 40.1963,44.5238 --second 39.6517,44.4011 --cam-offset 0 --cam-height 0.05 \
--hfov 34 --air 0.8 --city 0.8 --trees 0.5 --near-km 8 --near-lamps 16 --aperture 40
Add --only-plan before -- to print the sun positions without rendering.
Still life: workflow
Scenes are JSON files in $SK/scenes/ (pomegranate.json, wine_and_marbles.json, prism_and_crystal.json). Copy one and edit it; the renderer never needs editing. Read references/scenes.md for every field (camera, lights, materials, objects, render and post settings) before writing a new scene.
python $S/pathtracer.py --scene $SK/scenes/pomegranate.json --size 600x200 --spp 8 --tag draft --work work/still
python $S/post_pathtrace.py --tag draft --work work/still --out draft.png
# final: every run ADDS samples to the same accumulator; --time stops cleanly inside a time-limited shell
python $S/pathtracer.py --scene $SK/scenes/wine_and_marbles.json --size 2400x800 --spp 80 --tag final \
--work work/still --time 3300
python $S/post_pathtrace.py --tag final --work work/still --out wine_and_marbles.png --jpg
- Sampling is adaptive after 8 spp: later passes put samples where the noise is still visible (glass, caustics, metal) and fewer on diffuse areas the denoiser will clean.
--sppis the frame average added by this run. - Primitives:
sphere,ellipsoid,cylinder,box,disk,tube(drinking glass),bowl(open spherical shell: balloon glass, metal bowl),prism,gem(round brilliant), ascattergenerator, plusplanesfor table and wall. All but the sphere takerot. - Liquid in a glass: give the
tubeorbowlafill(level,material). Do not model the liquid as a separate solid touching the glass. - Materials:
diffuse,coat(pigment under clear coat: fruit, lacquer, ceramic),metal(f0colour,roughGGX),glass(ior,sigmaabsorption per cm for colour, optionalabbefor rainbow dispersion). - Caustics: add
"caustics": {"photons": 250000, "k": 40, "rmax": 0.8}torenderwhen glass or mirrors sit in a small, strong light. Without it caustics come only from lucky paths and stay speckled. - Lights: rectangles;
spotnarrows the beam into a pool of light. A small, far, bright light gives crisp shadows and caustics; a large near one gives soft window light. - Look at a top view (
"camera": {"position": [0,110,-5], "target": [0,0,0.5], "up": [0,0,1]}) when caustics do not show: it tells you where they land and what hides them. - Useful flags:
--crop x0:x1,y0:y1renders one window (fixing one region),--no-caustics,--clamp,--basic(no MIS and no specular light connections, for comparisons). Post:--exposure,--denoise,--sigma-l,--bloom,--vignette,--grain,--saturation; defaults come from the scene'spostblock.
Painterly finish
scripts/paint.py turns any image into a painting with procedurally placed brush strokes or washes: a terrain render, a path-traced still life, or a photo the user uploads. Ink draws objects line-first and landscapes as sumi-e washes (--ink-mode, chosen automatically). Read references/painting.md to choose a style and tune it.
python $S/paint.py --in final.png --out painting.png --style watercolor --size 1500x500 # draft, 5–20 s
python $S/paint.py --in final.png --out painting.png --style oil --size 3000x1000 --seed 1 --jpg
python $S/paint_compare.py --out sheet.jpg --width 1800 --item final.png "render" --item painting.png "oil"
| Style | Looks like | Use it for |
|---|---|---|
oil |
Smooth blended oil on canvas | The safe default; subjects that must stay readable |
impasto |
Thick loaded strokes, strong relief, broken colour | Landscapes and skies when energy beats fidelity |
gouache |
Opaque, matte, flat shapes from an 18-colour palette | Poster and illustration looks |
watercolor |
Transparent glazes, wet edges, granulation, deckled paper | Landscapes with sky; the strongest preset |
ink |
Monochrome ink wash on rice paper | Mountains and misty landscapes only; poor on busy, dark scenes |
--size resizes and centre-crops to fill (brushes scale with it, so a 1500×500 draft looks like the final downscaled). --detail 1.5 / 0.7 = tighter / looser, --strokes-scale multiplies brush sizes, --relief 0 turns off the raking-light impasto. Peak memory is about 0.9 GB at 3000×1000.
Rules that came from real failures
- Look before scaling up. Render tiny (600×200), view it, fix it, then render big. Every quality jump in this work came from looking at a draft.
- Light direction beats detail. Moving the sun did more than any texture work.
- Caches follow the place.
pbr_terrain.pykeepsdem.npzand the resampled heightfieldhf.npzin--workand reuses them only for the same peak and radius; another mountain rebuilds them. A separate--workper place still saves refetching when you switch back and forth. - Low cameras, water, trees and cities each have their own pitfalls (mist around a low camera, streak shadows, rippled reflections);
references/terrain_features.mdlists them. - Denoiser vs lighting edges: a filter guided only by normal, depth and albedo cannot see shadows and caustics and blurs them away.
post_pathtrace.pyscales its edge-stop by each pixel's measured noise, so keep the variance (don't pass--no-variance) and raise--sigma-lonly for very low sample counts. - Coincident surfaces: a glass base exactly on the table (both at y = 0) loses the light under it. Lift glass objects 0.02 cm.
- Where caustics land: a low light throws caustics far from the object (about height / tan(elevation)); they are easily hidden behind the next object. Check with a top view before the final.
- Memory: rays are processed in chunks (path tracer 200k by default,
--chunk); the terrain mirror pass is chunked too. Keep chunking if you add geometry. - Time limits: everything is resumable (row bands, sample accumulators, timelapse frames). Background jobs may die when a shell call returns; run chunks in the foreground, or use
pathtracer.py --timeso a run stops cleanly before the shell limit. - Showing results: after writing output files, always present them. A file that is never presented can't be opened on mobile.
Honest limits (tell the user)
Light, atmosphere, water reflections, glass, metal and real terrain at a distance are convincing. Trees and houses hold up from about 60 m out even with the camera standing in a field, but the nearest big crowns still look rendered on close inspection; cities follow real streets but their buildings are boxes, so they only work at blue hour or night, and water doesn't move. A timelapse renders every frame, so a 20 s clip takes hours even with four frames rendering at once. The path tracer lacks tori and rounded boxes, and paintings keep detail down to about 2 px only where the source draws it cleanly (a noisy render's speckled highlight becomes one soft shape). On one CPU core a 3000×1000 terrain frame with water and trees takes about 13 minutes and a clean glass still life about an hour. references/lessons.md has the full list of limits, what each technique buys and the mistakes worth not repeating.
scripts/dem.py (elevation download and loading with void filling) is shared with procedural-terrain-art; both skills ship an identical copy. Change both or neither.