Documentation

From flat render
to a dome you can
walk inside.

Dome Forge turns eight flat images plus a sky and a floor into a stitched, explorable environment. This is the whole process — geometry, alignment, rendering, fitting, viewing — with every command ready to copy.

overview

What it is

A flat picture doesn't sit right on a curved wall — the edges look wrong when you stand in the middle. Dome Forge solves that with a ring of panels, each geometrically corrected, plus a polar-wrapped sky cap and a floor. The result is a space you move through, not a picture you look at.

There are four browser tools and one GIMP script:

toolGeometry Lab → toolAlignment Grid → renderMidjourney → scriptGIMP fit → toolDome Viewer

The three browser tools live at domeforge.org. The GIMP script runs on your machine. Midjourney makes the images.

onboarding · first dome

Quick start

The short version, start to finish. Each step links to its full section below.

  1. Set the geometry. Open Geometry Lab, leave it at 8 panels, note the --ar it shows (16:9). details ↓
  2. Export the parameters. Open Alignment Grid, confirm 8 panels, click for GIMP to download dome-params.scm. details ↓
  3. Render 10 images in Midjourney: 8 wall panels at --ar 16:9, one cap, one nadir, all sharing one light and time of day. details ↓
  4. Fit the walls in GIMP. Install the script, run Filters → Dome Forge → Fit dome panels. details ↓
  5. Walk inside. Open Dome Viewer, load the fitted folder plus cap and nadir, press I. details ↓
The walls need GIMP's geometric warp. The cap and nadir don't — the viewer wraps them live, so they go straight in unfitted.
step 1 · geometry lab

Set the dome's shape

Everything downstream depends on the panel count and the aspect ratio it implies. More panels means each render covers a narrower arc, so less edge distortion — but more images to make.

  • 8 panels — the default. Each wall renders at 16:9, 8.1% edge stretch. A good balance.
  • 12 panels — 3.4% stretch, flatter, but twelve renders to keep consistent.
  • 6 panels — 15.6% stretch, only six images, but visible curvature.

Walk inside (press I) to feel the curve before committing. The number that matters for rendering is the --ar the panel shows — that's the aspect ratio every wall render must use.

At 8 panels and wall height 5.3m the aspect lands exactly 16:9. If you change panel count or wall height, the --ar changes with it — always read it off the tool.
step 2 · alignment grid

Export the parameters

The Alignment Grid shows where the panel rulings must fall on the curved surface (amber) versus where a flat render puts them (blue). The pre-warp slider bends one to meet the other. You don't have to understand the grid to use it — the important action is the export.

Set the panel count to match your renders, then click for GIMP. It downloads dome-params.scm — the file the GIMP script reads for the warp curve, panel count, aspect, and horizon. Put it next to the script (see step 4).

The exported panel count must match what you actually render. An 8-panel export against 12 renders warps everything wrong.
step 3 · midjourney

Render the images

You need 8 wall panels, 1 cap (sky, straight up), and 1 nadir (ground, straight down). The walls wrap 360° around the viewer, so they have to agree on one horizon height, one light direction, one time of day — or the seams show.

Wall panels

Render each at the --ar from step 1. Give every wall an identical style suffix so they stitch. The scene is split by compass bearing — decide what sits at each of the eight directions around the viewer.

The cap

Straight up. Either a uniform sky (use the viewer's flat cap mode) or a radially-composed zenith shot (use polar mode). Uniform is more forgiving.

midjourney · cap
pre-dawn indigo sky directly overhead, deepest blue at center fading toward edges, faint scatter of stars, wisps of high cloud, no horizon, seamless radial composition, muted desaturated palette, subtle film grain, photorealistic --ar 1:1 --style raw

The nadir (floor)

Straight down. The viewer lays this flat, so it wants uniform ground — calm water works beautifully — with no strong directional feature or central void.

midjourney · nadir
directly overhead aerial view straight down at perfectly calm dark water, smooth still black water filling the entire frame edge to edge, uniform gentle ripples, no shoreline, no horizon, no central feature, evenly textured, faint pre-dawn blue reflection, deep indigo tone, seamless and radially uniform, photorealistic, seen from directly above --ar 1:1 --style raw
Name files so they sort right: Panel01.png…Panel08.png, plus one with cap and one with nadir in the name. Avoid "cap" in the folder name — it confuses the detector.
step 4 · gimp fit

Fit the walls in GIMP

Only the walls get fitted — the cap and nadir skip GIMP entirely. Requires GIMP 3.0+ (the script refuses 2.10).

Install

Find your scripts folder — GIMP tells you under Edit → Preferences → Folders → Scripts. On macOS it's usually:

bash · install
cp ~/Downloads/dome-fit.scm ~/Downloads/dome-params.scm \
   ~/Library/Application\ Support/GIMP/3.2/scripts/

Both files go in the same folder. Restart GIMP or run Filters → Script-Fu → Refresh Scripts.

Prepare the output folder

Script-Fu can't make folders, so create the output folder by hand first:

bash · setup
mkdir -p ~/Desktop/CapeCanav/fitted

Run it

Filters → Dome Forge → Fit dome panels. Point Folder of renders at your image folder, leave Burn grid on unchecked for clean output, click OK. It writes panel-01.png…panel-08.png plus cap.png into fitted/.

If your folder name contains "cap" (like "CapeCanav"), the current script handles it — but older copies classified every file as the cap. Make sure you're on the current dome-fit.scm.

You can also run it from the console for a single panel — see GIMP commands.

step 5 · dome viewer

Walk inside

Open the viewer. Load your images three ways — drag the folder onto the drop zone, click folder…, or files…. It sorts them into 8 walls, cap, and nadir automatically.

Move around

  • I — step inside / out
  • W A S D — walk · drag — look · Q E — up/down · shift — faster

If WASD does nothing, click once on the 3D area first so keyboard focus leaves the sliders.

Arrange the panels

Filename order isn't always right. Fix it in-viewer:

  • Drag a slot onto another to swap.
  • Click one slot, then another, to move it.
  • Right-click a slot to load a fresh image into it.

Cap & floor

Both wrap live. If the cap shows a sunburst at the zenith, switch it to flat mode. Use rotation to line the sky and ground up with the walls. See viewer controls.

reference · gimp console

GIMP commands

Open Filters → Script-Fu → Console. Paste one line at a time (start at the (, end at the final ) — don't include the terminal prompt).

Reload the script without restarting

After editing dome-fit.scm, force a fresh load:

script-fu · reload
(load "/Users/David/Library/Application Support/GIMP/3.2/scripts/dome-fit.scm")

Load the parameters

If dome-warp-curve is unbound, load the params file first:

script-fu · params
(load "/Users/David/Library/Application Support/GIMP/3.2/scripts/dome-params.scm")

Fit one wall panel

Re-process a single re-rolled render without redoing all eight:

script-fu · one wall
(dome-fit-wall "/Users/David/Desktop/CapeCanav/Panel03.png"
               "/Users/David/Desktop/CapeCanav/fitted/panel-03.png"
               3 2048 1.778 0.32 0.0833
               dome-warp-curve dome-warp-samples 96 12 8 FALSE)

Arguments: in-path, out-path, index, width, aspect, horizon-frac, overlap-frac, curve, samples, strips, cells-x, cells-y, burn-grid. Set the last to TRUE to overlay the diagnostic grid.

Fit the cap plate

The cap doesn't need this (the viewer wraps it), but the script can square-crop and flip it if you want a baked plate:

script-fu · cap
(dome-fit-cap "/Users/David/Desktop/CapeCanav/Cap.png"
              "/Users/David/Desktop/CapeCanav/fitted/cap.png"
              2048 0.14 FALSE)

Run the whole batch

script-fu · batch
(script-fu-dome-fit "/Users/David/Desktop/CapeCanav"
                    8 1.778 0.32 0.0833 2048 2048 0.14 96 FALSE)

Check the version

script-fu · version
(car (gimp-version))
reference · viewer

Viewer controls

Source toggle

fitted shows your GIMP-warped panels (warp off — already baked). raw shows unfitted renders with the warp applied live in-shader. Flip between them to compare, or to skin a dome from raw renders without GIMP.

Geometry

Load dome-params.scm or set panels, radius, wall height, cap rise, eye height, and overlap by hand. Changing panel count adopts the slot layout.

Cap

  • polar / flat — polar wraps a radial zenith render; flat lays a uniform sky flat (no sunburst).
  • dead zone — polar only; hides the smeared center.
  • rotation — spin to align with walls.

Nadir

Always flat-mapped. rotation and scale tune how the ground texture sits; the rim fades into the wall bases.

Seams & checks

  • present / register / build — clean, edge-tinted, or grid-overlaid display.
  • highlight seams, tuck & cross-fade, reference grid, wireframe.
  • seam fade width — how softly panels blend at the tuck.

Mode

build shows all instruments. user hides the chrome for a clean walk-through and drops you inside.

reference · prompts

Prompt recipes

The rule that makes walls stitch: one shared style suffix on every wall, locking horizon height, sky gradient, time of day, and light direction. Only the foreground subject changes per bearing.

Shared wall suffix

midjourney · suffix
pre-dawn blue hour, low flat horizon at one third height, cold indigo sky graduating to faint teal near the horizon, still calm water with soft reflections, wisps of ground mist, no sun visible, muted desaturated palette, subtle film grain, photorealistic wide-angle landscape photography, no people, no text --ar 16:9 --style raw

Prepend a per-panel foreground clause (what sits at that bearing) before the suffix. Keep the suffix identical across all eight.

Seam continuity lives at the vertical edges: the right edge of each panel must match the left edge of the next. If a form is cut off with nothing continuing it on the neighbor, that's a re-roll — blending can't invent the missing half.
reference · deploy

Deploy the site

The browser tools are static single-file HTML on Cloudflare Pages. From the site folder:

bash · first time
npx wrangler login
npx wrangler pages project create domeforge --production-branch main
npx wrangler pages deploy . --project-name domeforge
bash · redeploy
npx wrangler pages deploy . --project-name domeforge

The custom domain is attached in the dashboard: Workers & Pages → domeforge → Custom domains. The stable URL is domeforge.pages.dev; each deploy also gets a preview-prefixed URL.

reference · troubleshooting

When something breaks

GIMP: “string-length: argument 1 must be: string”

Usually a stale script or the folder-name-contains-"cap" issue. Reload the script fresh (see above), and make sure you're on the current dome-fit.scm.

GIMP: script changes don't take effect

Refresh Scripts often isn't enough for structural edits. Fully quit GIMP (Cmd+Q) and relaunch, or (load "…/dome-fit.scm") in the console to force it.

Viewer: cap has a sunburst at the top

That's polar wrapping collapsing to the center point. Switch the cap to flat mode.

Viewer: nadir looks like a pinwheel

Older versions polar-wrapped the floor. Current builds lay it flat — reload the page. If it persists, the render has a strong central feature; re-roll with a uniform ground.

Viewer: WASD doesn't move me

Keyboard focus is on a slider. Click once on the 3D area, then use the keys.

Viewer: clicking a panel to swap does nothing

Fixed in current builds (draggable elements were swallowing clicks). Reload the page to get the latest.