MapStage skill
The MapStage skill tunes how a map or globe looks: projection, satellite, relief, 3D terrain, region isolate and JSON preset export
- 499 ★ on the repository
- Last commit
- MIT
Extended access
Why this level
- The tuner page loads tiles and relief data from external EOX, Mapterhorn and OpenFreeMap addresses
- Running the tuner locally starts an HTTP server from the project folder
- Data sources have their own terms of use, and the repository contains a license exceptions file
Install
- Works in
Manual install
npx skills add hopechen067/MapStage --skill mapstage -gInstalls only the mapstage folder, not the whole repository.
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- The tuner page loads tiles and relief data from external EOX, Mapterhorn and OpenFreeMap addresses
- Running the tuner locally starts an HTTP server from the project folder
- Data sources have their own terms of use, and the repository contains a license exceptions file
This is third-party code. Review the repository files before installing.
What it does
MapStage helps an agent build and tune a MapLibre map scene: switch between a flat map and a globe, blend in satellite imagery and hypsometric relief, raise 3D terrain and isolate a region as a separate island. The look is tuned in a live tuner page with sliders, and the result exports as a version 3 JSON preset with projection, layer switches and camera. The skill sets the working order. First open the demo at https://hopechen067.github.io/MapStage/ or a local server from the tuner folder. Then apply the antique-default preset, settle the look, export the JSON and move it into the production scene. Relief and hillshade use Mapterhorn DEM with terrarium encoding, water comes from OpenFreeMap vector layers, and satellite defaults to EOX Sentinel-2 cloudless. The references folder holds parameter tables, a settlement tier schema (capital, large, medium, small, pass, station, ordos) and a workflow description, and schemas holds JSON schemas for the preset and the site list.
Who it is for. For developers and designers who build map scenes and video on MapLibre, such as historical maps, and want to tune the look without editing code.
Good fit when
- You need a live page with sliders for projection, satellite, relief and color grade instead of tuning values in code
- The map look has to be locked and exported as JSON to move into another application
- The map needs settlements by tier: capital, large, medium, small, pass, station
- You need a region isolated as a separate relief island over a globe
- Frames are recorded for video, so the camera moves with jumpTo and waits for the idle event
Not a fit when
- You need a ready host for final rendering: the skill explicitly forbids rendering the final output from the tuner page
- The task is geocoding, routing or place search rather than map styling
- You cannot use the public EOX and Mapterhorn tiles and are not ready to put your own addresses in the config
- You plan to use easeTo or flyTo for recorded frames: the skill advises jumpTo and idle
Example request
Open the MapStage tuner, apply the antique-default preset, turn on the globe with relief and export JSON for my sceneLimitations
- Tiles are not bundled: MapStage fetches relief and basemap at runtime from configured addresses. Use only sources you are allowed to use.
- The relief source must set encoding: 'terrarium', otherwise hillshade and terrain break.
- The demo with EOX satellite and Mapterhorn DEM needs internet.
- Next to the MIT license the repository has LICENSE-EXCEPTIONS.md and DATA-PROVENANCE.md with exceptions and data origins; read them before publishing a result.
How to disable. Delete the mapstage folder from the agent's skills directory. The npx skills add install brings only the mapstage folder, not the rest of the repository.
FAQ
How do I install the MapStage skill?
With npx skills add hopechen067/MapStage --skill mapstage -g. Cloning the whole repository gives you the full project with the demo and showcases, while the skill itself is only the mapstage folder.
What is the tuner in MapStage?
An HTML page with sliders for projection, satellite, relief, region, CSS color grade and settlements. It opens at the public demo address or locally with python -m http.server in the tuner folder, and the result exports to JSON.
Why not render final frames in the tuner?
The skill says the final render comes from the production scene, not the tuning page. For recorded frames the camera must move with jumpTo and wait for idle, without easeTo and flyTo.
Where does MapStage get maps and relief?
The default basemap is EOX Sentinel-2 cloudless, relief is Mapterhorn DEM with terrarium encoding, and water comes from OpenFreeMap vector layers. Addresses are set in tuner/map-tiles.config.js and can be overridden with a local file.
Which settlement tiers does MapStage have?
Seven tiers: capital, large, medium, small, pass, station and ordos. The schema is described in references/city-tier-schema.md, and the site list format is defined by the sample-sites.schema.json JSON schema.
Discussion
No questions or reviews yet.
Related
SkillsA skill that turns your photo or description into a hand-drawn character and uses it for diagrams, knowledge cards and slides
A loop skill: the agent generates a target screenshot, builds toward it, and uses a critic subagent to close the gap until they match
A skill that turns a topic into a short animated card with facts from found sources and Live Photo assets for the iPhone
A skill that draws interactive isometric illustrations in SVG, with WebGL shaders and React output, explaining an idea as a working machine
3dviz Pro Max
3dviz-pro-max
A skill for 3D visualizations (Three.js, Blender, glTF): an idea becomes a scene. Screen capture is optional through Playwright. Some demos are historical
Skills, a CLI and an MCP server that let Claude Code or Codex make video from a brief: editing, graphics, voiceover, subtitles
Comparison with similar tools
Entries that share the main search query, and how they differ.
| Entry | Official | Authentication | Repository stars | Main difference |
|---|---|---|---|---|
| MapStage (this entry) | no | 499 | ||
| Mapbox MCP Server | yes | OAuth | 363 | Mapbox's official MCP for geocoding, place search and routing, while MapStage styles how the map looks |
| yandex-maps-v3 | no | 1 | a reference skill for the Yandex Maps JS API v3 with markers and clustering, with no relief or globe tuning |
README in short
The README describes MapStage as an open-source tuner with map and globe, satellite, hypsometric relief, 3D terrain, region isolate and JSON presets. The news section mentions Mapterhorn replacing AWS Terrarium, OpenFreeMap vector water and the repository rename. A live demo, showcase scenes and run instructions follow.
README badge
Original SKILL.md
--- name: mapstage description: MapStage live tuner for map/globe projection, satellite, hypsometric relief, 3D terrain, region isolate, CSS color grade, and JSON presets. --- # MapStage Use this skill when building or tuning a MapStage scene: map/globe projection, satellite, hypsometric relief, Mapterhorn terrain, region isolate, CSS color grade, and JSON export. ## When to use - Need a live MapStage tuner (map vs globe, satellite vs relief, isolate). - Need to lock paint / CSS / camera, then export JSON into another host. - Need tiered settlements (`capital` / `large` / `medium` / `small` / `pass` / `station` / `ordos`). Do **not** use the tuner page as the final render host. ## Modes | Mode | Purpose | |------|---------| | **Production stack** | Embed MapStage in your app: optional satellite/raster + Mapterhorn DEM (`encoding: 'terrarium'`) + hillshade + OpenFreeMap vector water + CSS filter + city extrusions. Drive look from exported JSON. | | **Tuner** | HTTP page under `tuner/` (or the public demo) for sliders, projection, isolate, preset load/export. | ## Workflow 1. Open the tuner: public demo https://hopechen067.github.io/MapStage/ **or** `cd tuner && python -m http.server` and open the local URL printed in the terminal. 2. Tiles: default **EOX Sentinel-2 cloudless** (on) + **Mapterhorn** (`tuner/map-tiles.config.js`). Override with gitignored `map-tiles.config.local.js`. 3. Apply default preset [`tuner/preset-antique-default.json`](tuner/preset-antique-default.json) (same as [`tuner/presets/antique-default.json`](tuner/presets/antique-default.json)). Schema **version 3**. 4. Adjust projection / satellite / relief / isolate / CSS / cities until the look locks. 5. **Export JSON** (copy or download). Confirm `version: 3` plus `ui.projection`, `ui.showSatellite`, `ui.showRelief`, `ui.showCssFilter`, `isolate`. 6. **Migrate** those fields into the production MapStage scene (see references). 7. In production: `jumpTo` camera; wait for `idle`; optionally pre-cache tiles. **Avoid `easeTo` / `flyTo`** for recorded frames. 8. Always set DEM with **`encoding: 'terrarium'`**. Wrong encoding breaks hillshade/terrain. 9. Final frames render from the production host — **not** from the tuner UI. ## Hard rules - **Tiles not bundled** — MapStage fetches DEM and basemap at runtime from **configured** URLs only. - **Only use basemap endpoints you are allowed to use** — defaults are public demo tiles (EOX); swap via config when needed. - **`encoding: 'terrarium'`** on the terrain source — mandatory. - **No `easeTo` / `flyTo`** in recorded production paths; prefer `jumpTo` + `idle`. - **Do not host final render on tuner.** - **Water** on the public tuner is OpenFreeMap / OpenMapTiles vector layers (`water` / `waterway`). Export `ui.showWater` is always `false` (old GeoJSON overlay is off). Do not expect or commit `tuner/assets/water-data.js`.