Web 图形与 3D / 系统课时

清点 glTF 节点与网格数据

清点 glTF 节点与网格数据

一个 GLB 下载只有几兆字节,加载时仍可能因网格解码、纹理上传和首次绘制出现长帧。本篇用静态报告与节点树脚本,查明 glTF 2.0 的层级、图元、动画通道和纹理引用,并形成可核对的资源成本清单。

学习目标

  • 区分场景节点、Mesh、Primitive 与材质纹理的共享关系,避免重复计数。
  • 对 GLB/glTF 输出网格、节点层级、动画目标和纹理来源清单。
  • 用文件体积、图元实例数和纹理估算值筛选加载尖峰风险。

分清节点实例与网格资源

glTF 的 Scene 引用根 Node;节点通过 children 形成层级,可以用 mesh 引用一个网格。一个 Mesh 包含多个 Primitive,每个图元可指定自己的 Material,材质的贴图槽再引用 Texture 和 Image。动画通道指向节点的位移、旋转、缩放或权重,而不是直接变更共享网格资源。

例如,两个节点都引用同一个具有两个图元的网格:文件里只有一份网格资源,却有四个图元实例的候选绘制工作。实际 draw calls 还受可见性、实例化、渲染通道等影响,不可直接照搬这个数值。

glTF 场景节点、共享网格、动画及纹理引用结构

用检查命令取得静态报告

准备 Node.js 的受支持 LTS 版本,把模型放到项目的 assets/hero.glb;对于 .gltf,保留它引用的 .bin、图片文件及相对目录。glTF Transform 的 inspect 会列出场景、网格、材质、纹理和动画,适合先找异常的大图与复杂网格。

bash
npm install --save-dev @gltf-transform/cli
npx gltf-transform inspect ./assets/hero.glb

预期输出(仅摘录报告的分区名称,省略随资产变化的表格数据和边框):

text
OVERVIEW
SCENES
MESHES
MATERIALS
TEXTURES
ANIMATIONS

重点看 MESHES 中的 primitives、vertices、instances 与 size,其中 glPrimitives 表示三角形等图元数量,并非 draw calls;看 TEXTURES 的分辨率、格式和大小,以及 ANIMATIONS 的通道数据。若命令报找不到外部资源,先核对 .gltf 内的 URI 与磁盘路径,不要直接判定模型已损坏。

展开层级并追踪引用

inspect 的场景摘要不足以呈现所有父子节点。下面脚本直接读取 .gltf JSON 或 .glb 的 JSON 块,不需要解码网格压缩数据;它会打印节点树、图元资源数、按节点累计的图元引用、动画目标,以及核心材质纹理槽。将代码保存为 inventory.mjs。

js
import { readFile } from 'node:fs/promises';

const file = process.argv[2];
if (!file || !/\.(gltf|glb)$/i.test(file)) {
  throw new Error('用法: node inventory.mjs <model.gltf|model.glb>');
}
const bytes = await readFile(file);
let doc;

// GLB 的第一块是 JSON;这里只盘点引用,不解码二进制顶点或图片。
if (/\.glb$/i.test(file)) {
  if (bytes.length < 20 || bytes.readUInt32LE(0) !== 0x46546c67 ||
      bytes.readUInt32LE(4) !== 2 || bytes.readUInt32LE(16) !== 0x4e4f534a) {
    throw new Error('无效的 glTF 2.0 GLB');
  }
  const length = bytes.readUInt32LE(12);
  doc = JSON.parse(bytes.subarray(20, 20 + length).toString('utf8'));
} else {
  doc = JSON.parse(bytes.toString('utf8'));
}
const scenes = doc.scenes ?? [];
const nodes = doc.nodes ?? [];
const meshes = doc.meshes ?? [];
const animations = doc.animations ?? [];
const textures = doc.textures ?? [];
const images = doc.images ?? [];
const primitiveCount = meshes.reduce((n, m) => n + (m.primitives?.length ?? 0), 0);
const referencedPrimitives = nodes.reduce(
  (n, node) => n + (node.mesh === undefined ? 0 : (meshes[node.mesh]?.primitives?.length ?? 0)), 0
);
console.log(`bytes=${bytes.length} scenes=${scenes.length} nodes=${nodes.length} meshes=${meshes.length} primitives=${primitiveCount} referencedPrimitives=${referencedPrimitives}`);

// 从每个场景的根节点按层级展开;节点编号对应 glTF 的 nodes 数组。
for (const [si, scene] of scenes.entries()) {
  console.log(`scene[${si}] ${scene.name || '(unnamed)'}`);
  const visit = (index, depth) => {
    const node = nodes[index];
    if (!node) return;
    console.log(`${'  '.repeat(depth)}node[${index}] ${node.name || '(unnamed)'} mesh=${node.mesh ?? '-'}`);
    for (const child of node.children ?? []) visit(child, depth + 1);
  };
  for (const index of scene.nodes ?? []) visit(index, 1);
}
for (const [i, animation] of animations.entries()) {
  console.log(`animation[${i}] channels=${animation.channels?.length ?? 0}`);
  for (const channel of animation.channels ?? []) {
    console.log(`  target node=${channel.target?.node ?? '-'} path=${channel.target?.path ?? '-'}`);
  }
}

// 列出 glTF 核心材质的纹理槽;扩展材质另用 inspect 核对。
for (const [i, material] of (doc.materials ?? []).entries()) {
  const pbr = material.pbrMetallicRoughness ?? {};
  const slots = [
    ['baseColor', pbr.baseColorTexture],
    ['metallicRoughness', pbr.metallicRoughnessTexture],
    ['normal', material.normalTexture],
    ['occlusion', material.occlusionTexture],
    ['emissive', material.emissiveTexture]
  ];
  const used = slots.filter(([, ref]) => ref?.index !== undefined)
    .map(([name, ref]) => `${name}=texture[${ref.index}]`);
  console.log(`material[${i}] ${used.join(', ') || 'no core textures'}`);
}
for (const [i, texture] of textures.entries()) {
  const source = texture.source ?? texture.extensions?.KHR_texture_basisu?.source
    ?? texture.extensions?.EXT_texture_webp?.source ?? texture.extensions?.EXT_texture_avif?.source;
  console.log(`texture[${i}] image=${source ?? '-'} uri=${images[source]?.uri ?? '(embedded/extension)'}`);
}

预期结果的验证方式:保存脚本后运行下面命令,替换为自己的文件路径。

bash
node inventory.mjs ./assets/hero.glb

预期输出(数量和名称取决于输入资源;没有动画、材质或纹理时对应行不会出现):

text
bytes=<BYTES> scenes=<N> nodes=<N> meshes=<N> primitives=<N> referencedPrimitives=<N>
scene[0] <SCENE_NAME>
  node[0] <NODE_NAME> mesh=<INDEX_OR_DASH>
animation[0] channels=<N>
  target node=<INDEX_OR_DASH> path=<PATH>
material[0] <TEXTURE_SLOTS_OR_NONE>
texture[0] image=<INDEX_OR_DASH> uri=<URI_OR_EMBEDDED>

注意 referencedPrimitives 累加的是文件中全部节点的网格引用,可能包含当前未激活场景或不可见节点,不能当作实测绘制次数。脚本的 bytes 只包含主文件;.gltf 的外置缓冲和图片还要另外计入传输体积。

把清单换算成加载成本

下表是一个假设的角色模型盘点样例,用来填写评审单,而非实际测量结果:

指标 假设数据 成本判断
主 GLB 体积 6 MiB 代表传输大小,不代表解码后的 GPU 占用
网格图元实例 1 个 Mesh × 2 个 Primitive × 40 个节点 80 个候选图元实例,需再用运行时 draw calls 核对
图片上传 2 张 2048×2048 RGBA8,完整 mipmap 约 42.7 MiB 显存,仅为未压缩纹理估算
动画 3 个动画、共 120 条通道 关注激活通道与关键帧处理,不把通道数算成绘制次数

纹理估算按每张 2048 × 2048 × 4 × 4/3 字节计算,约为 21.3 MiB;4/3 是完整 mipmap 链的近似系数。KTX2 等 GPU 压缩纹理必须按实际压缩格式另算;多个材质引用同一张图片,也不能简单重复累加图片体积。

对照 Three.js 中的实测值

  1. 固定相机、模型和画布分辨率,分别记录首次加载后的一帧与预热后的稳定帧。
  2. 在 WebGLRenderer 渲染完成后读取 renderer.info.render.calls、renderer.info.render.triangles、renderer.info.memory.textures;有多个渲染通道时,按项目实际重置策略统计整帧。
  3. 将 inspect 的纹理分辨率、主文件字节数和节点引用清单,与浏览器 Network、Performance 中的下载、解码和上传时间对应。

若文件很小但首次出现纹理时卡顿,优先调查图片解码、GPU 上传和着色器编译;若稳定帧调用次数持续很高,则回查节点复用、图元数量与材质切分。交付清单至少保留文件版本、场景名、Mesh/Primitive 数量、纹理规格、动画通道数及两类帧的实测值,后续优化才有可比较的基线。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

清点 glTF 节点与网格数据

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通