MapStage README

The project's README from github.com/hopechen067/MapStage. As one markdown file: README.md.

MapStage

English | 中文

Open-source MapStage tuner: map and globe projection, satellite, hypsometric relief, 3D terrain, region isolate, and JSON presets.

Live demo

→ https://hopechen067.github.io/MapStage/
Interactive tuner (EOX satellite + Mapterhorn DEM need internet. No install.)

What's new

Showcases

Current tuner: national map, 3D terrain, globe, isolate.

Tuner national map view
Tuner · national view (map) 		Tuner 3D terrain
Tuner · 3D terrain
Tuner globe projection
Tuner · globe 		Tuner isolate China terrain island
Tuner · isolate
Item Value
Skill folder mapstage
Runtime MapStage
Default basemap EOX Sentinel-2 cloudless (public demo WMTS; check provider terms)
Terrain / hillshade Mapterhorn DEM (runtime fetch; Terrarium encoding)
Water OpenFreeMap / OpenMapTiles vector water
Look CSS color grade, map/globe, isolate island, HanCity3D settlements
License MIT for code/docs; showcase media & third-party terms in LICENSE-EXCEPTIONS.md / NOTICE.md
Hosted demo Live demo — Pages publishes mapstage/tuner to the site root

Quick pull (install)

git clone pulls the whole repository, not a standalone skill.
You get README, showcases, the tuner, and the mapstage/ skill folder. Agents do not auto-discover that folder from a clone. Copy mapstage/ into your skills directory (step 2) if you want the agent skill.

1) Clone the repo

git clone https://github.com/hopechen067/MapStage.git
cd MapStage

Update later:

cd MapStage
git pull

2) Install as an agent skill

Skill folder (browse, not a second clone): mapstage/

One command — installs only that folder:

npx skills add hopechen067/MapStage --skill mapstage -g

GitHub CLI 2.90+:

gh skill install hopechen067/MapStage mapstage --scope user

Then reload skills. On Windows, add --copy to the npx command if symlink creation fails.

Or after a full clone, copy mapstage/ into your agent's skills directory.

3) Paste this to your agent

请使用 MapStage skill。
在线调参：https://hopechen067.github.io/MapStage/
仓库：https://github.com/hopechen067/MapStage
我会在 demo 里调好风格后导出 JSON，请按 SKILL.md / references 应用到地图场景（jumpTo + idle，encoding terrarium）。

Style workflow: open the live demo → tune → Copy JSON → paste to your agent.

Quick start (local tuner)

The live demo already runs on GitHub Pages. You do not start a server on your computer to use it.

Only if you want to edit files or preview offline do you start the tuner locally. Run the command on your machine; when it is up, open the local URL printed in the terminal (do not use file://).

cd mapstage/tuner

# Option A — Python 3
python -m http.server

# Option B — Node
npx --yes serve

Optional check (Node on PATH):

cd mapstage/tuner
node verify.mjs

Features

Configure map tiles

  1. Read NOTICE.md.
  2. Defaults: tuner/map-tiles.config.js (EOX + Mapterhorn).
  3. Personal endpoints: map-tiles.config.local.js (gitignored). See map-tiles.config.example.js.

EOX public tiles are typically non-commercial with attribution (~10 m). This project does not grant rights to any commercial map vendor.

Tiles are not bundled

Satellite and DEM tiles are fetched at runtime from configured URLs only.

Attribution & compliance

Install as an agent skill

The GitHub repo is the full project. The skill is only mapstage/.

  1. Install with npx skills add hopechen067/MapStage --skill mapstage -g, or gh skill install hopechen067/MapStage mapstage --scope user, or copy mapstage/ into your agent's skills directory.
  2. Reload agent skills so SKILL.md is discovered.
  3. Ask the agent to open the tuner, apply an exported JSON preset (version 3), or wire the same look into a MapStage scene.

Layout

.
├── LICENSE
├── LICENSE-EXCEPTIONS.md      # showcase / third-party / user geodata (not MIT)
├── NOTICE.md
├── DATA-PROVENANCE.md
├── SECURITY.md
├── README.md / README.zh-CN.md
├── showcases/                 # README images & sample frames
└── mapstage/
    ├── SKILL.md
    ├── agents/openai.yaml
    ├── references/
    ├── schemas/
    └── tuner/                 # published to GitHub Pages site root

Contributing / security

Next reads

MapStage (hopechen067/MapStage)

Searching Database…

479 ·GitHub
MapStage
What is this?MapStage is an open-source live tuner for maps and globes — you tweak satellite imagery, hypsometric relief, 3D terrain and region-isolate effects, then export the look as a JSON preset. It also ships as an installable 'agent skill' so AI coding agents can drive the same tuner.
Is this a web app I open in a browser, or something I install as an agent skill?Both — there is a live demo hosted on GitHub Pages you can use directly with no install, and the repo also contains a 'mapstage/' folder that can be installed separately as a skill for AI coding agents.
How do I get started with the tuner?Just open the live demo and use 'Copy JSON' to export a preset — no install needed. To edit or run offline, clone the repo and run the local tuner command, then open the local URL printed in the terminal (not file://).
Do I need internet access to see satellite imagery and terrain?Yes — the default EOX Sentinel-2 satellite basemap and the Mapterhorn DEM terrain/hillshade are fetched at runtime from external servers and are not bundled with the project.
Can I use the default satellite tiles commercially?No by default — the EOX tiles are typically non-commercial with attribution required, and the project grants no rights to any commercial map vendor; you can swap in your own licensed tile URL via a gitignored local config file.
Can I use my own map tiles instead of the default satellite imagery?Yes — create a map-tiles.config.local.js (gitignored) pointing at any tile URL you're licensed to use; it overrides the default EOX Sentinel-2 cloudless basemap.
What does 'region isolate' do?It's an optional mode that isolates a chosen region from the surrounding map, turning it into a standalone 3D terrain island.
What are the 'city tiers' feature?HanCity3D renders settlements by tier — capital, large, medium, small, pass, station and ordos — letting you control which cities and markers appear as you zoom.
Can I save and reuse a look I create in the tuner?Yes — the 'Copy JSON' button exports a versioned preset including camera position and resource switches, which you can paste back into the tuner or an agent.
What are similar projects?maplibre-gl-js, GeoLibre, gods-eye-view, cesium, turf, fireworks-open-eli5, city-roads, marco-polo.skill
Which topics is it in?maplibre, mapping, gis, geospatial, github-pages, interactive, agent-skill, visualization, 3d, skill, china, web-app
Creator
hopechen067
Size
35 MB
Stars
479
Updated
CommitSep 13
Age
2mo
Commits · 90 Days