WebGL 高度图导入实战:从灰度图片到三维地形的网格构建全解析(webgl-fundamentals)
WebGL 高度图导入实战:从灰度图片到三维地形的网格构建全解析(webgl-fundamentals)
本文以 webgl-fundamentals 仓库中的问答文章 webgl-qna-how-to-import-a-heightmap-in-webgl.md 为骨架,完整讲解「如何在不依赖 three.js / Babylon.js 等第三方库的情况下,用纯 JavaScript + WebGL 导入灰度高度图并生成三维地形」。读完本文你将掌握:高度图与网格坐标的映射原理、通过 2D Canvas + getImageData 读取图片数据的标准流程、线框网格与三角形网格的顶点/索引生成方法,以及网格法线生成与基础光照渲染的完整实现,并附上仓库内三个可直接运行的示例作为对照。
一、问题背景:把一张灰度图片变成三维地形
在 WebGL 中,地形(terrain)通常不是从建模软件导出的模型,而是由一张**高度图(heightmap)**驱动生成的。高度图本质上是一张灰度图片,像素的亮度(0~255)代表该位置的海拔:越亮越高,越暗越低。程序需要把图片上每个像素的亮度值读出来,映射成网格顶点的 Y(或 Z)坐标,从而"捏"出起伏的山丘与沟壑。
提问者在 Stack Overflow 上的原始诉求,是希望用纯 JavaScript(不引入任何第三方库)完成这一流程,并总结出了理论公式:
- 高度图上的取样坐标:
x = 宽度HM / 宽度Terrain * xTerrain,y = 高度HM / 高度Terrain * yTerrain - 高度换算:
min_height + (colorVal / (max_color - min_color) * (max_height - min_height))
这两条公式本身没有错误,它回答的是**「如何把地形上的一个点,映射回高度图上的像素,再把像素亮度换算成高度」的问题。但提问者真正卡住的是实现层面**:图片数据在浏览器里怎么读出来?读出来的像素如何与网格顶点一一对应?为什么代码一加上图片就黑屏?本仓库给出的标准答案概括起来只有一句话:
你只需要先生成一个平面点阵网格,然后按高度图的数据逐个修改顶点的 Z(或 Y)值即可。
下面先剖析提问者踩过的坑,再给出仓库中三个示例的完整实现与源码级解析。
二、常见错误与"黑屏"排查:提问者代码的问题分析
提问者最初的实现是把高度硬编码进 modifyGeometry 函数,靠 if (x>=0 && x<100) return 25; 这样的区间判断返回阶梯状高度。这种做法显然不可扩展——每换一张地形图就要改一遍代码,而且边界条件容易写错,地形永远只能是"台阶"而不是连续起伏。
随后提问者改成读取图片数据,结果画面变成空白,且没有任何报错。对照 example-2 的参考实现,可以从提问者贴出的代码中定位出几个典型的致命问题:
-
异步加载问题:提问者把
img.onload = run;注释掉了,却在window.onload中直接调用generateHeightPoints()。new Image()加载图片是异步的,若读取img.width时图片尚未就绪,其值为 0,后续ctx.canvas.width = img.width会创建一张 0×0 的画布,getImageData得到空数据,整个网格退化成一个点甚至什么都没有。正确做法是像 example-2 第 23-26 行那样,把初始化逻辑放进img.onload回调里执行。 -
变量初始化顺序错误:提问者把
var rowStride = gridWidth + 1;和numVertices的计算放在模块顶层,而gridWidth、gridDepth要到generateHeightPoints()内部才被赋值。此时gridWidth还是undefined,rowStride、numVertices直接被算成NaN。即使图片加载成功,generateIndices()里使用的rowStride也仍是NaN,最终drawElements(gl.LINES, NaN, ...)画不出任何东西——这正是"空白但无报错"的最可能原因。 -
CORS 与本地文件限制:示例中使用了
img.crossOrigin = 'anonymous';(见 example-2 第 25 行),因为getImageData会污染画布,跨域图片若未正确设置 CORS 头,读取会抛安全错误。需要特别说明:直接双击以file://协议打开页面时,跨域图片通常仍会失败,应通过本地 HTTP 服务器(如python -m http.server)访问页面,这也是仓库所有示例的运行前提。 -
顶点数量上限:示例使用
Uint16Array作为索引缓冲(gl.UNSIGNED_SHORT),单个网格顶点数需小于 65536。高度图分辨率越高,网格越密,越容易触及这一上限,后续会单独讨论。
三、标准做法三步走:网格 + 修改 Z 值
仓库答案给出的实现思路非常清晰,按三个示例循序渐进:先画平面线框 → 读取高度图修改顶点高度 → 升级为带法线的三角形网格。
3.1 第一步:生成平面网格(线框)
example-1 是一个 40×40 的平面线框网格,所有顶点高度为 0。核心代码(第 42-66 行):
const gridWidth = 40;
const gridDepth = 40;
const gridPoints = [];
for (let z = 0; z <= gridDepth; ++z) {
for (let x = 0; x <= gridWidth; ++x) {
gridPoints.push(x, 0, z); // (x, 0, z),高度先置 0
}
}
const gridIndices = [];
const rowStride = gridWidth + 1;
// x 方向的线
for (let z = 0; z <= gridDepth; ++z) {
const rowOff = z * rowStride;
for (let x = 0; x < gridWidth; ++x) {
gridIndices.push(rowOff + x, rowOff + x + 1);
}
}
// z 方向的线
for (let x = 0; x <= gridWidth; ++x) {
for (let z = 0; z < gridDepth; ++z) {
const rowOff = z * rowStride;
gridIndices.push(rowOff + x, rowOff + x + rowStride);
}
}
这里的关键点在于理解行优先存储:顶点按"z 行、x 列"的顺序压入数组,第 z 行的起始索引是 z * (gridWidth + 1)。索引缓冲中,每个网格单元由"一条 x 方向线段 + 一条 z 方向线段"组成。总线段顶点数由公式计算(第 106-107 行):
const numVertices = (gridWidth * 2 * (gridDepth + 1)) +
(gridDepth * 2 * (gridWidth + 1));
逐项拆解:gridDepth + 1 行,每行有 gridWidth 条 x 方向线段(每条 2 个顶点);gridWidth + 1 列,每列有 gridDepth 条 z 方向线段。以 40×40 为例,numVertices = 40*2*41 + 40*2*41 = 6560。数据准备好后,用 gl.bufferData(gl.ARRAY_BUFFER, new Float32Array(gridPoints), gl.STATIC_DRAW) 上传位置缓冲,用 gl.drawElements(gl.LINES, numVertices, gl.UNSIGNED_SHORT, 0) 绘制。这一阶段渲染的只是地形骨架,用于验证网格生成逻辑本身是否成立。
3.2 第二步:用 2D Canvas 读出高度图,逐顶点修改高度
example-2 在第一步的基础上加入了高度图数据。仓库示例使用的是一张 96×64 的灰度图片 heightmap-96x64.png(示例代码中为外部资源地址,实际使用时替换为自己的高度图即可)。读取流程分为三步(第 23-26 行加载、第 50-54 行读取):
const img = new Image();
img.onload = run; // 必须等图片加载完再初始化
img.crossOrigin = 'anonymous'; // 跨域读取的前提
img.src = '...heightmap-96x64.png';
// 在 run() 内部:
const ctx = document.createElement('canvas').getContext('2d');
ctx.canvas.width = img.width;
ctx.canvas.height = img.height;
ctx.drawImage(img, 0, 0);
const imgData = ctx.getImageData(0, 0, ctx.canvas.width, ctx.canvas.height);
把图片先画到一张隐藏的 2D Canvas 上,再用 getImageData 取出像素数组,是 WebGL 中读取图片数据的标准手法(WebGL 本身无法直接读取解码后的像素)。imgData.data 是一个 RGBA 交错存储的 Uint8ClampedArray,每个像素占 4 个字节。紧接着,网格尺寸直接由图片分辨率决定(第 56-66 行):
const gridWidth = imgData.width - 1;
const gridDepth = imgData.height - 1;
const gridPoints = [];
for (let z = 0; z <= gridDepth; ++z) {
for (let x = 0; x <= gridWidth; ++x) {
const offset = (z * imgData.width + x) * 4; // 每个像素 4 字节
const height = imgData.data[offset] * 10 / 255; // 高度 0~10
gridPoints.push(x, height, z);
}
}
这里有两个值得细讲的点:
- 像素坐标与网格坐标天然一一对应。因为网格分辨率被设置为"图片宽高各减 1"(96×64 的图片 → 95×63 个网格单元 → 96×64 个顶点),所以遍历像素
(x, z)得到的正是网格顶点(x, z),无需再做提问者公式里的widthHM / widthTerrain比例换算。那个换算公式只有在"地形尺寸与高度图分辨率不一致"时才需要。 - 高度映射公式的实战形式。
imgData.data[offset]取的是红色通道(R),因为灰度图中 R=G=B,取任意通道均可。* 10 / 255把 0~255 的像素值线性映射到 0~10 的世界坐标范围。这就是提问者理论公式min_height + (colorVal / (max_color - min_color) * (max_height - min_height))取min=0、max=10时的简化形式。若希望地形落在[minH, maxH],写成通用形式即为:
const height = minHeight + imgData.data[offset] / 255 * (maxHeight - minHeight);
3.3 第三步:从线框升级为三角形网格,并生成法线
线框网格无法表现实体表面,example-3 把它升级为三角形网格。生成方式是在每个网格单元(cell)内放置 4 个三角形,共用单元中心的一个顶点,而不是常见的 2 个三角形。注释中的 ASCII 图(第 48-57 行)说明了两种布局的区别:
2 4
+----+ +----+
| /| |\ /|
| / | | \/ |
| / | | /\ |
|/ | |/ \|
+----+ +----+
4 三角形布局的好处是每个顶点附近有更多相邻面,法线平均时更稳定,但代价是顶点数更多。核心生成逻辑(第 63-115 行):
const positions = [];
const texcoords = [];
const indices = [];
const cellsAcross = imgData.width - 1;
const cellsDeep = imgData.height - 1;
for (let z = 0; z < cellsDeep; ++z) {
for (let x = 0; x < cellsAcross; ++x) {
const base0 = z * imgData.width + x;
const base1 = base0 + imgData.width;
const h00 = getHeight(base0); const h01 = getHeight(base0 + 1);
const h10 = getHeight(base1);
const h11 = getHeight(base1 + 1);
const hm = (h00 + h01 + h10 + h11) / 4; // 中心点取四角平均高度
const x0 = x; const x1 = x + 1;
const z0 = z; const z1 = z + 1;
const ndx = positions.length / 3;
positions.push(
x0, h00, z0, // 顶点 0:左上
x1, h01, z0, // 顶点 1:右上
x0, h10, z1, // 顶点 2:左下
x1, h11, z1, // 顶点 3:右下
(x0 + x1) / 2, hm, (z0 + z1) / 2, // 顶点 4:中心
);
// 纹理坐标同步生成(0~1 归一化)
const u0 = x / cellsAcross; const v0 = z / cellsDeep;
const u1 = (x + 1) / cellsAcross; const v1 = (z + 1) / cellsDeep;
texcoords.push(u0, v0, u1, v0, u0, v1, u1, v1,
(u0 + u1) / 2, (v0 + v1) / 2);
indices.push(
ndx, ndx + 4, ndx + 1, // 三角形 1:0-4-1
ndx, ndx + 2, ndx + 4, // 三角形 2:0-2-4
ndx + 2, ndx + 3, ndx + 4, // 三角形 3:2-3-4
ndx + 1, ndx + 4, ndx + 3, // 三角形 4:1-4-3
);
}
}
其中 getHeight(第 43-46 行)与第二步的取高度逻辑一致,只是把像素偏移换算封装成了独立函数:
function getHeight(offset) {
const v = imgData.data[offset * 4]; // ×4 因为 RGBA 四通道
return v * 10 / 255; // 0~10
}
法线生成:源自 lathe 文章的通用算法
把顶点 Y 值抬高之后,每个顶点的法线不能再沿用平面网格时的"朝上"方向,否则光照会完全错误。example-3 复用了 webgl-3d-geometry-lathe.md 中介绍的一套通用法线生成代码(example-3 第 209-358 行),算法分四步:
- 计算每个面的法线:对每个三角形,用
m4.cross(m4.subtractVectors(v1, v2), m4.subtractVectors(v3, v2))求两条边的叉积并归一化,得到面法线。 - 找出共享顶点:由于网格中同一个位置可能出现在多个三角形里,代码通过
x + "," + y + "," + z字符串作为 key 建立顶点去重表。注释里特别用"圆柱首尾相接处 UV 不同、顶点必须分开处理"的例子说明了为什么不能简单按索引判断共享关系。 - 按共享顶点聚合面法线:遍历每个顶点的所有相邻面,只把与当前面法线夹角不超过
maxAngle的面的法线累加进来——这正是maxAngleCos = Math.cos(maxAngle)判断的作用(第 322 行)。示例传入maxAngle = 2 * Math.PI / 180(2°),目的是让地形呈现**小平面(facetted)**的硬边效果;把角度调大,折角处的法线会被平均,地形会显得更平滑。 - 重新生成顶点数据:因为"位置相同但法线不同"的顶点不能共享,代码按
位置+法线+UV的完整组合再次去重,输出新的 positions / texcoords / normals / indices。
值得一提的是,lathe 文章中的这套代码是为任意几何体设计的通用方案。正如答案中指出的,网格地形其实可以做网格特化的法线计算:因为网格结构规则、共享顶点关系已知,可以跳过"查找共享顶点"这一最耗时的步骤,直接按邻域累加法线,速度会更快。
用 twgl 压缩样板代码
example-3 使用 twgl,相关理念见 webgl-less-code-more-fun.md)。核心调用只有四条(第 161-202 行):
// 编译着色器、链接程序、查询 attribute/uniform 位置,一步完成
const programInfo = twgl.createProgramInfo(gl, [vs, fs]);
// 为每个数组自动执行 createBuffer / bindBuffer / bufferData
const bufferInfo = twgl.createBufferInfoFromArrays(gl, arrays);
// 绑定缓冲并设置顶点属性指针
twgl.setBuffersAndAttributes(gl, programInfo, bufferInfo);
// 设置 uniform 并绘制
twgl.setUniforms(programInfo, { projection, modelView });
twgl.drawBufferInfo(gl, bufferInfo);
如果不借助 twgl,这几步需要手写 createShader、createProgram、getAttribLocation、getUniformLocation、bindBuffer、bufferData、enableVertexAttribArray、vertexAttribPointer、useProgram、uniformMatrix4fv、drawElements 等一长串调用(对应提问者贴出的手工代码)。答案强调:"从 twgl 函数名就能看懂它在做什么",因此这套代码同样适用于希望回归原生 WebGL 的读者。
四、渲染与光照:让地形"立"起来
三角形网格与法线就绪后,example-3 的渲染阶段给出了完整的着色器与相机设置。
顶点着色器把位置、法线、纹理坐标传入,并计算 modelView 矩阵下的法线方向(第 127-143 行):
attribute vec4 position;
attribute vec3 normal;
attribute vec2 texcoord;
uniform mat4 projection;
uniform mat4 modelView;
varying vec3 v_normal;
varying vec2 v_texcoord;
void main() {
gl_Position = projection * modelView * position;
v_normal = mat3(modelView) * normal;
v_texcoord = texcoord;
}
片元着色器实现了一个简化的方向光漫反射模型(第 145-158 行):
precision highp float;
varying vec3 v_normal;
varying vec2 v_texcoord;
void main() {
vec3 lightDirection = normalize(vec3(1, 2, -3)); // 任意指定一个光源方向
float l = dot(lightDirection, normalize(v_normal)) * .5 + .5;
gl_FragColor = vec4(vec3(0, 1, 0) * l, 1); // 绿色地形 × 光照强度
}
dot(lightDirection, normalize(v_normal)) 计算法线与光线方向的夹角余弦,.5 + .5 把结果从 -1, 1] 映射到 [0, 1],避免背光面全黑。更完整的光照模型可参考仓库的 [webgl-3d-lighting-directional.md。
渲染循环(第 167-206 行)里还有三个值得注意的细节:
- 每帧调用
twgl.resizeCanvasToDisplaySize(gl.canvas)并重新设置 viewport,确保画布尺寸与 CSS 尺寸一致(相关原理见 webgl-resizing-the-canvas.md)。 - 开启了
gl.enable(gl.DEPTH_TEST)与gl.enable(gl.CULL_FACE),前者保证地形自遮挡关系正确,后者剔除背面三角形、减少片元处理量。 - 通过
m4.yRotate(view, time)让地形随时间绕 Y 轴旋转,并用m4.translate(..., imgData.width / -2, 0, imgData.height / -2)把网格中心平移到原点,方便观察(相机构造使用m4.lookAt/m4.inverse,见 webgl-3d-camera.md)。
五、延伸:从"导入高度图"到"绘制高度图"
仓库中还有一篇姊妹问答 webgl-qna-drawing-a-heightmap.md,讨论的是另一类需求:不修改顶点位置,而是在着色器里对纹理亮度做位移映射(displacement mapping),让顶点在片元阶段根据纹理亮度"隆起"。那篇文章同样强调了一个本篇已经遇到的问题:顶点被抬高后,法线必须重新计算——一个被抬高的顶点 E 周围有 6 个三角形,每个三角形都需要各自不同的法线。文中给出了三条路线:
- 在片元着色器中使用标准导数(
dFdx/dFdy)实时计算法线; - 在片元着色器中对位移贴图多点采样来估算法线;
- 初始化时遍历高度图,预计算一张法线贴图,例如把
RGB = 法线、A = 高度打包进同一张纹理。
这三种方案与本文的"CPU 端预计算顶点法线"思路互补,适合不同精度/性能需求的场景。更完整的问答索引见 webgl-qna.md。
六、小结与实践清单
回到最初的公式——高度图坐标映射与高度换算确实重要,但在"网格分辨率 == 图片分辨率"的标准做法下,公式可以大幅简化:像素 (x, z) 直接对应顶点 (x, z),高度用 data[offset] * 10 / 255(或更通用的 minH + data[offset] / 255 * (maxH - minH))线性映射即可。完整的可运行参照实现依次是:
- 平面线框网格:webgl-qna-how-to-import-a-heightmap-in-webgl-example-1.html
- 读取高度图并修改顶点高度:webgl-qna-how-to-import-a-heightmap-in-webgl-example-2.html
- 三角形网格 + 法线 + 光照:webgl-qna-how-to-import-a-heightmap-in-webgl-example-3.html
动手实践时的核对清单:
- 图片必须加载完成后再读取(把初始化放进
img.onload); - 跨域图片需设置
img.crossOrigin = 'anonymous',并通过 HTTP 服务访问页面; gridWidth/gridDepth/numVertices等派生量必须在赋值之后计算,避免NaN悄悄进入缓冲;- 高度抬升后必须重算法线,否则光照结果错误;
- 使用
Uint16Array索引时,顶点数需小于 65536,大分辨率高度图需考虑分块(tiling)或改用 32 位索引。
说明:本文基于仓库问答文章撰写,其中问题与引用部分遵循 CC BY-SA 4.0 协议,原作者为 Stack Overflow 用户 cosmo(问题编号 59253917)。