map-motion — скилл

---
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` 揭晓 | 猜地点系列、悬念片头 |