refactored-recon/CONTOUR-REBUILD.md

Contour Tile Rebuild — Terrarium DEM Alignment Fix

Problem

Contour lines are misaligned from hillshade terrain. Root cause:

• Contours: built from SRTM HGT (EPSG:4326, ~30m resolution)
• Hillshade: built from Mapzen Terrarium (EPSG:3857, ~10m at z12)

Different DEMs = different elevation values at same coordinates = visible offset.

Solution

Regenerate contours from the same Terrarium DEM tiles used for hillshade. The hillshade-na.pmtiles file contains 93GB of Terrarium-encoded RGB PNGs. Decode elevation from those tiles, generate contours. Same pixels = guaranteed alignment.

Infrastructure

Resource	Location	Specs
Compute	cortex (192.168.1.150)	i9-10900X, 16 cores, 22GB RAM
Storage	pi-nas NFS /mnt/pi-nas	16TB free on /export/data
Source DEM	hillshade-na.pmtiles	93GB, z0-12, Terrarium encoding
Tools	cortex	GDAL 3.8.4, tippecanoe, pmtiles

Terrarium Encoding

elevation_meters = (R * 256 + G + B / 256) - 32768

Source tiles are EPSG:3857 (Web Mercator), 256x256 PNG, z0-12.

Output Specification

Must match existing contours-na.pmtiles structure for frontend compatibility:

{
  "layer": "contours",
  "attributes": {
    "elevation_ft": "Number",
    "elevation_m": "Number", 
    "tier": "String"  // "minor" | "intermediate" | "index"
  },
  "zoom": "4-14",
  "format": "MVT"
}

Tier mapping:

• 40ft interval → tier: "minor"
• 200ft interval → tier: "intermediate"
• 1000ft interval → tier: "index"

Regions

Process in chunks to fit RAM:

Region	Bounds (W,S,E,N)
alaska	-168,51,-130,72
canada-west	-141,48,-90,72
canada-east	-90,42,-52,72
conus-west	-125,31,-104,49
conus-central	-104,25,-84,49
conus-east	-84,24,-66,48
mexico	-118,14,-86,33
caribbean	-86,14,-59,28

Pipeline Phases

Phase 1: Extract DEM from Terrarium PMTiles

1. Read z12 tiles from hillshade-na.pmtiles
2. Decode Terrarium RGB → elevation (meters)
3. Mosaic into regional GeoTIFFs (EPSG:3857)
4. Reproject to EPSG:4326 for gdal_contour

Phase 2: Generate Contours

For each region:

# Convert meters to feet
gdal_calc.py -A region.tif --outfile=region_ft.tif --calc="A*3.28084"

# Generate contours at all intervals
gdal_contour -a elevation -i 40 -f FlatGeoBuf region_ft.tif region_40ft.fgb
gdal_contour -a elevation -i 200 -f FlatGeoBuf region_ft.tif region_200ft.fgb
gdal_contour -a elevation -i 1000 -f FlatGeoBuf region_ft.tif region_1000ft.fgb

Phase 3: Build Vector Tiles

1. Add tier attribute and merge intervals into single FGB per region
2. Generate mbtiles with tippecanoe:

   tippecanoe -o region.mbtiles -l contours -Z4 -z14      --no-feature-limit --no-tile-size-limit      --simplification=10 region_merged.fgb
   

3. Join all regions: tile-join -o contours-na.mbtiles *.mbtiles
4. Convert: pmtiles convert contours-na.mbtiles contours-na.pmtiles

Phase 4: Deploy

1. Copy to VM 130: /mnt/nav/tiles/contours-na.pmtiles
2. Verify with pmtiles show
3. Browser test at navi.echo6.co

Workspace

/mnt/pi-nas/nav/contour-rebuild/
├── dem/           # Regional GeoTIFFs (keep for future rebuilds)
├── contours/      # Intermediate FlatGeoBuf files (delete after)
├── tiles/         # Output mbtiles and pmtiles
├── logs/          # Timestamped logs per phase
├── scripts/       # Pipeline scripts
└── backup/        # Original contours-na.pmtiles backup

Verification

After deploy, manual browser test:

1. Hard refresh navi.echo6.co
2. Toggle contours on
3. Zoom to Twin Falls / Snake River Canyon
4. Contour lines should align precisely with hillshade canyon walls

Constraints

• All operations as zvx (pi-nas root_squash)
• Do not modify hillshade-na.pmtiles (read only)
• Do not touch frontend code
• Keep intermediate GeoTIFFs for future interval changes
• Delete .fgb and .mbtiles after final pmtiles verified

Created

2026-04-27 — Alignment fix rebuild