# kpterrain

> Free CesiumJS terrain for the contiguous United States from USGS 3DEP: 1 m lidar (S1M) where USGS has it, 10 m (1/3 arc-second) everywhere else. Quantized-mesh 1.0 with vertex normals. No account or API key.

## How to add it to a CesiumJS app

Prefer option 1. Use option 2 only when the tool accepts nothing but a terrain URL.

### Option 1 (recommended): the client module

It reads PMTiles archives with HTTP range requests, served from Cloudflare's cache. It is dependency-free, tested with CesiumJS 1.134, and needs a browser with `DecompressionStream` (all current browsers; Safari 16.4+).

```js
import { createUsgsTerrainProvider } from "https://kpterrain.com/sdk/usgs-terrain.js";

const viewer = new Cesium.Viewer("cesiumContainer");
viewer.terrainProvider = await createUsgsTerrainProvider(Cesium);
```

- The first argument is the Cesium namespace: the `Cesium` global (script-tag builds) or `import * as Cesium from "cesium"` (bundlers).
- It returns a Promise of a `TerrainProvider`; await it before assigning it.
- To pin a version, copy https://kpterrain.com/sdk/usgs-terrain.js into the project and import it locally.
- Other exports: `DEFAULT_URL`, `archivePath`, `tileId`, `createArchiveReader`, `decodeQuantizedMesh`, `gunzip`.

### Option 2: stock Cesium terrain URL

```js
viewer.terrainProvider = await Cesium.CesiumTerrainProvider.fromUrl(
  "https://tiles.kpterrain.com/terrain/conus/", { requestVertexNormals: true });
```

Until the rebuild finishes (progress: https://tiles.kpterrain.com/status), this URL serves the previous dataset. It then switches to the new data in place, and the URL does not change.

## Facts to rely on

- Coverage: contiguous US. Zooms 0-15 from the 10 m base; zooms 13-17 from S1M where it exists. There are no tiles above zoom 17; Cesium refines zoom 17 for closer views.
- Heights: NAD83(2011) ellipsoid heights in metres (NAVD88 + GEOID18). They are not orthometric; subtract the GEOID18 undulation to get NAVD88 elevations.
- Horizontal: NAD83(2011) coordinates labelled WGS84 with no datum shift (EPSG:9774 null convention). It matches NAD83 lidar and survey data, and sits about 1-1.5 m from ITRF/GNSS positions. Do not apply a Helmert shift.
- Outside US data: Copernicus GLO-90 in Canada and Mexico; sea level over the ocean.
- Tiling: geographic TMS (EPSG:4326), y counted from the south, as in Cesium's quantized-mesh URLs.
- Freshness: new and updated USGS data is picked up within a day, and layer.json lists every available tile.
- Sampling heights: use `Cesium.sampleTerrainMostDetailed(provider, cartographics)` with either provider.

## Attribution (required)

Show the provider's credit; Cesium does this automatically. Data: U.S. Geological Survey 3D Elevation Program (public domain). Outside US coverage: Copernicus DEM GLO-90 © DLR e.V. 2010-2014 and © Airbus Defence and Space GmbH 2014-2018, provided under COPERNICUS by the European Union and ESA.

## Do not

- Do not scrape or bulk-download the tile archives; use the provider.
- Do not use tiles.kpterrain.com/terrain/conus-v2/*.pmtiles URLs as a stock Cesium terrain URL; they are archives, read by the client module.

## Links

- [Landing page](https://kpterrain.com/)
- [Client module](https://kpterrain.com/sdk/usgs-terrain.js)
- [v2 layer.json (archive layout)](https://tiles.kpterrain.com/terrain/conus-v2/layer.json)
- [Rebuild progress](https://tiles.kpterrain.com/status)