# Ortho Earth
> Equal to all, fair to the Earth. This is the project for all people on the earth. The earth is round.
One true-scale Earth, for people and their AI agents. Ortho Earth reads the open data of the Earth in your own browser — on a round globe, at true scale, with no server, no account and no install. A map engine built from scratch (WebGPU with a WebGL2 fallback) draws government vector tiles straight onto the sphere, lifts real terrain, and raises 3D cities as you zoom in. Big data is drawn from GeoParquet, the intelligence layer (identify, topology, choropleths) is Gint, and nothing is exaggerated (terrain at real scale).
## Current facts
These numbers are generated from the source at each deploy, so they match the latest release. The same facts as JSON: [facts.json](https://www.ortho-earth.com/facts.json). All guides in one file: [llms-full.txt](https://www.ortho-earth.com/llms-full.txt).
- Latest release: 2.4.2 (2026-11-16) — `@ortho-earth/globe` 2.4.2, `@ortho-earth/core` 2.4.2, `@ortho-earth/cesium` 0.3.1. What changed: [CHANGELOG](https://github.com/kenjiyoshidahome2026-bit/ortho-earth/blob/main/CHANGELOG.md).
- MapLibre GL JS code: of 137 graded official examples (MapLibre GL JS 6.11.2), 91 draw the same picture, 43 give the same answers with a different picture, 3 run only in part, 0 do not run. Every example with its score: [/maplibre/](https://www.ortho-earth.com/maplibre/).
- CesiumJS code: of 304 compared Sandcastle examples (CesiumJS 1.146.0), 264 draw the same picture, 40 give the same answers with a different picture, 0 run only in part, 0 do not run. Every pair side by side: [/sandcastle/](https://www.ortho-earth.com/sandcastle/).
- License: the engine is GPL-3.0-or-later (a commercial license is available); the data formats and converters (geopbf, altpbf, geoedit, glbconv, native-bucket) are MIT.
- Browsers: WebGPU where the browser has it (desktop Chrome and Edge, Safari on macOS/iOS/iPadOS, Chrome on Android), WebGL2 otherwise. Shadows, ambient occlusion, clipping planes, atmospheric scattering and the post effects are WebGPU only.
## Made to work with AI agents
Ortho Earth is meant to be a map that AI coding agents can use well. What that means in practice:
- An agent already knows how to write it. The globe speaks the MapLibre GL JS and CesiumJS APIs that agents learned from years of public code, and every official example of both is graded on the globe (numbers above), so code an agent writes from memory runs.
- One request is enough. [Build with Ortho Earth](https://www.ortho-earth.com/start.md) is a recipe written for people and agents; every step is run by an automated test against the published npm packages, and an agent given only a one-paragraph request built and verified a working globe page on its first run. It ends with notes for agents (what to install, how to check the page works: `[boot] frame1 received` in the console).
- Nothing to sign up for. No API key, no account, no tile server: public data is read by the browser, so an agent can finish without asking you for credentials.
- The map says what it can do. `map.supports(key)` and `map.capabilities()` report what is built in, what a plugin adds and what is only accepted as a spec, so an agent can check instead of guessing. The packages ship TypeScript types (`globe.d.ts`, `maplibre.d.ts`).
- An MCP server answers instead of guessing. Add `https://www.ortho-earth.com/mcp` as a remote MCP server (Streamable HTTP, stateless; or run `npx -y @ortho-earth/mcp` for stdio): read-only tools for the current facts, the tested recipe, whether a MapLibre or CesiumJS example runs on the globe, API declarations from the published types, documentation search and links to a place on the globe. No key. Machine-readable sources it reads: [compat.json](https://www.ortho-earth.com/compat.json) (each official example's grade) and `/ref/*.ts` (the public types). It is a reference server for writing code with Ortho Earth; it does not drive a live map, render images or analyse data. Setup for Claude Code, Claude Desktop, Cursor and VS Code, and the tool list: [the endpoint itself](https://www.ortho-earth.com/mcp) (a plain GET returns the guide).
- Current facts in one fetch. This file, [llms-full.txt](https://www.ortho-earth.com/llms-full.txt) and [facts.json](https://www.ortho-earth.com/facts.json) are rebuilt from the source at every deploy, so the version and the compatibility numbers are never older than the site.
- Built that way, too. The developer wrote no code by hand: design and judgement are his, implementation and verification were done with an AI ([the story](https://www.ortho-earth.com/docs/introduction), Japanese).
## How it compares
Written by the developer of Ortho Earth, who has tried to say where the other engines are stronger. The articles below give the conditions and versions; the raw data of the benchmarks is public.
- Different starting points. MapLibre GL JS grew out of 2D cartography and is the strongest for expressive 2D maps. CesiumJS grew out of a 3D Earth with time; 3D Tiles came from Cesium, and it has the longest experience with them. TerriaJS is a finished data-viewing app built on Cesium. Navara pairs a Rust/WebAssembly GIS core with three.js rendering. Ortho Earth puts MapLibre's way of writing a map and Cesium's 3D Tiles, terrain and clock on one always-round globe, draws in a worker (OffscreenCanvas), and uses WebGPU first.
- One model of the Earth at every scale. From the whole planet to a street corner, the map is the same sphere seen by one camera; there is no second, flat mode to switch to. So countries keep their true size side by side, the shortest way between two places is drawn as the arc it really is ([great circle vs rhumb line](https://www.ortho-earth.com/globe/arcs)), terrain is never exaggerated, and when a flat world map is wanted it is Equal Earth, which keeps areas true ([how it is drawn](https://www.ortho-earth.com/docs/equal-earth)).
- Compatibility, not a rewrite. MapLibre and CesiumJS code runs on Ortho Earth unchanged, and the score of every official example is published next to the original (numbers above). Where the picture still differs, the gallery says so.
- Speed on phones (2026-11-11, PLATEAU Chiyoda LOD2 buildings, iPhone XS and Galaxy Tab A11+; MapLibre GL JS 6.17.0 + deck.gl 9.4.1, CesiumJS 1.147.0, Navara 0.3.1, Ortho Earth 2.4.1): Navara and Ortho Earth held the 60 fps screen limit in orbit and zoom on both devices, CesiumJS ran at 57/60 fps on the tablet, and MapLibre + deck.gl stayed below 60 fps in orbit. Navara was the steadiest of all. First display varied more with the network than between engines, so it is not ranked. The data set was small; the gain from WebGPU is not measured yet. [Article (Japanese)](https://www.ortho-earth.com/docs/story-benchmark-mobile-jp).
- Speed on desktops (2026-10-20, two Macs and an iPhone 16 Pro, Ortho Earth 2.0.2): every engine held 60 fps while moving except MapLibre + deck.gl on the M1 and the iPhone; first display tied among the leaders. [Article](https://www.ortho-earth.com/docs/story-benchmark).
- Features (2026-10-21, Ortho Earth 2.0.2; compatibility has grown since, see the numbers above): [Web map engines, feature by feature](https://www.ortho-earth.com/docs/story-features).
- Where Ortho Earth is behind. It is young (first commit April 2026) and made by one developer; see the next section for what that means in practice. It alone of these engines is GPL-3.0 (the others are BSD, Apache-2.0 or MIT), so a page that ships it falls under the GPL unless you take the commercial license. There is no native mobile SDK.
## Maintenance and continuity
Ortho Earth is made by one person. That is a real limit, and a fair evaluation should name it: there is no support contract, no team on call, and answers may not come fast. If you need an SLA, a product with a company behind it is the safer choice. What the project does instead is to be built so that it keeps working, and stays yours, whatever happens to its maker.
- Long-term maintenance. Few moving parts: no map server, no backend, and outside its own packages the core depends only on earcut and pmtiles. 345 automated checks run on every change, and the MapLibre and CesiumJS galleries are graded again as the engine changes. Every app built on 1.x runs on 2.x, every 2.x release has kept the same API, and 3.x is being planned on the same rule: code written for Ortho Earth keeps running.
- Vulnerabilities. Private reporting through GitHub with a reply within 7 days and a 90-day disclosure window ([SECURITY.md](https://github.com/kenjiyoshidahome2026-bit/ortho-earth/blob/main/SECURITY.md)). CodeQL scans every pull request; dependencies are updated monthly and new upstream versions wait 7 days before they are taken. There are no accounts and no server-side user data to leak: the map runs in the visitor's browser.
- Questions. One person answers, in English or Japanese, through GitHub issues. The documentation is also written to be read in one fetch ([llms-full.txt](https://www.ortho-earth.com/llms-full.txt)), so an AI agent can answer most questions on the spot.
- If the developer stops. The code is GPL-3.0-or-later (formats and converters MIT), so anyone may continue it; contributions are under a [CLA](https://github.com/kenjiyoshidahome2026-bit/ortho-earth/blob/main/CLA.md), so the rights stay clear. Nothing depends on the project's own servers: published npm packages and your own copies keep working. Data goes in and out in open, documented formats (the GeoPBF specification is MIT). And code written for it uses the MapLibre GL JS and CesiumJS APIs, so the way back to those engines is open from day one.
## Build with it
- [Build with Ortho Earth](https://www.ortho-earth.com/start.md): Step-by-step recipe for putting the globe in your own page — with Vite (npm `@ortho-earth/globe`) or without a bundler (npm `@ortho-earth/japan`). Written for people and AI coding agents; every step is run by an automated test against the published packages.
- [MapLibre GL JS examples on ortho-earth](https://www.ortho-earth.com/maplibre/): Ortho Earth is MapLibre GL JS compatible — `import * as maplibregl from "@ortho-earth/globe/maplibre"` runs existing MapLibre code on the globe (recipe section A8). The page lists all 139 official MapLibre GL JS examples running unchanged, each with its source (in the ortho-earth form), how closely it matches MapLibre, and a Run button.
- [MapLibre GL JS code on a 3D globe](https://www.ortho-earth.com/docs/from-maplibre): Change one import and MapLibre GL JS code runs on the globe — what carries over, the 139 official examples, and what works differently.
- [Coming from CesiumJS](https://www.ortho-earth.com/docs/from-cesium): Keep your CesiumJS code with npm `@ortho-earth/cesium` (CesiumJS 1.146's names, drawn on the globe), or move to the globe's own API — a table of CesiumJS features (3D Tiles, I3S, quantized-mesh terrain, glTF/GLB, the WGS84 ellipsoid, CZML, the clock) and how to write each one, with a live example per row.
- [CesiumJS Sandcastle on ortho-earth](https://www.ortho-earth.com/sandcastle/): CesiumJS's official Sandcastle examples, each run unchanged on real CesiumJS and on the globe and shown side by side; of the 304 compared, 264 draw the same picture and 40 give the same answers.
- [Coming from Leaflet](https://www.ortho-earth.com/docs/from-leaflet): npm `@ortho-earth/leaflet` gives an `L` like Leaflet 1.9's that draws on the globe — what is translated, what is not, and how to check a port.
- [Coming from Google Maps](https://www.ortho-earth.com/docs/from-google-maps): npm `@ortho-earth/gmaps` gives a `google.maps` on the globe with no Google key for the map; with your key, Geocoder, Directions, Places and Street View are relayed to Google.
- [Equal Earth on the GPU](https://www.ortho-earth.com/docs/equal-earth): How the Equal Earth world map is drawn — the projection in the shader, a central meridian that follows the view, and a morph from the globe.
## Apps
- [japan(demo)](https://www.ortho-earth.com/japan/?demo=1#5.2/36.2/137.8): A demo that draws everything with one camera — from Japan's city data (PLATEAU) to the Solar System, from flat maps to 3D maps.
- [Equal Earth](https://www.ortho-earth.com/globe/?start=equal): A scrolling Equal Earth world map with choropleths. Right-click any point to turn it into a 3D globe centered there.
- [World quiz](https://www.ortho-earth.com/quiz/): A geography quiz for kids and grown-ups: flags, capitals and where countries are on the 3D globe. Three levels, the whole world or one region, stars and badges — and the countries you miss come back until you know them.
- [geoedit](https://www.ortho-earth.com/japan/geoedit#5.1/38.2/136.9): A map editor. Draw and fix shapes on the 3D globe, and save them as GIS data.
- [Nations of the World](https://www.ortho-earth.com/world/): Basic data for the countries and territories of the world, as cards — facts, flag and anthem, Wikipedia and map.
- [Landforms of the World](https://www.ortho-earth.com/globe/physical): Mountains, rivers, lakes, seas and deserts of the world on a 3D globe — rank them, compare their heights and lengths, and overlay ocean currents, plate boundaries and climate zones.
- [National Parks of the United States](https://www.ortho-earth.com/globe/parks): All 63 national parks of the United States on a 3D globe — photos, the National Park Service's boundaries, facts and Wikipedia links.
- [World clock](https://www.ortho-earth.com/globe/clock): What time is it there? The local time of every time zone on a 3D globe, with daylight saving time and the night side — hover a place, or hold Shift for a whole country.
- [World population in hexagons](https://www.ortho-earth.com/globe/hex): Where the world's 8 billion people live, as hexagonal columns on a 3D globe (H3 cells, Kontur Population). Zoom in for finer hexagons, drop your own points to count them.
- [The shortest way is an arc](https://www.ortho-earth.com/globe/arcs): On a globe the shortest way between two places is a great circle. Arcs from anywhere to every capital, 37,000 air routes, great circle vs rhumb line, and your own CSV.
- [World earthquakes](https://www.ortho-earth.com/globe/quakes/): Reads USGS earthquake data directly and shows each quake in 3D by its energy and depth. It can also play year by year or month by month.
- [Satellites](https://www.ortho-earth.com/globe/sats): The current positions of satellites from CelesTrak data. Click a satellite to draw its orbit in 3D.
- [Clouds now](https://www.ortho-earth.com/globe/clouds#3.2/18/135): Infrared images from five geostationary weather satellites (Himawari, GOES, Meteosat), read straight from NASA GIBS and EUMETSAT and drawn in 3D over the globe.
- [ortho-solar](https://www.ortho-earth.com/solar/): The current positions of the planets and their moons — and a replay of how they move over time.
- [Daily calendar](https://www.ortho-earth.com/himekuri/): A Japanese tear-off calendar (lunisolar date, rokuyō, solar terms, holidays) with sunrise, sunset, twilight and the Moon for where you stand, computed with your elevation. Scroll a week without end; add your own iCal.
- [Make a video](https://www.ortho-earth.com/japan/scene#5.2/36.2/137.8): Cut out scenes of the 3D map and save or play them as one continuous video.
- [GeoPBF](https://www.ortho-earth.com/geopbf/): Drop a GIS file, check it on the globe, write it in another format — 18 formats in, 14 out. The file never leaves your machine.
- [MapLibre examples](https://www.ortho-earth.com/maplibre/): All 139 official MapLibre GL JS examples, run unchanged on the ortho-earth globe. Each card shows how closely it matches MapLibre; press Run to try it, or copy the code.
- [Sandcastle](https://www.ortho-earth.com/sandcastle/): The official CesiumJS Sandcastle examples, run unchanged on the Ortho Earth globe through its Cesium-compatible facade. Each card puts CesiumJS and Ortho Earth side by side, with how closely the pictures match.
- [Japan's open GIS data](https://www.ortho-earth.com/gishub-jp/): View and convert the open GIS data published in Japan.
- [census2020](https://www.ortho-earth.com/japan/census2020/#5.2/36.2/137.8): Drill down into Japan's 2020 census — small-area statistics, disaster risk zones and land parcels.
- [Yokohama digital twin](https://www.ortho-earth.com/yokohama/): A citizen-first digital twin of Yokohama: tap your home to see your school districts, nearest stations, flood risk and nearest evacuation site on one card. Walking distance from stations, facility search and hazard maps over PLATEAU 3D buildings, in 26 languages.
- [Kyoto digital twin](https://www.ortho-earth.com/kyoto/): A citizen-first digital twin of Kyoto on the same core as Yokohama: tap your home for nearest stations, flood and landslide risk and evacuation sites on one card. Temples, a history tour from 794 and PLATEAU 3D buildings, in 26 languages.
- [Fukuoka digital twin](https://www.ortho-earth.com/fukuoka/): A citizen-first digital twin of Fukuoka on the same core as Yokohama and Kyoto: tap your home for nearest stations, flood, storm-surge and tsunami risk and evacuation sites on one card. Hakata and Tenjin, a history tour from 57 AD and PLATEAU 3D buildings, in 26 languages.
- [Sapporo digital twin](https://www.ortho-earth.com/sapporo/): A citizen-first digital twin of Sapporo on the same core as Yokohama and Kyoto: tap your home for nearest stations, flood and landslide risk and evacuation sites on one card. Odori Park, a history tour from 1869 and PLATEAU 3D buildings, in 26 languages.
- [Satellite data (COG)](https://www.ortho-earth.com/japan/tellus): Satellite images (COG) on a server (Tellus), laid over the globe in 3D.
- [ortho-japan](https://www.ortho-earth.com/japan/#5.2/36.2/137.8): A map drawn only from Japan's public data. Try out the basic features.
- [National Parks of Japan](https://www.ortho-earth.com/japan/parks): All 35 national parks of Japan on a 3D globe — photos, the official boundaries, facts and Wikipedia links.
- [Hot springs of Japan](https://www.ortho-earth.com/japan/onsen): About 2,000 hot springs of Japan from Wikipedia on a 3D map, colored by spring type, with onsen districts, distant sources and member inns of the Japan Secluded Hot Spring Association.
- [Landforms of Japan](https://www.ortho-earth.com/japan/terrain): Mountains, volcanoes, rivers, lakes, plains, islands and seas of Japan on a 3D map, with their heights, lengths, areas and depths side by side.
- [GLB models](https://www.ortho-earth.com/japan/models): Landmarks such as Tokyo Tower, placed on the globe as GLB models. Download them in a range of 3D formats.
- [Fireworks over Sumida](https://www.ortho-earth.com/japan/fireworks): Full-scale fireworks (a 10-inch shell opens 320 m wide at 330 m) launched over the Sumida River, hidden by the buildings and Tokyo Skytree in front of them.
- [Statistics in 3D](https://www.ortho-earth.com/japan/?g=showcase/pop-density-2020.geopbf#7.6/35.3/139.1/62t/-25r): A 3D graph from the 2020 census — every municipality raised by its population density.
- [An old map of Edo](https://www.ortho-earth.com/japan/?iiif=/japan/showcase/edo-nihonbashi-1850.iiif.json#15.7/35.6895/139.778): A woodblock map of Nihonbashi from 1850, read as IIIF tiles straight from the National Diet Library and laid on today's Tokyo by its control points.
- [ortho-nl](https://www.ortho-earth.com/nl/): The Netherlands in 3D — PDOK 3D Basisvoorziening buildings standing on OpenStreetMap vector tiles and terrain. Hop between eight cities, from Delft to Maastricht.
## Formats and libraries
- [GeoPBF](https://www.ortho-earth.com/docs/geopbf): Compact binary format for geometry and an in-browser converter — 18 formats in, 14 out. npm `geopbf` (MIT).
- [Gint](https://www.ortho-earth.com/docs/gint): Shared-edge topology in a GPU-readable form (GPL-3.0-or-later).
- [AltPBF](https://www.ortho-earth.com/docs/altpbf): Elevation tiles in Protocol Buffers. npm `altpbf` (MIT).
- glbconv: GLB → glTF / OBJ / PLY / STL / USDZ / 3D Tiles in the browser. npm `glbconv` (MIT).
- `@ortho-earth/japan`: a 3D globe of Japan for any page with no bundler — GSI vector tiles and PLATEAU buildings in one self-contained bundle (GPL-3.0-or-later).
- geoedit: the GeoPBF editor — shapes edited on the sphere, large files in place. npm `geoedit` (MIT).
- `@ortho-earth/ephem`: planets, Moon and Sun 1800–2050, satellites (SGP4/SDP4) and the shared clock (GPL-3.0-or-later).
- native-bucket: Cloudflare R2/Workers ↔ IndexedDB bridge and cache for heavy binary data (MIT).
- `@ortho-earth/tile-formats`: lazily loaded decoders — MLT vector tiles and LAZ points for COPC (GPL-3.0-or-later).
- Add-ons for the globe: `@ortho-earth/react`, `@ortho-earth/google3d`, `@ortho-earth/ktx2`, `@ortho-earth/splat`, `@ortho-earth/scene`, `@ortho-earth/h3` (GPL-3.0-or-later).
Since 2.0 the libraries are written in TypeScript (strict) and ship their types; upgrading from 1.x: [MIGRATION.md](https://github.com/kenjiyoshidahome2026-bit/ortho-earth/blob/main/MIGRATION.md).
## Documentation
- [Docs](https://www.ortho-earth.com/docs/): Guides and reference for using and embedding the map engine.
- Release notes: Ortho Earth 2.4.1 (2026-11-11) are in the [CHANGELOG](https://github.com/kenjiyoshidahome2026-bit/ortho-earth/blob/main/CHANGELOG.md): `@ortho-earth/globe` and `core` 2.4.1; nearly caught up with CesiumJS (all Sandcastle examples run and give Cesium's answer; same picture 234 → 264), then measured on phones (60 fps on an iPhone XS and a Galaxy Tab A11+, [article in Japanese](https://www.ortho-earth.com/docs/story-benchmark-mobile-jp)); same API as 2.4.0.
- [Release notes: Ortho Earth 2.4](https://www.ortho-earth.com/docs/story-v240) (2026-11-09, [日本語](https://www.ortho-earth.com/docs/story-v240-jp)): `@ortho-earth/globe` and `core` 2.4.0; Android starts on WebGPU (checked on a 4 GB Mali-G615 tablet), faster start-up (progressive pipelines), lighter drawing while the camera moves (PLATEAU buildings, terrain), Unity 6 and Unreal Engine 5.6+ plugins and Minecraft worlds (Java, Bedrock, WorldEdit .schem; round trip through an anchored glTF), point clouds read by sheet with class filter; closer to CesiumJS (Sandcastle same picture 226 → 234 of 303, MapLibre examples kept at 91/43/3/0); same API as 2.3.
- [Release notes: Ortho Earth 2.3](https://www.ortho-earth.com/docs/story-v230) (2026-11-02, [日本語](https://www.ortho-earth.com/docs/story-v230-jp)): `@ortho-earth/globe` and `core` 2.3.0, `@ortho-earth/cesium` 0.2.0; closer to CesiumJS (Sandcastle same picture 226 of 303) and MapLibre GL JS (official examples 91/43/3/0 of 137); WebGPU screen-space reflections, contact shadows, height fog, light shafts, rain, toon; same API as 2.2. Also in [CHANGELOG](https://github.com/kenjiyoshidahome2026-bit/ortho-earth/blob/main/CHANGELOG.md) and on [GitHub Releases](https://github.com/kenjiyoshidahome2026-bit/ortho-earth/releases).
- [Release notes: Ortho Earth 2.2](https://www.ortho-earth.com/docs/release-2-2) (2026-10-31, [日本語](https://www.ortho-earth.com/docs/release-2-2-jp)): `@ortho-earth/globe` and `core` 2.2.0, new `@ortho-earth/cesium`, `@ortho-earth/leaflet` and `@ortho-earth/gmaps`; same API as 2.1. Also on [GitHub Releases](https://github.com/kenjiyoshidahome2026-bit/ortho-earth/releases).
- [Release notes: Ortho Earth 2.1](https://www.ortho-earth.com/docs/release-2-1): the MapLibre GL JS face.
## Source
- [GitHub repository](https://github.com/kenjiyoshidahome2026-bit/ortho-earth): Full source code (MIT / GPL-3.0-or-later).
---
# Full text
The pages linked above, copied as Markdown so that one fetch is enough. Each section names its source page.
## Build with Ortho Earth
Source: https://www.ortho-earth.com/start.md
A step-by-step recipe for putting the Ortho Earth globe in your own web page — written for people and for AI coding agents alike.
Every step below is checked by an automated test that installs the published npm packages into an empty project and runs them.
- No API key, no account, no server of your own. Public data is fetched by the visitor's browser and cached there.
- MapLibre GL JS compatible: existing MapLibre code runs on the globe by changing one import (A8).
- The globe draws with WebGPU and falls back to WebGL2 automatically.
- License: the engine is GPL-3.0-or-later (a commercial license is available: kenji.yoshida.home.2026@gmail.com). The data format `geopbf` is MIT.
There are two routes. Pick one.
| Route | Use it when | Package |
|---|---|---|
| **A. With Vite** (recommended) | You write JavaScript in a project with `npm` | `@ortho-earth/globe` — the whole world, extend with your data |
| **B. Without a bundler** | You only want to drop a map into an existing HTML page | `@ortho-earth/japan` — a prebuilt bundle with the Japan pack (GSI basemap, PLATEAU 3D buildings) |
---
### Route A — with Vite
Requirements: Node.js 20.19+ or 22.12+ (what the Vite that `npm create vite` installs needs).
#### A1. Create a project
```bash
npm create vite@latest my-globe -- --template vanilla --no-interactive
cd my-globe
npm install
npm install @ortho-earth/globe
```
#### A2. Tell Vite about the package's workers
Create `vite.config.js` in the project root:
```js
export default {
optimizeDeps: { exclude: ["@ortho-earth/globe", "@ortho-earth/core"] },
worker: { format: "es" },
};
```
The globe runs its drawing in Web Workers that live inside the package. Vite's dependency pre-bundling would move them away from their files, so these two packages must be excluded from it. Without this file `npm run dev` fails with "Could not load …?url".
#### A3. Replace `index.html` and `src/main.js`
`index.html`:
```html
My globe
```
`src/main.js` (the template's `src/counter.js`, `src/style.css` and `src/assets/` are no longer used — delete them if you like):
```js
import { createGlobe } from "@ortho-earth/globe";
const map = await createGlobe({ target: "#map", view: "#3/20/140" }); // "#zoom/lat/lon"
```
#### A4. Run it
```bash
npm run dev
```
Open the address it prints. You should see the Earth with the night side, stars at low zoom, and country borders.
`npm run build` writes a static site to `dist/` that you can host anywhere (it needs no special server headers).
#### A5. Add your own data
The layer API follows MapLibre GL JS.
```js
map.addSource("cities", {
type: "geojson",
data: {
type: "FeatureCollection",
features: [
{ type: "Feature", properties: { name: "Tokyo" }, geometry: { type: "Point", coordinates: [139.77, 35.68] } },
{ type: "Feature", properties: { name: "Seoul" }, geometry: { type: "Point", coordinates: [126.98, 37.57] } },
],
},
});
await map.addLayer({ id: "cities", type: "circle", source: "cities",
paint: { "circle-radius": 6, "circle-color": "#e4572e" } });
```
`data` can also be a URL of a GeoJSON file. Layer types: `fill`, `line`, `circle`, `symbol`, `fill-extrusion`, `heatmap`, `raster`, `hillshade`, `color-relief`.
Other formats (Shapefile, GeoPackage, FlatGeobuf, GeoParquet, KML, GPX …) are read with `geopbf` — `import { geopbf } from "@ortho-earth/globe"`.
Dropping a time-tagged `.czml` or `.gpx` file (or opening it with `?g=`) plays it on the shared clock (`map.clock`), like Cesium: the CZML `clock` sets the time range and speed.
#### A6. Clicks, popups, markers and the camera
```js
import { createGlobe, Marker, Popup } from "@ortho-earth/globe";
const popup = new Popup();
map.on("click", "cities", e => { // e.features, e.lngLat ({ lng, lat }), e.point ({ x, y })
popup.setLngLat(e.lngLat).setText(e.features[0].properties.name).addTo(map);
});
new Marker().setLngLat([139.77, 35.68])
.setPopup(new Popup().setText("Tokyo"))
.addTo(map);
await map.flyTo({ center: [139.77, 35.68], zoom: 12, pitch: 60 }); // resolves when the flight lands
```
Camera: `jumpTo`, `easeTo`, `flyTo`, `fitBounds`, `getCenter`, `getZoom`. Events: `map.on("move" | "settle" | "click" | "time", …)`.
#### A7. More
- 3D Tiles and I3S: `await map.add3DTiles(url)`, `await map.addI3S(url)`
- Your own terrain (`raster-dem`): `map.setTerrain({ source: { tiles: [url], encoding: "terrarium" } })`
- Raster tiles (XYZ, WMS, WMTS, PMTiles): `map.addSource(id, { type: "raster", tiles: [url] })` + a `raster` layer
- A MapLibre `style.json`: `createGlobe({ style: url })`
- Time: `map.clock` (night side, stars and satellites follow it)
- Analysis: `map.sunShadow()`, `map.viewshed()`, `map.lineOfSight(a, b)`
- Screen ⇄ map: `map.project([lng, lat])` → `{ x, y }`, `map.unproject([x, y])` → `{ lng, lat }` (or `null` off the globe)
- The country name that follows the mouse at low zoom: `createGlobe({ countryTip: false })` turns it off
- TypeScript definitions ship with the package (`@ortho-earth/globe/globe.d.ts`) — your editor picks them up by itself. The `map` API is the same in both routes. The engine overview is at https://www.ortho-earth.com/docs/core.html
#### A8. Already have MapLibre GL JS code?
Change one import. `@ortho-earth/globe/maplibre` is the MapLibre GL JS API — `Map`, `Marker`, `Popup`, `addProtocol`, the controls — drawn on the globe engine. Keep `vite.config.js` and `index.html` from A2 and A3 and put your MapLibre code in `src/main.js`:
```js
import * as maplibregl from "@ortho-earth/globe/maplibre";
const map = new maplibregl.Map({
container: "map",
style: "https://demotiles.maplibre.org/style.json",
center: [139.77, 35.68],
zoom: 4,
});
map.on("load", () => {
map.addSource("cities", {
type: "geojson",
data: { type: "FeatureCollection", features: [
{ type: "Feature", properties: { name: "Tokyo" }, geometry: { type: "Point", coordinates: [139.77, 35.68] } },
] },
});
map.addLayer({ id: "cities", type: "circle", source: "cities",
paint: { "circle-radius": 6, "circle-color": "#e4572e" } });
});
```
Zoom levels follow MapLibre's, so `zoom`, `minzoom`/`maxzoom` and tile levels mean the same as in your existing code. If you use MapLibre's controls, keep linking `maplibre-gl.css`.
All 139 official MapLibre GL JS examples run on it with their code unchanged — each one with its source, how closely it matches MapLibre, and a Run button: https://www.ortho-earth.com/maplibre/
---
### Route B — without a bundler
```bash
npm install @ortho-earth/japan
cp -R node_modules/@ortho-earth/japan/dist/lib public/lib
cp -R node_modules/@ortho-earth/japan/assets public/assets
```
`public/index.html`:
```html
```
Serve `public/` over HTTP (for example `npx serve public`) — opening the file directly (`file://`) does not work, because ES modules and workers need a server.
The `map` object has the same API as in Route A.
---
### Notes for AI coding agents
- Install from npm; do not load the engine from a CDN (`esm.sh`, `unpkg`). Its workers must come from the same origin as the page.
- Keep the `vite.config.js` of step A2 exactly. It is the most common cause of a blank page in `npm run dev`.
- Top-level `await` in `main.js` is fine.
- After each change, run the dev server, open the page, and check the browser console. A healthy start logs `[boot] frame1 received` and no errors.
- Coordinates are `[longitude, latitude]` in degrees (WGS84), as in GeoJSON.
- Zoom levels match web maps: the whole Earth is about z0–z2, a city about z12, streets z16+. Without a region pack the world data is honest up to about z8.
## Changelog (latest releases)
Source: https://github.com/kenjiyoshidahome2026-bit/ortho-earth/blob/main/CHANGELOG.md
### mcp 0.1.0 — 2026-11-11
**@ortho-earth/mcp 0.1.0** — new: an MCP server, so AI agents can look Ortho Earth up instead of guessing.
```
npx -y @ortho-earth/mcp # local (stdio)
https://www.ortho-earth.com/mcp # remote (Streamable HTTP)
```
- **Seven read-only tools, no key**: `get_facts` (version, packages, compatibility numbers), `get_started` (the tested
recipe), `check_compat` (how each official MapLibre GL JS and CesiumJS example runs on the globe), `lookup_api` (the
declaration from the published types), `search_docs`, `view_link` (a link to a place on the globe) and `list_apps`.
- **Always current**: answers come from files the site rebuilds on every deploy — `/facts.json`, `/llms-full.txt`,
`/start.md`, and new `/compat.json` and `/ref/*.ts`.
- Listed in the official [MCP Registry](https://registry.modelcontextprotocol.io/) as
`io.github.kenjiyoshidahome2026-bit/ortho-earth`. Setup for each client: [packages/mcp](packages/mcp/README.md).
### 2.4.2 — 2026-11-16
**@ortho-earth/globe 2.4.2 · @ortho-earth/core 2.4.2** (core has no changes; the two keep one version).
```
npm i @ortho-earth/globe@2.4
```
- **MapLibre shim: `map.remove()` now really stops the map.** A `map.on("render", fn)` listener started a
requestAnimationFrame loop that `remove()` never cancelled, so a removed map kept firing `render` every frame, and an
app that mounts and unmounts maps (deck.gl's `MapboxOverlay` listens to `render`) gained one endless loop per map.
`remove()` now cancels the loop, drops every listener after the `remove` event, detaches the DOM listeners on the
container and `window`, and discards queued calls; a map removed while still starting up destroys its engine as soon
as it exists and never fires `load`. Calling `remove()` twice is harmless.
- **Same API as 2.4.1.**
## MapLibre GL JS code on a 3D globe — change one import
Source: https://www.ortho-earth.com/docs/from-maplibre
Change one import @ortho-earth/globe/maplibre · Map · Marker · Popup · addProtocol · style.json · the controls
`@ortho-earth/globe/maplibre` is the MapLibre GL JS API drawn on the Ortho Earth globe engine (WebGPU with a WebGL2 fallback). Code you wrote for MapLibre keeps working; the map it draws is a round Earth with terrain at true scale, and the same map can also show 3D Tiles, I3S, glTF models and the sky.
### 1. The one line
```
import * as maplibregl from "@ortho-earth/globe/maplibre"; // was: from "maplibre-gl"
const map = new maplibregl.Map({
container: "map",
style: "https://demotiles.maplibre.org/style.json",
center: [139.77, 35.68],
zoom: 4,
});
map.on("load", () => {
map.addSource("cities", { type: "geojson", data: "cities.geojson" });
map.addLayer({ id: "cities", type: "circle", source: "cities",
paint: { "circle-radius": 6, "circle-color": "#e4572e" } });
});
```
Install with `npm i @ortho-earth/globe` and build with Vite. Zoom levels follow MapLibre's, so `zoom`, `minzoom`/`maxzoom` and tile levels mean the same as in your code. If you use MapLibre's controls, keep linking `maplibre-gl.css`. The full recipe, run by an automated test against the published package, is section A8 of [Build with Ortho Earth](https://www.ortho-earth.com/start.md).
### 2. The 139 official examples
Every official MapLibre GL JS example runs on the globe with its code unchanged — only the import is switched. The [MapLibre examples page](https://www.ortho-earth.com/maplibre/) shows each one with its source, a Run button, and how closely the picture matches MapLibre's. On the grading for 2.4.0 (9 November 2026), 91 draw the same picture, 43 give the same answers to queries, 3 run with visible differences, and none fail to run (2 have no MapLibre picture to compare with).
| Example | What it shows here |
| --- | --- |
| [3D terrain](https://www.ortho-earth.com/maplibre/examples/3d-terrain) | `setTerrain` with a `raster-dem` source, on the sphere |
| [Terrain from quantized-mesh tiles](https://www.ortho-earth.com/maplibre/examples/add-3d-terrain-from-quantized-mesh-tiles) | Cesium's terrain format, read directly |
| [Buildings in 3D](https://www.ortho-earth.com/maplibre/examples/display-buildings-in-3d) | `fill-extrusion` on the globe |
| [3D Tiles with three.js](https://www.ortho-earth.com/maplibre/examples/add-3d-tiles-using-threejs) | three.js drawn in the same frame as the map |
### 3. What works differently
- **Always a globe.** There is no flat Mercator mode: `projection` is read as globe whatever it says, and `renderWorldCopies` has nothing to copy. The flat world map of this project is [Equal Earth](https://www.ortho-earth.com/docs/equal-earth).
- **Drawing happens in a worker.** A custom layer passed as an object is drawn on top of the map; a custom layer with a `url` runs inside the render worker and is hidden by terrain and buildings. deck.gl's `MapboxOverlay` works as an overlay (`interleaved: true` falls back to overlaid).
- **For three.js, use `map.addThree({ module })`.** It draws inside the render worker with the map's camera, is hidden by terrain and buildings, and answers clicks. Your module imports `"three"` and `"three/addons/…"` as usual (three.js comes from jsDelivr by default; depth needs r180 or later). With `renderer: "webgpu"` it uses three's WebGPURenderer and, when the map runs on WebGPU, shares the GPU device and the depth (no per-frame copy). To move a MapLibre custom layer over unchanged, put it in a module and pass `url` and `three` (guide: THREE.md in the package).
- **More than MapLibre.** The same map takes 3D Tiles (`map.add3DTiles`), I3S, quantized-mesh terrain, glTF models, a shared clock with the night side and the stars, and analysis such as sun shadow and viewshed. Coming from CesiumJS too? See [From CesiumJS](https://www.ortho-earth.com/docs/from-cesium).
The ledger of every difference, kept as the work goes on, is `packages/globe/maplibre-compat.md` in the repository.
## Coming from CesiumJS — the same things in Ortho Earth
Source: https://www.ortho-earth.com/docs/from-cesium
The same things, written with Ortho Earth 3D Tiles · I3S · quantized-mesh terrain · glTF/GLB · WGS84 ellipsoid · CZML · the clock
Ortho Earth is a 3D globe map engine for the browser (WebGPU with a WebGL2 fallback) whose API follows MapLibre GL JS. Many of the things you do in CesiumJS have a counterpart here. This page lists them side by side: what you write in CesiumJS, what you write in Ortho Earth, and a page where you can see it running. All examples assume `const map = await createGlobe({ target: "#map" })` from `npm i @ortho-earth/globe`.
### Or keep your Cesium code
If you would rather not rewrite anything, `npm i @ortho-earth/cesium` gives a namespace with the same names as CesiumJS 1.146's. Everything that does not draw (math, time, `Camera`, `Entity`, CZML, GeoJSON and KML data sources, the clock, ion, the widgets) is Cesium's own code, unchanged; only `Viewer` and what it draws are replaced with the Ortho Earth globe. Only the import changes:
```
import * as Cesium from "@ortho-earth/cesium";
const viewer = new Cesium.Viewer("cesiumContainer");
const tileset = await Cesium.Cesium3DTileset.fromUrl("tileset.json");
viewer.scene.primitives.add(tileset);
await viewer.zoomTo(tileset);
```
The yardstick is CesiumJS's own 309 Sandcastle examples, run unchanged on real Cesium and on the globe and compared picture by picture: see them side by side at [/sandcastle](https://www.ortho-earth.com/sandcastle/). What is not drawn yet is reported once in the console as `[csshim] unsupported: …`, and `viewer.orthoMap` is the globe underneath. The tables below are for moving to the globe's own API instead.
### 3D data and terrain
| Topic | CesiumJS | Ortho Earth | See it |
| --- | --- | --- | --- |
| 3D Tiles | `await Cesium3DTileset.fromUrl(url)` + `scene.primitives.add(tileset)` | `await map.add3DTiles(url)` | [The Netherlands in 3D](https://www.ortho-earth.com/nl/) (PDOK 3D Basisvoorziening tileset) |
| I3S scene layers | `I3SDataProvider.fromUrl(url)` | `await map.addI3S(url)` | — |
| quantized-mesh terrain | `CesiumTerrainProvider.fromUrl(url)` | `map.setTerrain({ source: { type: "quantized-mesh", url: ".../layer.json" } })` | [quantized-mesh example](https://www.ortho-earth.com/maplibre/examples/add-3d-terrain-from-quantized-mesh-tiles) |
| Cesium ion terrain | `CesiumTerrainProvider.fromIonAssetId(id)` | `map.setTerrain({ source: { type: "quantized-mesh", ion: { assetId, accessToken } } })` | — |
| Ellipsoidal vs orthometric heights | heights above the ellipsoid | `heights: "ellipsoidal"` (default; a bundled EGM96 geoid turns them into elevations) or `"orthometric"` | — |
| Draping onto 3D Tiles / terrain | `new ClassificationPrimitive({ geometryInstances, classificationType: ClassificationType.CESIUM_3D_TILE })` / `GroundPrimitive` | `map.addClassification(geojson, { color, type: "tiles3d" })` (type `"both"` (default), `"terrain"` or `"tiles3d"`; lines become `width`-metre ribbons; the handle has `setStyle`, `setData`, `remove`) | — |
| Height on 3D Tiles / models | `scene.sampleHeightMostDetailed(cartos)` / `scene.clampToHeight(pos)` | `await map.sampleHeight([[lng, lat], …])` → `{ height, source: "tiles3d"\|"model"\|"terrain", id, featureId }` (misses fall back to terrain; tiles without feature IDs need `add3DTiles(url, { pickable: true })` to keep a CPU copy) | — |
| Polygon clipping | `new ClippingPolygonCollection({ polygons: [new ClippingPolygon({ positions })], inverse })` | `map.setClipping({ polygon: GeoJSON Polygon or ring array, inverse })` (removes the inside; `inverse: true` keeps only the inside; concave shapes OK; up to 64 vertices; combines with planes such as `vertical`). WebGL2 also clips terrain, buildings, models and the basemap (gint layers and overlays are WebGPU only) | — |
| Vertical exaggeration | `scene.verticalExaggeration = 3` | `map.setTerrainExaggeration(3)` or `map.setTerrain({ source, exaggeration: 3 })` (default 1 = true scale; buildings, models and labels on the terrain are lifted with the ground, their own heights are not stretched) | — |
| glTF / GLB models | `Model.fromGltfAsync({ url, modelMatrix })` | `await map.gadget.model(url, { at: [lon, lat], heading, scale })` — a `CESIUM_RTC` or ECEF placement in the file wins | [GLB models](https://www.ortho-earth.com/japan/models) |
| three.js in the scene | — | `map.addThree({ three, module })` — runs in the render worker, on the same camera, hidden by terrain and buildings | [3D Tiles with three.js](https://www.ortho-earth.com/maplibre/examples/add-3d-tiles-using-threejs) |
### The globe and the camera
| Topic | CesiumJS | Ortho Earth | See it |
| --- | --- | --- | --- |
| WGS84 ellipsoid | `Ellipsoid.WGS84` (always) | `createGlobe({ ellipsoid: true })` or `?ell=1`; `"auto"` (default) uses the ellipsoid on capable desktops. Measurements are always WGS84 | [Japan on the ellipsoid](https://www.ortho-earth.com/japan/?ell=1) |
| Fly the camera | `camera.flyTo({ destination })` | `map.flyTo({ center: [lon, lat], zoom, pitch, bearing })` | [Globe](https://www.ortho-earth.com/globe/) |
| Set the camera | `camera.setView({ destination, orientation })` | `map.jumpTo({ … })` or `map.setCamera({ lng, lat, height, heading, pitch, roll })` | — |
| Follow a moving object | `viewer.trackedEntity = entity` | `map.follow(target)` — a point, a function of time, or the id of a loaded CZML track | [Satellites](https://www.ortho-earth.com/globe/sats) |
| Look at a point | `camera.lookAt(target, offset)` | `await map.lookAt(target)` | — |
### Time
| Topic | CesiumJS | Ortho Earth | See it |
| --- | --- | --- | --- |
| The clock | `viewer.clock` | `map.clock` — one clock for the night side, the stars, satellites and timed data | [World clock](https://www.ortho-earth.com/globe/clock) |
| Clock range | `clock.clockRange = ClockRange.LOOP_STOP` | `map.clock.setRange(start, end, "loop")` — `"clamped"`, `"loop"`, `"unbounded"` (the CZML names are accepted too) | — |
| CZML | `CzmlDataSource.load(url)` | `const h = await map.loadCZML(url \| packets \| file)` (or drop a `.czml` file on the map): sampled positions play on `map.clock` with the same interpolation (ECEF, linear / Lagrange); points, billboards, labels and paths, `model` (static or moving; `orientation` as `unitQuaternion` or `velocityReference`, heading only), `polyline` (on the ground, or in 3D with height along great circles) and `polygon` / `rectangle` (color, outline, `extrudedHeight`) are drawn while available; the document clock is copied to the map clock. `h.remove()` clears it | [ortho-japan](https://www.ortho-earth.com/japan/) (drop a file) |
| Sun and shadows | `viewer.shadows = true` | `await map.sunShadow({ mode: "instant" })` or `"duration"` (hours of shadow) | — |
| Visibility analysis | — | `map.viewshed()` · `map.lineOfSight(a, b)` | — |
### What works differently
- **The API is MapLibre-shaped.** Sources and layers, `style.json`, `setPaintProperty` and `queryRenderedFeatures` work as in MapLibre GL JS. If you also know MapLibre, see [From MapLibre GL JS](https://www.ortho-earth.com/docs/from-maplibre).
- **Drawing happens in a worker.** The map is drawn on an OffscreenCanvas in a render worker, so your own drawing joins through `map.overlay(module)`, `map.addThree()` or a custom layer with a `url`.
- **No server, no account.** The engine reads public data directly; there is no token unless the data you read needs one.
- **The flat world map is Equal Earth**, not Web Mercator. See [Equal Earth on the GPU](https://www.ortho-earth.com/docs/equal-earth).
The full list of methods is in the package's type definitions (`@ortho-earth/globe/globe.d.ts`) and the [engine overview](https://www.ortho-earth.com/docs/core). Step-by-step setup is in [Build with Ortho Earth](https://www.ortho-earth.com/start.md).
## Coming from Leaflet — your Leaflet code on the 3D globe
Source: https://www.ortho-earth.com/docs/from-leaflet
Your Leaflet code on the 3D globe `npm i @ortho-earth/leaflet @ortho-earth/globe`
`@ortho-earth/leaflet` gives you an `L` namespace shaped like Leaflet 1.9's. Its maps, tile layers, markers, popups, vector layers and GeoJSON draw through MapLibre GL: either on the Ortho Earth globe (`@ortho-earth/globe/maplibre`) or on the real `maplibre-gl`. Code written for Leaflet keeps its shape; only the import changes. Leaflet's stylesheet is not needed.
```
// on the globe
import L from "@ortho-earth/leaflet/globe";
const map = L.map("map").setView([35.6812, 139.7671], 15);
L.tileLayer("https://tile.openstreetmap.org/{z}/{x}/{y}.png", { maxZoom: 19, attribution: "© OpenStreetMap" }).addTo(map);
L.marker([35.6812, 139.7671]).addTo(map).bindPopup("Tokyo Station ").openPopup();
L.geoJSON(parks, { style: f => ({ fillColor: f.properties.kind === "park" ? "green" : "gray" }) }).addTo(map);
```
`@ortho-earth/leaflet/globe` also has Leaflet's named exports (`map`, `tileLayer`, `marker`, …), so a bundler alias ports a whole app without touching its imports:
```
// vite.config.js
export default { resolve: { alias: { leaflet: "@ortho-earth/leaflet/globe" } } };
```
To keep a flat map, give it `maplibre-gl` instead: `createLeaflet(maplibregl, { style })` from `@ortho-earth/leaflet`, and `installGlobal(L)` for scripts and plugins that read `window.L`.
### What is translated
| Leaflet | On the globe |
| --- | --- |
| `L.map` and its options, `setView`, `flyTo`, `fitBounds`, `panTo`, point conversions, handlers (`map.dragging.disable()` …) | the camera. **Zoom is shifted by one** (Leaflet zoom z = MapLibre zoom z − 1, 256 px vs 512 px tiles). `fitBounds` uses Leaflet's own arithmetic, so a port lands on the same zoom. Rotation and tilt stay off unless you ask for them (`rotate: true`) |
| Map events (`click`, `move`, `zoomend`, `popupopen` …) | MapLibre events with Leaflet's event object (`latlng`, `containerPoint`, `layerPoint`). A path's mouse event reaches its groups and then the map, as in Leaflet |
| `L.tileLayer` (`{s}`, `{r}`, `tms`, your own `{keys}`, `maxNativeZoom`, `bounds`, `opacity`), `L.tileLayer.wms`, `L.GridLayer` with `createTile` | raster sources; a `GridLayer`'s canvas or ` ` tiles are drawn through a protocol |
| `L.marker`, `L.icon`, `L.divIcon`, popups and tooltips (`bindPopup`, `bindTooltip`, `permanent`, `sticky`, `direction`) | MapLibre markers and popups, placed where Leaflet places them. The default icon is Leaflet's blue pin as SVG, no image files to serve |
| `L.polyline`, `L.polygon`, `L.rectangle`, `L.circle` (metres), `L.circleMarker` (pixels), `setStyle`, `toGeoJSON` | one GeoJSON source per pane, like Leaflet's one renderer per pane, so 10,000 features cost one source |
| `L.geoJSON` (`style`, `pointToLayer`, `onEachFeature`, `filter`), `L.layerGroup`, `L.featureGroup` | one layer per feature, as in Leaflet |
| `L.imageOverlay`, `L.videoOverlay` | image and video sources |
| `L.control.zoom`, `attribution`, `scale`, `layers`, `L.Control.extend`; panes (`createPane`, `zIndex`) | controls in MapLibre's corners; panes become the order of the layers |
| `L.Class`, `L.Evented`, `L.Util`, `L.DomUtil`, `L.DomEvent`, `L.latLng`, `L.latLngBounds`, `L.CRS` … | plain values and helpers, so plugins built on `L.Class.extend` load |
### What is not
- **Other CRSs** (`L.CRS.Simple`, EPSG:4326 maps): the globe is drawn in WGS84, and a flat MapLibre map in Web Mercator.
- **The SVG and DOM inside vector layers**: `path.getElement()` returns null (a path is a MapLibre feature), and plugins that draw into Leaflet's panes or renderers, such as marker clustering or Leaflet.draw, do not draw.
- HTML `GridLayer` tiles, `detectRetina`, and the `zoomanim` event.
### Checking a port
Anything the namespace does not translate is reported once in the console as `[lfshim] unsupported: …`; it never throws. `L.unsupportedReport()` lists them, so you can check a port just by running it. For anything else, `map.getMapLibre()` returns the map underneath, and on the globe that map also has everything in [the engine](https://www.ortho-earth.com/docs/core): terrain, 3D Tiles, the shared clock and the night side.
The test suite runs the Leaflet calls above against the real globe (`npm run verify:ui -- t-leaflet` in `packages/globe`). Unlike [MapLibre](https://www.ortho-earth.com/maplibre/) and [CesiumJS](https://www.ortho-earth.com/sandcastle/), there is no gallery of Leaflet's own examples yet, so the tables on this page are the list of what is covered.
Coming from other libraries? See [From Google Maps](https://www.ortho-earth.com/docs/from-google-maps), [From MapLibre GL JS](https://www.ortho-earth.com/docs/from-maplibre) and [From CesiumJS](https://www.ortho-earth.com/docs/from-cesium).
## Coming from Google Maps — your Google Maps code on the 3D globe
Source: https://www.ortho-earth.com/docs/from-google-maps
Your Google Maps JavaScript API code on the 3D globe `npm i @ortho-earth/gmaps @ortho-earth/globe`
`@ortho-earth/gmaps` gives you a `google.maps` namespace. Its `Map`, `Marker`, `InfoWindow`, shapes and `Data` draw through MapLibre GL: either on the Ortho Earth globe (`@ortho-earth/globe/maplibre`) or on the real `maplibre-gl`. Code written for Google Maps keeps its shape; only the import changes. The map itself needs no Google API key and sends nothing to Google.
```
// on the globe
import google from "@ortho-earth/gmaps/globe"; // { maps }
const map = new google.maps.Map(document.getElementById("map"), { center: { lat: 35.6812, lng: 139.7671 }, zoom: 15, tilt: 45 });
const marker = new google.maps.Marker({ map, position: { lat: 35.6812, lng: 139.7671 }, title: "Tokyo Station" });
const info = new google.maps.InfoWindow({ content: "Tokyo Station " });
marker.addListener("click", () => info.open({ map, anchor: marker }));
map.data.loadGeoJson("/parks.geojson");
map.data.setStyle(f => ({ fillColor: f.getProperty("kind") === "park" ? "green" : "gray" }));
```
Code that loads the API with `@googlemaps/js-api-loader` can take the `Loader` from `@ortho-earth/gmaps/globe` instead, and `google.maps.importLibrary("maps" | "marker" | "places" | …)` works too. To keep a flat map, give `createGoogleMaps(maplibregl, { styles })` a MapLibre style per map type; `installGlobal(maps)` sets `window.google.maps` for code that reads the global.
### What is translated
| Google Maps | On the globe |
| --- | --- |
| `Map` options and methods (`center`, `zoom`, `heading`, `tilt`, `restriction`, `moveCamera`, `panTo`, `fitBounds`, `controls[ControlPosition]` …) | the camera. **Zoom is shifted by one** (Google zoom z = MapLibre zoom z − 1, 256 px vs 512 px tiles). `mapTypeId` and `mapId` pick a MapLibre style |
| Map events (`click`, `idle`, `bounds_changed`, `zoom_changed`, `dragend` …) | MapLibre events with Google's event object (`latLng`, `pixel`, `stop()`). A click on a marker or a clickable shape is not also a map click, as in Google Maps |
| `Marker` (`icon` as URL, `Icon` or `Symbol`, `label`, `draggable`), `marker.AdvancedMarkerElement`, `marker.PinElement` | MapLibre markers with Google's red pin, your image, or the SVG symbol |
| `InfoWindow` (`content`, `headerContent`, `pixelOffset`, `open({ map, anchor })`) | a MapLibre popup above the marker, following it when it moves |
| `Polyline`, `Polygon` (holes), `Circle`, `Rectangle`, `MVCArray` paths, `geodesic`, `zIndex` | GeoJSON line and fill layers; editing the path redraws it, and `geodesic` follows the great circle |
| `Data` (`addGeoJson`, `loadGeoJson`, `setStyle` as an object or a function, `overrideStyle`, feature events) | one GeoJSON source; each feature's style is evaluated into its properties |
| `LatLng`, `LatLngBounds`, `MVCObject`, `MVCArray`, `event.*`, `geometry.spherical`, `geometry.encoding`, `geometry.poly` | plain values; the geometry library is computed on a sphere of radius 6,378,137 m, as Google does |
### Google's services, with your key
The services that live on Google's servers need your own key: `createGlobeMaps({ apiKey, language, region })`, `maps.setApiKey(key)`, or `new Loader({ apiKey })`. The key is sent only to `*.googleapis.com`, and Google's terms and billing apply to these calls. Without a key the methods answer `REQUEST_DENIED` and the map keeps working.
| Google Maps | Relayed to |
| --- | --- |
| `Geocoder.geocode` | Geocoding API |
| `DirectionsService.route`, `DirectionsRenderer`, `DistanceMatrixService` | Routes API (the renderer draws the route and lettered markers on the map, and the steps in its panel) |
| `ElevationService` | Elevation API |
| `places.PlacesService`, `places.AutocompleteService`, `places.Autocomplete` | Places API (New) |
| `StreetViewService.getPanorama`, `StreetViewPanorama` | Street View metadata and Static APIs: a still image that turns when dragged. Google does not publish its panorama tiles outside its own API, so there is no smooth 360° view |
### What is not
- **Google's JSON map styling** (`styles: [{ featureType, … }]`) and cloud-based styles: give MapLibre styles by map type or `mapId` instead.
- Editable or draggable shapes, `Polyline.icons`, marker animations, `overlayMapTypes`, `MVCObject.bindTo`, and the map type, Street View and rotate controls.
### Checking a port
Anything the namespace does not translate is reported once in the console as `[gmshim] unsupported: …`; it never throws. `google.maps.unsupportedReport()` lists them, so you can check a port just by running it. For anything else, `map.getMapLibre()` returns the map underneath, and on the globe that map also has everything in [the engine](https://www.ortho-earth.com/docs/core): terrain, 3D Tiles, the shared clock and the night side.
The test suite runs the calls above against the real globe (`npm run verify:ui -- t-gmaps` in `packages/globe`), and every service against a stand-in for Google's servers. Unlike [MapLibre](https://www.ortho-earth.com/maplibre/) and [CesiumJS](https://www.ortho-earth.com/sandcastle/), there is no gallery of Google's own samples yet, so the tables on this page are the list of what is covered.
Coming from other libraries? See [From Leaflet](https://www.ortho-earth.com/docs/from-leaflet), [From MapLibre GL JS](https://www.ortho-earth.com/docs/from-maplibre) and [From CesiumJS](https://www.ortho-earth.com/docs/from-cesium).
## Equal Earth projection on the GPU — an interactive world map
Source: https://www.ortho-earth.com/docs/equal-earth
An interactive world map in the Equal Earth projection equal-area · WebGPU with a WebGL2 fallback · central meridian follows the view · morph from the globe
A globe shows only half of the Earth at a time. For the whole Earth on one sheet, Ortho Earth uses the **Equal Earth** projection (Šavrič, Patterson and Jenny, 2018): an equal-area pseudocylindrical projection, so every country is drawn at its true relative size. You can try it at [/equal/](https://www.ortho-earth.com/equal/), or open the globe on its Equal Earth side at [/globe/?start=equal](https://www.ortho-earth.com/globe/?start=equal).
### 1. The projection in the shader
The world data (Natural Earth 10m borders, coasts, lakes, rivers and cities, read as Gint) is sent to the GPU once, in longitude and latitude. The projection itself is in the shader: the vertex stage turns each point into Equal Earth coordinates every frame. The same formulas run on the CPU only for the camera (the center, the anchor under the pointer, and the smallest zoom).
```
// Equal Earth (unit sphere). θ = parametric latitude, Δλ = longitude minus the central meridian
sin θ = (√3 / 2) · sin φ
y = θ · (A1 + A2·θ² + θ⁶·(A3 + A4·θ²))
x = Δλ · cos θ / ((√3 / 2) · (A1 + 3·A2·θ² + θ⁶·(7·A3 + 9·A4·θ²)))
// A1 = 1.340264, A2 = −0.081106, A3 = 0.000893, A4 = 0.003796
```
Both backends draw the same picture: WebGPU by default, WebGL2 when WebGPU is not there, compared against each other on a real GPU.
### 2. The central meridian follows the view
The central meridian is always the longitude at the center of the screen. Longitude enters the projection only as Δλ, the difference from that center, so when you scroll sideways the map is projected again around the new center: it goes on east and west without a seam, and the place you are looking at is always where the projection distorts least. Zoom and scroll never show empty space outside the map's outline.
### 3. A morph from the globe
In the globe pages, the Equal Earth map opens out of the globe you are looking at. Its first frame is the same globe, with the same camera, matched to the pixel; the sphere then unfolds into the Equal Earth sheet in a little over a second, and the map data loads while it moves. Right-click a point on the globe and choose to center the world map there; going back folds the sheet into a globe at your current view. Both run in the same page and share one engine, so nothing is loaded twice.
### 4. On the map
- Country and city names in 26 languages.
- Choropleths from the world ledger, or from your own CSV joined by country.
- Relief (GEBCO) and climate (Köppen) layers.
Coming from another library? See [MapLibre GL JS code on a 3D globe](https://www.ortho-earth.com/docs/from-maplibre) and [Coming from CesiumJS](https://www.ortho-earth.com/docs/from-cesium).
## ortho-earth Engine Overview
Source: https://www.ortho-earth.com/docs/core
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](https://www.ortho-earth.com/docs/core#layers)
2. [Threads and Workers](https://www.ortho-earth.com/docs/core#threads)
3. [Backends — WebGPU First, WebGL2 Always](https://www.ortho-earth.com/docs/core#backend)
4. [Camera, Projection and Zoom](https://www.ortho-earth.com/docs/core#camera)
5. [Terrain at True Scale](https://www.ortho-earth.com/docs/core#terrain)
6. [Basemaps, Rasters and the World Band](https://www.ortho-earth.com/docs/core#basemap)
7. [Gint — Vectors You Can Ask Questions](https://www.ortho-earth.com/docs/core#gint)
8. [3D Meshes — Buildings, 3D Tiles, I3S, Models](https://www.ortho-earth.com/docs/core#mesh)
9. [The Sky and the Shared Clock](https://www.ortho-earth.com/docs/core#time)
10. [The Public Face](https://www.ortho-earth.com/docs/core#api)
### 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.
| Role | What it does |
| --- | --- |
| `render` | Owns the canvas. Draws globe, terrain, basemap scene, rasters, gint layers, labels and overlays in one frame with one camera. |
| `ortho:tile` / `ortho:scene` | Tile fetch and build / scene merge (the basemap pipeline). |
| `mesh` / `meshdecoder` | Streams large 3D meshes (buildings) — decode, dedup, ground, LOD, persist to OPFS/IndexedDB. |
| `model` | glTF/GLB, extrusions, 3D Tiles and I3S content; also sun-shadow and viewshed analysis. |
| `gintbake` | Bakes gint layers (LOD ranks, edges) off the render thread. |
| `ortho:height` | Decodes elevation tiles. |
| `rastertiles` / `imagequad` | Serves raster tiles from local GeoPackage/MBTiles, or from an image pinned by four corners. |
| `columnar` | Reads and packs column-chunk layers (GeoParquet, chunked GeoPBF) for `map.addColumnar`. |
| `vtdraw` / `vtextrude` | MapLibre fill / line / circle / symbol layers and fill-extrusions on vector sources. |
| `iiif` / `copc` | Georeferenced IIIF map images baked into tiles / COPC point clouds read by range. |
| `decoder:*` / `encoder:*` / `geopbf:*` | GeoPBF format conversion (dropped files, exports). |
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:
| Condition | Backend |
| --- | --- |
| `?gl2=1` | WebGL2 (manual escape hatch) |
| no `navigator.gpu` | WebGL2 directly |
| Android | WebGL2 (silent black-screen faults on some mobile GPU drivers) |
| Safari / WebKit, on a page that declares `glOverlay: true` | WebGL2 (a WebGL2 overlay over WebGPU is not composited there) |
| a previous WebGPU start failed in this tab | WebGL2 (once: the next boot only; twice: for the rest of the tab session; `?gpu=1` retries) |
| otherwise | **WebGPU** |
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](https://www.ortho-earth.com/docs/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](https://www.ortho-earth.com/docs/gint) is for knowing. A Gint layer holds the whole geometry of a [GeoPBF](https://www.ortho-earth.com/docs/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](https://github.com/kenjiyoshidahome2026-bit/ortho-earth/issues/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.
| Source | How it enters |
| --- | --- |
| City buildings (Japan's PLATEAU, the Netherlands' 3D Basisvoorziening (PDOK)) | per-district loads declared by the region pack |
| Any 3D Tiles tileset | `map.add3DTiles(url)` — screen-space-error traversal, b3dm / i3dm / pnts / cmpt / glb |
| I3S scene layers | `map.addI3S(url)` — decoded with loaders.gl |
| glTF / GLB models | dropped files, `?g=` links or `map.model(src, { at, heading, scale, slot })` — several side by side (one per `slot`); the handle moves, turns, scales and lifts the model afterwards (`setLngLat / setHeading / setScale / setAltitude`, no re-bake: the batches get a rigid transform, grounding follows the new spot) and `gizmo(true)` shows drag handles for placing by hand — a dropped model shows them at once |
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 });
```
| Area | Examples |
| --- | --- |
| Camera | `jumpTo` · `easeTo` · `flyTo` · `fitBounds` · `cameraForBounds` · `setMaxBounds` |
| Style and layers | `setStyle` · `addSource` / `addLayer` · `setPaintProperty` · `setFilter` · `queryRenderedFeatures` |
| 3D and terrain | `add3DTiles` · `addI3S` · `setTerrain` · extrusions · models |
| Analysis | `sunShadow` · `viewshed` · `lineOfSight` · profiles · measurement |
| Time | `map.clock` · `map.on("time")` |
| Extending | `map.overlay(module)` — your own canvas drawn in the render worker in the same frame, with the same camera and `api.time` · `addProtocol` · `transformRequest` · `Marker` / `Popup` |
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](https://github.com/kenjiyoshidahome2026-bit/ortho-earth/blob/main/MIGRATION.md).
## GeoPBF Technical Overview
Source: https://www.ortho-earth.com/docs/geopbf
Protocol Buffers-based geospatial binary format. Lightweight · Universal converter · ArrayBuffer-native — the wire format for browser GIS
1. [Why GeoPBF?](https://www.ortho-earth.com/docs/geopbf#why)
2. [Binary Format Structure](https://www.ortho-earth.com/docs/geopbf#format)
3. [Delta Encoding × Varint](https://www.ortho-earth.com/docs/geopbf#delta)
4. [GIS Conversion Hub](https://www.ortho-earth.com/docs/geopbf#hub)
5. [Antimeridian Handling](https://www.ortho-earth.com/docs/geopbf#antimeridian)
6. [ArrayBuffer & Worker Architecture](https://www.ortho-earth.com/docs/geopbf#worker)
7. [Gint Extension — 64-bit Coordinate Packing](https://www.ortho-earth.com/docs/geopbf#gint)
8. [Comparison with Other Formats](https://www.ortho-earth.com/docs/geopbf#comparison)
9. [API Reference](https://www.ortho-earth.com/docs/geopbf#api)
10. [Map Library Integrations](https://www.ortho-earth.com/docs/geopbf#integrations)
11. [Untrusted HTML & Sanitizing](https://www.ortho-earth.com/docs/geopbf#security)
12. [COG — Rasters, the Same Way](https://www.ortho-earth.com/docs/geopbf#cog)
13. [PMTiles & GeoParquet — the Way Out](https://www.ortho-earth.com/docs/geopbf#convert)
### 1. Why GeoPBF?
GeoJSON is readable and convenient, but has critical limitations at scale. As a text format it is expensive to transfer, slow to parse, and blocks the browser's main thread. Shapefile is widely adopted but its multi-file structure is ill-suited for the Web. Tiled MVT fragments data by zoom level, increasing round-trip overhead.
GeoPBF is a binary format designed as the **communication layer for browser GIS**. Protocol Buffers compression efficiency, coordinate delta-encoding, and an ArrayBuffer-native design make transfer, decoding, and inter-Worker handoff uniformly fast.
### 2. Binary Format Structure
A GeoPBF file consists of two parts: a **Header Section** and a **Body Section (FARRAY)**.
| Field | Tag | Type | Description |
| --- | --- | --- | --- |
| GTYPE | 8 | Varint | 0:Point 1:MPoint 2:Line 3:MLine 4:Poly 5:MPoly 6:Collection |
| LENGTH | 9 | Packed Varint | Vertex counts for rings and multi-part geometries |
| COORDS | 10 | Packed SVarint | Delta-compressed coordinate stream X₀,Y₀,ΔX₁,ΔY₁,... (see below) |
| INDEX | 12 | Packed Varint | Indices into the global KEYS dictionary |
| VALUE | 11 | Repeated Message | NULL/BOOL/INTEGER/FLOAT/STRING/DATE/COLOR/FUNC/JSON/BBOX/BLOB/IMAGE — one field per message, numbered by type |
| GARRAY | 13 | Message | GeometryCollection members as nested GEOMETRY messages |
Details a reader must know (all in the [wire specification](https://github.com/kenjiyoshidahome2026-bit/geopbf/blob/main/pbf%20spec.md)): the delta chain restarts at (0,0) for every ring, polygon rings omit the closing vertex, a `Multi*` with one member is written as the singular type, `BUFS` entries are individually raw-DEFLATE compressed, `COLOR` is used only for the canonical `rgb()`/`rgba()` strings, and `DATE` has second precision.
Metadata such as NAME, DESCRIPTION, and LICENSE is stored independently in the header, allowing direct binary-slice writes without touching the feature body. Renaming a dataset or updating license information on a multi-gigabyte file completes instantly, with no re-encoding required.
### 3. Delta Encoding × Varint
Storing coordinates as floating-point text like GeoJSON means the longitude `139.7412345` alone costs 11 bytes. GeoPBF reduces this in two stages.
The coordinate difference between adjacent vertices is typically just a few hundred metres, so after integer scaling the delta values are small. Varint encodes small integers in fewer bytes, giving GeoPBF a property that is ideal for geographic data: **denser vertex clusters compress more aggressively**.
A GeoJSON `"coordinates":[139.741234,35.681234]` pair is roughly 30 bytes (text). GeoPBF's delta-Varint representation costs 8 bytes for the first vertex and **2–3 bytes** for every subsequent one. Across the three datasets measured in §8.1 that is a **75–92% reduction** against raw GeoJSON. Layering gzip via `CompressionStream` removes a further 18–29% — comparatively little, precisely because the redundancy gzip looks for has already been squeezed out by the encoding.
### 4. GIS Conversion Hub
GeoPBF is not merely a storage format — it acts as a **conversion hub** among major GIS formats, with a decoding (import) path for every format and an encoding (export) path for most of them. Placing GeoPBF at the center enables any-to-any format conversion in a single step.
| Format | Read | Write | Notes |
| --- | --- | --- | --- |
| **GeoJSON** | ✓ | ✓ | File / Blob / Object all accepted |
| **Shapefile** | ✓ (.zip) | ✓ (.zip) | Multi-file bundle handled as a single .zip |
| **KMZ / KML** | ✓ | ✓ | Google Earth compatible |
| **GML** | ✓ | ✓ | OGC standard |
| **GPX** | ✓ | ✓ | GPS tracks & waypoints |
| **FlatGeoBuf** | ✓ | ✓ | Streaming-friendly binary |
| **TopoJSON** | ✓ | ✓ | Topology-preserving I/O |
| **NDJSON** / GeoJSON Text Sequence | ✓ | — | one feature per line (`.ndjson .geojsonl .geojsons .jsonl`); `geopbf/ndjson` streams it in. No built-in writer |
| **CZML** (Cesium) | ✓ | ✓ | time-sampled positions kept as `time` arrays; the rest of the packet round-trips in a `czml` property |
| **GeoPackage** | ✓ | — | dependency-free SQLite reader, one layer (`{ layer }`); `geopbf/gpkg` also opens tile tables |
| **SpatiaLite** | ✓ | — | `.sqlite .sqlite3 .spatialite .db`; same reader, SpatiaLite BLOB geometry |
| **File Geodatabase** | ✓ (.zip) | — | Esri `.gdb` folder zipped; detected by `*.gdbtable` inside the archive, `{ layer }` picks the table |
| **CSV / TSV / XLSX** | ✓ | ✓ | lon/lat columns or a WKT column (`{ lon, lat, wkt, sheet, delimiter }`); export: `pbf.getCSV()` (attributes + lng/lat for points, bbox otherwise) and `geopbf/encodeXLSX` |
| **DXF** | ✓ | — | AutoCAD DXF with `{ crs, unitScale, closedAsPolygon }`; JGD plane-rectangular zones via `geopbf/proj` |
| **MOJ 登記所備付地図** | ✓ (.zip) | — | Japanese cadastral parcels; JGD2011 plane-rectangular (19 zones) → WGS84 on decode. Opt in with `{ format: "moj" }`, since the extension is also `.zip` |
| **GeoParquet** (v1.5) | ✓ | ✓ | WKB + bbox covering column, spatially ordered rows. Dependency-free reader accepts geopandas / pyarrow / DuckDB output — §13 |
| **PMTiles** (MVT) (v1.5) | — | ✓ | Tiles are cut from Gint, so per-zoom simplification is a rank filter — §13. No inverse: tiles are simplified and quantized |
| **GeoPBF** | ✓ (native) | ✓ (native) | Native fast-load |
| **Gint** | ✓ (decode) | ✓ (encode) | Morton + VW extension (see §6) |
Every row with a ✓ under *Read* goes through the auto-detecting entry point `geopbf(input)` (GeoParquet included; the dependency-free reader lives in `geopbf/geoparquet`). PMTiles writing is large enough to be worth loading on demand, so it lives behind its own subpath export (`geopbf/pmtiles`) and is covered in §13. Rasters travel a separate path again: `geopbf/cog` reads Cloud Optimized GeoTIFF by HTTP Range without converting it at all (§12). Much of this also has a CLI equivalent — `npx geopbf enc / dec / pmtiles / parquet / parquet2pbf / gpkg2pbf / spatialite2pbf / dxf2pbf / csv2pbf / gdb2pbf` — running on plain Node with no GDAL.
Whatever you pass to `geopbf(input)` — a `File`, `Blob`, `ArrayBuffer`, or plain `Object` — the library auto-detects the format from the file extension, MIME type, or magic bytes and routes to the correct decoder. Accepted: `.geopbf .pbf .geojson .json .topojson .ndjson .geojsonl .geojsons .jsonl .fgb .gpkg .sqlite .sqlite3 .spatialite .db .parquet .geoparquet .csv .tsv .xlsx .zip .kml .kmz .gpx .gml .xml .czml .dxf`, each optionally `.gz` (gzip is recognised by signature, not extension). The caller never has to think about format. A `.zip` is looked into: `*.gdbtable` means File Geodatabase, otherwise Shapefile; the one exception is the MOJ cadastral archive, whose `.zip` extension collides with both and so is selected with `{ format: "moj" }`. A `File` that cannot be decoded raises an explicit error rather than silently yielding an empty FeatureCollection.
```
// Any format, the same API
const pbf = await geopbf(file); // File (Shapefile .zip, GeoJSON, KMZ ...)
const pbf = await geopbf(arrayBuffer); // ArrayBuffer (fetch response, etc.)
const pbf = await geopbf(geojsonObject); // GeoJSON object directly
const pbf = await geopbf(zip, { format: "moj" }); // cadastral .zip — plane-rectangular → WGS84
// Export to any format (each *File() encodes in a worker and resolves to a File)
const geojson = pbf.geojson; // → GeoJSON object (synchronous)
const topojson = pbf.topojson(); // → TopoJSON (topology-preserving, needs { gint: true })
const shp = await pbf.shapeFile(); // → Shapefile (.zip)
const kmz = await pbf.kmzFile(); // → KMZ
const gml = await pbf.gmlFile(); // → GML (also gpxFile, czmlFile, geojsonFile, topojsonFile)
const fgb = await pbf.fgbFile(); // → FlatGeobuf
// v1.5 — the two large formats, behind their own subpath exports (§13)
import { toPMTiles } from "geopbf/pmtiles";
import { toGeoParquet, fromGeoParquet } from "geopbf/geoparquet";
const { buffer } = await toPMTiles(pbf, { maxZoom: 12 }); // → PMTiles (MVT) bytes
const pq = await toGeoParquet(pbf); // → { buffer, geo, stats }
const { pbf: back } = await fromGeoParquet(u8); // ← GeoParquet, incl. geopandas/DuckDB output
// Save as native .geopbf (gzip-compressed)
const file = await pbf.geopbfFile(); // → File ".geopbf" (pbf.save() stores to the bucket instead)
```
### 5. Antimeridian Handling
The antimeridian (±180° longitude) is a well-known trap in geographic data. A polygon that straddles it — for example a geometry spanning the Bering Sea — is stored as a single ring in most formats, with coordinates jumping from +179° to −179°. Renderers, spatial indexes, and clipping operations all break silently on such data.
GeoPBF treats antimeridian correctness as a **format invariant**: every geometry stored in GeoPBF is guaranteed to be antimeridian-cut. No straddling polygon can exist inside the format. The one opt-out is `new GeoPBF({ cut: false })`, for a container that must round-trip shapes unchanged (geoedit's session save).
`setFeature()` calls `antimeridianFeature(q)` on every feature before writing it to the buffer — regardless of the source format. GeoJSON, Shapefile, KMZ, GML, GPX, FlatGeoBuf, TopoJSON — all go through the same path. The caller never needs to pre-process geometries.
#### 5.1 Spherical Great-Circle Intersection
The cut is not a naive ±180° coordinate clamp. `antimeridianCut()` computes the precise latitude at which each crossing segment intersects the antimeridian using the spherical formula — essential near the poles where meridian convergence is significant. After cutting, each sub-polygon is a valid closed ring with vertices inserted at the exact intersection latitude.
```
// Crossing detection: sign change + span > 180° means antimeridian crossing (not date line jump)
// p[i][0] * p[i+1][0] 180
// Spherical intersection latitude (great-circle formula)
// x = sin(lat0−lat1)·sin(avgLng)·cos(halfDeltaLng) - sin(lat0+lat1)·cos(avgLng)·sin(halfDeltaLng)
// z = cos(lat0)·cos(lat1)·sin(Δlng)
// intersectLat = atan2(x, |z|) ← geometrically exact on the sphere
```
Morton codes require coordinates in a bounded domain. A geometry that straddles ±180° would produce Morton codes that jump across the entire integer space, breaking binary search and spatial proximity guarantees. By cutting at encode time, all Morton codes in a GeoPBF tile are spatially coherent with no special-casing needed downstream.
### 6. ArrayBuffer & Worker Architecture
GeoPBF's internal representation is consistently an `ArrayBuffer`. This is a deliberate design choice for deep integration with the browser's parallel processing layer (Web Workers), yielding three important properties.
#### 6.1 Transferable — Zero-Copy Transfer
```
// ArrayBuffer moves from main thread → Worker with zero copy
// (ownership transfer, not a copy — no extra memory consumed)
worker.postMessage(pbf.arrayBuffer, [pbf.arrayBuffer]);
// After transfer pbf.arrayBuffer is detached (main thread can no longer access it)
// Worker side
onmessage = ({ data: buf }) => {
const view = new DataView(buf); // begin decoding immediately
postMessage(result, [result]); // return zero-copy
};
```
#### 6.2 SharedArrayBuffer — Concurrent Multi-Worker Reads
```
// Expand decoded gint coordinate data into a SharedArrayBuffer
// → multiple render Workers can read concurrently with no copies
const sab = new SharedArrayBuffer(buf.byteLength);
new Uint8Array(sab).set(new Uint8Array(buf));
// N tile workers run LOD filter + draw in parallel
tileWorkers.forEach(w => w.postMessage({ sab, zoom, viewport }));
```
#### 6.3 CompressionStream — Native gzip
```
// On save: browser-native gzip (no external library needed)
let blob = new Blob([buf]);
blob = await (new Response(
blob.stream().pipeThrough(new CompressionStream("gzip"))
)).blob();
postMessage(new File([blob], `${name}.geopbf`, { type: "application/x-geopbf" }));
```
GeoJSON is an object graph (JSON). Before a Worker can touch it you need `JSON.stringify` → transfer → `JSON.parse` — a full serialize/deserialize cycle that costs hundreds of milliseconds on large datasets. GeoPBF is an `ArrayBuffer` from the very start, so it moves between Workers via **zero-copy transfer**, and the receiver decodes by advancing a pointer. The main thread is never blocked.
### 7. Gint Extension — 64-bit Coordinate Packing
Applying gint encoding to GeoPBF packs each vertex's coordinates into a **single 64-bit integer** that simultaneously stores both the Morton code and the VW weight.
Packing **where (Morton)** and **which LOD (VW rank)** into a single 64-bit integer means both spatial queries and LOD filtering reduce to simple integer arithmetic.
```
// L1 / L2 check (most-significant bit)
const isAnchor = (code >> 63n) === 1n;
// Extract Morton code (L2: bits 6-62; the low 6 bits of the snapped grid are zero)
const mortonCode = code & 0x7FFFFFFFFFFFFFC0n; // bits 6-62
// Extract VW weight rank (L2: lower 6 bits)
const vwRank = Number(code & 0x3Fn); // bits 0-5 → 0–63
// LOD filter at zoom z (rank threshold corresponding to 1px²)
const minRank = rankFromZoom(z); // lower threshold at higher zoom (more vertices)
const visible = isAnchor || vwRank >= minRank;
```
### 8. Comparison with Other Formats
#### 8.1 Measured File Size
Three public datasets of different shape and scale, each converted and measured end to end on one machine. Every row holds the same features; sizes are decimal MB.
| Format | NE 10m admin_0 countries, v5.1.1 | KSJ N03 (2026) Japanese municipalities | TIGER 2024 ZCTA5 US ZIP code areas |
| --- | --- | --- | --- |
| features | 258 | 125,130 | 33,791 |
| vertices | 548,469 | 15,669,416 | 51,258,797 |
| coordinate grid | 10⁻⁶° (0.11 m) | 10⁻⁶° (0.11 m) | 10⁻⁵° (1.1 m) |
| **Shapefile** (.shp+.dbf+.shx) | 9.7 | 282.8 | 825.3 |
| └ +.prj, zipped −9 | 4.9 | 174.8 | 530.5 |
| **GML** (.xml) | — | 580.7 | — |
| └ + gzip −9 | — | 123.2 | — |
| **GeoJSON** | 13.3 | 579.6 | 1,089.6 |
| └ + gzip −9 | 4.7 | 138.6 | 265.8 |
| **FlatGeobuf** | 9.3 | 266.9 | 826.8 |
| └ + gzip −9 | 5.4 | 156.3 | 421.9 |
| **GeoParquet** (WKB, zstd, bbox) | 4.5 | 124.5 | 333.7 |
| **GeoPBF** | 3.3 | 48.6 | 117.8 |
| **GeoPBF + gzip −9** (distribution form) | **2.7** | **34.4** | **95.2** |
Per vertex, raw → compressed. This is where the formats separate:
| Bytes per vertex | NE 10m admin_0 | KSJ N03 | TIGER ZCTA5 |
| --- | --- | --- | --- |
| Shapefile | 17.7 → 9.0 | 18.1 → 11.2 | 16.1 → 10.3 |
| GeoJSON | 24.2 → 8.6 | 37.0 → 8.8 | 21.3 → 5.2 |
| FlatGeobuf | 17.0 → 9.8 | 17.0 → 10.0 | 16.1 → 8.2 |
| GeoPBF | 6.0 → 4.9 | 3.1 → 2.2 | 2.3 → 1.9 |
Both spend 16–18 bytes per vertex, for the same reason: two IEEE-754 doubles per point, whatever the geometry looks like. The spread between them is record headers and attribute encoding, not coordinates — two decades of format design separate the two, and the geometry section did not move. GeoPBF stores a delta on an integer grid instead, so its cost *falls* with vertex density: 2–3 bytes per vertex on a boundary sampled every few metres, more on sparse geometry with many attribute columns.
Gzipped against gzipped, GeoPBF is 1.8–4.0× smaller than GeoJSON — not the 5–17× the raw rows suggest, and every format here is normally shipped compressed. Compression does most of its work on text (GeoJSON keeps 24–36% of its bytes, GML 21%), a fair amount on the double-based binaries (shapefile 51–64%, FlatGeobuf 51–59%: consecutive coordinates share the high-order bytes of their doubles, even though the low mantissa bits are incompressible noise), and least on GeoPBF (71–82%), which has already removed by construction the redundancy the compressor goes looking for. The uncompressed rows are what a decoder walks through in memory; the compressed rows are what crosses the network.
Reproduce with `npx geopbf enc` and `npx geopbf parquet`; the FlatGeobuf rows use the official `flatgeobuf` npm writer on the same features, and the zipped-shapefile row is .shp+.dbf+.shx+.prj packed at deflate −9 so that all three datasets are measured the same way — the shipped archives differ in what else they carry (Natural Earth 4.9 MB with an HTML README, TIGER 528.8 MB with ISO metadata XML, KSJ N03 803.2 MB with GML *and* shapefile *and* GeoJSON in one archive) and are not directly comparable. The shapefiles hold the original full-precision doubles, but a shapefile spends a fixed 16 bytes per point whatever the precision, so its size rows are unaffected.
#### 8.2 Capability Matrix
| Metric | GeoJSON | Shapefile | MVT (tiles) | GeoPBF |
| --- | --- | --- | --- | --- |
| **Encoding** | Text UTF-8 | Binary (multi-file) | PBF binary | PBF + delta + Varint |
| **File count** | 1 | .shp + .dbf + .shx + … | zoom × tile count | 1 |
| **Transfer efficiency** | Low (large text) | Medium | Medium (zoom-split) | High (binary + gzip) |
| **Worker transfer** | JSON serialize required | Conversion required | ArrayBuffer | ArrayBuffer zero-copy |
| **LOD support** | None | None | Per-zoom files | VW weight built-in |
| **Spatial index** | None | .shx (linear) | Tile coords | None in the file (Morton 64-bit built in memory on load) |
| **Format conversion** | External library needed | External library needed | Limited | 18 read formats built-in |
| **Topology** | None | None | None | Arc sharing · boundary integrity |
### 9. API Reference
```
// ── Load ───────────────────────────────────────────────
const pbf = await geopbf(input, options);
// input: File | Blob | ArrayBuffer | GeoJSON object | URL string
// options: { name, gint, nocache, clean }
// gint: false → skip topology encode (gint conversion)
// nocache: true → bypass IndexedDB cache and re-fetch
// clean: true → run topology integrity clean pass
// worker: false → decode on the calling thread (automatic in Node, where there is no Worker)
// ── Data access ────────────────────────────────────────
pbf.length // feature count
pbf.keys // attribute name array ['name', 'rank', ...]
pbf.arrayBuffer // raw ArrayBuffer (for Worker transfer; set(ArrayBuffer) transfers it to the decoder worker)
pbf.geojson // convert to GeoJSON FeatureCollection
pbf.topojson() // convert to TopoJSON (topology-preserving; needs Gint)
pbf.getFeature(i) // decode only the i-th feature (getGeometry / getProperties / propsRow likewise)
pbf.contain([lng, lat]) // smallest polygon containing the point (fid or null)
pbf.identifyAt(lng, lat, opts) // point / line / polygon hit test, radii in metres
// ── Export ─────────────────────────────────────────────
await pbf.save() // store to the configured bucket (createGeopbf(apiBase, { bucket }))
await pbf.geopbfFile() // .geopbf File (geojsonFile / topojsonFile / shapeFile / kmzFile / gpxFile / czmlFile / gmlFile / fgbFile)
await pbf.preview(canvas) // thumbnail drawn in a worker (OffscreenCanvas / ImageBitmap)
// ── O(1) metadata update ───────────────────────────────
pbf.name('New Name'); pbf.description('...'); pbf.license('MIT'); // or pbf.updateHeader({ … })
// ── Lower-level entry points (package subpaths) ────────
// geopbf GeoPBF class (new GeoPBF(opts).set(…)) geopbf/core · /pbf-base GeoPBFBase, the container without extension methods
// geopbf/pbf protobuf wire read/write geopbf/gint · /topology · /identify Gint baking, GintBUF, hit tests
// geopbf/pmtiles · /geoparquet · /parquet · /spatial-order writers and readers (§13) geopbf/tilesource on-demand MVT from the Gint
// geopbf/convert every converter in one import geopbf/convert/gpu the WebGPU device the converters use
// geopbf/gpkg · /sqlite · /spatialite · /mbtiles · /filegdb · /fgb · /dxf · /table · /ndjson format readers, usable without the auto-detecting entry
// geopbf/proj · /epsg · /datum WKT / EPSG projections, TKY2JGD / PatchJGD datum shifts geopbf/convert/node-gint Gint from Node
// geopbf/cog · /cog/core · /cog/source · /cog/tiff · /cog/decode · /maplibre-cog · /leaflet-cog Cloud Optimized GeoTIFF (§12)
// geopbf/featureservice ArcGIS FeatureServer / OGC API – Features as a source geopbf/georef IIIF Georeference Annotation
// geopbf/edit · /edit/* the editing model (DOM-free) geopbf/worker · /no-builtin-workers the worker entry and its opt-out
// geopbf/sanitize · /czml · /gzip · /encodeZIP · /decodeZIP · /encodeXLSX · /fname2mime utilities
```
2.0 removes what 1.x kept for compatibility: the `noeval` option (FUNC values always stay source strings), `validate: "legacy"` (falls back to `"lenient"`), `closeFilter(f)` (use `cloneMap({ filter: f })`), the static `GeoPBF.concatinate` (use `pbf.concat(...others)`), and the name `GeoPBF` for the container in `geopbf/core` and `geopbf/pbf-base` (it is `GeoPBFBase` there; `GeoPBF` from `geopbf` is the full class). Internal fields such as `fmap` and `_name` are no longer in the published types: use `pbf.length`, `each` / `forEach` and `pbf.name()`. The library itself is now TypeScript (strict): the npm package ships the compiled JavaScript with `.d.ts` declarations, so `geopbf` and its subpaths are typed without extra packages. Every change, old → new: [MIGRATION.md](https://github.com/kenjiyoshidahome2026-bit/ortho-earth/blob/main/MIGRATION.md) (in Japanese).
### 10. Map Library Integrations (v1.1)
Since v1.1.0 the npm package ships ready-made adapters for the major web map libraries. None of them import the host library — each is a **zero-dependency subpath export** built on one shared loader: whole-file gzip is detected by magic bytes, decoding never runs `new Function` (FUNC values stay source strings, so it is CSP-safe; the only mode since 2.0), and properties are mapped to be JSON-safe (`Date` → ISO string, bbox → plain array, binary values dropped) so they survive each library's worker handoff.
| Import | Shape | For |
| --- | --- | --- |
| `geopbf/maplibre` | addProtocol handler (GeoJSON source, or vector tiles with `/{z}/{x}/{y}`) | MapLibre GL JS (v4+) |
| `geopbf/leaflet` | L.GeoJSON subclass | Leaflet (1.x) |
| `geopbf/openlayers` | VectorSource loader factory | OpenLayers (6+) |
| `geopbf/loaders` | loaders.gl Loader object | deck.gl · kepler.gl |
| `geopbf/load` | plain `loadGeopbf(url)` | Cesium · D3 · anything that eats GeoJSON |
```
// ── MapLibre — protocol source ─────────────────────────
import { geopbfProtocol } from "geopbf/maplibre";
maplibregl.addProtocol("geopbf", geopbfProtocol);
map.addSource("rail", { type: "geojson", data: "geopbf://https://…/N02-25_RailroadSection" });
map.addSource("rail-tiles", { type: "vector", tiles: ["geopbf://https://…/N02-25_RailroadSection/{z}/{x}/{y}"] }); // same URL + /{z}/{x}/{y} = on-demand MVT from the Gint (seamless shared borders, feature.id = fid)
// ── Leaflet — layer plugin ─────────────────────────────
import { extendLeaflet } from "geopbf/leaflet";
extendLeaflet(L);
L.geoPBF("geopbf://https://…").on("load", e => console.log(e.meta)).addTo(map);
// ── OpenLayers — source loader ─────────────────────────
import { makeGeopbfLoader } from "geopbf/openlayers";
const source = new VectorSource({ loader: makeGeopbfLoader(url, new GeoJSON()) });
// ── deck.gl — loaders.gl ───────────────────────────────
import { GeoPBFLoader } from "geopbf/loaders";
new GeoJsonLayer({ data: url, loaders: [GeoPBFLoader] });
// ── Everything else — plain loader ─────────────────────
import { loadGeopbf } from "geopbf/load";
const r = await loadGeopbf(url); // { geojson, name, license, attribution, minZoom, maxZoom, … }
viewer.dataSources.add(await Cesium.GeoJsonDataSource.load(r.geojson));
```
Attribution travels inside the file (§2), and the adapters honor it: Leaflet and OpenLayers wire the header's `attribution` into the map credit automatically (an explicit option wins), and `loadGeopbf` hands back all header metadata for manual wiring. One contract to know: with MapLibre, write the inner URL **absolute** (`geopbf://https://…`, pmtiles-style) — MapLibre normalizes source URLs through `new URL()`, which corrupts relative forms.
### 11. Untrusted HTML & Sanitizing (v1.2)
GeoPBF is an open format: anyone can produce a file and hand you a URL. Display properties — `@tip`, `@pop`, or any property your viewer renders as HTML — must therefore be treated as **untrusted input**. A crafted file could otherwise run script in your page (XSS) the moment a tooltip or popup opens. The rule is the classic one: sanitize at the *output* boundary, right before the string reaches `innerHTML` — never assume a file was cleaned upstream, because files reach viewers without passing through any editor.
```
// Sanitize at the output boundary — right before innerHTML
import { sanitizeHTML } from "geopbf/sanitize";
el.innerHTML = sanitizeHTML(feature.properties["@pop"]);
```
`sanitizeHTML` is a dependency-free allowlist filter: formatting tags, lists, tables, images and links pass through; `script`, `iframe`, `svg` and the like are dropped with their content; unknown tags are unwrapped, keeping their children; event handlers and `style` never survive. `href` accepts `http(s)`/`mailto`, `img src` accepts `http(s)`/`data:image`, and every link gets `target="_blank" rel="noopener noreferrer"`. It touches the DOM only when called, so importing it in a worker is safe. Note the division of labor with §10: `sanitizeProperties` makes values *JSON-safe* (types), `sanitizeHTML` makes them *display-safe* (markup). Use both.
### 12. COG — Rasters, the Same Way (v1.4)
A COG (Cloud Optimized GeoTIFF) is a static file read by HTTP Range requests — the same no-server philosophy as GeoPBF, applied to rasters. v1.4's `geopbf/cog` is a hand-written reader with zero new dependencies: the header is fetched in **one 64 KB range request**, tile requests are sorted and adjacent ranges **coalesced into a single request**, decode and reprojection run in a worker pool, and JPEG/WebP tiles go straight to the browser's native decoder. `cog.metrics()` reports the numbers at any time (range requests, coalesce ratio, decode time).
```
import { openCog } from "geopbf/cog";
const cog = await openCog("https://…/TCI.tif"); // header in one range request
const bm = await cog.renderXYZ(14, x, y); // ImageBitmap, warped to Web Mercator
```
The supported subset follows what public COG feeds actually serve: tiled and stripped layouts, BigTIFF, compression none/deflate/LZW/JPEG/WebP, predictor 2, uint8 RGB(A)/palette/single-band uint16/int16/float32 (auto percentile stretch, `GDAL_NODATA` → transparent), CRS lon/lat (EPSG:4326/4258/4269/4612/6668), 3857, UTM (WGS84 326xx/327xx, JGD 6688–6691 / 3097–3101) and the Japanese plane-rectangular zones I–XIX (6669–6687 / 2443–2461), through the same hand-written Krüger n-series as `geopbf/proj` (nm accuracy). Anything outside fails with an explicit error pointing to `gdal_translate -of COG`. One line each for MapLibre (`cog://` protocol via `geopbf/maplibre-cog`) and Leaflet (`geopbf/leaflet-cog`). The CLI prints structure and measured numbers: `npx geopbf cog info --bench`.
### 13. PMTiles & GeoParquet — the Way Out (v1.5)
Through v1.4 the hub read formats. v1.5 opens the other direction: a GeoPBF leaves as a **PMTiles** archive of Mapbox Vector Tiles or as a **GeoParquet** file, and a GeoParquet comes back in. Still no new dependencies — in fact `pako` was *removed*. Every codec now goes through the platform (`CompressionStream` in browsers and workers, `node:zlib` in Node), leaving `pbf` as the only runtime dependency — and 1.6 dropped that one too, by bringing the protobuf wire reader/writer in-house. The dependency list is now empty.
```
# CLI — plain Node, no native build
npx geopbf pmtiles countries.geopbf countries.pmtiles --maxzoom 10
npx geopbf parquet countries.geopbf countries.parquet
npx geopbf parquet2pbf countries.parquet back.geopbf # and back again
```
```
import { toPMTiles } from "geopbf/pmtiles";
import { toGeoParquet } from "geopbf/geoparquet";
const pbf = await geopbf(file, { gint: true });
const { buffer, stats } = await toPMTiles(pbf, { maxZoom: 12 }); // stats.engine → "gpu" | "cpu"
const pq = await toGeoParquet(pbf); // pq.buffer, pq.geo
```
**Tiles are cut from Gint, not from the raw features.** That is the same derived buffer ortho-earth draws on the GPU: a shared border exists once, as a single arc, and every vertex carries its Visvalingam–Whyatt rank. Per-zoom simplification is therefore a `rank >= threshold` filter, which means two neighbouring polygons are necessarily reduced to the *identical* vertex list — no slivers, no gaps, at any zoom. The thresholds are calibrated per arc against a Douglas–Peucker decomposition, so vertex counts land within roughly 10 % of tippecanoe's while *which* vertices survive is still decided by rank, keeping both sides of a border in step.
On Natural Earth 10m countries (258 polygons, 480k vertices, z0–10, 4-core Node) that is **about 6.5 s from GeoJSON** for 573,896 tiles / 151.0 MB, against tippecanoe v2.82 at 58 s for 573,885 tiles / 147 MB — the same tile set within a handful, with interior tiles byte-for-byte the same size apart from the layer name and the feature `id`. GDAL's PMTiles driver (3.12) took 780 s for the same job. On US Census ZCTA5 (33,092 ZIP areas, 52M vertices, z0–12): 47 s for 238,322 tiles / 251 MB against tippecanoe's 251 s for 238,319 tiles / 246 MB, indistinguishable in MapLibre at z3/z7/z11.
**Parquet rows come out spatially ordered.** Feature bbox centres are packed Sort-Tile-Recursive style (`order: "str"`, the default), so each row group's `bbox` statistics cover a disjoint patch and any reader that pushes an area filter down — DuckDB, pyarrow datasets, GeoPandas — fetches only the row groups that actually intersect it. On 1,000,000 points in 50 row groups the row-group overlap ratio runs 24.5 unsorted → 0.87 Morton → 0.28 Hilbert → 0.00 STR, and a city-sized query touches 1–2 row groups instead of all 50. This follows Kanahiro Iguchi's *Spatial sort for well-packed GeoParquet* (CNG Japan 2026).
**Where the GPU is, honestly.** Projection, the per-zoom rank filter, the integer→double conversion and the bbox reduction run on WebGPU when it is available, with a CPU path performing the *same integer arithmetic* when it is not — the output is byte-identical either way, verified kernel by kernel in headless Chromium. But those stages are only 3–6 % of the job on every dataset measured so far; ring assembly, clipping, MVT encoding and gzip dominate. The GPU keeps the browser's main thread free. It is not the reason the converter is fast — that comes from Gint and from the assembly stage.
**And back again.** `fromGeoParquet()` turns a GeoParquet into a GeoPBF using a dependency-free Parquet reader — Thrift compact footer, DataPage v1/v2, PLAIN and dictionary encodings, codecs none / snappy / gzip / zstd — plus a WKB parser. A file geopbf wrote comes back bit-identical, and files written by GeoPandas, pyarrow and DuckDB read back to the same features. The CRS must be lon/lat (CRS84 / EPSG:4326) unless `ignoreCrs` is passed. PMTiles has no such inverse: its tiles are simplified and quantized, so only an approximate reassembly would be possible, and this package does not pretend otherwise.
## Gint — Guide and Architecture
Source: https://www.ortho-earth.com/docs/gint
Geographic **Int**erleaved Binary Format **int**erleave (Morton bit-interleaving) · **int**eger (64-bit integer vertex codes) · **int**ended (level of detail designed in) A whole dataset on the GPU — drawn at any zoom, and able to answer questions
1. [Why Gint — Tiles Draw, Gint Knows](https://www.ortho-earth.com/docs/gint#why)
2. [Your First Gint Layer](https://www.ortho-earth.com/docs/gint#start)
3. [Choropleths — Three Examples](https://www.ortho-earth.com/docs/gint#examples)
4. [Expressions — What Is Promised](https://www.ortho-earth.com/docs/gint#expressions)
5. [When Data Overlaps](https://www.ortho-earth.com/docs/gint#overlap)
6. [API Reference](https://www.ortho-earth.com/docs/gint#api)
1. [Pipeline Overview](https://www.ortho-earth.com/docs/gint#overview)
2. [Encoding — Topology, Vertex Codes, Ranks](https://www.ortho-earth.com/docs/gint#encoding)
3. [Level of Detail in the Vertex Shader](https://www.ortho-earth.com/docs/gint#lod)
4. [Filling Polygons Without Triangles](https://www.ortho-earth.com/docs/gint#fill)
5. [Lines and Styles](https://www.ortho-earth.com/docs/gint#lines)
6. [On a Sphere — Horizon and Antimeridian](https://www.ortho-earth.com/docs/gint#sphere)
7. [In 3D — On the Terrain](https://www.ortho-earth.com/docs/gint#terrain)
8. [Asking Questions — Picking and Identify](https://www.ortho-earth.com/docs/gint#identify)
9. [Design Philosophy](https://www.ortho-earth.com/docs/gint#philosophy)
### 1. Why Gint — Tiles Draw, Gint Knows
The ortho-earth engine has two kinds of vector layers. The basemap is drawn from vector tiles (MVT): the server cuts the world into 4z tiles per zoom level, each zoom fetches a new set, and each tile is triangulated once on the CPU. That is right for a background picture. It is wrong for data you want to *ask* about — every feature is chopped at tile edges, simplified differently at each zoom, and exists only as triangles.
A **Gint layer** keeps the whole geometry of a [GeoPBF](https://www.ortho-earth.com/docs/geopbf) dataset on the GPU, once:
| | Vector tiles | Gint |
| --- | --- | --- |
| Files | one per tile per zoom | one file |
| Bytes when you zoom | new tiles | **+0** — level of detail is chosen on the GPU |
| Polygon fill | CPU triangulation per tile | winding count — no triangulation |
| Features | cut at tile edges | whole, shared borders exact |
| Restyle | re-run the style per tile | one texture update — every feature can have its own colour |
| Questions | — | pick, identify, highlight, join to a table |
### 2. Your First Gint Layer
Five steps: load, add, paint, filter, ask. The words come from MapLibre GL JS — paint properties, expressions, `setPaint`, `setFilter` — so what you already know works here. It is not a copy of MapLibre. The vocabulary is borrowed to make the first step short; the layer underneath is Gint.
```
import { createGlobe, geopbf } from "@ortho-earth/globe";
const map = await createGlobe({ target: "#map" });
// 1. Load — any format geopbf reads. { gint: true } also builds the GPU form (kept in IndexedDB).
const pbf = await geopbf("https://example.com/municipalities.geojson", { gint: true });
// 2. Add — a new layer on top. Nothing is replaced.
const layer = map.addGint(pbf, { tip: true });
await layer.ready; // true when the layer is on the GPU
// 3. Paint — MapLibre paint properties and expressions, evaluated once per feature.
await layer.setPaint({
"fill-color": ["interpolate", ["linear"], ["get", "pop"], 0, "#fff5eb", 1000000, "#7f2704"],
"fill-opacity": 0.85,
"line-color": "#ffffff",
"line-width": 0.5,
});
// 4. Filter — hide features. Nothing is rebuilt.
await layer.setFilter([">=", ["get", "pop"], 10000]);
// 5. Ask.
layer.on("click", e => console.log(e.fid, e.properties, e.lngLat));
const hit = layer.query([139.767, 35.681]); // { fid, properties } or null
const hits = map.queryAll([139.767, 35.681]); // [{ layer, fid, feature }], top layer first
```
#### 2.1 Load
`geopbf(input, { gint: true })` takes a URL, a `File`, an `ArrayBuffer` or a GeoJSON object, in any format [GeoPBF](https://www.ortho-earth.com/docs/geopbf) reads — GeoJSON, Shapefile, GeoPackage, FlatGeobuf, GeoParquet, KML, GPX and more. `gint: true` also builds the form the GPU draws: the topology encoder (WebAssembly, in a worker) turns every shared border into one shared arc. The result is kept in IndexedDB, so the next visit skips the encoder. `geopbf` is re-exported by `@ortho-earth/globe`; you do not need a second package.
Features whose properties are exactly the same become one feature — a multi-part feature with one `fid`. They are coloured, highlighted and answered together. If you need them apart, give each one its own property, such as an `id`.
#### 2.2 Add
`map.addGint(pbf, options)` adds a layer and returns its *handle* at once. The baking — edge tables, the level-of-detail ladder, a box per feature — runs in a worker, so the map keeps drawing. `await layer.ready` gives `true` when the layer is on the GPU (`false` if it failed). `addGint` does not move the camera.
Before any paint, a layer draws in its default style: polygon outlines in orange (`#FF6B35`), lines in cyan (`#00B4D8`). When the polygons shrink below a few pixels, the layer shows them as a solid fill instead of a mesh of lines, and switches back as you zoom in. Layers stack in the order you add them; the `order` option (smaller is lower) fixes the order whatever the sequence of calls. Any number of layers can be on the map at once, on both backends (WebGPU and WebGL2).
#### 2.3 Paint
`setPaint(paint, filter?)` takes MapLibre paint properties. Each value is a constant or an expression (§4). The expressions are evaluated **once**, in JavaScript, for every feature, and the results are written into a style table — one texel per feature. The GPU reads that table while it draws; no expression runs per frame. A restyle is one pass over the features plus one texture update. The geometry is never rebuilt. For the 1,919 municipalities of Japan the table is 31 KB. On WebGPU you can opt in to building the same table on the GPU — `createGlobe({ gpuExpr: true })`, or `?gintexpr=1` in the URL: the expressions become a compute shader once, and a feature-state change rewrites one cell instead of evaluating every feature again. Expressions it cannot take, and WebGL2, fall back to JavaScript; the picture is the same.
| Property | Applies to | Value |
| --- | --- | --- |
| `fill-color` | polygons | colour |
| `fill-opacity` | polygons | 0–1, multiplies the colour's alpha |
| `line-color` | lines and polygon outlines | colour |
| `line-width` | lines and polygon outlines | CSS pixels, in steps of 1/8, up to 31.875 · `0` = no line |
| `circle-color` | points | colour |
| `circle-radius` | points | CSS pixels, in steps of 1/4, up to 63.75 · `0` = no point |
| `line-opacity` | lines, outlines and points | 0–1, multiplies the line or circle colour's alpha |
Every property can be data-driven. Colours are CSS colours: `#rgb`, `#rgba`, `#rrggbb`, `#rrggbbaa`, `rgb()`/`rgba()` with commas, `hsl()`/`hsla()` and the CSS colour names. Lines and points share one colour slot per feature, so `line-opacity` also fades points.
- **Once a layer has a paint, only `fill-color` fills its polygons.** Leave it out and they are outlines at every zoom.
- **To hide a line, set its width to 0** — and a point, its radius. A fully transparent line or circle colour falls back to the default colour.
- **`setPaint` replaces the whole paint:** pass every property you want, each time. `setPaint(null)` returns to the default style. To change one property at a time, use the MapLibre-shaped entrance (§6.5).
Decide what a missing value means, and say it in the expression. A feature without the property gets no fill from `interpolate`, but the lowest colour from `step`, and the fallback from `match`. Wrap the input in `["coalesce", ["get", "pop"], …]`, test it with `["has", "pop"]`, or filter those features out.
#### 2.4 Filter
`setFilter(expression)` hides every feature for which the expression is false; `setFilter(null)` shows them all again. Like paint, the filter is evaluated once and written into the same table — nothing is rebuilt. A hidden feature is not drawn, and it takes no part in the fill, so it cannot spoil the fill of what lies under it (§5). It also drops out of hover and of questions: the answer is the next feature under the pointer, as if the hidden one were not there.
The filter lives in the same table as the paint. A filter given before the first `setPaint` is kept and applied with it; `setPaint(paint, filter)` sets both in one call.
#### 2.5 Ask
One layer holds the cursor at a time: hover, the tip, the highlight and `layer.on("click")` belong to it. Adding an interactive layer gives it the cursor, `layer.activate()` moves it, and a layer added with `interactive: false` never takes it — the layer that held the cursor keeps it. Hover is continuous — a pick every 32 ms — so it stays on one layer and costs one pick. A click is rare, so it can afford to ask every layer. A layer of lines only (no polygons, no points) does not answer hover yet; ask it through `map.on("click")` or `query`.
```
layer.on("hover", f => …); // { fid, properties } or null
layer.on("mouseenter", f => …); // entering a feature: { fid, properties }
layer.on("mouseleave", e => …); // leaving it: { fid }
layer.on("click", e => …); // { fid, properties, lngLat: [lng, lat] }
map.on("click", ({ lngLat, hits }) => { // every Gint layer under the point, top first
for (const { layer, fid, feature } of hits) …
});
```
A `fid` is the index of a feature inside its own layer — two layers both have a feature 7 — so keep it together with its layer.
`layer.query(lngLat)` and `map.queryAll(lngLat)` answer at once, in JavaScript, with no round trip to the GPU. They look for a point within 50 m, then a line within 30 m, then the smallest polygon that contains the position — a click on a ward inside a city returns the ward. Features hidden by the filter are skipped.
- **`map.queryAll` and `map.on("click")` answer what is shown now.** A layer switched off with `setVisible(false)`, or outside its zoom range, is left out. Layers added with `interactive: false` are included — a click can tell you that a parcel is also inside a hazard zone. The layers the globe draws for itself, such as the country outlines, never appear.
- **`layer.query` asks one layer on purpose.** It answers even when the layer is switched off or outside its zoom range.
#### 2.6 More on the handle
- **Labels.** `label: { field: ["get", "name"], size: 13, color: "#fff", halo: "#000" }` in the options, or `setLabel(…)` later. The labels share the collision and fading of the basemap's own labels, and follow the filter. `field` is an expression (or a function of the properties); a plain string is shown as it is, on every feature.
- **Feature state.** `setFeatureState(fid, { selected: true })`, read in paint with `["feature-state", "selected"]`. Many calls in one task are drawn in one frame.
- **Zoom.** `["zoom"]` in a paint or a filter is read when you set it. When the camera stops after moving a quarter of a zoom level or more, the layer evaluates again by itself. The change comes at rest, not during the zoom.
- **Data.** `setData(pbf)` swaps the data; the handle, its events, the paint and the filter stay.
- **The rest.** `setOrder(n)`, `setVisible(bool)`, `remove()` — §6.
### 3. Choropleths — Three Examples
#### 3.1 Municipalities, coloured from your own table
The values often live in a table — a census CSV, a spreadsheet — and not in the boundary file. There is no need to edit the data: build a `match` from the table. Two thousand labels are fine, because the expression runs once, not per frame.
```
// Your table: municipality code → value (for example population from a census CSV)
const values = { "13101": 66680, "13102": 169179, /* … */ };
const breaks = [10000, 50000, 100000, 300000, 1000000];
const colors = ["#f7fbff", "#c6dbef", "#6baed6", "#3182bd", "#08519c", "#08306b"];
const classOf = v => breaks.filter(b => v >= b).length;
// "N03_007" = the code field of Japan's national boundary data; use your own field name
const fill = ["match", ["to-string", ["get", "N03_007"]]];
for (const [code, v] of Object.entries(values)) fill.push(code, colors[classOf(v)]);
fill.push("rgba(0,0,0,0)"); // not in the table: no fill
await layer.setPaint({ "fill-color": fill, "fill-opacity": 0.85, "line-color": "#ffffff", "line-width": 0.3 });
```
`match` compares with `===`: the text `"13101"` is not the number `13101`, so the input is passed through `to-string`. The number of colours does not change the cost of drawing. Every feature may have its own colour — the fill is two passes whether there are six colours or 1,919.
#### 3.2 Parcels, by lot number
Japan's land registry map (登記所備付地図, published by the Ministry of Justice; `geopbf` reads its XML directly) gives each parcel a lot number, `地番`. In central Sapporo — 57,341 parcels — the same field also holds words: 道 (road), 河川 (river), 無地番 (no lot number), 筆界未定地 (boundary not settled). One expression puts public land and unsettled boundaries on the map:
```
await parcels.setPaint({
"fill-color": ["match", ["get", "地番"],
["道", "河川", "無地番"], "#e41a1c88", // road, river, no lot number
"筆界未定地", "#ff7f00aa", // boundary not settled
"rgba(0,0,0,0)"], // every other parcel: no fill
"line-color": "#ffffff66",
"line-width": 0.5,
});
```
A `match` label can be an array: any of its values selects the output.
#### 3.3 Two layers — a parcel inside a hazard zone
Put a hazard layer under the parcels. The parcels hold the cursor; a click reaches both.
```
// Landslide warning zones (Japan's National Land Numerical Information A33). A33_002 = 2: special warning zone
const zones = map.addGint(await geopbf(zonesUrl, { gint: true }), { order: -1, interactive: false });
await zones.setPaint({
"fill-color": ["match", ["to-number", ["get", "A33_002"]], 2, "#c0392b80", "#d9a4416b"],
"line-width": 0, // fill only, no outline
}); // interactive: false — the cursor stays on the parcels
map.on("click", ({ hits }) => {
const parcel = hits.find(h => h.layer === parcels);
const zone = hits.find(h => h.layer === zones);
if (parcel && zone) console.log(parcel.feature.properties["地番"], "is in a warning zone");
});
```
Turning a layer on and off is `setVisible` — nothing is baked again. The questions “which zone is this parcel in?” and “what is under this point?” are the reason Gint exists: the layers are data, not only pictures.
### 4. Expressions — What Is Promised
The expressions are MapLibre's. The set below is promised for Gint layers: it is the set listed in the type definitions (`globe.d.ts`) and it is tested. The evaluator is shared with the basemap, which reads MapLibre style files, so it accepts more operators than these; the others are not promised for Gint layers.
| Group | Operators |
| --- | --- |
| Data | `get` `has` `feature-state` `geometry-type` `zoom` `literal` |
| Choice | `match` `case` `step` `coalesce` |
| Interpolation | `interpolate` — `["linear"]` and `["exponential", base]`, numbers and colours |
| Comparison and logic | `==` `!=` `>` `>=` `<` `<=` `!` `all` `any` `in` |
| Arithmetic | `+` `-` `*` `/` `%` `^` `min` `max` |
| Types and text | `to-number` `to-string` `concat` |
| Variables | `let` `var` |
#### 4.1 Rules
1. **Once, not per frame.** Expressions run when you call `setPaint` or `setFilter` (and when feature state changes). The GPU only reads the results.
2. **`["zoom"]` is a snapshot.** It is the zoom at evaluation time; the layer re-evaluates when the camera stops (§2.6). There is no interpolation between frames.
3. **No exceptions.** When an expression fails or gives the wrong type for a feature, that feature keeps the default: no fill, a 1 px line, a 1.5 px point. An operator outside the evaluator gives the default too.
4. **Strict equality.** `==`, `!=` and `match` compare with `===`. Convert with `to-string` or `to-number` when the types differ.
5. **`in`** is `["in", needle, haystack]`, where the haystack is a string or an array (`["literal", […]]`).
6. **Colours** interpolate in RGB, and may be nested — an `interpolate` inside a `match` branch works.
### 5. When Data Overlaps
Real data overlaps: a prefecture polygon over its municipalities, a zone registered twice, parcels drawn over each other. Gint fills by the nonzero winding rule — the even-odd rule is never used — so overlaps behave in a way you can predict:
- **One colour** (no paint, or the same colour for all): the union is filled. Two copies of the same parcel fill like one; a hole covered by another feature is filled.
- **A colour per feature** (a choropleth): where two features overlap, the later one in the data — the higher `fid` — wins. If that one is transparent or filtered out, the one below shows through. This is exact where two features overlap; where three or more pile up, the result is not guaranteed.
- **Filtered features take no part in the fill.** When a dataset mixes levels — municipalities together with the larger polygons that contain them — filter out the level you are not painting, and the rest fills cleanly.
- **Questions** return the smallest polygon that contains the point and is not hidden by the filter.
The winding sum carries more than a colour. Read differently, it shows where two different features overlap, where one feature is registered twice, and where a ring runs the wrong way. During development the engine paints exactly those pixels: on a land registry map, a question of data quality that no one could see becomes a picture. This view is a development tool today, not part of the API.
One limit: the per-feature fill adds feature numbers in a float target. On GPUs that cannot blend 32-bit floats, the numbers are 16-bit and a layer can colour up to 2,047 features one by one; a larger layer loses the per-feature fill and is drawn in its plain style. If you meet this limit, merge the features that share a style into multi-polygons — the fill cost is the same.
### 6. API Reference
#### 6.1 Adding a layer
##### map.addGint(pbf, options) → handle | null
Adds a Gint layer on top and returns its handle at once. Returns `null` when `pbf` has no GPU form. The layer becomes the active one unless `interactive` is false (§2.5).
- **`pbf`** (GeoPBF): from `geopbf(input, { gint: true })`.
- **`options.order`** (Number): stacking order, smaller is lower. Default: the order of addition.
- **`options.minZoom` / `options.maxZoom`** (Number): the zoom range of this layer. Default: `minZoom` from the size of the data (a small area starts at a higher zoom); `maxZoom` from the coordinate precision.
- **`options.interactive`** (Boolean): `false` = never takes the cursor; the layer that holds it keeps it. Such a layer still answers `map.on("click")` and `queryAll`. Default `true`.
- **`options.tip`** (Boolean | Function): `true` = a tip with every property as “key: value”; a function `properties → string[]` writes your own lines. Default: no tip.
- **`options.label`** (Object): `{ field, size, color, halo, haloW, minZoom, maxZoom }` — see `setLabel`.
- **`options.style`** (Object): the look without paint — `{ fillColor: [r, g, b, a], lineWidth, ptRadius }`, colours 0–1.
- **`options.fillMaxEdges`** (Number): the fill stops above this many edges (default 2,000,000); `0` = outlines only.
- **`options.lowFill`** (Boolean): when the fill is off (over `fillMaxEdges`), still draw the one-colour fill of low zoom — for very large layers.
##### layer.ready → Promise
`true` when the layer is on the GPU, `false` if baking failed.
#### 6.2 Style
##### await layer.setPaint(paint, filter?)
Evaluates the paint (and the filter) for every feature and sends one table to the GPU. Replaces the whole paint. `null` = the default style. Without `filter`, the current filter stays.
- **`paint`** (Object): `fill-color`, `fill-opacity`, `line-color`, `line-opacity`, `line-width`, `circle-color`, `circle-radius` (§2.3).
- **`filter`** (Expression | null): a boolean expression (§4).
##### await layer.setFilter(filter)
Only the filter. Before the first `setPaint` it is kept and applied with it. `null` = show all.
##### layer.setFeatureState(fid, state) · layer.removeFeatureState(fid?)
Temporary state per feature, read by `["feature-state", key]`. `state` is merged; `null` removes it. `removeFeatureState()` with no fid clears all.
##### await layer.setLabel(label | null)
- **`field`** (Expression | Function | String): the text — an expression such as `["get", "name"]` or `["concat", …]`, a function `properties → string`, or a fixed string.
- **`size`, `color`, `halo`, `haloW`**: text size (px), colour, halo colour and width.
- **`minZoom`, `maxZoom`**: zoom range of the labels (default: the layer's).
Anchors: the centre of the feature's box for polygons and lines, the point for points. Hidden features have no label.
##### layer.style(style)
Changes the look without paint (the same object as `options.style`).
#### 6.3 Data, order, visibility
##### await layer.setData(pbf, { minZoom?, maxZoom? }) → boolean
Swaps the data. The handle, its events, the paint and the filter stay; the paint is evaluated again on the new features. Resolves `true` when the new data is on the GPU.
##### layer.setOrder(order) · layer.setVisible(visible) · layer.remove()
Moves the layer in the stack (smaller is lower) · shows or hides it (nothing is baked again) · removes it for good. If the active layer is removed, no layer holds the cursor until you call `activate()` or add another interactive layer.
#### 6.4 Events and questions
##### layer.on(type, callback) → layer
For the active layer only. A layer of lines only does not answer hover yet.
- **`"hover"`**: `{ fid, properties }`, or `null` when the pointer leaves the features.
- **`"mouseenter"`** / **`"mouseleave"`**: at the edges of a feature — `{ fid, properties }` / `{ fid }`.
- **`"click"`**: `{ fid, properties, lngLat }`, `lngLat` = `[lng, lat]` of the pointer.
##### layer.activate()
Gives the cursor (hover, tip, highlight, `layer.on("click")`) to this layer.
##### layer.query([lng, lat]) → { fid, properties } | null
Synchronous, in JavaScript. A point within 50 m, else a line within 30 m, else the smallest polygon containing the position. Features hidden by the filter are skipped. Answers for any layer, interactive or not, even when it is switched off or outside its zoom range.
##### map.queryAll([lng, lat]) → [{ layer, fid, feature }]
`layer.query` on every Gint layer that is shown now — switched on and inside its zoom range — top layer first. `feature` is `{ fid, properties }`. The globe's own layers (country outlines and the like) are not included.
##### map.on("click", ({ lngLat, hits }) => …)
Every click on the globe, with `hits` = `map.queryAll(lngLat)`. Also `map.on("move" | "settle" | "load", …)` and `map.off(type, callback)`; `"load"` fires at once if the map is already drawn.
#### 6.5 The MapLibre-shaped entrance
`map.addSource(id, { type: "geojson", data })` with `map.addLayer({ type: "fill" | "line" | "circle", … })` builds a Gint layer underneath, so MapLibre code runs as it is: `setPaintProperty`, `setLayoutProperty` (`visibility`), `setFilter`, `moveLayer`, `setFeatureState({ source, id }, state)`, `queryRenderedFeatures` and `map.on("click", layerId, …)` all work on it. Consecutive layers of one source share **one** Gint layer, drawn fill, then line, then circle; each layer's own filter, zoom range and geometry type decide, feature by feature, what it draws. A second layer of the same type, or a fill above a line, starts another Gint layer. Zoom ranges follow MapLibre: without `minzoom` a layer is drawn from zoom 0.
The older single-layer methods (`applyGintData`, `paint`, `paintTable`, `onGintClick`) remain for existing apps. New code should use `addGint`.
### 7. Pipeline Overview
### 8. Encoding — Topology, Vertex Codes, Ranks
#### 8.1 Shared arcs
The encoder (Rust compiled to WebAssembly, run in a worker) splits every ring and line at junctions into **arcs**, and stores each arc once. A polygon is a list of arc references — `[fid][nRings][arcCount][±arcIdx…]`, where a reversed arc is written `~idx`. Two neighbouring municipalities share their border arc, so it is simplified identically for both: no slivers, no gaps, at any zoom. Lines and a neighbour list are stored in separate streams.
#### 8.2 The 64-bit vertex code
Longitude and latitude become integers — `ix = (lon + 180) × 107`, `iy = (lat + 90) × 107` (about 1 cm) — and their bits are **interleaved (Morton order)** into one 64-bit code. The code also carries the vertex's level of detail:
Long arcs get an extra L1 vertex every 1° along the great circle (a *degree anchor*), so a long edge can never be simplified into a chord that cuts across the curve of the Earth.
#### 8.3 Visvalingam–Whyatt rank
Each interior vertex is weighted by the Visvalingam–Whyatt effective area — the area of the triangle it forms with its neighbours, carried as a running maximum so a vertex never outranks the ones removed before it, and corrected by cos(latitude). The area becomes a 6-bit rank:
The same formula, fed the ground area of one screen pixel, gives the rank the current zoom needs (§9). Rank and zoom speak the same unit.
#### 8.4 GintBUF
The result is one buffer: a 64-byte header (magic `"Gint"`, version, counts, bbox, stream lengths), then the arc vertex codes, the point codes, per-arc metadata `[offset, length, weight, –, bbox]`, the point fids, and the polygon, line and neighbour streams. It is cached in IndexedDB, so a second visit skips the encoder entirely.
### 9. Level of Detail in the Vertex Shader
The bake step turns arcs into **edges** (vertex A → vertex B) in an integer texture. Each frame:
1. **Required rank.** The ground area of one pixel goes through the rank formula: `rank = floor(1.5·log2(pxArea) + 61.524)`.
2. **Discard.** The vertex shader drops every edge whose start vertex ranks below it.
3. **Forward snap.** The surviving edge's end is moved forward to the next vertex that is kept. The simplified line stays connected — no gaps, no T-junctions, because the decision is made per vertex, and a shared arc makes the same decision for both polygons.
Nothing is uploaded when you zoom. What changes is one uniform.
#### 9.1 Tiers and chunks
A national dataset can have millions of edges. Two structures keep the vertex shader from touching them all:
- **Tier ladder** — up to 9 pre-filtered edge lists, each at most 600,000 edges. The steps adapt to the dataset's own histogram of weights (only for datasets over 200,000 edges). A frame draws the lightest tier that still contains every vertex the current rank needs.
- **Culling chunks** — edges are grouped in blocks of 16,384, ordered by the Morton code of each feature's bbox centre, so features near each other sit together. Only the runs of chunks inside the view are drawn; each feature is also tested against the view on the GPU by its bbox.
### 10. Filling Polygons Without Triangles
Polygons are never triangulated. Each polygon's edges are drawn as a **fan** from a pivot — the centre of that feature's bbox — into the stencil buffer (in a layer with multi-part features — islands, exclaves, a climate zone scattered over the world — each part has its own pivot and its own bbox, and is culled on its own): front-facing triangles increment, back-facing triangles decrement (**nonzero winding**). A second pass covers every pixel whose count is not zero. Concave shapes and holes come out right with no special cases; the fan's own overlaps cancel.
- **Boundary meta.** An arc shared by two polygons of the same fill cancels in the winding count, so it need not be drawn in the fill at all. The bake step drops arcs whose net reference is zero, so for a dense partition — parcels, districts — a one-colour fill costs roughly the length of the outer boundary, not the number of features inside it. The fan of this fill uses one pivot for everything, because the kept arcs of many features form mixed loops. In central Sapporo (about 370,000 edges of parcels) this took a mid-zoom frame from 20–37 ms to about 2 ms.
- **Low zoom.** When the features are smaller than a few pixels, the layer switches to a solid fill and fades back as you zoom in; while the camera moves, that switch is held a little longer so it does not flicker.
- **Choropleth.** For a map coloured per feature, each fan triangle adds ±(feature id + 1) and ±1 into a float target; dividing the two recovers the id per pixel, and the style table turns it into a colour. The number of passes does not depend on the number of colours. A fourth channel keeps the largest id that touched the pixel, which decides overlaps (§5). This fill needs every edge: the cancelling of shared arcs works only when the two sides have the same colour.
- **Moving camera.** A frame has a budget of 250,000 edges while the camera moves. Over it, a layer draws a cheaper form — the outline, or a one-colour silhouette — and the full picture comes back when the camera stops.
- Fill switches itself off above 2 million edges (`fillMaxEdges`); lines still draw.
### 11. Lines and Styles
Each edge is drawn as a small quad (six vertices) with a capsule signed-distance function, so lines have round joins and ends at any width without extra geometry. Colour, width, point radius and flags come from a per-feature style table on the GPU, and a 256-slot style table and dash table serve shared styles — restyling a map is a texture update, not a rebuild.
### 12. On a Sphere — Horizon and Antimeridian
- **Horizon.** Vertices on the far side of the globe are projected onto the horizon circle in 3D, so a polygon that straddles the horizon keeps a closed outline and still fills correctly. Features entirely on the far side are culled by a spherical-cap test — for the fill, each part of a multi-part feature on its own, so a part on the far side cannot paint over the near side.
- **Antimeridian.** Features that cross ±180° are cut there when encoded; the seam edges are recognised and never drawn as lines, so the cut is invisible.
### 13. In 3D — On the Terrain
- **Fills** are painted into the ground texture that the terrain samples — the same one that carries raster maps — so they lie exactly on the ground, whatever its shape.
- **Lines and points** are draped on the same elevation field. Long edges are subdivided on the GPU according to the terrain under them (instanced draws, within a budget), so a border crossing a mountain range follows the ridges instead of cutting through them.
- Parts hidden behind terrain are shown as a faint dashed line when the camera is still — you can see where a boundary goes behind a mountain.
### 14. Asking Questions — Picking and Identify
- **Lines and points** are picked on the GPU: each is drawn with its feature id into a small target, which is read back asynchronously (a pixel buffer and fence on WebGL2, `copyTextureToBuffer` + `mapAsync` on WebGPU).
- **Polygons** are answered in JavaScript by a point-in-polygon test with bbox rejection, *smallest wins* — a click inside a ward inside a city returns the ward. About 1,900 Japanese municipalities answer in 0.5–4 ms. A line or point under the pointer comes before the polygon around it.
- The pick target is built when the camera stops, for the active layer only — one target, however many layers.
- Hover highlights the feature (a thicker outline) and can darken everything outside it.
### 15. Design Philosophy
How geographic data is represented is also a choice about which level of detail to treat as "reality." Just as Natural Earth's physical/cultural distinction organizes phenomena on Earth from a human perspective, Gint's level-of-detail design implements the idea that what is visible changes with scale.
The Visvalingam–Whyatt weight quantifies "how much shape would be lost by removing this vertex." It is a measure of significance — a way to separate the essential structure of a coastline or boundary from detail that only matters at finer scales. Packing it into the vertex code itself means the data carries its own answer to "what should be seen at this scale."
Two quirks belong to globes, not flat maps: polygons crossing the antimeridian must be cut, and polygons crossing the horizon must be closed along it. They are the quiet surprises that separate a flat map renderer from a globe renderer.
The API follows the same idea from the other side. The data stays as it is — the paint is a view of it, computed once and kept beside it. Borrowing MapLibre's words is not about being a copy; it is about letting what people already know carry over.
## altpbf Technical Overview
Source: https://www.ortho-earth.com/docs/altpbf
Protocol Buffers-based raster elevation tiles. 3-tier zoom LOD · GEBCO + ALOS (+ GSI DEM10B in Japan) · Int16 delta + deflateRaw · Worker zero-copy
1. [What is altpbf?](https://www.ortho-earth.com/docs/altpbf#what)
2. [Data Sources](https://www.ortho-earth.com/docs/altpbf#sources)
3. [3-Tier Tile Hierarchy](https://www.ortho-earth.com/docs/altpbf#tiers)
4. [Binary Format](https://www.ortho-earth.com/docs/altpbf#format)
5. [Tile Naming](https://www.ortho-earth.com/docs/altpbf#naming)
6. [Worker & Cache Architecture](https://www.ortho-earth.com/docs/altpbf#worker)
7. [GEBCO Processing Pipeline](https://www.ortho-earth.com/docs/altpbf#gebco)
8. [API Reference](https://www.ortho-earth.com/docs/altpbf#api)
### 1. What is altpbf?
altpbf is a binary raster elevation tile format built on Protocol Buffers. Where GeoPBF handles *vector* geometry (coastlines, roads, polygons), altpbf handles *raster* elevation grids — the digital elevation model (DEM) and bathymetry data needed for terrain rendering, shadow calculation, and 3D visualization.
Each tile is a rectangular grid of `Int16` elevation values (meters), delta-encoded and compressed with deflateRaw. Three tile sizes cover the globe at different resolutions, and the ortho-earth engine selects the appropriate tier automatically based on zoom level.
The `altpbf` npm package (1.2.0) is the *format* only: `encode`, `decode`, `encodeName` / `decodeName` and `altpbf2png`. It is written in TypeScript (strict) and ships type definitions (`AltpbfTile`, `AltpbfDecoded`, `AltpbfSource`, `Altpbf2PngOptions`, …). Its only runtime dependency is `geopbf`; it needs `CompressionStream`, and `altpbf2png` also needs `OffscreenCanvas`. Fetching, caching, worker decoding and height lookup (`createGetHeight`, `createTileLoader`) live in the engine, `@ortho-earth/core/elevation`.
Earth's elevation range is roughly −11,000 m (Mariana Trench) to +8,849 m (Everest). A signed 16-bit integer covers −32,768 to +32,767 m — exactly enough, with no wasted bits. Compared to Float32, Int16 halves the data size before any compression is applied.
### 2. Data Sources
| Source | Coverage | Resolution | Used for |
| --- | --- | --- | --- |
| **GEBCO** General Bathymetric Chart of the Oceans | Global (land + sea) | ~450 m (15 arc-sec) | HGT90 · HGT10 |
| **ALOS AW3D30** JAXA ALOS World 3D | Land only | ~30 m (1 arc-sec) | HGT01 |
| **GSI DEM10B** Geospatial Information Authority of Japan | Japan only (bare earth) | ~10 m, baked to a 1″ grid | HGT01 (Japan) · HGT10 (Japan, merged with GEBCO) |
GEBCO provides global coverage including ocean bathymetry, making it the baseline for all zoom levels. ALOS AW3D30 is a high-precision land-only DEM published by JAXA, used for close-up terrain rendering where its 30 m resolution delivers visually meaningful detail. Since ALOS tiles only exist for land areas, the engine keeps an index of available tiles and falls back gracefully to GEBCO HGT10 for ocean queries. In Japan, HGT01 tiles are re-baked from GSI DEM10B (bare-earth DTM, where AW3D30 is a surface model) and stored in the bucket; the engine reads the bucket first and only falls back to JAXA when no baked tile exists.
### 3. 3-Tier Tile Hierarchy
altpbf defines three tile sizes, each covering a different angular extent of the globe. `createGetHeight` (`@ortho-earth/core/elevation`) switches between tiers based on the current zoom level, defaulting to `level1 = 7` and `level2 = 12`.
Each tier is a strict fallback chain: **HGT01 → HGT10 → HGT90**. If a high-resolution tile is unavailable (ocean, no ALOS data) or returns no elevation, the next coarser tier answers the query transparently. The caller always receives a valid elevation value.
Within each tile, `calcHeight(x, y, v)` performs bilinear interpolation across the four nearest grid cells — no staircase artifacts. Normalized coordinates (0–1) within the tile are computed from the raw lat/lng and passed directly to the interpolation function.
### 4. Binary Format
Each .altpbf tile is a **deflateRaw-compressed Protocol Buffers message**.
#### 4.1 Delta Encoding for Elevation
Terrain elevation changes gradually — neighboring cells in a DEM rarely differ by more than a few tens of metres. Delta encoding exploits this locality: storing differences rather than absolute values keeps numbers small, and small numbers encode to fewer Varint bytes.
After delta encoding, most values in a smooth terrain tile fit in a single Varint byte. Combined with deflateRaw on top, altpbf tiles are typically **5–15× smaller** than an equivalent raw Int16 array.
`decode` reads the packed SVarint body straight into the output `Int16Array` — no intermediate JS arrays — using a small embedded WebAssembly kernel (SIMD128 where available, scalar wasm otherwise) with a plain-JS fallback when wasm is unavailable (e.g. blocked by CSP). A 5.7M-point HGT10 tile decodes in ~21 ms / +12 MB instead of ~99 ms / +230 MB with the previous implementation.
#### 4.2 Elevation Color Map
`altpbf2png` renders a tile as a PNG image using altitude/depth step colors:
### 5. Tile Naming
Each tile is uniquely identified by a compact name string encoding its range, latitude, and longitude:
```
encodeName(lng, lat, range)
// range > 0 → "R{02d(range)}{lat_prefix}{03d(|lat|)}{lng_prefix}{03d(|lng|)}"
// range omitted / 0 → "{lat_prefix}{03d(|lat|)}{lng_prefix}{03d(|lng|)}" (key of the JAXA AW3D30 index)
// (lng, lat) is the tile's bottom-left (south-west) corner; decodeName(name) → [lng, lat, range]
// Examples:
encodeName(0, -90, 90) // → "R90S090E000" (HGT90 quadrant 0–90°E · 0–90°S)
encodeName(130, 30, 10) // → "R10N030E130" (HGT10 Japan region)
encodeName(135, 35, 1) // → "R01N035E135" (HGT01, Kinki region)
encodeName(135, 35) // → "N035E135" (AW3D30 index key)
decodeName("R01N035E135") // → [135, 35, 1]
```
ALOS AW3D30 tiles exist only over land. Before requesting an HGT01 tile, the engine checks an in-memory index loaded from the JAXA tile list (`index_alos()` in `@ortho-earth/core/elevation`, cached in IndexedDB). Ocean queries immediately fall back to HGT10 without a network round-trip. If JAXA is unreachable, the engine continues with an empty index and refetches it in the background.
### 6. Worker & Cache Architecture
```
// packages/ortho-core/src/elevation/worker.ts — zero-copy Int16Array transfer to main thread
import { load, setApiUrl } from "./loader.ts";
onmessage = async e => {
const { name, apiUrl } = e.data;
if (apiUrl) setApiUrl(apiUrl);
try { const obj = await load(name);
obj ? postMessage(obj, [obj.data.buffer]) // ← Transferable: zero-copy
: postMessage(null);
} catch (e) { postMessage(null); }
};
```
The worker inflates and decodes the tile off-main-thread, then transfers the `Int16Array` buffer back via the Transferable interface — no copying, no serialization. The worker runs under the engine's `"ortho:height"` worker role. `createGetHeight` uses a single worker that handles requests one at a time; while a load is in flight, render-side queries return 0 until it arrives, and `{ wait: true }` callers wait for it. `createTileLoader` (used by the terrain atlas) runs a pool of up to 3 workers, merges concurrent requests for the same tile, and decodes in-thread when nested workers are unavailable. Once decoded, tiles are persisted to IndexedDB for instant re-use across sessions.
### 7. GEBCO Processing Pipeline
The raw GEBCO source is a set of GeoTIFFs at 21,600 × 21,600 pixels per 90° quadrant (eight quadrants, 86,400 × 43,200 for the globe). The uploader app's `GEBCO()` function (`apps/uploader/src/terrain/gebco.ts`, not part of the altpbf package) downloads and tiles it into altpbf format:
```
// Step 1 — HGT90: 8× average-pool downsampling
// 21600 × 21600 → 2700 × 2700 (one 90° tile per quadrant)
// Each output pixel = mean of 8×8 source pixels
// Step 2 — HGT10: extract 9×9 = 81 sub-tiles per quadrant (2400 px tall)
// Apply polar width shrink so tiles remain square on-screen
// shrink(lat): fraction of full-width actually used at that latitude
```
#### 7.1 Polar Width Correction
Meridians converge toward the poles, so a 10° longitude span represents far fewer kilometres at high latitudes than at the equator. GEBCO HGT10 tile generation compensates by reducing the pixel width of polar tiles:
Tile pixel width relative to equatorial baseline. Polar tiles are narrower, matching the reduced real-world extent per degree of longitude.
### 8. API Reference
```
// ── altpbf (npm) — the format ───────────────────────────
import { encode, decode, encodeName, decodeName, altpbf2png } from "altpbf";
import type { AltpbfTile, AltpbfDecoded, AltpbfSource, AltpbfColorMap, Altpbf2PngOptions } from "altpbf";
// ── createGetHeight — engine entry point (@ortho-earth/core/elevation) ──
import { createGetHeight } from "@ortho-earth/core/elevation";
const getHeight = await createGetHeight({
apiUrl: 'https://your-api.example.com', // nativeBucket base URL
level1: 7, // zoom threshold HGT90 → HGT10
level2: 12, // zoom threshold HGT10 → HGT01
onstart: name => console.log(`loading ${name}...`),
onend: name => console.log(`done ${name}`),
});
// Query elevation at any (lng, lat, zoom)
const h = await getHeight(139.77, 35.68, 14); // → height in metres
// Zoom omitted → always use highest resolution (HGT01)
const h = await getHeight(139.77, 35.68);
// ── altpbf2png — render tile as PNG ────────────────────
const blob = await altpbf2png(pbfBlob, {
size: 256, // output PNG size (square)
colorMap: h => [r, g, b] // custom color function (optional)
});
// ── Low-level encode / decode ───────────────────────────
const buf = await encode({ name, source, lng, lat, range, width, height, data }); // → Uint8Array
const obj = await decode(blob); // → { name, source, lng, lat, range, width, height, data: Int16Array }
// ── GEBCO bulk tile generation (apps/uploader) ─────────
await GEBCO({ year: 2026, noIce: false, log: console });
// Downloads ~12 GB source, generates HGT90 + HGT10 altpbf tiles, uploads to bucket
// ── ALOS tile index (engine-internal, elevation/loader.ts) ──
const index = await index_alos();
// → { "N035E135": "v2404", "N036E135": "v2404", ... }
```
## Ortho Earth 2.4 is out
Source: https://www.ortho-earth.com/docs/story-v240
2026-11-09 · Kenji Yoshida
On 3 November I bought an Android tablet. It is a Galaxy, with a Mali-G615 GPU and 4 GB of memory: the first Android I have ever bought with my own money.
I chose an everyday 4 GB model on purpose, not a high-end one. This is the kind of machine most people actually hold, and I wanted to see with my own eyes how well the globe runs on it.
Everything around me is Mac, iPhone and iPad. Working alone, you can only imagine the machines you do not have. Once one arrived, I could not keep my hands off it. 2.4 is the record of six days spent with that one tablet.
### 3 November: WebGPU ran
Until now Android started on WebGL2, just in case. In August one Android phone had reported the map going black while moving, so I had played it safe.
On the day the tablet arrived, I first made a GPU check page ([/check/](https://www.ortho-earth.com/check/)). It shows on one page whether the device takes WebGPU or WebGL2, its adapter, features and limits, and a test drawing. Nothing is sent anywhere.
I opened /japan/ on WebGPU, and it worked. PLATEAU buildings were even faster than on WebGL2. That same day Android started on WebGPU like every other platform, so the reflections, fog and other effects added in 2.3 can now be seen on Android too. If anything goes wrong, `?gl2=1` goes back to WebGL2.
Along the way, laptops now use the faster of their built-in and discrete GPUs (`powerPreference` defaults to `"high-performance"`). I checked it on a real Windows machine as well.
### What only a real device shows
Once it runs, you want it to run well. Touching it on the tablet, I kept finding room to grow that the Mac never showed. The HUD (`?hud=1`) shows where each frame's time goes, part by part, and I went through them one by one like a treasure hunt.
- **The resolution did not drop.** Flying over PLATEAU took about 120 ms a frame, yet dynamic resolution stayed at full size. Tile-based GPUs can report less GPU time than they spend. Now real time over 50 ms is taken into account too.
- **The main thread stopped for 800 ms.** The function that samples elevation did not keep the tiles it read from IndexedDB, so tens of MB of tiles were read again at every move. It now keeps the last three.
- **Nearby buildings smeared.** The Earth is computed as a sphere of radius 1, so the w of nearby vertices came to about 1e-6, and Mali treated it as 0. Scaling clip space by 220 before handing it over removed the smear. The picture on the Mac does not change.
- **Tiles went through the main thread.** Tile geometry now goes straight from the tile worker to the render worker; the main thread only receives the index.
### A lighter start
On the tablet the screen sometimes waited for a while after the first picture. The start-up timeline (`[boot] timeline`) showed the GPU process compiling shaders one at a time, 6–14 seconds in all, while the renderer waited.
So the globe and terrain are now drawn first, and the other layers appear as they become ready (progressive drawing). Only the pipelines needed now are built first; the rest come later. The freeze went from 6.5–6.9 s to 1.0–2.1 s. On Mali, unused shader branches are dropped when the shader is generated, which shortens compiling. Baked glyphs can also be kept in IndexedDB so the next start does not bake them again (`?glyphdb=1`).
### From Kyoto to the whole of Japan
One of the demos glides in one go from the streets of Kyoto out to the whole Japanese archipelago. On the tablet the first 8 seconds ran at 8–10 fps.
One culprit was in an unexpected place. Whenever a frame was free, the map took itself to have "landed", even mid-flight, and rewrote the URL. Chrome on Android then redrew the address bar, which blocked the GPU process for 0.1–6 seconds: 102 times in 20 seconds, 11.4 seconds in all. Writing no URL during a flight and waiting until it lands raised the frame count from 167 to 227 (about 36% more).
The other was terrain. With terrain off it ran at about 60 fps. Now, only while moving, terrain is drawn with a coarser mesh. On 4 GB devices, the elevation that lines sample is lighter too.
### From Marunouchi to the Rainbow Bridge
What remained last were the PLATEAU buildings. The glide from Marunouchi to the Rainbow Bridge ran at 12–18 fps for its first 6–8 seconds. The middle of Tokyo simply has that much to draw.
So the map now takes a few shortcuts, only while it moves. The full picture comes back the moment it stops, so what you look at does not change.
| Only while moving | Frames in glide seconds 4–12 |
| --- | --- |
| Skip low buildings (6 → 12 → 24 m) | 182, 240 → 280, 262 (about 30% more) |
| Drop small triangles (reordering only, no extra GPU memory) | 208 → 295 |
| Draw buildings with a lighter pixel shader | average 236 → 294 (about 25% more, ahead in all 3 alternating pairs) |
Note: all measured on the tablet (Mali-G615). They went in one after another, so each row starts from a different point. All three are now the default on every device. They only kick in while the camera moves and a frame takes over 40 ms, so nothing changes on a fast machine.
### To games, and back to the globe
The other big newcomer is the link with games. There are three destinations: Unity, Unreal Engine and Minecraft. You can take a city from the globe into a game, and bring what you built in the game back to the globe.
What travels is terrain and PLATEAU buildings (for Unity and Unreal also the building attributes and point clouds), for an area of about two or three city blocks. Streaming tiles inside a game is already done by Cesium for Unity and the PLATEAU SDK for Unity, so this sticks to "cut it out and hand it over as files".
#### Just one agreement
All three are joined by one agreement. A point on the ground is chosen as the anchor (longitude, latitude, ellipsoidal height and a heading), and everything is given in metres east, north and up from it. The hand-over is a GLB with the anchor inside (`asset.extras.orthoEarth`). In Minecraft one block is 1 m and the anchor sits at block (0, 0, 0).
| | Unity 6 | Unreal Engine 5.6+ | Minecraft |
| --- | --- | --- | --- |
| Install | Plugin (Package Manager) | Plugin (zip into `Plugins/`) | Nothing (world files are written directly) |
| From the globe | Menu: **Place export folder…** | Same menu | `ortho-minecraft` bakes a world |
| To the globe | **Export selection to GLB…** | Same menu | An area or a diff, taken out as GLB |
| Axes and units | X east, Y up, Z north, m | X east, Y south, Z up, cm | X east, Y up, Z south, 1 block = 1 m |
| Building attributes | In the Inspector | In Details | — |
| Point clouds | PLY | LAS | — |
#### From the globe to a game
All three start from the same `ortho-export`. Export an area, and the anchor, terrain, buildings and the building attribute table land in one folder. Point clouds are read at [/japan/pointcloud](https://www.ortho-earth.com/japan/pointcloud) and saved as PLY or LAS.
In Unity and Unreal, choosing **Place export folder…** from the menu is all it takes: everything is laid out in the right place under the anchor. Each building can be selected by its PLATEAU `gml_id` and shows attributes such as use, height, address and flood risk; code can read them too, with `b.Get("bldg:usage")` or `b.MeasuredHeight`. PLATEAU's webp textures are re-baked to jpeg, which the engines can read.
For Minecraft the same folder goes to `ortho-minecraft`. Terrain and buildings are baked into blocks, the ground and roofs are painted with the blocks closest in colour to the aerial photo, and buildings get floors. Out come three things: a Java Edition world, a WorldEdit `.schem` and a Bedrock `.mcworld`, which opens with a double-click. The anchor is the spawn point, so the coordinates F3 shows are metres from the anchor. It opens in Creative, frozen at midday.
#### From a game back to the globe
The way back ends at the same door for all three. In Unity and Unreal, put the model under the anchor and choose **Export selection to GLB…**. In Minecraft, take the house you built out by area, or as the difference from the world you exported. Each becomes a GLB with the anchor inside.
Drop that GLB on [/japan/](https://www.ortho-earth.com/japan/) and it stands where it came from. A model made in Unity and a house built in Minecraft stand side by side in Marunouchi. `map.model()` also uses the GLB's anchor when no position is given. Large models can be turned into 3D Tiles with `glbconv`.
#### Checked in Marunouchi
All three samples are Marunouchi.
- **Unity 6**: the four corners of the placed terrain matched the exported area exactly, and the tallest building, 238 m, stood where Tokyo Midtown Yaesu is. A test point cloud with its anchor deliberately moved 158 m east and 139 m south came back with all four points within about 1 cm. Terrain exported again and read back matched the original in vertex count and extent.
- **Unreal Engine 5.8.4**: the same sample was used to check axis directions and point cloud positions. Nanite meshes export as they are.
- **Minecraft**: the world files are read and written with Node alone. Opened with another reader (Amulet), both the Java and Bedrock worlds matched block for block.
The Unity and Unreal plugins (both 0.1.0) are attached to the GitHub Release. Minecraft is part of `ortho-export`.
### Also new
- **Point clouds.** Sheets are shown side by side without seams, the memory they use has a ceiling, and they can be filtered by class (`map.readPointCloud`). PLY export for Unity.
- **Lines and terrain.** In tilted 3D the edges of wide roads were eaten into by terrain and came out jagged, and nearby lines turned into a string of translucent beads. Both are fixed.
### One tablet, faster for everyone
Over 130 changes went in during those six days. Most of what was added for the tablet became the default on every device. Nothing changes on a fast machine; the more modest the device, the more it helps. Choosing an everyday model was the right call. One Android tablet made the globe lighter for everyone.
Please try it on your own Android or Windows device. If anything looks wrong, a report with the result of [/check/](https://www.ortho-earth.com/check/) attached helps a great deal.
It was not only about speed. Through those six days with Android, the work on Cesium did not stop. A fresh shoot of all 309 Sandcastle examples at the end (v259, v260) raised the same picture from 226 to **234**. Examples that do not run stayed at 0.
| Shoot | 3 | 2 | 1 | 0 | What went in |
| --- | --- | --- | --- | --- | --- |
| v2.3.0 | 226 | 77 | 0 | 0 | The last count before |
| v2.4.0 | **234** | 69 | **0** | **0** | Shapes on terrain, classifying 3D Tiles, Cesium's way of choosing tiles, outlines on lines and points |
Note: 303 examples including those checked by eye (on a real Mac GPU). 3 = same picture, 2 = same answers, 1 = runs, 0 = does not run. Every picture is in the [Sandcastle](https://www.ortho-earth.com/sandcastle/) gallery, side by side with the original. The MapLibre official examples were shot again the same day and held at 91 / 43 / 3 / 0.
- **Shapes on terrain.** GroundPrimitive polygons were placed at 0 m and buried inside the 2.5 km Mount St. Helens. Their outlines are now rebuilt from the triangles and painted along the terrain. A fill on terrain that hid under Cesium's imagery is fixed too.
- **Classifying 3D Tiles.** ClassificationPrimitive boxes for trees and buildings were drawn as translucent solids. Now only the 3D Tiles surfaces inside a box are coloured.
- **Cesium's way of choosing tiles.** For Cesium's imagery layers only, the distance to a tile is now measured to its point nearest the eye. Keeping the small tiles in front of ridges brought the fog example from 56.6% to 95.0% and the point cloud example from 58.2% to 91.7% of the real thing.
- **Lines and points.** Entity outlines are 1 px like Cesium's, path outlines (polylineOutline) and glow (PolylineGlow's thin core and soft halo) are drawn, and point outlines sit outside pixelSize. A cos φ applied twice when choosing imagery detail is fixed.
On a globe that runs light on an everyday device, Cesium code came one more step closer to the real picture.
### And on to v3
With this, the work on v2 is nearly done. I have started to think about v3. WebGPU now works in almost every browser: Chrome and Edge on computers, Chrome on Android, and Safari on iPhone, iPad and Mac (from 26). Firefox is getting there too. And these six days showed that it runs well enough on an everyday device. Until now I have kept everything working the same on WebGL2, and that has held back what the globe could do. For v3 I am thinking of dropping WebGL2 and going WebGPU only. The API will stay the same, so today's code keeps running. It is planned for the end of the year. Stay tuned.
Published: `@ortho-earth/globe` and `@ortho-earth/core` 2.4.0, `@ortho-earth/cesium` 0.3.0 (globe 2.4 or later), `@ortho-earth/voxel` 0.6.2, `glbconv` 0.3.0, and the Unity and Unreal plugins 0.1.0. Same API as 2.3 (`npm i @ortho-earth/globe@2.4`). The knobs that restore the old way of drawing while moving (`?meshshed=0` and others) and `?gl2=1` to go back to WebGL2 on Android are still there.
## Web map engines, feature by feature: MapLibre, Cesium, TerriaJS, Navara and ortho-earth
Source: https://www.ortho-earth.com/docs/story-features
2026-10-21 · Kenji Yoshida
Note added on 11 November 2026: this comparison describes ortho-earth 2.0.2. Since then, of MapLibre's official examples 91 draw the same picture, 43 give the same answers and 3 run only in part (here: 66, 50 and 21), and of 304 CesiumJS Sandcastle examples 264 draw the same picture. The other engines have moved on too. The current scores are always on the [MapLibre](https://www.ortho-earth.com/maplibre/) and [Sandcastle](https://www.ortho-earth.com/sandcastle/) galleries.
### Introduction
In the [previous story](https://www.ortho-earth.com/docs/story-benchmark) I drew the PLATEAU buildings with five engines and compared their speed. This one is its companion: it compares what they can do. I checked each point against the documentation and source of the versions used in the benchmark: MapLibre GL JS 6.15.0 (with deck.gl 9.4), CesiumJS 1.146, TerriaJS 8.13.0 (its Cesium is about 1.142), Navara (@navaramap/three 0.2.1) and ortho-earth (@ortho-earth/globe 2.0.2).
Again, a disclosure first: I am the developer of ortho-earth. I have tried to say where the other engines are strong, and where ortho-earth falls short.
### In short: different starting points
All five are called map engines, but they start from different places. MapLibre grew out of 2D cartography (vector tiles and labels), Cesium out of a 3D Earth with time. Terria is a finished data-viewing app built on Cesium, Navara pairs a Rust GIS core with photorealistic three.js rendering, and ortho-earth puts the MapLibre API on an always-round globe.
So they do not line up on a single scale of more or fewer features. For expressive 2D maps, MapLibre is strongest; for depth in 3D Tiles and time-varying data, Cesium; for a complete kit to gather and present data, Terria; for photorealistic rendering, Navara. What ortho-earth has that no other does is the combination: MapLibre's way of writing a map and Cesium's 3D and clock on one sphere, with rendering moved to a worker.
| | MapLibre (+deck.gl) | Cesium | Terria | Navara | ortho-earth |
| --- | --- | --- | --- | --- | --- |
| What it is | 2D map library | 3D Earth library | Finished data viewer (Cesium + Leaflet) | 3D map library (Rust/WASM + three.js) | 3D globe library |
| Projection | Mercator at heart; globe only at low zoom, turning into Mercator as you zoom in | WGS84 ellipsoid; morphs to 2D and Columbus view | 3D is Cesium, 2D is Leaflet (Web Mercator) | Sphere (ellipsoid) only | Sphere only (ellipsoid optional); flat maps in Equal Earth |
| GPU | WebGL2 (deck.gl is trying WebGPU) | WebGL2 | WebGL2 | WebGL2 (three.js) | WebGPU, else WebGL2 |
| Render thread | Main (tile decoding in workers) | Main (decoding and geometry in workers) | Main (with the React UI) | Main (heavy work in workers) | Render worker (OffscreenCanvas) |
| 3D Tiles | Not in core; overlaid with deck.gl | Nearly all of 1.0/1.1, I3S, point clouds, splats, voxels | Same as Cesium (I3S too) | b3dm, pnts, glb (no i3dm or cmpt yet), splats | b3dm, i3dm, pnts, cmpt, glb, I3S, COPC, splats (plugin) |
| Terrain | raster-dem (hillshade, colour relief) | quantized-mesh, Google, ion | Same as Cesium | raster-dem, quantized-mesh | raster-dem, quantized-mesh |
| Vector tiles | MVT, MLT; home of the style spec | MVT converted to 3D Tiles (1.142+) | MVT baked into images (protomaps) | MVT, PMTiles, partial MapLibre style | MVT, MLT, PMTiles, MapLibre style |
| Labels | SDF text, collision, along lines, vertical | LabelCollection; no collision, grouping via EntityCluster | Same as Cesium | SDF text, along lines, web fonts (no glyph PBF) | Drawn with Canvas2D; collision, along lines, icons, vertical, 26 languages |
| Time | No clock (deck.gl Trips has currentTime) | Clock, Timeline, interpolated CZML | Time slider (WMS time, CSV, CZML) | Sun date, glTF animation | map.clock (CZML, satellites, stars, night side, trips) |
| Picking | queryRenderedFeatures, feature-state | pick, drillPick, pickPosition, tile properties | Feature info panel (templates) | GPU click and hover, terrain/depth position | queryRenderedFeatures, GPU ids, overlays too |
| Analysis | None (add Turf etc.) | Clipping, shadows, sampleTerrain | Split-screen compare, measuring, stories | Shadows, geodesic measuring, terrain height | Shadow and sun hours, viewshed, line of sight, profiles, measuring |
| Look | Sky, fog, light (within 2D) | Atmosphere, shadows, PBR, point-cloud EDL | Same as Cesium (30 fps cap and shadows by default) | Atmosphere, clouds, shadows, SSR, SSAO, depth of field, bloom | Atmospheric scattering, shadows, AO (WebGPU), bloom, clouds |
| Extension points | Custom layers, addProtocol | Primitive, CustomShader, post-processing | New catalog types, init JSON | Four API tiers, plugins, custom Descriptors | definePlugin, custom layers in the worker, three.js |
| Device care | Native is the separate MapLibre Native | Nothing special | Mobile UI | Mobile: 8x coarser LOD, pixel ratio capped at 2 | Touch devices: 3 concurrent fetches, 160 MB GPU |
| Licence | BSD-3 | Apache-2.0 | Apache-2.0 | MIT or Apache-2.0 | GPL-3.0 |
### Projection: how much of it is a sphere
The deepest difference is the projection. With projection set to "globe" in its style, MapLibre draws a sphere at low zoom and moves to Mercator as you zoom in. Underneath it is a Mercator map, and you can read the order of things: the sphere was added later as the view from far away. Cesium is the reverse: a WGS84 ellipsoid in 3D from the start, with 2D and Columbus view made by morphing the 3D scene. Terria keeps two engines and switches between them, Cesium for 3D and Leaflet for 2D.
Navara and ortho-earth have only the sphere. ortho-earth is written so that it cannot switch to a Mercator screen, and it reads MapLibre's projection as globe whatever it says. When a flat world map is needed it has Equal Earth (equal-area) separately, joined to the globe by an unfolding morph. Of the five, only ortho-earth never passes through the Web Mercator plane.
### Threads: where the drawing happens
The free main thread that showed up in the benchmark comes from this difference. MapLibre and Cesium hand tile decoding and geometry building to workers, but draw on the main thread. Terria runs its React UI on that same thread as well. Navara runs its Rust core (Bevy ECS) in WebAssembly and sends heavy work such as terrain meshing to workers, but the per-frame ECS update and the three.js rendering stay on the main thread.
ortho-earth draws the map into an OffscreenCanvas in a render worker. What stays on the main thread is mostly input, UI and the label overlay. The price is that deck.gl's interleaved mode (sharing one GL context) is not available, and it falls back to overlaid. three.js and custom layers passed by URL are drawn inside the worker with the same camera and depth; passed as objects, they land on a separate canvas on the main thread and cannot share depth. That is the honest cost of drawing in a worker.
### 3D data
Cesium is far ahead in 3D Tiles. Its core reads the 1.0 and 1.1 formats, I3S, point clouds, Gaussian splats and voxels, and Cesium3DTileStyle and CustomShader let you style each feature. Since 1.142 it can read MVT by converting it to 3D Tiles, and 1.146 can drape it over terrain and 3D Tiles. Terria is Cesium inside, so it inherits all of this.
MapLibre has no 3D Tiles in its core; in the benchmark I overlaid deck.gl's Tile3DLayer. What it can read is whatever loaders.gl reads, and the MapLibre style cannot touch it. Navara reads b3dm, pnts and glb, but not yet i3dm or cmpt (there is a TODO in the source). ortho-earth reads b3dm, i3dm, pnts, cmpt, glb, I3S and COPC point clouds, with splats added by a plugin.
### Vector tiles and labels
For 2D cartography MapLibre is the original, and the others are judged by how close they get. It has MVT and MLT, expressions, SDF text, collision, labels along lines, and a plugin for right-to-left scripts.
This is also where the five differ most. Cesium's MVT is a conversion to 3D Tiles, styled with Cesium3DTileStyle rather than a MapLibre style. Its LabelCollection has no map-style collision; overlapping labels are grouped with EntityCluster. Terria bakes MVT into images with protomaps, so text becomes a picture painted on the ground and lies flat when you tilt. Navara has a MapLibre style plugin, but support is partial, and it draws text with web fonts rather than glyph PBFs.
ortho-earth is checked against MapLibre's 139 official examples: 66 give the same picture, 50 the same answer, 21 run, and none fail to run. Labels are not GL SDF text but a Canvas2D overlay; collision is thinned so the winners stay stable, and positions are reprojected every frame. Vertical text and 26 languages feel like what you would expect from an engine that began with Japanese maps.
### Time
Treating time as first-class is Cesium's tradition: Clock and Timeline, interpolated CZML positions, even imagery that changes over time. Terria turns this into a time slider for users, playing back WMS time dimensions and CSV time series as they are. MapLibre has no clock; the app expresses time by rewriting the style (deck.gl's TripsLayer has currentTime). Navara's time stops at the sun's position and glTF animation; there is no data clock.
ortho-earth moves the night side, stars, satellites (SGP4), interpolated CZML positions and trips on a single map.clock. The page for people coming from Cesium includes Clock and CZML in its side-by-side table.
### Look
For photorealism Navara has gone furthest. Atmosphere, clouds, cascaded shadows, SSR (reflections on water), SSAO, depth of field, bloom and colour LUTs: three.js post-processing, used on a globe. Cesium is solid, with atmosphere, shadows, PBR and point-cloud EDL. ortho-earth draws shadows, AO, clipping and atmospheric scattering with WebGPU, and on WebGL2 you get the same map without them. MapLibre stays within a 2D map's sky, fog and light.
### Finished product or building block
Terria alone is a finished product rather than a part. A catalog (close to 40 kinds of source, including WMS, ArcGIS, CKAN and SDMX), a workbench, feature-info templates, split-screen comparison, stories, share links and a mobile UI all come with it. That extra is why its JS heap was larger than Cesium's in the benchmark, and if you want a tool for presenting data, the weight is worth what it holds. Cesium's Viewer also bundles a timeline and geocoder widgets, but the other three hand you the map itself, and the app builds the UI.
### Licence
One difference you cannot ignore when embedding: ortho-earth alone is GPL-3.0, while the other four are BSD, Apache or MIT. If you distribute a page that includes ortho-earth, that page's code falls under the GPL too. Any fair comparison should say so in a line.
### Where ortho-earth stands
On breadth alone, ortho-earth covers the widest range of the five: it reaches for both MapLibre's 2D way of writing (style, expressions, queryRenderedFeatures, labels) and Cesium's 3D and time (3D Tiles, I3S, quantized-mesh, CZML, the clock). On top of that, analyses such as sun hours, viewshed and line of sight are in the core.
Against each original, though, it is still the one catching up in depth. Of MapLibre's 139 examples, 21 run but give a different picture or answer, and it has nothing yet like Cesium's voxels or 3D Tiles styling language, or Terria's years of catalog work. The interleaved limit that comes with drawing in a worker, and the GPL licence, are conditions for anyone choosing it.
In performance it sits in the same band as Cesium, and in features it takes the intersection of MapLibre and Cesium on a single sphere. That, I think, is the fair way to describe ortho-earth today.
## Rendering PLATEAU 3D city models: MapLibre, Cesium, TerriaJS, Navara and ortho-earth compared
Source: https://www.ortho-earth.com/docs/story-benchmark
2026-10-20 · Kenji Yoshida
Note added on 11 November 2026: these measurements are of the versions current in October 2026 (ortho-earth 2.0.2). A second round, on a 2018 iPhone and an everyday Android tablet with the latest version of every engine, is in [Measuring performance on phones](https://www.ortho-earth.com/docs/story-benchmark-mobile-jp) (Japanese).
### Introduction
I drew the LOD2 buildings of PLATEAU, Japan's open 3D city model, for Chiyoda ward in central Tokyo with five web 3D map engines under the same conditions, and measured them on three machines of mine: a MacBook Pro, an M1 Mac mini and an iPhone 16 Pro. I learned three things.
1. For the first display, the leaders tie on every machine, and on the Macs even the slowest engine is only about 0.5 s behind. Almost all of the time is spent downloading tiles. On the iPhone, the engines that deliberately hold back fall behind.
2. While the camera moves, every engine sticks to 60 fps, except MapLibre + deck.gl, which does not reach 60 fps on the M1 or the iPhone and needs 1 to 3 s to finish drawing after the camera stops.
3. The same 60 fps hides different work. Cesium does not load while moving, Navara coarsens the picture on phones, and ortho-earth and MapLibre draw while loading. How each engine cuts corners reveals its design.
I should say up front that I am the developer of ortho-earth. To avoid favouring my own engine, I also include reference runs that align each engine's default behaviour, and I describe the strengths and weaknesses of the other engines exactly as the numbers came out. A developer's point of view may still have crept in. The code and raw data are public, so please check them yourself and judge fairly.
### The five engines
All five are open-source map engines that run in the browser, but they come from different places and are good at different things.
**MapLibre GL JS**: one of the most widely used libraries for 2D web maps. When Mapbox GL JS stopped being open source in 2020, volunteers forked the last open version and carried it on. Its job is drawing vector tiles with WebGL, and it cannot read 3D Tiles, so here the buildings are drawn by the Tile3DLayer of the visualisation library deck.gl (born at Uber, now part of the OpenJS Foundation), overlaid on the map. Licence: BSD-3-Clause (deck.gl is MIT).
**CesiumJS**: the standard 3D globe engine. The 3D Tiles format itself came from Cesium and became an OGC standard. It has the longest history of reading 3D Tiles, so it serves as the yardstick here. Licence: Apache-2.0.
**TerriaJS**: built by Australia's national science agency CSIRO (Data61) for the national map site NationalMap. It uses CesiumJS for 3D drawing and adds the parts of a map application on top: a data catalogue, legends and sharing. I loaded PLATEAU into its sample application, TerriaMap. The first version of PLATEAU VIEW was also built with TerriaJS. Licence: Apache-2.0.
**Navara**: a new 3D map engine published under the MapLibre organisation on GitHub (version 0.2.1 here). Decoding and geometry building happen in a Rust (WebAssembly) layer, and drawing is left to Three.js. It offers a graded choice, from the ease of writing only a configuration down to the depth of writing shaders. Licence: MIT or Apache-2.0.
**ortho-earth**: the engine I build. It uses ordinary map tiles but draws the Earth on screen as a sphere. It draws with WebGPU and switches to WebGL2 where WebGPU is not available. Drawing happens inside a worker, which leaves the main thread free. Its API follows the shape of MapLibre GL JS. Licence: GPL-3.0-or-later.
### How I compared them
Every engine loaded the same tileset.json from the same origin and drew only the buildings on a plain background.
| Engine | Version | How it reads 3D Tiles |
| --- | --- | --- |
| MapLibre GL JS | 6.15.0 + deck.gl 9.4.0 | deck.gl Tile3DLayer overlaid (MapLibre alone cannot read 3D Tiles) |
| CesiumJS | 1.146.0 | Cesium3DTileset |
| TerriaJS | TerriaMap, terriajs 8.13.0 (about Cesium 1.142) | a 3d-tiles item in the init file |
| Navara | @navaramap/three 0.2.1 | 3D Tiles source |
| ortho-earth | @ortho-earth/globe 2.0.2 | map.add3DTiles |
- **Data**: PLATEAU Chiyoda ward, buildings LOD2 (untextured), 3D Tiles.
- **Scenarios**: first display (1,500 m above Tokyo Station, looking down at 60°), orbit (one lap of a 1 km radius at 500 m altitude in 30 s), zoom (from 10 km to 300 m altitude in 20 s). Vertical field of view fixed at 45°.
- **Metrics**: time to first display (when the tiles for the initial view have finished loading), fps and 95th-percentile frame time, time from stopping the camera to finishing drawing, memory, and the amount of tiles fetched.
- **Runs**: median of 5 runs each. Cache disabled, browser restarted for every scenario. Each run's screen was captured, and runs with no buildings drawn were discarded.
| Machine | Spec | Browser, display, network |
| --- | --- | --- |
| MacBook Pro | M5 Pro, 64 GB | Chrome, external 4K 60 Hz, Wi-Fi |
| Mac mini | M1, 16 GB | Chrome, 60 Hz display, Wi-Fi |
| iPhone 16 Pro | iOS 18.7 | Safari 26.6, Wi-Fi (the Mac mini served the pages and relayed the tiles) |
To keep differences in features out of the comparison, I aligned the following:
- Drawing resolution 1x (CSS pixels) for every engine. The iPhone screen is 3x, but all engines drew with 1/9 of the pixels.
- Level-of-detail threshold (screen space error) 16 for every engine.
- No MSAA, shadows, terrain, atmosphere or base map. I turned off the default 4x MSAA of Cesium and Terria, and Terria's default 30 fps cap and shadows.
- ortho-earth's dynamic resolution (down to 0.55x under load) was fixed.
- A single sunlight for every engine; Navara was given a noon sun as well.
In this comparison every engine reads PLATEAU's 3D Tiles as they are, and ortho-earth was measured through this general path too. ortho-earth's map of Japan has a dedicated path that converts PLATEAU buildings in advance to a lighter format, serves them, and keeps them on the device for reuse, which displays faster than the numbers here (that path is not part of this measurement).
### Result 1: first display
First display took 4.7 to 8.2 s. On the Macs, the spread within one machine was about 0.5 s. On the iPhone, Navara and ortho-earth fall behind.
Time to first display in seconds, median of 5 runs, vsync on, every engine at its defaults
(My measurements, 19–20 October 2026. MacBook from the re-run on 20 October, Mac mini at 60 Hz, iPhone excluding runs disturbed by sleep. The 5 runs of one engine spread by ±0.3 to 0.5 s.)
Most of the first display is the time to download the roughly 70 to 75 MB (about 110 to 120 tiles) needed for the initial view. The time to fetch a single tile hardly differs between engines; the differences come from the order of loading and how many requests are in flight at once. The top three are within about 0.1 s, less than the spread of five runs of one engine, so read them as a tie, not a ranking.
On the iPhone, two engines deliberately hold back. ortho-earth treats every touch device as low-memory and cuts concurrent tile requests from 6 to 3. Navara makes its level of detail 8 times coarser up close, but that does not affect this initial view (more in "The same 60 fps, different work").
### Result 2: while moving
Apart from MapLibre + deck.gl, the four engines held 60 fps in orbit and zoom on all three machines, with a 95th-percentile frame time of 18 to 21 ms. Finishing the drawing after the camera stopped took under 15 ms.
Orbit (500 m altitude, 1 km radius): fps / p95 / time to finish after stopping
| Engine | MacBook Pro | Mac mini | iPhone 16 Pro |
| --- | --- | --- | --- |
| ortho-earth | 60 / 18.7 ms / 4 ms | 60 / 19.0 ms / 4 ms | 60 / 20 ms / 6 ms |
| Cesium | 60 / 18.5 ms / 14 ms | 60 / 18.4 ms / 8 ms | 60 / 19 ms / 2 ms |
| Navara | 60 / 18.3 ms / 14 ms | 60 / 18.6 ms / 6 ms | 59 / 19 ms / 10 ms |
| TerriaJS | 60 / 18.3 ms / 12 ms | 59 / 18.4 ms / 14 ms | 60 / 19 ms / 7 ms |
| MapLibre + deck.gl | 50 / 15.6 ms / 2.9 s | 40 / 26.8 ms / 0.8 s | 38 / 28 ms / 3.3 s |
MapLibre + deck.gl does not reach 60 fps in orbit even on the fastest MacBook, and keeps adding buildings for 1 to 3 s after the camera stops. Because deck.gl draws on a separate canvas over MapLibre, its displayed fps comes out at about twice the real rate; the table shows how often the screen actually updated (main-thread fps).
Zoom (10 km down to 300 m) has the same shape: 60 fps except MapLibre at 47 to 56 fps. But what "holding 60 fps" means differs between engines, which a later section covers.
### Result 3: memory
ortho-earth's JS heap is an order of magnitude smaller at 15 MB; MapLibre + deck.gl is the largest at about 0.9 GB. Even on the 16 GB Mac mini, swap did not grow for any engine.
| Engine | JS heap | Renderer process | GPU process |
| --- | --- | --- | --- |
| ortho-earth | 15 MB | 1.4 GB | 0.20 GB |
| Cesium | 0.18–0.19 GB | 1.4 GB | 0.37–0.38 GB |
| Navara | 0.15–0.16 GB | 1.8–1.9 GB | 0.40–0.42 GB |
| TerriaJS | 0.24–0.32 GB | 1.5–1.6 GB | 0.40 GB |
| MapLibre + deck.gl | 0.91–0.94 GB | 2.2–2.3 GB | 0.37–0.40 GB |
These are the maxima over the three scenarios in Chrome; ranges reflect the MacBook and the Mac mini. ortho-earth decodes and draws tiles in workers, so its JS heap (the main thread) comes out small. That memory is counted in the renderer process instead, where it is level with Cesium. Safari on the iPhone does not let me measure memory.
### The same 60 fps, different work
Every engine delivers 60 fps, but they cut corners in different places. Cesium and TerriaJS hold back loading while moving, Navara coarsens the picture up close on phones, and ortho-earth and MapLibre draw while loading.
Tiles fetched during zoom (M1 Mac mini, vsync on, 10 km → 300 m, median of 5 runs)
All of these are each engine's default behaviour and work as designed. So, apart from the main tables at the defaults, I ran four reference measurements with that behaviour switched off.
| Reference | Default | Aligned condition | What it shows |
| --- | --- | --- | --- |
| Cesium's culling while moving (cullRequestsWhileMoving and two others), Mac mini | 37 tiles, 5 MB during zoom, 60 fps | No culling: 350 tiles, 129 MB, 60 fps, p95 18.2 ms | Smooth on the M1 even without culling. First display 4.72 → 4.99 s |
| Navara's LOD multiplier on iPhone (8 on mobile) | 81 tiles, 31 MB in orbit, finishes in 10 ms | Multiplier 1: 299 tiles, 112 MB, finishes in 2.08 s | First display (8.16 → 8.46 s) and zoom unchanged; only close views are coarsened |
| ortho-earth's concurrent requests on iPhone (3 on touch devices) | First display 6.99 s (range 6.85–8.72) | 6 requests: 6.32 s (range 6.22–6.70) | The limit of 3 is the bottleneck. Smoothness unchanged, ties with Cesium |
| Cesium without vsync (no frame cap) | First display MacBook 7.31 s, Mac mini 12.2 s | vsync on: 5.91 s, 4.72 s | The uncapped render loop occupies the main thread and tile requests wait |
Cesium's culling is insurance for keeping things smooth on weaker devices; on these three machines, 60 fps held even without it. Navara and ortho-earth are built to hold back on mobile: Navara gives up detail, ortho-earth gives up loading speed. Following this measurement, ortho-earth now lets you set the number of concurrent requests with the maxInflight option of add3DTiles.
### Strengths and weaknesses of each engine
Once the numbers were laid out, my impression of each engine became clear. I start with the engines that are not mine.
**Cesium**: the engine that impressed me most. Even on the M1 Mac mini its 95th-percentile frame time stayed at 18.1 to 18.4 ms, the most even of the five, and it finishes drawing 2 to 14 ms after the camera stops. Its renderer process memory, 1.4 GB, is on the smallest side with ortho-earth. Its culling while moving turned out to be a clever default rather than a shortcut: during zoom it reads only 37 tiles, about a tenth of the others, but the moment it stops it reads what it needs and finishes at once. With culling off, reading the same 350 tiles as the others, it still held 60 fps on the M1. It is smooth without culling; the culling is headroom for the network and the battery. I felt the depth built up over many years by the company that created 3D Tiles showing directly in the numbers. Its weakness appears when the frame cap is removed: the render loop takes over the main thread, tile requests wait, and first display stretches to 12.2 s on the M1. Ordinary browsers have vsync, so the real harm is small, but it was where the limit of drawing on the main thread showed most clearly.
**TerriaJS**: underneath it is about Cesium 1.142, only four versions from Cesium's own 1.146. So on the Macs, I think its gap from Cesium is better read as the overhead of the framework, the catalogue and the UI, than as Cesium's own progress. Indeed, on the Macs its first tile arrives late, at 1.0 to 1.1 s (Cesium about 0.5 s), and its JS heap is 30 to 70% larger than Cesium's. On the iPhone, on the other hand, it tied for first with 5.85 s, faster than Cesium itself (6.32 s). Its default 30 fps cap is also the right, battery-friendly choice for a finished product that shows data.
**MapLibre + deck.gl**: its first tile arrives earliest (0.3 to 0.4 s), and on the iPhone it ties for first display. Its loading itself is fast. But MapLibre does not draw the 3D itself; deck.gl draws it on top. So on the M1 and the iPhone it manages only about 40 fps in orbit, takes up to 3.3 s to finish after stopping, and uses the most memory of the five. This is less a weakness of MapLibre than the weight of combining a 2D map with a second library for 3D. For richness of 2D cartography, I think MapLibre is the best of the five.
**Navara**: still young at 0.2.1, yet it held 60 fps on all three machines, and with the cap removed on the M1 it reached 153 fps in orbit, the most headroom of any. Drawing handed to Three.js is light. Its weakness is per-tile processing, a median of 665 to 911 ms, two to four times the others, which puts it a step behind on first display. Coarsening the picture up close on the iPhone is a deliberate trade to protect smoothness. It is an engine whose growth I look forward to.
### Where ortho-earth stands, and what remains
My own assessment is that ortho-earth sits in the same speed band as the mature Cesium while keeping the main thread free and memory small. On both Macs it tied for first display (5.90 s and 4.66 s), held 60 fps while moving, and finished drawing 3 to 10 ms after stopping. Its JS heap of 15 MB and GPU process of about 0.2 GB are both the smallest, and its per-tile processing, 149 ms on the M1, is the fastest.
Its defining feature is that the whole of drawing runs in a worker; of these five, ortho-earth is the only one that does this by default. With the main thread almost idle, it is built so that heavy UI on top of the map does not drag the drawing down. That said, its renderer process memory as a whole is 1.4 GB, about the same as Cesium, so it is not overwhelmingly lighter in total. And since these test pages do nothing but draw buildings, the benefit of a free main thread is not yet shown in numbers.
To be honest, four problems remained at the time of measurement. First, a brief white flash when the camera stops: it cleared the area of tiles not yet arrived before redrawing, and that is now fixed. Second, the 6.99 s first display on iPhone, because every touch device is treated as low-memory and limited to 3 concurrent requests. With 6 it ties Cesium at 6.32 s, and the number can now be set. These two shipped in 2.1.0 (23 October). Third, extra redraws while the fog catches up after the camera jumps (60 to 80 right after start-up). Fourth, a WebGL error on the page that draws clouds. Both are now fixed as well and ship in the next release. Of the bugs this measurement found, the inability to draw b3dm and the excess redraws at start-up were already fixed in 2.0.2.
### Pitfalls in measuring
Along the way I fell into several pitfalls that badly distorted the numbers. I note them for anyone making a similar comparison.
- **No buildings were drawn**: Navara loads Draco's wasm from a worker by a relative path, so it was not copied into the Vite build and not a single building was drawn. Tile requests are still counted, so the numbers looked plausible. Now every run's screen is captured and runs without buildings are discarded.
- **Some engines keep a cap even with vsync off**: Chrome's uncapping applies only to pages that draw on the main thread. ortho-earth draws in a worker, so about 55 fps is the ceiling of the method. That is why the main tables compare with vsync on.
- **Some engines get slower to first display with vsync off**: Cesium's uncapped render loop occupies the main thread and tile requests wait (12.2 s to first display on the M1).
- **deck.gl's fps comes out doubled**: because the canvas overlaid on MapLibre is counted too. I compared how often the screen actually updated.
- **Two displays cap the fps**: Chrome draws in step with the display it sits on. On the Mac mini the measuring window opened on a 30 Hz secondary display and every engine ran at 30 fps. I fixed the window position and measured again.
- **iPhone sleep and other devices**: the iPhone was measured with a scheme that hands the next step to whichever device opens the serving page. At first results from a Mac browser got mixed in, and the iPhone also stopped when it went to sleep. I checked the device by the browser name recorded in each result and dropped the disturbed runs.
- **Network**: most of the first display is tile download, so it moves by hundreds of milliseconds with network conditions. For the MacBook I show the values re-measured with other work stopped.
### Summary
If all you need is to show PLATEAU buildings, the choice of engine makes no big difference to first display or smoothness. What to look at is less the speed numbers than where each engine cuts corners, and what you want to use it for.
If you want smoothness even on weak devices, Cesium, which culls loading while moving, is the surest choice. If you need a map application with a data catalogue and sharing, TerriaJS sits on top of it. If you already have a 2D MapLibre map, overlaying deck.gl is easy, but on an M1 or an iPhone it cannot hold 60 fps in orbit. If you want to keep loading detail while moving and keep the main thread and memory free, ortho-earth; for drawing headroom and future growth, Navara. That is my reading.
Looking back, this test was a little too light. With only untextured buildings of Chiyoda ward, four engines hit the 60 fps ceiling and their underlying strength was hard to see. Nor did I measure what each engine is truly good at: terrain and base maps, Cesium's time-dynamic data, MapLibre's 2D cartography. Next I plan to widen the area to several central wards, use textured buildings, and give the main thread work of its own.
Once more, at the end: I am the developer of ortho-earth, so I may well be too kind to my own engine in places. Please do not take my assessment on trust; check it against the published pages and data, and judge fairly.
The pages and scripts used for the measurement, and the raw data and screens of every run, are published as [plateau-bench](https://github.com/kenjiyoshidahome2026-bit/plateau-bench) (MIT). Follow its instructions and you can measure your own machines the same way. If you notice bias or errors, please tell me in an Issue.
## モバイルでのパフォーマンスを測ってみた:古い iPhone と Android の普及機で PLATEAU を回す
Source: https://www.ortho-earth.com/docs/story-benchmark-mobile-jp
2026-11-11 · Kenji Yoshida
### はじめに
10 月に、PLATEAU の千代田区 LOD2 建物を Web の 3D 地図エンジン 5 つで描き、Mac 2 台と iPhone 16 Pro で測りました([PLATEAU 3D 都市モデルの描画性能比較](https://www.ortho-earth.com/docs/story-benchmark-jp))。どれも速い機械で、差はあまり出ませんでした。そこで今回は、もっと厳しい機械で測りました。2018 年の iPhone XS と、普及帯の Android タブレット Galaxy Tab A11+ です。エンジンはどれも 11 月 11 日時点の最新版にそろえました。分かったことは 3 つです。
- **Navara は、どの計り方でも崩れませんでした。** 2 台とも周回とズームで画面の上限(59.5〜60.3 fps)を保ち、遅いフレームはほぼ 0 でした。Android の初回表示も振れが一番小さく、かっちり作られたエンジンだと感じました。
- **普及機でも 60 fps は出ます。** ortho-earth と Navara は 2 台とも 60 fps に張り付き、CesiumJS も Android で周回 57 fps・ズーム 60 fps でした。MapLibre+deck.gl は周回で 60 fps に届きません。
- **CesiumJS 1.147 は、古い iPhone でも動くようになりました。** 前の版(1.146)は、XS で読み込み中に落ちていました。1.147 は 1 回なら最後まで完走します。ただし、続けて測ると途中で Safari が落ちました。
先に断っておくと、私は ortho-earth の開発者です。身内びいきにならないよう、条件は全エンジンでそろえ、測った数字のとおりに書きます。
### 比べ方
前回と同じ、PLATEAU 千代田区の建築物 LOD2(テクスチャなし)3D Tiles を、全エンジンに同じオリジンから読ませました。シナリオも同じです。初回表示(東京駅の上空 1,500 m・俯角 60°)、周回(高度 500 m・半径 1 km を 30 秒で 1 周)、ズーム(高度 10 km から 300 m まで 20 秒)を、それぞれ 5 周測り、中央値を取りました。1 周ごとにエンジンの順番を 1 つずらしています。
| | iPhone XS | Galaxy Tab A11+ |
| --- | --- | --- |
| 位置づけ | 2018 年発売 | 現行の普及帯 |
| 中身 | A12 Bionic・iOS 18.7 | MediaTek MT8775・メモリ 6 GB・Android 16 |
| ブラウザ | Safari 18.7 | Chrome 156 |
| 画面 | 60 Hz | 60 Hz(計測の前後で確認)、描画 800×1184 |
| 配信 | Mac から Wi-Fi | Mac から USB |
| エンジン | 版 |
| --- | --- |
| MapLibre GL JS + deck.gl | 6.17.0 + 9.4.1(Tile3DLayer を重ね描き) |
| CesiumJS | 1.147.0 |
| Navara | @navaramap/three 0.3.1 |
| ortho-earth | @ortho-earth/globe 2.4.1 |
エンジンの機能差を混ぜないよう、次の条件をそろえました。
- 描画解像度は全エンジン 1x(CSS ピクセル)。ortho-earth は既定でスマホを 2x で描くので、1x に固定しました。
- 細かさの倍率は全エンジンで同じ。Navara は既定でモバイルの細かさを下げるので、倍率 1 に固定しました。
- 初回表示の完了は「タイルの読み込みが 5 秒止まった時刻」。キャッシュは無効です。
- **2 台を同じ回線で、同時に測りました。** タイルを取り合ううえに、計測中の通信状態にもばらつきがありました。初回表示は目安として読んでください。fps は回線の影響を受けません。
- TerriaJS は描画に CesiumJS を使っているので、今回は特に測っていません。
### 結果 1:動かしたとき
ortho-earth と Navara は、2 台とも周回とズームで画面の上限の 60 fps でした。
| エンジン | XS 周回 | XS ズーム | Android 周回 | Android ズーム |
| --- | --- | --- | --- | --- |
| Navara | 59.5 | 60.0 | 60.3 | 60.2 |
| ortho-earth | 59.6 | 59.6 | 60.1 | 59.9 |
| CesiumJS | —(結果 3) | — | 57.4 | 60.5 |
| MapLibre + deck.gl | 46.8 ※ | ※ | 38.5 ※ | 58.6 ※ |
(fps、5 周の中央値。60 が画面更新の上限。※ は下の注を参照)
遅いフレーム(1 フレーム 33 ms 超)の割合は、周回で Navara が XS 0.2%・Android 0%、ortho-earth が 0.7%・0.1%、CesiumJS が Android 2.4%、MapLibre+deck.gl が 14%・21% でした。
※ MapLibre+deck.gl は、地図の上に deck.gl が別のキャンバスを重ねて描きます。そのため数えた fps が画面の更新と合わず、XS のズームでは 80 fps と、上限を超える値が出ました。主スレッドの更新は周回で XS 23・Android 19 回/秒なので、実際の見た目は表の値より低いと考えてください。MapLibre の本業は 2D のベクトルタイルで、3D Tiles は deck.gl を借りて描いています。
### 結果 2:初回表示
| エンジン | iPhone XS | Galaxy Tab A11+ |
| --- | --- | --- |
| MapLibre + deck.gl | 12.3 秒(10.7〜17.1) | 6.0 秒(5.1〜7.4) |
| Navara | 15.4 秒(11.4〜23.9) | 8.3 秒(6.3〜9.3) |
| ortho-earth | 18.9 秒(11.6〜25.6) | 10.0 秒(8.5〜12.1) |
| CesiumJS | 11.1 秒(1 回) | 10.2 秒(9.4〜14.5) |
(5 周の中央値、括弧内は最小〜最大)
通信状態のばらつきで、同じエンジンでも XS では周によって 2 倍近く違いました。エンジンの間の差はこの振れより小さいので、順位は付けません。その中で Android の Navara は 6.3〜9.3 秒と、振れが一番小さく出ています。
### 結果 3:iPhone XS の CesiumJS
CesiumJS だけを先に単独で 1 回測ると、XS でも初回表示 11.1 秒・周回 56.1 fps・ズーム 60.0 fps で最後まで走りました。前の版の 1.146 は、読み込み中に Safari ごと落ちていました。ただし、他のエンジンと順に 5 周測ると、1 周目のズームで Safari が落ちました。そのため XS の表からは外しています。Android では 5 周とも完走しました。
### エンジンごとに
**Navara**:今回いちばん印象に残ったエンジンです。細かさの倍率を他とそろえて、モバイルでの手加減を外しても、古い iPhone でも普及機でも 60 fps を崩しませんでした。遅いフレームもほぼ出ず、初回表示の振れも小さい。データの解読と形の組み立てを Rust(WebAssembly)で行い、描画を Three.js に任せる作りが、弱い機械でもそのまま効いています。かっちり作られている、というのが素直な感想です。
**CesiumJS**:1.147 で、古い iPhone でも 1 回なら最後まで走るようになりました。Android では周回 57 fps・ズーム 60 fps で、普及機でも十分に滑らかです。
**ortho-earth**:2.4.1 のいちばんの成果は、CesiumJS に機能の面でほぼ追いついたことです。Cesium の公式例(Sandcastle)304 本が全部動き、264 本で同じ絵、残る 40 本も同じ答えになりました。そのうえで性能を見たのが今回の計測です。2.4.1 では 3D Tiles の描き方も軽くしました。片面の建物は裏面を描かず、深度の持ち方を変えて GPU が早めに描かない画素を捨てられるようにしています。その結果、2 台とも 60 fps に届きました。
**MapLibre+deck.gl**:2D の地図では定番の組み合わせですが、3D Tiles を重ね描きすると、弱い機械では周回で 60 fps に届きませんでした。前回の Mac と iPhone 16 Pro でも同じ傾向です。初回表示は、今回も速い側に入っています。
### おわりに
古い iPhone と普及機のタブレットでも、PLATEAU の千代田区を 60 fps で回せるエンジンが、もう複数あります。速い機械だけでなく、多くの人が実際に持っている機械でも、都市の 3D を気軽に見られるようになってきた、というのが今回のいちばんの収穫でした。
ただし、今回の結果には限りがあります。前回と同じく、測ったのは千代田区のテクスチャなしの建物だけで、データの規模が小さすぎました。ほとんどのエンジンが 60 fps の天井に届いてしまい、地力の差は見えていません。ortho-earth が WebGPU で描くことによる速さも、実はまだ評価できていません。XS の Safari 18 には WebGPU が無く、ここでは WebGL2 で動いています。Android では WebGPU で動いていますが、天井に届いているので差が出ません。WebGPU の効き目を確かめるには、都心の複数の区、テクスチャ付きの建物、地形や背景地図まで載せた大規模なデータでの評価が必要です。次はそれを測るつもりです。