SkillFoxx

map-motion skill

A Claude Code skill that renders map animation videos from Amap data: routes, district borders, satellite maps, as MP4 and GIF.

  • 119 ★ on the repository
  • Last commit
Skill

Extended access

Why this level

  • The skill runs rendering on your machine and calls Amap, Esri and AWS servers for tiles and elevation.
All reasons and checks

spacezephyr/map-motionAuthor:SpaceZephyr

Install

In your terminal, with SkillFoxx CLI

npx skillfoxx add skills/map-motion

Detects the agents on your machine, shows the access level and pins the version.

Other ways to install

Access and checks

How we review

Extended accessThe tool runs code or makes network calls and only reads external data.

  • The skill runs rendering on your machine and calls Amap, Esri and AWS servers for tiles and elevation.

This is third-party code. Review the repository files before installing.

What it does

map-motion turns a description or a JSON storyboard into a map animation video. Routes come from real Amap (Gaode) driving, walking and cycling data, borders from true administrative outlines, elevation from SRTM satellite data. There are 14 shot types, from an Earth fly-in and an I-am-here intro to a hiking elevation profile, a multi-day route, flight lines and district highlighting, plus 14 map styles. Rendering runs through headless Chromium and ffmpeg and outputs a vertical or horizontal MP4 and a GIF. The set includes extra skills. photo-spot shows where a photo was taken on the map, map-3d renders 3D terrain and computes mountain lighting from the Sun position, travel-vlog walks a cartoon character along a route with stops.

Who it is for. Travel video creators and bloggers who need an animated route over a map of China or the world without manual editing.

Good fit when

  • A ten-second vlog intro: Earth zooms to the shooting spot, then coordinates and elevation appear.
  • A mountain hike becomes a video with an elevation profile and total ascent.
  • A multi-day trip is assembled into one animation with daily mileage.
  • City flight lines or business expansion are drawn on a dark map.

Not a fit when

  • You need commercial advertising: Amap and Esri tiles require separate licensing, which the vector styles avoid.
  • ffmpeg, uv or a free Amap Web Service key is missing.
  • You need an exact GPX track: the route is built from planned data rather than your recording.

Example request

Make a vertical video of my mountain hike: walking route, elevation profile at the bottom and a flag at the summit, dark style.

Limitations

Amap tiles are used unofficially: for personal and educational videos the credit stays in the frame, while commercial advertising needs an Amap license or one of the seven vector styles. Foreign locations use Esri satellite imagery with the same limits. 3D scenes render through software WebGL at roughly one second per frame, so a thirty-second video takes 15–25 minutes. SRTM lowers peaks, and computed sun times carry an error of around 3 minutes.

How to disable. Delete the map-motion folder and the photo-spot, map-3d and travel-vlog links from ~/.claude/skills. The Amap key is stored in ~/.config/map-motion/amap_key and is removed separately.

FAQ

How do I install map-motion in Claude Code?

Clone the repo into `~/.claude/skills/map-motion`, run `uv run --with playwright playwright install chromium` once and put the Amap key into `~/.config/map-motion/amap_key`.

Which key is needed?

A free Web Service key from the Amap open platform. Other external services are needed only by individual skills.

How do I enable the extra skills?

Symlink `photo-spot`, `map-3d` and `travel-vlog` into the `~/.claude/skills` directory.

Which output formats are produced?

A vertical or horizontal MP4 and a GIF.

Are the videos suitable for advertising?

Commercial use needs an Amap license or one of the seven vector styles. Amap tiles suit personal and educational videos.

Discussion

No questions or reviews yet.

Skills

A Claude Code skill that turns two places on a map into a pixel-art fly-through of the real road with OpenStreetMap buildings

SkillBroad access325

Six Claude Code skills make animation for reels with no footage: graphs, map routes, exploded views and narrated explainers

PluginExtended access709

The MapStage skill tunes how a map or globe looks: projection, satellite, relief, 3D terrain, region isolate and JSON preset export

SkillExtended access525

A skill for Claude Code and Codex: the agent writes animation scenes, a browser player shows them, export to MP4 and Lottie.

SkillExtended access56

Fifteen Claude Code skills for launch films, animated charts and reels made entirely from code, with no After Effects

SkillExtended access660

A Claude Code skill for code-made video: it splits a clip into scenes and picks an engine for each, from Paper.js to Manim.

SkillExtended access115

README in short

The project code is MIT licensed, fonts are SIL OFL, and map data follows the terms of its sources. Ready storyboards are in assets/examples. Music and sounds are synthesized by the audio.py script.

README badge

Original SKILL.md

---
name: map-motion
description: "地图动效视频：用高德地图（真实路线、行政区边界、标准/卫星瓦片底图）做旅行与解说视频里的地图动画，出竖屏/横屏 MP4 和 GIF。十四种镜头：地球俯冲定位（从地球放大到某地）、Vlog「我在这里」瞄准锁定＋坐标卡、落点标注、公园/景区/校园地块轮廓描边与绕行、路线描线（驾车/步行/骑行/GPX，车随线走、里程表滚动、镜头跟车、海拔剖面）、飞线航线、行政区描边高亮、一对多辐射飞线、多站旅程（路线+邮戳+照片+返程；可换成卡通形象走路、到站拍照的 vlog 模式，配原创 BGM 和音效）、片尾照片墙、全景收束、标题卡、机位揭秘（咔嚓翻出照片，可做 Live Photo）、猜地点；另有 3D 地形模式（真实山体立体、卫星贴图、地球俯冲到鸟瞰、跟着人沿轨迹走、里程/海拔/爬升/小地图/海拔剖面、沿途弹照片）；十四种样式（高德标准、高德暗色、高德灰、高德复古、高德手账、卫星、境外卫星、暗色科技、极简白、水彩手账、复古纸、赛博霓虹、国风水墨、工程蓝图）。当用户说「地图动画」「地图动效」「轨迹动画」「出行轨迹视频」「旅行路线动图」「从地球放大到」「定位到某地」「飞线」「航线动画」「行政区高亮」「门店分布动画」「Vlog 地图片头」「标出某个公园/景点」「徒步/登山/骑行轨迹」「海拔剖面」「我在这里坐标卡」「3D 地形」「立体地图」「像 Google Earth 那样的轨迹」「两步路/六只脚那种 3D 轨迹回放」，或要把行程、GPX、照片位置做成地图视频时使用。"
---

# 地图动效 map-motion

> 子 skill：「找机位」（照片 → 机位揭秘视频）`photo-spot/`；3D 地形与光线推演 `map-3d/`；旅行 vlog（照片 → 卡通小人沿路线走、到站拍照、配乐）`travel-vlog/`。流程和坑在各自目录；本文件只讲引擎。

一份「镜头表」JSON → 编译（高德解析地名、取路线和边界、算镜头）→ 逐帧渲染（Chromium 画布 + ffmpeg）。

```sh
D=~/.claude/skills/map-motion/scripts
$D/make.sh 我的片子.json 成片.mp4 --gif 动图.gif           # 一键：编译 + 渲染
$D/make.sh 我的片子.json 静帧/ --stills 1,4.5,9            # 先抽几帧看构图（快）
```
首次使用：`uv run --with playwright playwright install chromium`；高德 key 见下。

## 工作流

1. **定内容**：问清地点/路线/日期/照片、发哪个平台（定 `size`）、要什么感觉（定 `style`）。不确定样式时，同一份 spec 换 `style` 各渲一帧给用户挑（至少三种）。
2. **写 spec**：从 `assets/examples/` 挑最近的一份复制改。镜头类型与全部参数见 [references/spec.md](references/spec.md)。
3. **编译并核对地点**：编译会逐个打印「地点 X → 高德解析结果（级别）[坐标]」。**每一行都核对**：同名地点会解析错（实测「香格里拉」曾被解析成某家酒店）。不对就换更具体的名字，或直接写坐标。
4. **抽静帧**：`--stills` 取每个镜头中段和结尾各一帧。输出末尾有**自动质检**（出画、文字互压、文字压照片、黑块）：「质检：通过」就不用读图；报了问题，或要判断审美（构图、配色）时，才 Read 对应静帧。
5. **出片**：渲染整片（30fps 约每秒 2.5 帧画面；40 秒片子约 1.5–2 分钟），需要时加 `--gif`、`--audio`。长片放后台跑；结束只输出几行摘要（成片路径、时长、边渲边抽检的质检结论），`-v` 才打印逐段进度。中途看进度用 `python3 scripts/status.py`（一行），不要反复读日志。
6. **交付**：说清时长、文件位置、用了哪些真实数据（高德路线公里数等），以及哪些是示意。

## 镜头一览

| type | 效果 | 典型用途 |
|---|---|---|
| `globe` | 地球自转 → 俯冲到地点，落点弹标签 | 片头、地点引入 |
| `locate` | 地球俯冲 → 瞄准镜锁定 → 坐标卡（经纬度滚动、海拔、日期） | Vlog 片头「我在这里」 |
| `pins` | 多个地点依次落针＋涟漪 | 打卡点、门店 |
| `route` | 高德真实路线或 GPX 描线，车/人沿线走，可镜头跟车、里程表、海拔剖面、终点插旗 | 自驾、徒步登山、骑行、跑步 |
| `flight` | 大圆航线向上拱起，飞机沿线飞 | 出差、旅行、跨城 |
| `region` | 行政区描边 → 填色 → 写名 | 城市群、区域介绍 |
| `area` | 公园/景区/校园轮廓（OSM 边界）描边填色，可让小人绕一圈 | 介绍一个地点、游园路线 |
| `radiate` | 一个中心向多点放射飞线 | 总部/仓库辐射、业务覆盖 |
| `trip` | 多站旅程：逐段路线＋累计里程＋到站邮戳＋照片＋原路返程；加 `avatar` 进入 vlog 模式（卡通形象走路、到站咔嚓拍照、照片弹出、脚步/快门/啵/叮音效踩拍点） | 假期出行复盘、旅行 vlog |
| `wall` | 片尾照片墙：全程照片依次落下 +「N 个机位 · 共走 X km」+ 形象摇摆 | vlog 收尾 |
| `overview` | 镜头框住至今所有地点 | 片尾收束 |
| `title` | 画面中央标题卡 | 开场、章节 |
| `snap` | 地球俯冲 → 机位（相机图标）＋被摄地 → 取景扇形 → 取景框对焦 → 咔嚓（自动配快门声）→ 照片从机位翻折立起，背景是这张照片的虚化；`live` 可做 iPhone Live Photo 播放效果 | 「这张照片在哪拍的」、机位揭秘、摄影 Vlog |
| `guess` | 整屏照片＋「这张照片在哪拍的？」＋提示＋倒数，闪白露出地球，接 `locate` 揭晓 | 猜地点系列、悬念片头 |

Report a problem