Working on a globe

A whole-world project keeps the planet as the source of truth. You cut low-distortion regions off it, work each one in the section editor, and fold the result back onto the sphere. The globe workspace is where the cutting and the folding happen, and where the world tells you which parts of it are current.

You reach it by opening a world whose workflow mode is A whole world. A flat map never sees this screen; it is the single map, so there is nothing to cut or reassemble.

The three things on a globe#

Everything in the workspace is one of three objects.

The globe is the equirectangular world layer plus, once you have run a colour pass, a composited mosaic on top of it. One world has one globe. It is what Export globe ships.

Regions are the areas you drew and chose to work on. A region is a real section: it opens in the section editor, it has its own heightmap, biomes and render, and it carries a four-stage pipeline. Regions are listed in the Regions panel.

Globe tiles are created for you by the world colour pass. They cover the planet's land in overlapping circles so the whole sphere can be coloured without you drawing anything. They are hidden system sections: they never appear in the regions list, but they can be opened and edited like a region, and they get their own collapsible group in the side panel.

Editing a region or a tile marks the globe out of date. One action, Re-compose globe, folds every edit back in.

Cutting a region off the globe#

Pick the Box or Lasso tool from the Globe tools toolbar and drag on the sphere. Rotate is the default tool and orbits the planet instead of drawing. Pressing Escape anywhere on the stage clears the draft selection and returns you to Rotate.

New region in the panel header does not open a dialog. It selects the Box tool so you can draw; the dialog appears once you have a selection.

The client refuses a selection it cannot use, with the reason under the name field:

• a box needs both corners, and non-zero width and height;
• a lasso needs at least three distinct points and has to enclose an area.

The server refuses three more cases. A selection whose farthest vertex sits 100 degrees or more from its centre is near-global or not representable as one local section. A crop that runs off the edge of the projection canvas is refused as clipped. A crop larger than 8192 px on its long edge, or larger than 32 Mpx in total, is over the pixel budget; draw a smaller area or lower the output resolution.

Why the cut is a reprojection#

An equirectangular world map stretches east to west as you move away from the equator, by a factor of 1/cos(latitude). At 60 degrees a pixel covers half the ground east to west that it covers north to south. Cutting a rectangle straight out of that image and calling it a map would hand the terrain model, the brushes and the river routing a landscape that is stretched by a factor of two, and the amount of stretch would change with where you drew.

So a region is not a crop. It is reprojected into an oblique Hammer chart centred on your selection. Hammer is equal-area, and about the centre of an oblique aspect the local distortion is small, so a kilometre is a kilometre across the section. That is what makes a 33 km brush 33 km wherever you use it, and what lets the engine's physical parameters (catchment area in km², snow line in degC, lapse rate per km) mean the same thing on every section of the planet. The same transform runs in reverse to put the finished section back on the sphere.

The cost is that the projection has a boundary and a local limit. A region has to stay local, which is the 100 degree rule above. A near-hemispheric selection is not one section.

The composer dialog#

Two values are fixed and not exposed: margin_px is 32 and square_crop is false. The line above the advanced controls reads <N> geographic points · feathered edge included, which is the reminder that the raster you get is slightly larger than the ground you drew.

Two extents, and which one you are being shown#

Every section carries two sizes. extent_km measures the persisted raster, feather included, which is the honest size of the file on disk. selection_extent_km measures the great-circle span of what you actually drew, before the feather. On a region with the default 32 px margin they differ by roughly 20 percent. On a globe tile, whose margin is scaled to the canvas rather than to the tile, they differ by roughly 45 percent: a nominal 3000 km tile persists as a raster covering about 5900 km.

The readouts you see quote the selection extent and fall back to the persisted extent only when a legacy section cannot state it. That applies to the region card, the tile rings drawn on the sphere, and the EXTENT field in the section editor's footer.

The globe view#

The sphere is a WebGL surface. It falls back to the flat view when WebGL is unavailable or when the stage is under 280 px on its short side.

Zoom runs from 0.65 to 2.0. The on-canvas Zoom in, Zoom out and Reset view buttons step by 0.15 rather than the keyboard's 0.10, and Zoom in disables at 2.0, Zoom out at 0.65.

The sphere carries a faint graticule at meridians every 30 degrees and parallels every 15 degrees, a coloured patch and a SEC NN label per region, and the draft selection as a dashed outline while you draw. Region patches are green when the region is ready, amber when it needs terrain or has been edited since the last compose, and daylight-yellow otherwise.

The Flat view is the same world as an equirectangular image, with its own zoom range of 0.75 to 4.0. With a selection tool active it is keyboard-drawable: arrow keys move the cursor by 1 degree (5 with Shift), Space anchors the first corner, Enter completes the selection and Escape cancels. A live readout shows the cursor's longitude and latitude. The small inset in the corner of the globe view switches you to it.

Show original appears once a mosaic exists. It swaps the composited globe for the world's own global colour or height layer, so you can see the planet as it was before the colour pass.

The Guide overlay group in the side panel is the same control the section editor's Draw panel mounts, and one guide selection is shared between them. On the globe the guide is drawn as a second textured sphere between the terrain and the atmosphere, so a reference sketch can be traced directly onto the planet.

Scale chip, explainer and scale bar#

The scale chip in the top bar reads the composited globe's ground resolution followed by the planet's circumference, for example 90 m/px ⌀ 40000 km. A ≈ prefix means the server has not published a scale contract for this world and the figures are derived from the equirect width.

Clicking the chip opens the scale explainer, which unpacks it into four rows:

The scale bar over the canvas picks a round 1, 2 or 5 times a power of ten distance and draws it at its width in pixels.

The regions panel#

The panel header carries the eyebrow Geographic layers, the title Regions, a count, and the New region button. New region is disabled while the focus-area list is still loading and while a world enhance pass is running.

While a region is being carved, a live row shows its section id and <STATUS> · <stage> · N%, or RECONNECTING… if the event socket dropped. The row has a cancel X. Cancelling past 90 percent asks first, because the region may finish before the cancellation is accepted.

A finished region gets a card: preview thumbnail, name, status (with · EDITED appended when it has changed since the last compose), its extent and id, four pipeline dots, and a delete button. Clicking the card opens the region drawer. Deleting asks for confirmation and warns that shared or unsafe assets are refused by the server.

With nothing drawn yet the panel shows No regions yet and a Draw the first region button, which also just selects the Box tool.

The four-stage pipeline#

Every region and every tile moves through the same four stages, always in this order:

1. Rough terrain
2. Terrain detail
3. Analytic colour
4. Learned enhance

Each is marked DONE, CURRENT (the first incomplete one) or TODO. The four dots on a region card are the compact form of the same thing.

The region drawer lists the stages, names the next incomplete step using the same words the editor uses for it (Generate terrain, Add terrain detail, Render section colour, Enhance section colour), and says that step runs in the section editor. It cannot run a stage itself, which is why its only action is Open in editor. When everything is done it says so instead.

Globe tiles#

Tiles are planned by the colour pass, not by you. The planner covers the sphere with equal-area centres, keeps only the tiles that sit over land, and gives each one a circular selection ring in its own oblique frame.

The Globe tiles group in the side panel is collapsed by default and hidden entirely when the world has no tiles. Its header shows the tile count and, when any tile has been edited since the last compose, an N EDITED badge. The On globe checkbox draws the tile rings on the sphere.

Rings are derived from each tile's centre and the ground it claims, so they show the tile, not its feathered crop. An edited tile draws amber with a dot at its centre; every other tile draws in daylight yellow at lower opacity. Clicking a ring, or a thumbnail in the grid, opens the drawer for that tile. Tiles that are not ready are disabled in the grid.

Opening a tile in the section editor#

Open in editor on a tile hands off to the same section editor a region uses. A tile is a real Hammer section, so it has a heightmap, biomes, a render and the same pipeline.

Editing a tile has one consequence you need to know before you start. It marks the tile edited, which marks the globe out of date, and the two ways of updating the globe treat that differently:

• Re-compose globe re-renders only the tiles whose sections changed and folds them into a fresh mosaic. Your tile edits survive.
• A fresh Colour globe re-plans and rebuilds every tile from scratch. The server refuses to run it while edited tiles exist unless you tick Rebuild all tiles, discarding N per-tile edits in the modal. That checkbox does exactly what it says.

Colouring the whole world#

Enhance world in the actions row opens a modal with two stages that can be run separately or chained. The button reads Enhancing world terrain… or Colouring globe… while those passes are running, and is disabled until the region list has loaded.

The footer states the estimate and the primary button names exactly what will start: Enhance terrain, then colour globe, Enhance world terrain, Colour globe, or Nothing selected.

Two warnings sit permanently in the modal, and both are worth taking literally: This processes the entire world and can take many hours. and Try at least one focus-area section first to confirm you're happy with the look before running the whole globe. The look is driven by the same render parameters a section uses, so a section is the cheap way to find out whether you like them.

The modal also notes that the AI colour pass over every tile is not available yet. AI colour runs per section: open a section, use Enhance section colour, then fold that colour in with a re-compose.

What Target resolution actually sets#

mosaic_long_side is the tile detail target. It sets each tile's reprojection canvas, which is the resolution the retained per-tile crops are saved at. It is not the size of the globe you look at: the on-screen composite is capped at 4096 px on its long edge whatever you pick. What the setting really buys you is export headroom, because a world export re-composes from the retained crops at up to 32K.

Picking Native keeps the world's own resolution, capped to the section canvas bound. Picking a value below native shrinks the whole pass and is the fast-preview option.

How the pass runs#

Tiles are scheduled west to east, and a small equirect preview is republished as the completed frontier advances. That is why the globe appears to have dawn breaking across it while the pass runs: the lit region is the rendered region, and the terminator is real geography. The unrendered hemisphere is dimmed toward #071016 at 88 percent depth over a 2.5 degree ramp, so it reads as a planet's night side rather than a hole in the image.

Reveal frames are composed at 1024 px and paced off their own measured cost, so a large world gets fewer, longer dawn steps instead of a pass eaten by its own decoration. The terminator strip above the canvas is bound to the job's real progress.

Every ready region is folded into the same globe at a higher priority than the auto tiles, so a hand-authored region wins where it overlaps one. A region contributes only inside its own mask, so open ocean stays on the base. Where no tile covers, the composite falls back to the deep-ocean colour the tiles themselves paint (which is why the sea does not step at every tile boundary) and to hypsometric land colour in the small gaps between overlapping circles.

If a tile has a fresh Enhance section colour result, the pass uses it instead of re-rendering. Fresh means the enhance still matches that section's current analytic colour.

What the globe pass does not do#

The whole-world pass routes no flow. It has no rivers and no lakes. Those are section features, and a region rendered in the editor will have them where the globe will not.

Several other engine parameters are widened for the equirect pass before your own parameters are applied, because the section defaults are km-scale and fall below one pixel at a roughly 10 km/px analysis pitch: koppen_blur_km becomes 150 km, geo_sigma_km 350 km, lith_sigma_km 560 km, chaos_sigma_km 60 km and ecotone_dither_km 45 km. Without that, climate borders render as hard poster edges. The class-weight blur does not wrap the dateline, and its residual seam there is accepted for this fast pass.

If you tick per-tile diffusion at the default native canvas, the server will usually warn you that under half an octave of generated detail survives. Crops persist at the tile canvas resolution, so anything the model generates finer than that band is thrown away when the crop is saved. Raise Target resolution above native if you want that detail to survive into an export.

World status and the stale banner#

One derived status drives the chip over the canvas, the banner, the footer dot and the panel button.

While a pass runs the summary reads <verb> · <stage> · N%, using the same verb as the job card: Enhancing world terrain, Colouring globe, Re-composing globe or Rebuilding globe. When nothing is outstanding it reads Everything you edited is folded into the globe.

What makes the globe stale#

The server compares the world's current globe inputs against the superset the active mosaic recorded when it was composed. Any of these flips it:

• a region added since the compose;
• a region edited since the compose;
• a region removed since the compose;
• a globe tile whose section changed (a per-tile Generate or Enhance);
• the imported heightmap re-imported, or the world's layer definitions changed.

The summary line states which, for example 2 regions changed · 1 tile edited or heightmap re-imported. The banner adds a screen-reader line with the same counts.

With no mosaic yet, the current inputs alone decide: every region counts as an unfolded addition and every tile as edited. A world with neither reads up to date, because the imported world layer is the globe.

The tile-edited test is deliberately over-sensitive. It hashes the whole section record, so a rename moves it too. For a guard that protects work from being discarded, warning too often is the safe direction.

Re-compose globe#

The banner's primary action, and the same button in the panel footer, is Re-compose globe. It is enabled only while the globe is stale.

What it does depends on the world. When a globe already exists and the change is not structural, it is an incremental fold: unchanged tile crops are reused, only changed tiles are re-rendered, regions are folded in, and a fresh mosaic is published. When the change is structural (the heightmap was re-imported, or there is no coloured globe yet) it routes to a from-scratch re-tile instead. Before any globe exists at all, the button builds the world map from your ready regions.

The panel footer alongside it states READY n/N across regions and tiles, and NEXT EXPORT · <w> × <h> px, or no globe yet.

Export globe#

Export globe sits in the top bar and again in the panel footer, and is disabled until an active mosaic exists. The modal carries its own status chip (UP TO DATE, NEEDS UPDATE, UPDATING), a fixed source of the whole globe, a resolution ladder from Native up to 32K, a layer checklist, a destination preset and an output folder.

Two rules bite here. Every numeric resolution is disabled until the globe has retained tiles, because the high-resolution export is re-composed from them; run a re-compose first. And AI colour cannot be composed at export time. Globe colour is fixed when the globe is coloured, so an export ships exactly the per-tile colour that pass produced. Enhance the sections you want, then re-compose to fold that colour in.

A world export caps at 32768 px on the long edge. A section export caps at 16384 px.

The job dock#

Long globe jobs report to a stack of cards in the bottom-left of the stage, whether they are queued, running, done or failed. The dock outlives the modal that started the job, so a dialog closing on submit can never be mistaken for success.

Card titles are Rebuild globe, Re-compose globe, Colour globe, Enhance world terrain and Create region. Status reads Queued, Running, Done or Failed. The meta line shows <stage> · N% while running, stopped at N% on a failure that got somewhere, and the elapsed duration when done, plus reconnecting… while the event socket is retrying. A failed card prints the reason and a Try this: fix.

Running and queued cards offer Cancel where the job is cancellable. Failed cards offer Retry, except a region creation, whose button says Refresh because the selection you drew is gone and only the list can be re-synced. Retrying a terrain or colour pass reopens the Enhance world modal so you confirm the options against the current state rather than replaying stale ones. Finished cards can be dismissed.

When anything is running or failed, the top bar grows a rollup like 1 RUNNING · 1 FAILED. Clicking it scrolls the dock into view.

Cancellation is cooperative. The flag is checked between passes, between layers and at stage boundaries, and a cancelled job keeps everything it had already completed.

A practical order of work#

1. Create the world in whole-world mode. Import an equirectangular heightmap, or start from a blank ocean planet and paint continents onto the sphere.
2. Cut one region first. Draw a box over somewhere representative, open it, and take it through the pipeline: generate terrain, add detail, render colour. This is where you settle the render parameters. It is also what the Enhance world modal tells you to do before committing hours to the planet.
3. Colour the globe. Run Enhance world with Colour globe ticked. Start at 2048 × 1024 · fast preview if you only want to see the planet whole; raise Target resolution when you know what you are shipping. Leave per-tile diffusion off unless you have raised the target above native, or the model's detail is decimated at crop-save time anyway.
4. Cut the regions you actually care about. Anywhere that needs real detail becomes a region, worked in the section editor. See Painting terrain for the section-side work.
5. Edit tiles opportunistically. A tile that reads badly can be opened and fixed without becoming a region. Just remember a full re-colour would discard that edit.
6. Re-compose globe whenever the banner says the globe is out of date.
7. Export globe at the resolution and layer set you need.

Steps 4 to 6 are a loop. The globe is never rebuilt behind your back; nothing here auto-fires.

What it costs#

Two operations are expensive, and both are explicit, costed and cancellable: terrain enhancement on the GPU, and colour rendering on the CPU. Everything else in the workspace (drawing, panning, opening drawers, toggling overlays) is free.

Some honest relative figures:

• A section render is progressive, at 512, 1024 then 2048 px, and each pass writes a frame you can look at. Progress is weighted by pixel area, so the last pass is most of the bar.
• Flow routing, which the section render needs and the globe pass does not, takes roughly 1.5 to 2.3 s at the 4096 analysis grid, after a one-off numba warmup of about 1.3 s that is cached on disk.
• A whole-world colour pass renders every land tile: on the order of 20 to 40 renders on an Earth-like world at the default 3000 km tile size. Two tile renders run concurrently by default (LORESAT_GLOBE_RENDER_WORKERS overrides; 1 forces the serial loop).
• Re-compose globe re-renders only what changed, so it is proportional to the number of edited regions and tiles rather than to the planet.
• Per-tile diffusion multiplies the colour pass by a full terrain generation on every land tile.