map-3d

3D 地形地图视频:真实立体山体(卫星贴图 + 高程)上做轨迹/路线/地点动画,竖屏 MP4。卫星地球俯冲 → 整条路线 3D 鸟瞰 → 镜头贴着人/车沿路线走(走过的线变黄、里程、海拔、累计爬升、小地图、底部海拔剖面、沿途弹照片)→ 拉回全景出总数据;或单个地点俯冲后绕着转一圈(地名、经纬度、海拔);或光线推演:某天日出/日落时太阳照到哪座山、几点日照金山、机位几点见光(按真实太阳位置 + 山体

SKILL.md

GitHub

3D 地形 map-3d

一份 spec("mode": "3d")→ 一段竖屏 3D 片子。渲染引擎是 map-motion(scripts/terrain3d.py 算镜头,scripts/runtime/t3d.js + MapLibre GL 出画面),本 skill 管流程:选路线来源 → 写 spec → 连续小段检查 → 出片。

片型 节奏(缺省) 用在
路线(有 track) 0–6s 地球俯冲 → 6–8.6s 整条路线鸟瞰、白线画出、标题 → 2.4s 压低贴到起点 → 跟随 10–26s(按长度)→ 6s 拉回全景、绕一点、总里程/爬升/最高海拔 徒步、登山、自驾、骑行、跑步、步道
光线("mode": "sun") 0–6s 俯冲到山峰 → 从机位方向看山,14s 时间快进(关键时刻附近慢放):山体明暗跟真实太阳方位走、天空变色、太阳方向光线、顶部时钟+罗盘、底部关键时刻表到点打勾 → 拉远看机位和视线 日照金山、日出日落机位规划、「几点有光」
单点(只有 place) 0–6s 俯冲 → 8s 绕着转(缺省 90°),底部地名卡+经纬度+海拔滚动 雪山、景点、营地、「我在这里」

光线片 spec

{"mode": "sun", "peak": [98.6833, 28.4367], "name": "卡瓦格博", "ele": 6740,
 "spot": {"name": "飞来寺观景台", "at": [98.9177, 28.4114]}, "date": "2026-10-15", "event": "sunrise"}
字段 说明
peak name ele 要拍的山(坐标或地名);ele 写公开海拔(峰顶受光时刻按它算)
spot 机位,可省(省了就背对太阳看受光面,没有「机位见光」一行)
date event tz 日期、sunrise/sunset、时区(缺省 8)
zoom pitch bearing lapse 看山镜头(缺省 12.6 / 70° / 机位看山的方向)、快进秒数(14)
编译时打印关键时刻(天文日出、山峰受光=日照金山开始、金色褪去=太阳高度 5°、机位见光),交付时把这几行原样告诉用户,并说明:按 30 m 高程推算,云和雾算不了,误差约 ±3 分钟;机位见光受身边小山坡影响大,坐标要准。

准备

  • map-motion 引擎(同一仓库根目录 scripts/)、uv、ffmpeg、Chromium(uv run --with playwright playwright install chromium)。高德 key 只在用地名或高德路线时需要(见 map-motion 主 skill)。
  • X=~/.claude/skills/map-3d/scripts/m3d.sh
    • $X check spec.json 在每个关键时刻前渲 0.6 秒连续小段并自动质检(出画、文字互压、黑块),输出文字结论;拼图照样生成(5–6 分钟)
    • $X make spec.json 成片.mp4 整片 + 预览 GIF(约 1 秒一帧:30 秒片子 15–25 分钟,放后台跑);边渲边每 0.5 秒抽检,结束只出几行摘要
    • $X status 一行看进度(别反复读日志)

流程

1. 定路线来源(按可信度)

用户给了什么 track 写法 说明
GPX / KML 转的 GeoJSON(两步路、六只脚、Strava、Keep、手表) "track": "xx.gpx" 最准,就是真实走过的线。WGS-84,不用转
只说了起终点,开车/骑车/城里走 {"mode": "driving" | "bicycling" | "walking", "from": "地名", "to": "地名", "via": [...]} 高德路线规划(GCJ → 自动转 WGS)。景区台阶路高德步行也常有(泰山红门→南天门实测可用)
山野徒步,没有 GPX {"via": [途经点…], "margin": 0.02} 沿 OpenStreetMap 小路取最短路连起来。山里 OSM 常断头:报「不连通」就加中间点、缩短,或请用户给 GPX
一串坐标 [[lng, lat], …] 直接用
只有一个地方 不写 track,写 "place" 单点环绕

地名一律经高德解析,编译会打印「地点 X → 解析结果」——每行核对(同名 POI 会解析错)。山峰 POI 可能偏几公里,主峰直接写公开资料的 WGS 坐标。

2. 写 spec

从 examples/ 挑最像的复制改:

例子 内容
hike_osm_yubeng.json 雨崩:南争垭口 → 上村 → 下村 → 神瀑,OSM 小路连线,9.8 km
walk_amap_taishan.json 泰山红门 → 中天门 → 南天门,高德步行,6.1 km 爬升 1181 m
drive_amap_shangrila.json 香格里拉 → 飞来寺,高德驾车 171 km(长路线自动拉远镜头)
place_orbit_meili.json 卡瓦格博单点俯冲 + 环绕
sun_meili_sunrise.json 10 月 15 日飞来寺看卡瓦格博日照金山:07:21 受光,07:52 褪色,飞来寺 09:54 才见光
字段 说明
title / sub 鸟瞰和片尾标题;长标题自动缩字号
marks 地名小标:{"name", "at"},at 可写地名;名字里可以带海拔(「卡瓦格博 6740m」)
photos 沿途照片:{"image", "at" 或 "km", "label"};走到那里停 pause(2.2s)弹大图,之后缩成小牌子留在原地。有人像的照片提醒用户这是要公开的
gcj true = spec 里的数字坐标是高德坐标;缺省按 WGS-84
zoom / pitch 跟随镜头,缺省按长度自动(10 km 内 15.1 级;170 km 约 11.7 级)/ 62°
exaggeration 地形夸张,缺省 1.35;平原路线可加到 2
follow pause dive overview swoop end 各段秒数
color 走过的线和数字颜色,缺省 #f2ee3a
单点:place name ele zoom pitch bearing turn orbit ele 写已知海拔(高程数据 30 m 网格会削峰:卡瓦格博 DEM 只有 6469 m)

3. 检查(必做,用连续小段,不要只看单帧)

cd 项目目录 && $X check spec.json
  • 「✓ 质检通过」:机器能查的都没问题,不用读拼图;只有要判断构图好不好看时才读一次。
  • 「✗ 质检 N 项」:按报的时刻和内容改,必要时读拼图对照。 机器查不了、要人看的:
  • 俯冲末/鸟瞰:整条线在画面里、标题不压线;没有黑块、没有直边断口(远处地形缺瓦片的样子)
  • 跟随:人在画面中部、前方能看到白线;顶部里程和小地图、底部海拔剖面清楚
  • 片尾:整条黄线都在画面内,总数据卡不压线
  • 不对就改 zoom/pitch/exaggeration 或 marks,再 check

4. 出片(后台)

$X make spec.json 名字.mp4             # 同时出 名字.gif(270px 预览)

首次跑会下载几千张卫星/高程瓦片(缓存在 ~/.cache/map-motion/tiles/,重渲很快)。

5. 交付

说清:文件位置、时长;路线来自哪(GPX / 高德规划 / OSM 小路推测——推测的要明说「不是你实际走的线」);里程、爬升是按 AWS 高程数据算的(和手表数字会差 5–15%);影像 Esri、地形 Mapzen/AWS 已在画面右下角署名。

踩过的坑

  • 单帧 --stills 一切正常,连续出片却露黑块/直边断口——MapLibre 连续换相机时远处瓦片会漏。所以检查一律用 check(连续小段)。黑块判定只算纯黑像素(RGB < 3),山体阴影不会误报。引擎已处理:12.2 级后换平面投影、天空 2D 自画、全景俯角 40–44°。
  • MapLibre 5.6 在地球↔地形切换时抛 clearFadeHold,已锁 5.24。
  • 国内也用 Esri 卫星(WGS-84):高德卫星是 GCJ,和地形、GPX 对不上。所以 3D 片里所有高德来的点都转回 WGS。
  • 雪山上白字看不清 → HUD 上下有压暗渐变;顶部 290px 内的地名小标会自动淡出,避免压住里程。
  • 软件 WebGL(SwiftShader)慢且吃 CPU,别同时跑两个整片。

公共组件(加新片型时复用,别重写)

件 管什么
scripts/geo.py 距离、方位、沿方位走 N km、墨卡托、缓动、fit_cam(把一堆点装进画面)、dive(地球俯冲)、blend(两镜头过渡)、frame、resolve(地名/坐标→WGS)
scripts/dem.py / sun.py 任意点海拔;太阳方位高度、地平线遮挡、过零时刻
scripts/runtime/hud.js 字体、描影文字、斜体大数字、压暗渐变、底板、照片牌、脉冲落点、度分秒、标题、署名
render.py / qa.py / status.py 按 runtime 字段加载 runtime/<名>.html,逐帧出片、自动质检、进度
m3d.py check 读时间轴里的 checks(关键时刻),不用为新片型改

新片型=scripts/<模块>.py 的 compile(SPEC, sp, out, W, H)(在 compile.py 的 MODES 登记)出时间轴,带 checks;画面能用 t3d.js 就在里面加一块(如 SUN),否则新写 runtime/<名>.html 实现 prepare(t) / renderFrame(t) / __canvas。