Ortho Earth

maplibre + cesium - mercator = ortho-earth. The MapLibre GL JS API you already know, on a 3D globe with terrain and 3D Tiles, and no flat Mercator anywhere: the flat world map is Equal Earth.

A serverless WebGPU/GL2 orthographic map engine and GIS workstation, built from scratch — zero runtime dependencies, no tile servers. Runs entirely in the browser.

top page: www.ortho-earth.com · ortho-japan (flagship 3D map): /japan/ · world globe: /globe/ · GIS-HUB (apps): /gishub/ · MapLibre examples: /maplibre/ · technical documents: /#technologies

Demos:

Guides: MapLibre GL JS code on a 3D globe · Coming from CesiumJS · Equal Earth on the GPU

Why Ortho Earth

• Always a globe. There is no flat Mercator mode to switch to or fall back on: orthographic and perspective are one continuum on a sphere (WGS84 ellipsoid optional), from the whole Earth down to street level. What you see at z2 and at z18 is the same model of the world. MapLibre's projection is read as "globe" whatever it says, and renderWorldCopies has nothing to copy.
• MapLibre code runs on it. @ortho-earth/globe/maplibre is a maplibregl namespace: style.json, expressions, sources (MVT · MLT · PMTiles · GeoJSON · raster · raster-dem · image · video · canvas), addLayer/setPaintProperty/queryRenderedFeatures, paint transitions, light, sky and fog, camera API (FreeCameraOptions, padding, constrain), Markers, Popups, Controls, and typings (maplibre.d.ts). The gate is MapLibre's own example gallery: of 139 official examples, 66 give the same picture, 50 the same answer and 21 run (none fail to run; graded on @ortho-earth/globe 1.16.0). The ledger is packages/globe/maplibre-compat.md; the gallery with every example's source, match score and a Run button is www.ortho-earth.com/maplibre/.
• Extension points, one shape. Every extension is definePlugin({ name, install(map, opts) }), installed with map.use(plugin). Plugins register into map.registry (data kinds, gadgets, tile formats, light types, clouds, post-process passes, handlers, texture transcoders), and map.supports(key) / map.capabilities() answer honestly what is built in, what a plugin renders, and what is only accepted as a spec. Handbook: packages/globe/PLUGINS.md; the ledger of extension points is maplibre-compat.md §9.
• WebGPU first, WebGL2 always. Shadows, ambient occlusion, clipping planes and atmospheric scattering on WebGPU; the same map, minus those, on WebGL2.
• Reads the formats you already have. 3D Tiles (b3dm · i3dm · pnts · cmpt · glb), I3S, COPC point clouds, quantized-mesh and raster-dem terrain, COG, WMS/WMTS, CZML/KML/GPX, GeoParquet, FlatGeobuf, Shapefile, GeoPackage, File Geodatabase, MVT and MLT — in the browser, with no server of your own (: 18 formats in, 14 out).

Quick start

npm i @ortho-earth/globe

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 });

Or keep your MapLibre code as it is:

import 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: 3 });

For Japan, @ortho-earth/japan is a self-contained bundle of the same engine plus the Japan region pack (GSI vector tiles, DEM, PLATEAU buildings, POI, search).

Upgrading from 1.x? 2.0 removes the aliases and internal import paths that 1.x kept for compatibility. MIGRATION.md lists every change, old → new, per package (in Japanese).

Repository layout

The monorepo is one npm workspace (packages/*, sdk/* and apps/*). Parts are arranged in four layers, hard at the top and soft at the bottom, with the SDKs beside them in sdk/ (LAYERS.md):

Layer	Where	What
core	packages/ortho-core (@ortho-earth/core)	Rendering, camera, projection, Gint, overlay contract. Knows no region
globe	packages/globe (@ortho-earth/globe)	The globe host: boot, world layers, region-independent gadgets, the MapLibre face, plugins, SDK types, gates
region pack	packages/jp (@ortho-earth/jp)	A region's declaration (terrain, buildings, basemap, rasters, search, POI, rail) and the parts only that region needs
apps	apps/*	Shells. japan = globe + jp pack + Japanese UI; world, equal, census2020, solar, …
sdk	sdk/*	SDKs and standalone tools for outside users: @ortho-earth/japan (the Japan SDK bundle), React bindings, KTX2, Google 3D Tiles, Google Maps API on MapLibre, scene and splat plugins, glbconv

Region names never appear in core or globe code (the verify:regionless gate counts them). Apps without a region load the shared engine from a versioned, immutable URL (www.ortho-earth.com/globe/engine/<hash>/); the Japan apps are two-stage: shared engine + their own bundle with orthoJapan and the jp pack.

Packages

Package	Version	License	What it is
@ortho-earth/core	2.2.0	GPL-3.0-or-later	Spherical vector-tile rendering engine shared by every ortho app
@ortho-earth/globe	2.2.0	GPL-3.0-or-later	The 3D globe: createGlobe(), MapLibre-shaped API, plugins, data layers, analysis
@ortho-earth/jp	0.0.1 (private)	GPL-3.0-or-later	Japan region pack
@ortho-earth/h3	0.2.0	GPL-3.0-or-later	H3 cells, binning and map.addH3()
@ortho-earth/tile-formats	0.2.0	GPL-3.0-or-later	Format plugins loaded on demand: MLT tiles, LAZ records for COPC
@ortho-earth/ephem	1.3.0	GPL-3.0-or-later	Solar-system ephemeris, shared clock, SGP4/SDP4 satellites
geopbf	2.1.0	MIT	GeoPBF container + Gint topology; converts 18 GIS formats in the browser (workers + WASM)

geopbf and altpbf are also published to standalone repositories as read-only mirrors on each release.

SDKs and tools

Published for outside users from sdk/*.

Package	Version	License	What it is
@ortho-earth/japan	2.0.2	GPL-3.0-or-later	Self-contained Japan globe for any web page: the engine plus the Japan region pack, no API keys or servers
@ortho-earth/react	0.1.0	GPL-3.0-or-later	React bindings for the globe
@ortho-earth/google3d	0.2.0	GPL-3.0-or-later	Google Photorealistic 3D Tiles: API key and session handling plus attribution
@ortho-earth/gmaps	0.2.0	GPL-3.0-or-later	Google Maps JavaScript API on MapLibre: a google.maps namespace (Map, Marker, InfoWindow, shapes, Data, geometry) for maplibre-gl or the globe; with an API key, Geocoder, Directions, Places and Street View are relayed to Google
@ortho-earth/leaflet	0.1.0	GPL-3.0-or-later	Leaflet on MapLibre: an L namespace (map, marker, popup, tooltip, tileLayer / WMS, polyline, polygon, circle, geoJSON, controls) for maplibre-gl or the globe
@ortho-earth/ktx2	0.1.0	GPL-3.0-or-later	KTX2 / Basis Universal texture transcoder for glb models and 3D Tiles
@ortho-earth/scene

Apps

Every page under apps/* is a shell over the packages above. The ones that are public today:

URL	App	What it shows
/japan/	apps/japan-map (served by apps/japan-host)	The flagship: Japan from public data only (GSI, PLATEAU, JAXA). Also /japan/terrain, /japan/parks, /japan/models, /japan/fireworks, /japan/scene, /japan/tellus, /japan/geoedit
/globe/	apps/globe-map (served by apps/globe-host)	The world globe. /globe/physical (landforms), /globe/parks (US national parks), /globe/sats, /globe/clouds, /globe/?start=equal (Equal Earth)
/globe/engine/	apps/engine	The shared engine: one versioned build of @ortho-earth/globe and the modules two or more apps use, loaded by URL
/globe/quakes/	apps/quakes	World earthquakes since 1967 at their true hypocenter depth (data: apps/quakes-mirror + USGS, fetched by the browser)
/world/	apps/world	Nations of the world as cards
/quiz/	apps/world-quiz	Geography quiz on the globe
/japan/census2020/	apps/census2020	Japan's 2020 census, small-area statistics and risk zones
/solar/

apps/uploader (bakes data and puts it in the bucket), apps/account (per-user file storage Worker), apps/quakes-mirror and apps/sats-mirror (Workers that mirror the USGS and CelesTrak feeds) are internal.

Development

Node 22.18 or newer (the tests import .ts sources directly, which needs Node's built-in type stripping) and npm. npm install at the root installs every workspace.

• npm run dev:www — the top page with the demo cards; each app has its own npm run dev -w <app> (for example -w japan-map, -w globe-map).
• npm run build:all — builds www, geopbf-demo, gishub-jp and world and assembles apps/www/dist (docs, geopbf, gishub-jp, world, the shared engine).
• Each package README documents its own API; packages/globe/README.md is the place to start for the engine, packages/geopbf/README.md for the data layer.

Tests

npm test at the repository root runs every Node-only test suite in the monorepo (scripts/test-all.mjs: the suites of each workspace are unrolled to their test files, about 190 of them, and run in parallel, no browser or network needed; npm run test:list shows the files, npm test -- geopbf runs a subset, TEST_JOBS=1 runs them one by one). npm run verify:i18n at the root runs the i18n gates of all apps. Browser suites stay per package: npm run verify:ui / verify:webgpu / verify:nocoi / verify:examples in packages/globe, npm run verify:ui / verify:webgpu / verify:prod in apps/japan-map (verify:prod in apps/japan-host), npm run verify:pages in packages/geopbf, npm run verify:gpu in apps/equal. They drive a pinned headless Chrome for Testing (downloaded once, about 150 MB, to ~/.cache/ortho-earth/chrome-for-testing; npm run chrome:install in packages/globe fetches it ahead of time, CHROME=<path> overrides it). It is a separate app from your everyday Google Chrome, so a running suite never blocks you from opening Chrome. The WebGPU suites need a real GPU.

Deploying

There is no CI/CD workflow in this repository (only GitHub's CodeQL scan runs on push). Publishing is done from a machine with a logged-in wrangler:

• Shared engine (apps/engine, Worker ortho-engine): npm run deploy:engine at the root. It first builds globe-host and runs its verify:prod against the new engine, then deploys the engine, then every app that loads it (globe-host, census2020, ortho-nl, quiz, choju, yokohama, world, equal, japan-host). Each app's own deploy refuses to go out if the engine version it was built against is not live yet.
• Workers (ortho-japan, ortho-globe, world, ortho-equal, census2020, ortho-solar, ortho-nl, ortho-himekuri, ortho-world-quiz, …; one wrangler.toml per app): npm run deploy -w <app>. Each app's deploy script runs its own gates first (i18n tables, verify:prod, tests) and then wrangler deploy; apps/japan-host uses scripts/deploy.mjs.
• www (www.ortho-earth.com, Cloudflare Pages): published automatically when main is merged, through the Pages Git integration. No manual wrangler pages deploy is needed.
• Order matters. Because www goes live on merge, deploy the Workers first, and the shared engine before the apps that load it (its URL is a content hash of its build; older entry points are redirected to the current version by the ortho-engine Worker).
• Bulk data (world, space, GeoPBF archives) lives in a Cloudflare R2 bucket and is uploaded with apps/uploader.

Contributors & Acknowledgments

This project is fully engineered and conceptualized by Kenji Yoshida. I also acknowledge the invaluable support of my AI collaborators:

• Claude (Anthropic) & Gemini (Google) - AI Collaborators for architectural ideation, coding, and technical writing.

License

• Engine, apps & SDKs (@ortho-earth/core, @ortho-earth/globe, @ortho-earth/jp, @ortho-earth/h3, @ortho-earth/tile-formats, @ortho-earth/ephem, quiet-mono, apps/*, sdk/* except glbconv): GPL-3.0-or-later
• Data formats & utilities (geopbf, geoedit, altpbf, glbconv, native-bucket, common, himekuri, apps/world): MIT
• Data package (world-data, including its sky/ names): CC BY-SA 4.0 (lunar place names from USGS are public domain)

For commercial use without GPL obligations, a separate commercial license is available — contact [email protected].