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.js) 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 can add roles (Japan adds its statistics worker) through a build-time slot, 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 render worker 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 run on both backends. Transition anti-aliasing: 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.

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 a sphere by default. A WGS84 ellipsoid is available (?ell=1); 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][/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: 1° cells at three resolutions, 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.

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.

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.