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）。

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。
3. 编译并核对地点：编译会逐个打印「地点 X → 高德解析结果（级别）[坐标]」。每一行都核对：同名地点会解析错（实测「香格里拉」曾被解析成某家酒店）。不对就换更具体的名字，或直接写坐标。
4. 抽静帧：--stills 取每个镜头中段和结尾各一帧。输出末尾有自动质检（出画、文字互压、文字压照片、黑块）：「质检：通过」就不用读图；报了问题，或要判断审美（构图、配色）时，才 Read 对应静帧。
5. 出片：渲染整片（30fps 约每秒 2.5 帧画面；40 秒片子约 1.5–2 分钟），需要时加 --gif、--audio。长片放后台跑；结束只输出几行摘要（成片路径、时长、边渲边抽检的质检结论），-v 才打印逐段进度。中途看进度用 python3 scripts/status.py（一行），不要反复读日志。
6. 交付：说清时长、文件位置、用了哪些真实数据（高德路线公里数等），以及哪些是示意。

镜头一览

3D 地形模式（"mode": "3d"）

真立体山体（AWS Terrain Tiles 高程 + Esri 卫星，MapLibre GL 渲染）。整片是固定一套：卫星地球俯冲 → 整条轨迹 3D 鸟瞰（白线 + 标题）→ 压低贴到起点 → 跟着人走（黄线、里程、海拔、累计爬升、小地图、底部海拔剖面；到照片点停下弹照片）→ 拉回全景、出总数据。写法见 references/spec.md；流程、例子和检查命令在子 skill map-3d/。

• 坐标一律 WGS-84（GPX、OSM、卫星、高程都是），所以国内也用 Esri 卫星；高德坐标写 "gcj": true。
• 没有 GPX："track": {"via": [途经点…]} 沿 OSM 小路取最短路连起来（山里 OSM 常断头，不连通就加中间点）。
• 软件 WebGL（SwiftShader）渲染，约 1–1.5 秒一帧，30 秒片子 15–25 分钟，放后台跑；先 --stills 抽帧看。

镜头之间自动「飞过去」（van Wijk 平滑缩放：远距离先拉远再推近，和 Mapbox flyTo 同一公式），不需要手写转场。

样式

矢量样式的边界是抽稀过的（约 2 km 精度），编译时自动把镜头封顶在 8 级（约一个地级市范围）并提示；要街道细节就用前三种。

高德

• key：export AMAP_KEY=… 或写入 ~/.config/map-motion/amap_key（Web服务类型）。没 key 时编译直接报错并说明怎么申请。不要把 key 写进 spec 或项目目录。
• API 响应缓存在 ~/.cache/map-motion/api/，瓦片缓存在 ~/.cache/map-motion/tiles/；改 spec 重编译不重复消耗配额。
• 用户的 GPS/照片 EXIF/GPX 坐标是 WGS-84，spec 里写 "wgs84": true 转成高德坐标。
• 海拔：elevation: true 用 OpenTopoData SRTM 30m（免费，每天约 1000 次请求，已缓存）；查之前把高德坐标换回 WGS-84，否则山区高度会错。
• 高德瓦片属非官方取用：个人/学习视频可用并保留右下角署名；商业投放需高德授权或改矢量样式。国界、南海九段线照内置数据画，不要删改。详见 references/amap.md。

要改画法时

• 画面全在 scripts/runtime/mm.js：样式表 ST（颜色、字体、是否发光/纸纹/虚线）、各图层绘制函数（route pin region hudTitle odometer caption photo）、地球（globeTexture/globeFill 逐像素反投影）。加样式＝往 ST 加一项（地球颜色用 globeOcean/globeLand 单独给，暗色样式要拉开对比），用瓦片的再加进 compile.py 的 TILED。
• 镜头逻辑在 scripts/compile.py 的 shot_* 函数；加镜头类型＝写一个 shot_xxx 并登记到 SHOTS。
• 改完用 assets/examples/showcase.json（覆盖全部镜头）在两三种样式下抽帧回归。

踩过的坑（改代码前先看）

• 3D：MapLibre 5.6 在地球↔地形切换时抛 clearFadeHold 错 → 用 5.24（render.py 的 VENDOR）。setData 在 worker 里异步，idle 可能先到，线会慢一帧 → t3d.js 先等 sourcedata(isSourceLoaded) 再等 idle。

• 3D：单帧抽图看着没问题、连续出片却在远处露黑块（天空/远处地形没画）——抽帧检查要用 --from/--to 渲一小段，别只看 --stills。现在的处理：推近到 12.2 级后从地球投影换成平面投影（地球投影下雾和天空不生效；12 级前换会跳一下），底色透明、天空由 2D 画布自己画渐变，全景/片尾俯角压到 40–44° 不露地平线。

• 3D：雪山上白字看不清 → HUD 上下压暗渐变。俯视全景按透视近大远小会出画 → 自动挑让轨迹顺着视线方向的朝向，再退 0.35 级。

• 正射地球上用多边形填陆地会破（背面点贴地平圈后围出错误区域，整球变白）→ 现在逐像素反投影取纹理；海岸线、省界只描线。

• 墨卡托下逐点做 ±180° 归位，环会在屏幕两侧来回跳、画出横贯全屏的线 → Pline 只对首点归位，之后按经度差连续累加。

• 推得很近时顶点投影到几十万像素外，画布填充破成楔形 → clipRing 先按屏幕外扩框裁剪。

• 地名先做 POI 搜索会把行政区名搜成同名商户；只信地理编码又会把「青海湖」编成乌鲁木齐同名小区 → geocode 先编码，落到兴趣点/道路/公交站/住宅区级才退 POI。编译打印的地点行仍要逐行核对。

• 过渡阶段的透明度要从外层一路传进 drawGlobe，内部重设 globalAlpha=1 会让交叉淡化失效。

• 从行政区推到街道级，区域填色会染满整屏 → 推近前那一镜写 clear（编译主循环统一处理）。

• OSM 主站常 504、单个镜像会超时 → osm.py 轮流试三个镜像并缓存；按名字查会查到同名地铁站，已按 railway/public_transport 标签排除。

map-motion · 地图动效视频 Skill

给 Claude Code 用的地图动画 skill：用一句话描述（或一份 JSON 镜头表），出一段基于真实高德地图数据的地图动效视频——竖屏/横屏 MP4，外加 GIF。

路线是高德真实的驾车/步行/骑行路线，边界是真实的行政区和公园轮廓，海拔是 SRTM 卫星高程，底图可以直接用高德标准地图或卫星图。

能做哪些视频

1. Vlog 片头「我在这里」

卫星地球俯冲 → 瞄准镜收缩锁定（LOCKED）→ 坐标卡：地名逐字打出、经纬度滚动到位、海拔、拍摄时间。10 秒，直接接你的 vlog 正片。

assets/examples/vlog_locate.json · vlog_locate_night.json

2. 徒步登山：路线 + 海拔剖面

镜头跟着人沿高德步行路线上山，底部的海拔曲线同步画出，实时显示海拔和累计爬升，山顶插旗。

深圳梧桐山，泰山涧 → 大梧桐：3.6 km，海拔 98 → 916 m，累计爬升 835 m。hike_elevation.json

3. 长途骑行 / 自驾：多站旅程

一次写完整趟行程：逐段路线、累计里程表、「DAY n · 日期 · km」、到站邮戳、照片拍立得、原路返程。

青海湖环湖骑行（高德骑行路线 365 km，海拔 3,200 m 上下）· 国庆自驾深圳 → 香格里拉往返 4,213 km。cycling_trip.json · road_trip.json

4. 介绍一个地方：公园、景区、校园

从地球或行政区推进到一个地块，描出轮廓、填色，再从地铁站步行过去、绕园一周。

上海徐汇区桂林公园。park_locate.json · park_walk.json

5. 航线、行政区、业务分布

城市间飞线（大圆航线，飞机沿弧飞）、行政区依次描边高亮、一个中心向多城辐射。

showcase.json · flight.json · region.json · radiate.json

6. 找机位：照片从地图上「咔嚓」翻出来（子 skill photo-spot）

给一张照片：卫星地球俯冲 → 相机图标落在拍照机位、被摄地落针 → 取景扇形扫过去 → 取景框对焦 → 快门声＋闪白 → 照片从机位处 3D 翻折立起，背景是照片自身的虚化；可加 iPhone Live Photo 播放效果（用真 MOV，或静态照片模拟）。照片带 GPS 时自动读出机位、朝向、焦距和参数。

富士山 × 新干线（境外，Esri 卫星）· 雨崩神瀑 → 卡瓦格博（Live Photo 模拟）· 香港钓鱼翁 → 布袋澳。photo-spot/（安装见下）· 示例 spec 在 photo-spot/examples/

7. 3D 地形：像 Google Earth 一样的立体轨迹（子 skill map-3d）

真实山体起伏（AWS 高程 + Esri 卫星，MapLibre GL 渲染）：卫星地球俯冲 → 整条路线 3D 鸟瞰 → 镜头贴着人/车沿路线走（走过的线变黄，里程、海拔、累计爬升、小地图、底部海拔剖面实时走，沿途弹照片）→ 拉回全景出总数据。路线可以是 GPX（两步路、六只脚、Strava、手表）、高德驾车/骑行/步行规划，或没有 GPX 时沿 OpenStreetMap 小路连途经点；也能只给一个地方，俯冲后绕着转一圈。

香格里拉 → 飞来寺自驾 171 km（高德驾车路线，预览 2 倍速）· 卡瓦格博单点环绕。map-3d/（安装见下）· 示例 spec 在 map-3d/examples/（另有雨崩神瀑徒步、泰山红门登顶）

8. 光线推演：几点日照金山、机位几点见光（map-3d 的 "mode": "sun"）

给山峰、机位、日期，按真实太阳位置（NOAA 算法）和周围山体遮挡（沿太阳方向在高程上找地平线）算出：天文日出、山顶受光（日照金山开始）、金色褪去、机位见光。画面上时间快进，山体明暗跟着真实太阳方位走，天空变色，顶部时钟 + 罗盘，底部关键时刻表到点打勾。

10 月 15 日飞来寺看卡瓦格博：07:21 峰顶受光（比天文日出早 4 分钟）、07:52 金色褪去，而飞来寺被身后山坡挡着，09:54 才见光。

9. 旅行 vlog：卡通小人沿路线走、到站拍照（子 skill travel-vlog）

一组旅行照片 → 按 GPS 和拍摄时间排出机位 → 沿真实步行/驾车路线连起来；用本人照片 AI 生成 Q 版形象（也有内置小人），小人一颠一颠地走，右上角里程累加，到站「咔嚓」拍照、照片弹出，最后照片墙 + 总里程。配原创欢快 BGM（程序合成，无版权问题）和脚步、快门、啵、叮音效，弹照片踩在拍点上。

西湖 5 个机位步行 8.8 km（演示用内置小人，预览 1.5 倍速、无声；成片带 BGM 和音效）。

也有独立仓库 SpaceZephyr/travel-vlog（自带引擎，单独安装即可用）。

14 种风格

同一份镜头表，改一个 style 字段就换风格。前 6 种直接用高德瓦片、satellite-world 用 Esri 卫星（能推到街道级），后 7 种用代码绘制矢量底图（全国到地级市尺度）。

14 种镜头

镜头之间自动「飞过去」：远距离先拉远再推近，和 Mapbox flyTo 同一套公式，不用手写转场。完整参数见 references/spec.md。

快速开始

1. 安装

git clone https://github.com/SpaceZephyr/map-motion ~/.claude/skills/map-motion
uv run --with playwright playwright install chromium     # 首次：无头浏览器

依赖：uv、ffmpeg。

要用「找机位」子 skill，再链接一下（它复用 map-motion 的渲染引擎）：

ln -s ~/.claude/skills/map-motion/photo-spot ~/.claude/skills/photo-spot
ln -s ~/.claude/skills/map-motion/map-3d ~/.claude/skills/map-3d          # 3D 地形、光线推演
ln -s ~/.claude/skills/map-motion/travel-vlog ~/.claude/skills/travel-vlog # 旅行 vlog（或单独装 github.com/SpaceZephyr/travel-vlog）

2. 配高德 key（高德开放平台 → 应用管理 → 添加「Web服务」类型 key，免费）

mkdir -p ~/.config/map-motion && echo '你的key' > ~/.config/map-motion/amap_key && chmod 600 ~/.config/map-motion/amap_key

3. 用

在 Claude Code 里直接说：

帮我做一个 vlog 片头，我在大理双廊，10 月 3 号早上 7 点 42

把我这次爬梧桐山的路线做成带海拔的动画

做一个从杭州辐射到全国 12 个城市的地图动画，暗色风格

或者自己写镜头表：

{"size": "portrait", "style": "satellite",
 "shots": [
  {"type": "locate", "to": "双廊古镇", "zoom": 15.6, "name": "大理 · 双廊", "sub": "洱海东岸 · DAY 3", "date": "2026.10.03  07:42"}
 ]}

~/.claude/skills/map-motion/scripts/make.sh 片头.json 片头.mp4 --gif 片头.gif
~/.claude/skills/map-motion/scripts/make.sh 片头.json 静帧/ --stills 2,6,9      # 先抽几帧看构图

编译时会打印每个地点被高德解析成了什么，请逐行核对——同名地点会解析错（实测过「香格里拉」→ 某家酒店、「青海湖」→ 乌鲁木齐一个同名小区）。

怎么做出来的

镜头表 spec.json
   │  compile.py  ── 高德：地名→坐标、驾车/步行/骑行路线、行政区边界
   │              ── OpenStreetMap：公园/景区轮廓    OpenTopoData：SRTM 海拔
   │              ── 算每个镜头的取景、镜头之间的飞行、图层出现/消失时间
   ▼
timeline.json
   │  render.py   ── 本地服务（运行时 + 高德瓦片代理缓存）→ 无头 Chromium 逐帧画 → ffmpeg
   ▼
成片.mp4 / .gif

• 地球：正射投影逐像素反投影取纹理（卫星样式的纹理就是高德卫星瓦片拼出来的），缩放到 3–3.6 级时和平面地图交叉淡化，所以能从太空一路推到街道。
• 平面：Web 墨卡托，512px 高清瓦片；矢量底图用多边形裁剪防止推近时破面。
• 坐标：全程 GCJ-02（高德坐标），GPS/照片/GPX/OSM 的 WGS-84 坐标自动转换；查海拔时再转回 WGS-84。
• 公共组件：渲染（按时间轴的 runtime 加载页面）、自动质检、进度、HUD 绘制（runtime/hud.js）、几何与镜头（geo.py：俯冲、取景、过渡）、高程（dem.py）、太阳（sun.py）各写一次，新片型只写自己的编译模块和画面差异（见 map-3d/SKILL.md「公共组件」）。
• 确定性：同一份时间轴两次渲染逐帧一致；瓦片、API、海拔全部本地缓存，改了重渲不再消耗配额。

参考了哪些 skill 和方法

Skill

• huashu-art-motion（花叔）：借鉴了它的工作方法——风格先在同一帧上出多个方向让人挑、所有渲染确定性可复现、交付前抽静帧逐帧检查、派独立 agent 只看成片审片、把踩过的坑写回 skill（本 skill 的 SKILL.md 末尾也保留了「踩过的坑」）。
• Anthropic skill-creator：skill 的组织方式——SKILL.md 只放流程和选择指南，参数细节放 references/，可执行部分放 scripts/，按需加载。

产品与灵感

• Mult.dev、TravelAnimator：旅行地图视频的常见镜头（航线、自驾、照片插入）。
• Google Earth Studio：从地球俯冲到地点的片头语言。
• Mapbox flyTo：镜头飞行的手感。

算法

• van Wijk & Nuij, Smooth and efficient zooming and panning（2003）：镜头先拉远再推近的最优路径。
• 正射投影与逐像素反投影；大圆插值（球面线性插值）画航线。
• Douglas–Peucker 折线抽稀；Sutherland–Hodgman 多边形裁剪。
• WGS-84 ↔ GCJ-02 坐标转换。

数据

• 高德开放平台 Web 服务 API（地理编码、路径规划、行政区）与地图瓦片
• 阿里云 DataV GeoAtlas：中国省级边界（含南海诸岛与九段线）
• Natural Earth / world-atlas：世界陆地轮廓
• OpenStreetMap（Overpass API）：公园、景区等地块轮廓 © OpenStreetMap contributors，ODbL
• OpenTopoData：SRTM 30m 海拔
• AWS Terrain Tiles（Mapzen Terrarium 编码）：3D 地形与 3D 片的海拔/爬升，© Mapzen 及各数据源（SRTM、GMTED、ETOPO1 等）
• MapLibre GL JS 5.24（BSD-3）：3D 片的渲染，运行时从 unpkg 下载并缓存
• Esri World Imagery：境外卫星影像（satellite-world）和 3D 片的全部卫星影像，© Esri, Maxar, Earthstar Geographics
• 太阳位置：NOAA Solar Calculator 算法（scripts/sun.py，自写实现）
• 卡通形象：LabNana 图像接口（gpt-image-2 / Gemini）按用户照片生成，需用户自己的 key；内置小人由代码绘制
• 配乐与音效：scripts/audio.py 程序合成（Karplus-Strong 拨弦、正弦钟琴等），原创，无第三方版权

使用边界

• 高德瓦片：渲染时直接取高德瓦片，属于非官方用法。个人视频、学习交流可用，成片右下角保留「© 高德地图」署名；商业投放需要高德的商业授权，或改用 7 种矢量风格。satellite-world 的 Esri 影像同理：个人非商业可用并保留署名，商用需 Esri 授权。
• 地图合规：中国边界按内置数据绘制（含台湾、南海诸岛与九段线），请勿删改；对外商用的地图内容在国内受《地图管理条例》约束。
• 海拔：SRTM 是约 30 米网格的平均高程，山顶会比实际略低（梧桐山顶实测 944 m，SRTM 916 m）。
• 3D 片：无头浏览器里是软件 WebGL（SwiftShader），约 1 秒一帧，30 秒片子 15–25 分钟；OSM 小路连出来的线是推测路线，不是你实际走的轨迹，有 GPX 一定用 GPX。
• 光线推演：按 30 m 高程推算，云、雾、霾算不了；时刻误差约 ±3 分钟，机位见光受身边小坡影响大，坐标要准。
• 旅行 vlog 形象：用本人照片生成会把照片发给 LabNana（第三方 AI 服务），先征得本人同意；里程是高德路线规划的距离，不是实际 GPS 轨迹。
• 公园轮廓：来自 OSM 志愿者绘制，精度不一，有的只有几个点。
• 示例里的日期（青海湖骑行、vlog 拍摄时间）是示意，路线、里程、海拔是真实数据。

License

代码 MIT。字体（思源黑体、霞鹜文楷、Anton）为 SIL OFL 1.1，见 assets/fonts/。地图数据遵循各自来源的条款（见上）。