Map Motion

地图动效 map-motion

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

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

shCopy code
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 标签排除。