Become a contributor

Scripted Relief is built by a community of mapmakers. Share the maps you generate, donate the DEM work that powers them, or improve the hillgen code itself.

View on GitHub Request Access

0Install hillgen

One command installs hillgen plus GDAL, the PMTiles CLI, and Python dependencies. Works on macOS and Linux.

curl -fsSL https://raw.githubusercontent.com/emuehlstein/hillshade-generator/main/install.sh | bash

After install, verify with hillgen --version and browse styles with hillgen themes.

1Contribute intermediates

Open · GitHub auth

Every hillgen run downloads a DEM, reprojects it, computes hillshade, and styles it. With --contribute, those expensive intermediate files are uploaded to a shared cache so the next person generating the same area gets instant reuse.

How it works

  • Authenticate with your GitHub account via the gh CLI — no AWS account needed.
  • hillgen exchanges your GitHub token for a short-lived presigned S3 URL through a Lambda broker at api.scriptedrelief.com.
  • Your GitHub username must be on the contributor allowlist. Open a GitHub issue to request access.
  • Intermediates are derived from public-domain data (USGS, state LiDAR programs) — no licensing concerns.

Quick start

# 1. Authenticate with GitHub (one time) gh auth login hillgen auth status # 2. Run anything with --contribute hillgen run --place "Crater Lake" --theme alpine-glacier --zoom 10-16 --contribute
If the upload step fails (e.g. you aren't on the allowlist yet) the run itself still succeeds — only the upload loop bails out with a hint. Your tiles are still produced locally.

2Publish to the gallery

Curator-reviewed · contributor key

Share finished PMTiles maps on the Community Gallery. Each submission gets a preview image, title, caption, and credit line, and is browsable on an interactive map.

Get a contributor key

Gallery publishing currently uses a direct-upload contributor key (AWS credentials scoped to the gallery prefix). Open an issue or ping @emuehlstein to request one.

Publish a map

Add --dry-run to validate the PMTiles file without uploading.

3Contribute code, themes, or DEM sources

Pull requests are welcome. The repo follows a standard fork-and-PR flow with tests run via pytest.

Good first contributions

  • Themes — add a color ramp under hillgen/themes/ramps/ and register it in hillgen/themes/registry.py.
  • State LiDAR sources — implement a new DEM source under hillgen/sources/ following the pattern in wi_dnr_lidar.py or igic_indiana_lidar.py.
  • Bug fixes & docs — see open issues for anything labeled good first issue.

Read first

CONTRIBUTING.mdSetup, conventions, PR checklist ARCHITECTURE.mdHow the pipeline fits together AGENTS.mdGuidance for AI assistants using hillgen ROADMAP.mdWhat's shipped and what's next