map-3d

# 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 ```json {"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. 检查（必做，用连续小段，不要只看单帧） ```sh cd 项目目录 && $X check spec.json ``` - 「✓ 质检通过」：机器能查的都没问题，**不用读拼图**；只有要判断构图好不好看时才读一次。 - 「✗ 质检 N 项」：按报的时刻和内容改，必要时读拼图对照。 机器查不了、要人看的： - 俯冲末/鸟瞰：整条线在画面里、标题不压线；**没有黑块、没有直边断口**（远处地形缺瓦片的样子） - 跟随：人在画面中部、前方能看到白线；顶部里程和小地图、底部海拔剖面清楚 - 片尾：整条黄线都在画面内，总数据卡不压线 - 不对就改 `zoom`/`pitch`/`exaggeration` 或 marks，再 check ### 4. 出片（后台） ```sh $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`。