生成的 GLB 怎么自动验收?五份模型实测

用五份真实 GLB 实测规范验证、三角面上限和画面验收。附实际错误、结果截图和可运行脚本。

生成的 GLB 怎么自动验收?五份模型实测

GLB 能在浏览器打开,仍可能交付不了。我们把五份生成文件放进同一套验收流程。Tripo P2 保留了狗、靠背和椅腿,但超过 20,000 面的上限 794 面。另一份 TRELLIS 文件通过了格式、体积和面数检查,画面里却只剩狗和一小块平面。要判断一个生成资产能否入库,需要把规范验证、交付门槛和画面验收连起来看。

先说结论

  • 五份原始 GLB 里,两份未通过自动验收,两份因警告进入人工复核,一份通过机器检查。五份都低于示例的 5,000,000 字节上限。
  • TRELLIS.2 的挎包同时触发了规范错误和面数门槛。Tripo P2 的长椅虽然没有验证错误,仍因实际面数超标而退回。
  • Tripo H3.1 和 Rodin Fast 的长椅样本均满足两项数字门槛,但各有一条切线空间警告,需要在目标查看器里复核材质。
  • TRELLIS 的长椅样本通过机器检查,却没有保留完整长椅。自动通过只表示可以进入下一步视觉验收。

为项目定义一份能执行的验收规则

先让 Khronos glTF Validator 检查文件是否符合规范,记录错误、警告和位置。再检查项目自己的交付要求。本文示例要求文件不超过 5 MB 和 20,000 个三角面,使用三角形图元,缓冲区和图片均内嵌,并声明基础色贴图。最后按输入图判断主体是否完整。长椅这组要同时看到狗、座面、靠背和椅腿,最后一项由人确认。

根据用途定门槛。网页预览可能要求一份自包含 GLB,加载后能看到原有的颜色。白模流程可能不需要基础色贴图。另一套产品也可能允许共用外部贴图。这里的脚本针对静态、贴图内嵌的 GLB,数的是文件里存储的图元。若预算针对某帧实际绘制的三角面,还要看场景中的引用、实例和可见性。 Khronos glTF 规范

五份 GLB 的自动验收报告截图,包含文件字节、三角面和决策

表格从脚本实际生成的 JSON 渲染。PASS 是机器检查结果,画面验收另做记录。

文件字节三角面内嵌图片错误 / 警告自动验收
TRELLIS.2 挎包4,380,64893,35221 / 0失败
Tripo P2 狗和长椅3,879,77220,79430 / 1失败
Tripo H3.1 狗和长椅4,447,73618,83430 / 1待复核
Rodin 2.5 Fast 狗和长椅3,125,64019,89230 / 1待复核
TRELLIS 狗和长椅3,981,80011,22210 / 0通过

文件来自 TRELLIS 两代对比、Tripo 面数实测 和 Rodin 两个档位的对比。四份长椅输出用了同一张原图,挎包用另一张图。本次用同一脚本重新检查原始输出,选样是为了覆盖三种验收分支,样本比例不能推算供应商的失败率。

运行验收脚本

1. 安装验证器

使用以下版本的 Khronos JavaScript 包,把测试 GLB 放在当前目录。脚本为每份文件计算 SHA-256,日志可绑定到实际验收过的文件。 Khronos glTF Validator

Shell
npm install [email protected]

2. 把规则保存为 qa.mjs

缺少基础色贴图声明或存在外部资源时,脚本会拒收。材质一栏统计声明数量。要检查每个可见部件有没有用对材质,还需沿着图元的材质索引查找,再对照渲染结果。警告数量取自验证器的汇总,同时保留每条问题的严重级别与位置。

JavaScript
import { readFile } from 'node:fs/promises';
import { createHash } from 'node:crypto';
import validator from 'gltf-validator';

const budget = { bytes: 5_000_000, triangles: 20_000 };
const paths = process.argv.slice(2);
if (!paths.length) {
  console.error('Usage: node qa.mjs file.glb [file.glb ...]');
  process.exit(2);
}
const records = [];
for (const path of paths) {
  const record = { path, checks: [] };
  try {
    const data = await readFile(path);
    record.bytes = data.length;
    record.sha256 = createHash('sha256').update(data).digest('hex');
    if (data.length < 28 || data.toString('ascii', 0, 4) !== 'glTF'
        || data.readUInt32LE(4) !== 2 || data.readUInt32LE(8) !== data.length
        || data.readUInt32LE(16) !== 0x4e4f534a
        || data.readUInt32LE(12) > data.length - 20) {
      throw new Error('Invalid GLB v2 header or JSON chunk');
    }
    const report = await validator.validateBytes(data, { uri: path });
    record.validator = {
      errors: report.issues.numErrors,
      warnings: report.issues.numWarnings,
      messages: report.issues.messages.map(({ code, severity, pointer }) => ({ code, severity, pointer })),
    };
    if (record.validator.errors) record.checks.push('VALIDATOR_ERROR');
    const json = JSON.parse(data.toString('utf8', 20, 20 + data.readUInt32LE(12)));
    const primitives = (json.meshes ?? []).flatMap(mesh => mesh.primitives);
    if (!primitives.length || primitives.some(p => (p.mode ?? 4) !== 4)) {
      throw new Error('This policy requires triangle primitives');
    }
    if ((json.images ?? []).some(image => image.bufferView === undefined)
        || (json.buffers ?? []).some(buffer => buffer.uri)) {
      throw new Error('This policy requires embedded buffers and images');
    }
    record.triangles = primitives.reduce((sum, primitive) => {
      const count = json.accessors[primitive.indices ?? primitive.attributes.POSITION].count;
      return sum + count / 3;
    }, 0);
    record.images = json.images?.length ?? 0;
    record.baseColorMaps = (json.materials ?? []).filter(m => m.pbrMetallicRoughness?.baseColorTexture !== undefined).length;
    record.normalMaps = (json.materials ?? []).filter(m => m.normalTexture !== undefined).length;
    if (record.bytes > budget.bytes) record.checks.push('FILE_BYTES_LIMIT');
    if (record.triangles > budget.triangles) record.checks.push('TRIANGLE_LIMIT');
    if (!record.baseColorMaps) record.checks.push('BASE_COLOR_TEXTURE_REQUIRED');
  } catch (error) {
    record.checks.push('UNSUPPORTED_OR_UNREADABLE');
    record.detail = error.message;
  }
  record.status = record.checks.length ? 'fail' : record.validator.warnings ? 'review' : 'pass';
  records.push(record);
}
console.log(JSON.stringify({ budget, records }, null, 2));
if (records.some(record => record.status === 'fail')) process.exitCode = 2;
else if (records.some(record => record.status === 'review')) process.exitCode = 1;

3. 对一批原始文件运行

下面是本文所用的本地文件名。你可以替换为自己的文件路径。即使一份模型失败,脚本也会先生成机器可读报告,再设置退出码。本文五份文件的批次返回 2,代表至少有一个文件需要退回。

Shell
node qa.mjs satchel-trellis2.glb bench-p2.glb bench-h31.glb bench-rodin-fast.glb bench-trellis.glb > qa-results.json
printf 'Intake exit code: %s\n' "$?"

4. 分别验证三个退出分支

接入 CI 时,可先用每个状态的一份文件检查分流逻辑。下面三个命令实测分别返回 0、1、2。保留 JSON 后,再按退出码分流。如果 shell 遇到非零就退出,可以用 if/else 捕获状态后继续读取报告。

Shell
node qa.mjs bench-trellis.glb > pass.json
printf 'Pass example: %s\n' "$?"
node qa.mjs bench-h31.glb > review.json
printf 'Review example: %s\n' "$?"
node qa.mjs satchel-trellis2.glb > fail.json
printf 'Failure example: %s\n' "$?"

5. 读取退回原因和验证位置

同一份文件可能同时超预算和触发材质警告。只保存一个失败标签,后面就难以判断是哪个环节出了问题。下面的命令把每个文件的状态、策略原因和验证位置输出。记录时和文件哈希放在一起,更新派生文件后可以再跑一遍,确认哪条问题消失、哪条仍在。

Shell
node --input-type=module -e '
import { readFileSync } from "node:fs";
const { records } = JSON.parse(readFileSync("qa-results.json", "utf8"));
for (const { path, status, checks, validator } of records) {
  console.log(path, status, checks.join(","));
  for (const { code, pointer } of validator?.messages ?? []) {
    console.log(" ", code, pointer ?? "");
  }
}
'

按原因处理三类文件

真实验证报告的三种决策,显示策略失败原因、Khronos 错误和警告路径

红色状态对应规范或预算退回。黄色状态保留材质警告,等待目标查看器复核。

挎包需要处理两条问题。 验证器在图元的 NORMAL 访问器上报了 ACCESSOR_VECTOR3_NON_UNIT,其中一个向量长度为零。需要检查或重新计算法线。该文件同时有 93,352 面,超出本文的门槛。先保留原件,处理后重跑验证和网格、材质检查。本文脚本只检查,挎包仍是原始输出。 Khronos 验证器问题定义

P2 长椅需要控制几何。 它的文件比 H3.1 小,但实际有 20,794 面,比 20,000 面高 3.97%。请求参数能指导生成,交付时要用实际文件计数。如果要减面,保留原件并另存派生文件,再按产品实际视距检查靠背开孔和椅腿。 减面与缩贴图实测

H3.1 和 Rodin 需要复核材质。 两份都有 MESH_PRIMITIVE_GENERATED_TANGENT_SPACE。法线贴图依赖运行时生成的切线空间,不同实现可能有差异。用上线版本的查看器打方向光,旋转模型观察高光和接缝。记录目标查看器是否可以接受此警告,或者要求下一版资产带显式切线。

把渲染结果与验收状态一起看

三份长椅 GLB 的实际渲染,依次是 P2 失败、Rodin Fast 待复核和 TRELLIS 自动通过

三份原始文件在 Three.js 中按主体对齐,使用统一光照与归一化画幅。标签来自自动验收结果。

左侧 P2 的座面、靠背和椅腿清楚可见,几何门槛仍未达标。中间 Rodin Fast 有狗和一小段座面,即便材质警告可以接受,视觉也达不到完整长椅的要求。右侧 TRELLIS 有基础色贴图,验证器没有错误或警告,实际却缺靠背和椅腿。如果你承诺交付完整的狗与长椅,就需要把这份文件的视觉结果标成退回。

视觉记录至少保留原图、按主体对齐的正面和侧面。需要旋转时补背面,再为最薄的部件或最关键的材质接缝截近景。长椅可以先看腿,再绕到背面看网格是否完整。若生产页面使用固定相机,也要用实际构图验一次。本文脚本的范围是文件、网格和材质声明,真实加载性能与可打印性需另行实测。

从 TRELLIS.2 图生 3D 或 Tripo H3.1 图生 3D 导出一份 GLB,先跑验收脚本保存报告,再打开查看器。超出门槛时,用准确的文件哈希记录退回原因。通过机器检查后,继续按主体清单验收画面,再决定是否入库。

要把原件、验收结果和派生文件串起来,可以继续看可检索的 GLB 资产库。

GLB 来自后台任务时,可以接着看异步图生 3D 从提交到下载,了解自动验收之前怎么取件。

同一个 TRELLIS.2 挎包的后续修复见 GLB 零法线与 Blender 验证。

常见问题

有法线贴图就算有基础色贴图吗?

脚本检查不同的材质属性。法线贴图影响光照,基础色贴图提供表面颜色。两种声明分别计数。有法线图的文件,如果缺少基础色声明,仍会触发相应规则。

可以在 CI 里直接用这三个退出码吗?

可以。0 表示转视觉验收,1 表示转警告复核,2 表示退回。多数 CI 会把非零都标成命令失败,接入时需要分别捕获并保存报告,避免丢失复核所需的信息。

一个网格被复用多次,面数要乘几倍?

本脚本对文件里的网格图元各计一次。若要估算实际绘制负载,需要考虑场景引用、可见性和实例,还要在目标应用测设备表现。把文件面数和实际渲染指标作为两个字段记录。

觉得有用?分享给更多人