Geo Tutorials

A step-by-step series for the Taos geo module — planet-scale geospatial streaming on top of the standard renderer. Each tutorial is short, runnable, and builds on the one before it.

These tutorials are the guided path; the Geo module guide is the reference. Read the Quick-Start Guide first — everything here assumes you know Engine, GameObject, Camera, and the deferred preset from the "Hello, Cube" project.

Runnable code. Every tutorial below has a working, build-verified entry in the standalone project standalone/geo_tutorials/ — one page per tutorial, plus a ▶ live launcher. Run npm install && npm run dev there and open the launcher, or copy an entry to start your own app. The smallest starting point is standalone/hello_cube/ (▶ live). Each tutorial page also has a "▶ Live demo" link at the top.

The path#

#	Tutorial	You'll learn
1	Hello, Geo	A complete streaming-globe app: floating origin, two keyless OSM sources, a fly camera. The geo equivalent of Hello Cube.
2	The Floating Origin	Why ECEF shreds f32, how `GeoFrame` rebases the world, and reanchoring as you fly.
3	Tileset & Imagery Layers	Stacking terrain + buildings + photorealistic tiles, and draping multi-layer imagery (base map + labels).
4	Anchors & Picking	Planting glTF models at lat/lon, casting screen rays to the globe, and picking per-feature metadata.
5	Atmosphere & Clouds	A curved-horizon physical sky and volumetric clouds wrapped around the planet.
6	Clipping	Cutting away tiles and terrain with geodetic clipping planes and polygons.
7	Vector Data	GeoJSON layers, declarative 3D-Tiles styling, and CZML time-dynamic animation.
8	Projection Textures	Casting an image onto terrain and buildings with a `Projector` — map-overlay drape or perspective slide, lit or unlit.
9	Terrain Physics	Building Jolt colliders from streamed terrain so things can roll down real mountains.
10	Other Worlds	The Moon and other bodies (`GeoFrame.atEcef`, custom ellipsoids), plus Google Street View.

Reference tutorials#

These two aren't steps in the linear path — read them when you're choosing data or chasing framerate, at any point in the series.

#	Tutorial	You'll learn
11	Data Sources	Every source the geo module streams — OSM, AWS, Cesium ion, Google Map Tiles, Gaussian splats, Street View — keyless vs keyed, and the one-line call that wires each in.
12	Performance, Quality & Debugging	The detail-vs-framerate knobs (`maxSSE`/pixel error, memory budgets, render distance, preloading, worker decode), plus the debugging tools: wireframe overlay, data-source/cache log, LOD stats, and attribution.

Additional render features#

Standalone feature deep-dives, readable any time after the path.

#	Tutorial	You'll learn
13	Water & Point Clouds	Two render features that draw over the lit scene: Cesium-style translucent water from a terrain mask, and `.pnts` point clouds with eye-dome lighting.

Conventions in these tutorials#

Imports use the taos/<subdir>/index.js form an external consumer writes (see the import conventions). Inside this repo, the same modules are relative paths (../src/geo/index.js); the samples cited in each tutorial use the relative form.
Keyless by default. Tutorials 1–9 stream entirely from keyless, no-account sources: AWS Terrarium elevation + OpenFreeMap vector-tile buildings + OSM/Esri/Carto imagery. The only exception is tutorial 10 (the Moon, which uses Cesium ion — get a free Bearer token at https://cesium.com/ion/tokens) and its optional Google Street View panel (a Google Maps key). Higher-fidelity ion terrain/buildings remain a drop-in swap anywhere — see tutorial 3.
Every tutorial cites the sample it's distilled from. When in doubt, the sample under samples/ is the ground truth.