ortho-earth Engine — Technical Overview

A map engine that draws everything on a sphere, in the browser, with no map server of its own
@ortho-earth/core · @ortho-earth/globe · WebGPU with a WebGL2 fallback · true-scale terrain · worker pipeline

1. Four Layers — Hard Core, Soft Apps

The engine is split so that the lower a part sits, the harder it is: guarded by test gates, type definitions and versions. Apps on top are shells and may change freely. New work starts by naming the layer it belongs to.

The rule that holds it together: core and globe never name a country. A machine gate (verify:regionless) counts region words in globe's code and fails if the count grows. The direction of imports is one-way — japan → globe → core → ephem and japan → jp → core; globe and jp never import each other. They meet only through the declaration that the app passes in.

2. Threads and Workers

The main thread holds the camera, input and DOM. Everything that decodes, builds or draws runs in workers. All workers start from one entry file (worker.ts) and are told their role by the Worker's name — so the bundler builds one worker graph, and shared code (the GeoPBF core, loaders.gl, the shaders) exists once, not once per worker.

A region pack starts its own workers from its own entry (Japan's statistics worker, estat-worker.ts in @ortho-earth/jp), so the host never knows about them. Cross-origin isolation is not required: with it, GeoPBF buffers travel to workers without copying (SharedArrayBuffer); without it, they are copied once. Every feature works either way, and a gate (verify:nocoi) checks that.

3. Backends — WebGPU First, WebGL2 Always

The core has two renderers with the same face — set, draw, dispose — one on WebGPU, one on WebGL2. The boot picks one at start:

WebGPU has three safety nets: an init failure falls back to WebGL2 inside the worker; a silent failure (initialised, but nothing reaches the screen) is caught by reading back the first frame; and if no frame arrives in 20 seconds the page restarts on WebGL2.

Two quality levers keep frames smooth. Transition anti-aliasing (WebGPU; WebGL2 fixes its anti-aliasing when the context is created): while the camera moves, frames are drawn at 1× MSAA; once it has been still for about half a second, one 4× frame is drawn. Dynamic resolution: when frames get slow, the canvas resolution steps down, and line widths stay constant on screen (both backends).

Text on the GPU (since 2.1): place names, road names, icons and road shields are baked into an SDF glyph atlas and drawn by WebGPU in the same frame as the map. Seen from straight above, text is drawn at its style layer's position, so a style that puts lines above its labels stacks as it does in MapLibre. On WebGL2 the engine falls back to Canvas2D text by itself; ?text=2d chooses it on WebGPU too.

4. Camera, Projection and Zoom

The camera is a small plain object — center, zoom, pitch, bearing — and the projection is one 4×4 matrix. Orthographic and perspective are one continuum: orthographic is perspective with the eye at infinite distance, so the projection is a slider, not a wall.

• Zoom means scale. The world is 256 px at z0; the same z is the same magnification everywhere. Latitude correction is not folded back into the camera.
• Floating point is kept honest. Absolute longitude and latitude never pass through 32-bit floats: meshes are drawn relative to a local origin (RTE), and the camera longitude is wrapped so it cannot drift across many turns of the globe.
• The globe is drawn as the WGS84 ellipsoid on ordinary desktops and as a sphere on low-memory and lower-tier devices (phones, integrated GPUs). Override it with the ellipsoid option or ?ell=1 / ?ell=0. Measurements (distance, area) always use the ellipsoid.
• Going underground fades to black instead of pushing the camera up — the camera is never moved behind your back.
• Flights (flyTo, easeTo, fitBounds) are plans evaluated in time; scene playback uses a virtual clock with a 35 ms step cap, so recordings on slow machines stay in sync.

The view lives in the URL — #zoom/lat/lon[/45t][/-30r][/15roll][/l=…][/c=theme][/t=UTC][/s=speed] — so the address bar is always a link to what you see.

5. Terrain at True Scale

Elevation is drawn without exaggeration. The heights come from AltPBF: tiles of three spans (1°, 10° and 90°), decoded in a worker and packed into two elevation atlases — a near atlas of fine cells around the camera, and a far atlas of coarse cells for the horizon. The shader reads one continuous height field from both.

• Hillshade, hypsometric tint and distant-mountain blue are computed on the GPU from the atlas.
• The basemap, rasters, vectors and buildings are all draped on the same field, so nothing floats or sinks.
• A region can declare that its elevation is a bare-earth model (DTM), which lets buildings be grounded on it.
• Any public raster-dem source (Terrarium, Mapbox, GSI encodings) can replace the built-in heights: map.setTerrain(…).

6. Basemaps, Rasters and the World Band

Below about z8, the globe draws the world on its own — Natural Earth 10 m countries, lakes, rivers and maritime boundaries, and a hypsometric tint computed every frame from global elevation and a climate field, so no raster tiles are downloaded. That is honestly as far as world data can carry.

Above that, a region takes over from the zoom its declaration names (Japan: z6.5, with the GSI vector basemap). Vector tiles go through the tile and scene workers; in tilted 3D views, a zoom-out keeps the finer tiles on screen while they still cover the ground, instead of swapping them for coarser ones. Tile formats are plugins on one registry: MVT is built in, and MLT (MapLibre Tile) comes from @ortho-earth/tile-formats, enabled at build time by aliasing #tile-formats to @ortho-earth/core/tileformats-mlt, which registers it — the decoder loads on the first MLT tile, so a map that never meets one pays nothing. A vector source says "encoding": "mlt" as in MapLibre; a PMTiles archive is recognised by its header.

Rasters — XYZ, WMS, WMTS, PMTiles, local GeoPackage/MBTiles, or one image by four corners — are first composited into a ground atlas, and the terrain shader samples that atlas per pixel. That is why a raster follows the slope of a mountain instead of lying flat across it. External MapLibre style.json files are converted into the same pipeline (map.setStyle).

7. Gint — Vectors You Can Ask Questions

Tiles are for drawing; Gint is for knowing. A Gint layer holds the whole geometry of a GeoPBF file on the GPU, so every feature can be picked, highlighted and joined to a table.

• Level of detail happens in the vertex shader. Each vertex carries a rank; the shader drops vertices below the rank the current zoom needs and snaps forward, so simplified shapes never open gaps.
• Polygons are filled with the stencil buffer (winding counts), so there is no triangulation step and shared borders stay exact.
• Picking is on the GPU, read back asynchronously; a JavaScript point-in-polygon fallback (smallest area wins) answers when the GPU cannot.
• Long edges bend with the terrain: in 3D, lines are subdivided on the GPU according to the terrain under them.

7.1 Column chunks — drawing without the topology pass

Gint's strengths cost a full pass before the first frame: shared arcs, ranks, degree anchors, a bake. For files you only want to look at, map.addColumnar(src) takes the other road (#90): GeoParquet row groups, or a GeoPBF cut into spatial chunks, are packed in a worker straight into GPU arrays (unit-sphere xyz relative to a chunk origin, earcut triangles, 2–3 grid-snapped LODs) and drawn by a same-frame overlay. Attributes stay columns; paint and filter (the Gint vocabulary) are evaluated in the worker into the same fid table Gint uses, so recolouring never rebuilds geometry. A dropped .parquet always takes this road; a .geopbf or .fgb does above columnarBytes (4 MB) — unless the reader's first chunk looks like a choropleth with long shared arcs (meta.share: admin1, administrative maps), which Gint draws better and keeps. The layer drapes on the terrain per vertex and is hidden by the scene depth; shared borders are drawn twice, and editing hands the data back to Gint.

8. 3D Meshes — Buildings, 3D Tiles, I3S, Models

One mesh core streams every kind of 3D data. It does not know which country the buildings belong to — the region only declares where the data is.

The path is the same for all: decode (Draco included) → Earth-centred coordinates → the ortho sphere → duplicate faces removed → grounded on the terrain → LOD → relative-to-origin vertices → a coverage mask that hides the basemap's own flat building footprints underneath. Decoded districts are kept in OPFS and IndexedDB in the form the GPU eats, so a second visit goes straight from disk to the GPU.

9. The Sky and the Shared Clock

Below about z5 the globe shows the sky: real stars, planets and the Moon, constellations, the ecliptic and the celestial equator, and the night side. Zooming out further leads into the solar system at real scale.

All of it follows one clock (map.clock, from @ortho-earth/ephem — the same clock the Solar System app uses). It runs in real time by default, and can be paused, fast-forwarded, run backwards or set to any moment between 1800 and 2049. The Sun's sub-solar point and sidereal time come from the same formulas in both apps, so the night side, the stars and the satellites always agree. The clock is shared with the render worker as one anchor — {sim, wall, rate} — sent only when its state changes.

10. The Public Face

import { createGlobe } from "@ortho-earth/globe";

const map = await createGlobe({ target: "#map", view: "#3/20/140" });
map.flyTo({ center: [139.767, 35.681], zoom: 14, pitch: 60 });

The shape of the API follows MapLibre where it can, so existing styles and habits carry over. Everything above is covered by gates that boot pages through the published package itself — what is tested is what you install. Since 2.0 the libraries are written in strict TypeScript and ship their type definitions (compiled .js + .d.ts on npm); the 1.x compatibility layers are gone — see MIGRATION.md.