map-animation
This skill should be used when the user asks to "make a Vox-style map animation", "animate a map zoom", "draw a route on a map", "highlight a country/region", "use Google Earth Studio", "drop pins on a map and animate them", "pan/orbit a camera over a map", or "add map graphics to an explainer video". Covers Earth Studio→After Effects camera import, GeoJSON/SVG vector map motion, pins/routes/highlights/labels, the 12fps stutter cadence, and data-driven Remotion renders.
1How It Works & Mechanism
The signature style is a quantifiable timing contract: graphic overlay layers step at 12fps (holding the same value for every 2 frames) within a 24fps final render, while base map footage and audio remain smooth at 24fps—stuttering only the overlays, not the base.
The single most recognizable trait of this style is **animating the map graphics at 12fps inside a 24fps edit**.
Frame stutter is implemented by "quantizing the frame number first, then calculating all graphic metrics using the quantized value," with step size derived from fps (Math.round(fps/12)) rather than hardcoding 2, ensuring the style remains intact across frame rates.
const f = Math.floor(frame / STEP) * STEP; // use `f`, not `frame`, for graphic motion
Two production pipelines are routed based on requirements: for photorealistic terrain/true 3D buildings/cinematic camera moves → Google Earth Studio outputs image sequences + camera .jsx to reconstruct the camera in After Effects and attach overlays to track nulls; for sketch/editorial style, total control, and data-driven workflows → GeoJSON/SVG is projected and rendered via code.
| Photoreal terrain, real satellite/3D buildings, cinematic camera | **Google Earth Studio → After Effects** | Image sequence + camera `.jsx`, composited in AE |
Vector paths are locked via a shared projection: base maps, pins, routes, and labels all pass through the same projection([lng,lat]), and the camera merely scales/translates the entire group, preventing elements from drifting relative to the shot.
The same `projection([lng,lat])` converts every pin coordinate to a screen position, so pins, routes, and labels all share one coordinate space
The overlay toolkit has dedicated mechanics: pin drops (spring overshoot followed by settling + optional pulse), route tracing (pathLength=1 normalization + dashoffset), regional highlights (focus + context: target brightened while the rest dims), and label guide lines (anchored to projected points, remaining horizontal).
`pathLength="1"` normalizes any route length so one progress value (0→1) draws it.
Orchestration is data-driven: a single beats array simultaneously dictates camera targets, pin sequences, route segments, and labels, while total duration is computed by calculateMetadata summing holds—enabling new videos by simply changing data without manual re-keyframing.
One array → camera targets, pin order, route segments, and labels stay in sync.
Verification is geographic fidelity-driven: every pin must land on accurate coordinates, routes must connect correct cities, highlighted areas must match target regions, and labels must be spelled correctly; it also requires sampling "two adjacent frames" to verify that overlays hold across two frames while the base camera advances frame-by-frame.
Two adjacent overlay frames are identical (12fps step holds) while the base camera advanced
The critical step in the Earth Studio pipeline is checking 3D Camera Export during export: only then are the camera .jsx and track-point data generated alongside the image sequence; missing it leaves only raw footage, preventing camera reconstruction in AE and breaking overlay tracking.
**CRITICAL — enable the After Effects / 3D Camera Export option**
2Core Capabilities
3External Dependencies
| Kind | Dependency / Endpoint |
|---|---|
| cli | npx remotion still / render（矢量路径的帧验证与编码） |
| package | d3-geo（geoMercator / geoPath / geoInterpolate 等投影与球面插值） |
| network | 底图数据源：Natural Earth（国家/州界 GeoJSON）或 world-atlas TopoJSON（用 topojson.feature 转换） |
| api | Google Earth Studio（浏览器工具，需 Google 账号；产出图像序列 + 相机 .jsx + track 数据） |
| package | zod（beats schema 校验） |
| cli | ffmpeg / ffprobe（contact-sheet.sh 拼图与 probe-mp4.sh 规格断言） |
4Recommended Governance & Evidence
- scripts/: Executes local scripts or commands: npx remotion still / render (SKILL.md Verify loop): fetches and runs Remotion CLI on demand from npm
- 网络端点: Declares external network access: Google Earth Studio (earth.google.com/studio): Path A camera keyframing and user interaction in Google's web app
- 本地工作目录: File I/O and artifact output: out/*.mp4, out/demo.gif, out/f-*.png (final renders and frame-by-frame stills), sheet.png (spritesheet/contact sheet)
5Second-Pass Verification
- [ok] 外部依赖调用点复核（npx remotion / d3-geo / zod / Earth Studio / 底图数据） — SKILL.md 确有 `npx remotion still MapSeq out/f-start.png ...` 与 `npx remotion render MapSeq out/map.mp4`；SKILL.md 代码块确有 `import { geoMercator, geoPath } from "d3-geo";`；vector-maps 确有 `export const schema = z.object({` 与 Natural Earth/world-atlas 建议；earth-studio-to-ae 确有 earth.google.com/studio 与 3D Camera Export 告警。全部落地。
- [ok] Earth Studio 路径是否引入 agent 侧凭证行为 — 文档措辞是「Keyframe in Earth Studio (browser)」「In After Effects: … Run Script File…」——由人操作；skill 未要求 agent 登录 Google、未涉及任何 cookie/token 读取。故不计入 credential_reads，只作为外部服务依赖记入 external_deps 并在 reason 中标注账号前提。
- [ok] 12fps 量化实现与描述一致性 — SKILL.md 的代码块 `const STEP = Math.round(fps / 12); const f = Math.floor(frame / STEP) * STEP;` 与文字「at 24fps, hold each graphic-layer value for 2 frames (update on even frames only)」一致；vector-maps 用同一写法并额外给出 `Math.max(1, …)` 的 30fps 保护；AE 侧给了 posterizeTime(12) 与 12fps 嵌套 precomp 两种等价做法。三处口径一致。
- [ok] 「共享坐标空间」主张的成立性 — 矢量路径中底图用 `toPath(feat)`、pin/route/label 用 `px([lng,lat])`（同 projection），相机是对同一 group 的 transform；AE 路径则用 track null + `toComp([0,0,0])` 表达式。两条路都确实把「元素锁定」交给共享坐标系，而非逐元素手调关键帧。
- [ok] 坐标序与投影边界的风险是否明示 — vector-maps 的 Gotchas 明示两点：GeoJSON 与 projection() 都是 [lng, lat] 而非 [lat, lng]（写反会把每个 pin 送错位置）；Mercator 在高纬/跨 ±180° 会截断或撕裂，建议世界视图改用 geoEqualEarth/geoNaturalEarth1 或旋转投影。均为操作级警告，非泛泛提醒。
- [discrepancy] 跨目录 / 跨 skill 引用可解析性 — 正文引用的 `scripts/contact-sheet.sh`、`scripts/probe-mp4.sh` 位于仓库根，单装本 skill 目录会悬空（需装整个 repo）；另外 SKILL.md 把矢量路径定位为「Remotion 或 D3」，但 D3 网页变体只给要点（?t 冻结），完整网页交付契约与同 pack 其他 skill 相比更薄——属能力边界，非错误。
- [ok] 功能声明 vs 实际能力 — frontmatter 宣称覆盖 Earth Studio→AE 相机导入、GeoJSON/SVG 矢量地图动效、pin/route/highlight/label、12fps 顿帧与数据驱动 Remotion 渲染；正文两条路径与两份 reference 逐项兑现。未夸大——AE 侧的产出被明确定义为「AE 工程 + 渲染素材，由人工 scrubbing 验收」，而非声称 agent 能自动完成 AE 合成。
6Verdict & Scenarios
8f12ba8c5bbce5eb…