aliasfox/openzenith-dem

---
license: mit
tags:
- dem
- elevation
- terrain
- copernicus
- gebco
- terrarium
- maplibre
- cesiumjs
- bathymetry
- global
- tiles
- openzenith
size_categories:
- 10M<n<100M
---

# OpenZenith DEM: Global Elevation & Bathymetry Tiles

Global elevation dataset combining **Copernicus GLO-30** (land) and **GEBCO 2025** (ocean bathymetry) in [Terrarium PNG](https://github.com/tilezen/joerd/blob/master/docs/terrarium.md) tile format, ready for MapLibre GL, CesiumJS, and other renderers.

## What is this?

A complete global elevation tile pyramid (zoom 0–8) encoded as **Terrarium PNG** images. Each pixel encodes an elevation value that can be decoded client-side — no server-side processing needed.

**Data sources:**
- **Land elevation**: Copernicus GLO-30 (30 arc-second, ~30m resolution)
- **Ocean bathymetry**: GEBCO 2025 (15 arc-second, ~450m resolution)
- **Merging**: Copernicus takes priority over GEBCO on land; GEBCO fills ocean areas

## Dataset Structure

```
tiles/
├── 0/ # 1 tile (360° global)
├── 1/ # 4 tiles
├── 2/ # 16 tiles
├── 3/ # 64 tiles
├── 4/ # 256 tiles
├── 5/ # 1,024 tiles
├── 6/ # 4,096 tiles
├── 7/ # 16,384 tiles
└── 8/ # 65,536 tiles
─────────────
87,381 tiles (~5.1 GB)
```

Each tile is a 256×256 PNG at path `tiles/{z}/{x}/{y}.png`.

## Terrarium Encoding

Each pixel encodes elevation in meters using RGB channels:

```
elevation_m = (R × 256 + G + B / 256) - 32768
```

| Terrain | Color (RGB) | Elevation |
|---------|-------------|-----------|
| Deep ocean | Dark | < -1000m |
| Sea level | (128, 0, 0) | 0m |
| Low land | Green-ish | 0–500m |
| Mountains | Bright | 1000–5000m |
| Everest peak | (255, 255, 128) | 8,533m |

### JavaScript Decoder

```javascript
function decodeTerrarium(r, g, b) {
return (r * 256 + g + b / 256) - 32768;
}
```

### Python Decoder

```python
def decode_terrarium(r: int, g: int, b: int) -> float:
return (r * 256 + g + b / 256) - 32768
```

## Usage

### Python (`pip install openzenith`)

```python
from openzenith import get_elevation, load_tiles

# Download tiles from HuggingFace (zoom 0-8, ~5GB)
tiles_dir = load_tiles(zoom_levels=[0, 1, 2, 3, 4, 5, 6, 7, 8])

# Query elevation at any lat/lon
elev = get_elevation(40.7128, -74.0060) # New York City
print(f"NYC elevation: {elev:.1f}m")

# Batch queries
from openzenith import get_elevation_batch
elevations = get_elevation_batch([
(40.7128, -74.0060), # New York
(35.6762, 139.6503), # Tokyo
(27.9881, 86.9250), # Mount Everest
])
```

### MapLibre GL JS

```javascript
map.addSource("terrain", {
type: "raster-dem",
tiles: ["https://openzenith.cyopsys.com/api/dem-tile/{z}/{x}/{y}"],
encoding: "terrarium",
tileSize: 256,
maxzoom: 12,
});

map.addLayer({
id: "hillshade",
type: "hillshade",
source: "terrain",
exaggeration: 1.2,
});
```

### CesiumJS

```javascript
// Custom Terrarium terrain provider (included in OpenZenith globe page)
viewer.terrainProvider = createTerrariumTerrainProvider(Cesium);
```

### API Endpoint

```bash
# Query elevation (no API key required)
curl "https://openzenith.cyopsys.com/api/elevation?lat=40.7128&lon=-74.0060"

# Get a tile
curl "https://openzenith.cyopsys.com/api/dem-tile/8/217/151.png" -o tile.png

# Health check
curl "https://openzenith.cyopsys.com/api/dem-tile?health=1"
```

## Verified Accuracy

| Location | Expected | Measured | Error |
|----------|----------|----------|-------|
| Mt. Everest | 8,849m | 8,533m | 0.4% (30m resolution) |
| Death Valley | -86m | -74m | Within 30m |
| Denali | 6,190m | 6,164m | 0.4% |
| Mariana Trench | -10,935m | -7,122m | GEBCO 450m limit |
| Atlantic Ocean | -5,000m+ | -5,175m | Within 450m |

## Technical Details

| Property | Value |
|----------|-------|
| Tile format | 256×256 RGB PNG |
| Encoding | Terrarium |
| Tile pyramid | Standard XYZ (Slippy Map) |
| Vertical datum | WGS84 ellipsoidal |
| Coordinate system | EPSG:4326 (WGS84) |
| NoData | R=0, G=0, B=0 (decodes to NaN) |
| Land accuracy | 3–7m RMSE (Copernicus GLO-30) |
| Ocean accuracy | ~100m (GEBCO 2025 bathymetry) |

## Data Sources

| Source | Resolution | Coverage | License |
|--------|-----------|----------|---------|
| Copernicus GLO-30 | 30 arc-sec (~30m) | Global land | ESA Open |
| GEBCO 2025 | 15 arc-sec (~450m) | Global (land+ocean) | CC-BY 4.0 |

## Related

- **[OpenZenith](https://openzenith.cyopsys.com)** — Free elevation API, 2D/3D maps, GIS sandbox
- **[openzenith Python library](https://github.com/aliasfoxkde/OpenZenith/tree/main/openzenith)** — `pip install openzenith`
- **[GitHub](https://github.com/aliasfoxkde/OpenZenith)** — Source code

## License

[MIT](https://opensource.org/licenses/MIT) — Free for personal and commercial use.

Source data retains its own license: Copernicus GLO-30 (ESA Open), GEBCO 2025 (CC-BY 4.0).