WebGL 高度图导入实战:从灰度图片到三维地形的网格构建全解析(webgl-fundamentals)

原创2026-10-14 23:37:091,437 阅读
文章标签:图形学

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 的参考实现,可以从提问者贴出的代码中定位出几个典型的致命问题:

  1. 异步加载问题:提问者把 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 回调里执行。

  2. 变量初始化顺序错误:提问者把 var rowStride = gridWidth + 1; 和 numVertices 的计算放在模块顶层,而 gridWidth、gridDepth 要到 generateHeightPoints() 内部才被赋值。此时 gridWidth 还是 undefined,rowStride、numVertices 直接被算成 NaN。即使图片加载成功,generateIndices() 里使用的 rowStride 也仍是 NaN,最终 drawElements(gl.LINES, NaN, ...) 画不出任何东西——这正是"空白但无报错"的最可能原因。

  3. CORS 与本地文件限制:示例中使用了 img.crossOrigin = 'anonymous';(见 example-2 第 25 行),因为 getImageData 会污染画布,跨域图片若未正确设置 CORS 头,读取会抛安全错误。需要特别说明:直接双击以 file:// 协议打开页面时,跨域图片通常仍会失败,应通过本地 HTTP 服务器(如 python -m http.server)访问页面,这也是仓库所有示例的运行前提。

  4. 顶点数量上限:示例使用 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 行),算法分四步:

  1. 计算每个面的法线:对每个三角形,用 m4.cross(m4.subtractVectors(v1, v2), m4.subtractVectors(v3, v2)) 求两条边的叉积并归一化,得到面法线。
  2. 找出共享顶点:由于网格中同一个位置可能出现在多个三角形里,代码通过 x + "," + y + "," + z 字符串作为 key 建立顶点去重表。注释里特别用"圆柱首尾相接处 UV 不同、顶点必须分开处理"的例子说明了为什么不能简单按索引判断共享关系。
  3. 按共享顶点聚合面法线:遍历每个顶点的所有相邻面,只把与当前面法线夹角不超过 maxAngle 的面的法线累加进来——这正是 maxAngleCos = Math.cos(maxAngle) 判断的作用(第 322 行)。示例传入 maxAngle = 2 * Math.PI / 180(2°),目的是让地形呈现**小平面(facetted)**的硬边效果;把角度调大,折角处的法线会被平均,地形会显得更平滑。
  4. 重新生成顶点数据:因为"位置相同但法线不同"的顶点不能共享,代码按 位置+法线+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 个三角形,每个三角形都需要各自不同的法线。文中给出了三条路线:

  1. 在片元着色器中使用标准导数(dFdx / dFdy)实时计算法线;
  2. 在片元着色器中对位移贴图多点采样来估算法线;
  3. 初始化时遍历高度图,预计算一张法线贴图,例如把 RGB = 法线、A = 高度 打包进同一张纹理。

这三种方案与本文的"CPU 端预计算顶点法线"思路互补,适合不同精度/性能需求的场景。更完整的问答索引见 webgl-qna.md。

六、小结与实践清单

回到最初的公式——高度图坐标映射与高度换算确实重要,但在"网格分辨率 == 图片分辨率"的标准做法下,公式可以大幅简化:像素 (x, z) 直接对应顶点 (x, z),高度用 data[offset] * 10 / 255(或更通用的 minH + data[offset] / 255 * (maxH - minH))线性映射即可。完整的可运行参照实现依次是:

动手实践时的核对清单:

  1. 图片必须加载完成后再读取(把初始化放进 img.onload);
  2. 跨域图片需设置 img.crossOrigin = 'anonymous',并通过 HTTP 服务访问页面;
  3. gridWidth / gridDepth / numVertices 等派生量必须在赋值之后计算,避免 NaN 悄悄进入缓冲;
  4. 高度抬升后必须重算法线,否则光照结果错误;
  5. 使用 Uint16Array 索引时,顶点数需小于 65536,大分辨率高度图需考虑分块(tiling)或改用 32 位索引。

说明:本文基于仓库问答文章撰写,其中问题与引用部分遵循 CC BY-SA 4.0 协议,原作者为 Stack Overflow 用户 cosmo(问题编号 59253917)。

登录后查看全文
webgl-fundamentals