市面上的 Three.js 教程要么只到 Hello Cube，要么停在炫技 Demo。这门课从「底层实现级」角度拆解诗贯山河的全部工程决策，帮你建立完整的古风地图引擎知识体系。
要不要系统学 Three.js 可视化、GIS 资产管线和视觉工程？这是很多想做创意网页、互动地图、短视频素材工具的同学都会卡住的问题。你可能已经看过不少 Three.js 教程，知道怎么创建 Scene、Camera、Mesh，也能跑出一个旋转方块；但一旦要做一个真正能上线、能扩展、能持续产出的作品，问题马上变得不一样。
比如你想做一张古风中国地图：山脉从哪里来？河流怎么对齐？点位是经纬度还是屏幕坐标？诗词卡片是 DOM 还是贴到 Canvas 里？雨雪风沙这些特效是全屏粒子，还是局部绑定到某个地点？镜头飞行是改 position，还是要设计一套相机状态机？这些问题，普通入门教程很少讲。
诗贯山河这门课，就是从这些真实问题出发。它不是教你堆一个好看的视觉效果，而是把一个完整的古风诗词地图引擎拆开：上游怎么生产地图资产，中游怎么组织 Three.js 场景，下游怎么录屏、部署、运营，最后怎么把它变成一条可以复用的内容产线。
为什么看 Demo 学不会工程
视觉项目最容易给人一种错觉：只要画面出来了，就说明技术掌握了。但工程上真正困难的，通常不是第一版画面，而是第二次、第三次改它。第一次你可以手动调一个坐标、临时裁一张图、把某个参数写死；但下一次你要换成四川、陕西、洛阳，或者把诗词换成历史人物、非遗路线、城市文学地图，这些临时做法就会全部变成债。
这也是为什么很多 Three.js Demo 看起来惊艳，但很难迁移。它们把资源、参数、动画和展示逻辑揉在一起，读者看到的是完成品，却看不到决策链：为什么资源要这样命名？为什么高程用 RG 编码？为什么点位不直接写屏幕坐标？为什么相机要有中间控制层？这些才是工程经验。
这门课想交付的不是一份可以复制的源码，而是一套把视觉灵感拆成可维护工程的判断方式。
— Curtin
诗贯山河到底是一套什么系统
你可以把诗贯山河理解成四层系统：地图资产层、内容数据层、实时渲染层、发布运营层。地图资产层负责从 QGIS / GDAL 产出边界、高程、河流遮罩、视觉底图；内容数据层负责诗词、古地名、点位、区域、标签；实时渲染层负责 Three.js 地形、局部特效、镜头、音频；发布运营层负责 4:5 画幅、统计埋点、OSS 增量上传和线上稳定性。
- 地图资产层解决「画面从哪里来」：地形、高程、水体、边界不能靠手工截图凑。
- 内容数据层解决「诗意怎么落地」：诗词、古地名、点位和标签必须可维护。
- 实时渲染层解决「浏览器里怎么动起来」：地形 shader、粒子、后期、镜头都在这里。
- 发布运营层解决「怎么持续产出」：画幅、性能、录屏、统计和部署都属于作品的一部分。
学到什么程度才够
你不需要成为 GIS 专家，也不需要能手推 WebGL 光照公式。但你必须理解几个绕不过去的底层概念：投影坐标系决定地图能不能对齐；纹理编码决定地形精度；坐标归一化决定点位能不能跨区域复用；渲染主循环决定性能边界；数据结构决定这个项目是一次性作品还是可扩展引擎。
这跟做 Agent 要理解 token、KV Cache、约束解码是一个道理。你不一定要会训练模型，但你要知道哪些机制会影响工程质量。做诗贯山河也一样：你不一定要精通 GIS 算法，但你要知道 CRS、bounds、height map、mask、shader、camera rig 这些概念为什么会影响最终作品。
这门课不会怎么讲
- 不会从 Three.js 基础 API 开始逐个念文档。Scene、Camera、Renderer 这些请先自学到能看懂。
- 不会把 QGIS 当成地理课来讲。我们只讲前端作品需要的那部分地图资产生产。
- 不会把视觉调参神秘化。好看的参数背后通常有构图、性能和可维护性的原因。
- 不会假装所有方案都一样好。每一章都会讲我为什么选择这条路径，以及它的代价。
我是谁
我是 Curtin，大厂全栈工程师，软硬件都了解一点点。HEELI.CC 系列站点目前包括诗贯山河、Bloom 花朵绽放、奶茶包装 AI 设计平台等。这些项目共同的底色，是把视觉创作当成工程来做：能脚本化就不手工，能数据化就不写死，能复用就不复制。
我做这些项目时踩过很多坑：地图贴图不对齐、坐标一换区域就漂、粒子效果在移动端掉帧、相机飞行看起来像瞬移、录屏画幅裁掉关键信息、资源上传后缓存不更新。这些坑不是靠灵感解决的，靠的是工程约束和稳定流程。
读完前言你应该带走什么
- 诗贯山河不是页面特效课，而是视觉内容产线课。
- 你要重点理解资产、数据、渲染、发布之间的边界。
- 学习目标不是记 API，而是掌握做同类项目时的判断标准。
- 后面每一章都可以被迁移到其他主题，不只服务古风诗词。