Web 图形与 3D / 系统课时
遍历场景树定位网格节点
遍历场景树定位网格节点
模型加载成功后,门板、外壳等部件未必是根节点的直接子对象。这里用一个可运行的 Three.js 场景模拟 glTF 层级,演示如何清点 Group 和 Mesh、按名称定位节点、读取局部与世界坐标,并建立不依赖数组下标的部件索引。
学习目标
- 使用
traverse遍历整棵场景树,并通过isMesh、isGroup区分节点。 - 使用
getObjectByName找到目标部件,读取变换和userData。 - 为交互部件建立可校验的查找表,避免层级调整后访问错误对象。
看懂场景树与查询范围
GLTFLoader 加载后通常从 gltf.scene 取得模型根节点。其下可能有用于整体移动的 Group、用于开门旋转的枢轴组,以及真正带几何体和材质的 Mesh。children 只包含直接子节点,而 traverse(callback) 会访问调用者本身和全部后代。
例如 DoorPanel 位于 ProductRoot / DoorPivot / DoorPanel 的第三层。使用 root.children[1].children[0] 依赖导出顺序;美术增加一个节点后,下标可能指向别的部件。按名称搜索并检查类型更可靠。

运行遍历与精准查找
使用 Node.js 20 或更新版本,在空目录依次执行 npm init -y 和 npm install three。保存以下代码为 inspect-scene.mjs,再执行 node inspect-scene.mjs。示例直接构造节点,便于在没有外部 GLB 文件的情况下验证查询逻辑。
import { BoxGeometry, Group, Mesh, MeshBasicMaterial, Vector3 } from 'three';
const root = new Group();
root.name = 'ProductRoot';
root.position.set(10, 0, 0);
const body = new Mesh(new BoxGeometry(2, 1, 1), new MeshBasicMaterial());
body.name = 'Body';
root.add(body);
const pivot = new Group();
pivot.name = 'DoorPivot';
pivot.position.x = 1;
root.add(pivot);
const door = new Mesh(new BoxGeometry(0.1, 0.8, 0.8), new MeshBasicMaterial());
door.name = 'DoorPanel';
door.position.x = 0.2;
door.userData.partId = 'door-main';
pivot.add(door);
// 清点所有组与网格,包括嵌套层级。
root.traverse((node) => {
if (node.isGroup || node.isMesh) console.log(`${node.type}: ${node.name}`);
});
const hinge = root.getObjectByName('DoorPivot');
const panel = root.getObjectByName('DoorPanel');
if (!hinge?.isGroup || !panel?.isMesh) {
throw new Error('门轴或门板节点不存在,或类型不匹配');
}
// 在渲染循环之外读取世界变换前,更新层级矩阵。
root.updateMatrixWorld(true);
const format = (v) => v.toArray().map((n) => n.toFixed(1)).join(', ');
console.log(`局部位置: ${format(panel.position)}`);
console.log(`世界位置: ${format(panel.getWorldPosition(new Vector3()))}`);
console.log(`部件标识: ${panel.userData.partId}`);
const parts = new Map();
root.traverse((node) => {
if (!node.isMesh || typeof node.userData.partId !== 'string') return;
const id = node.userData.partId;
if (parts.has(id)) throw new Error(`重复 partId: ${id}`);
parts.set(id, node);
});
console.log(`映射命中: ${parts.get('door-main') === panel}`);预期输出:
Group: ProductRoot
Mesh: Body
Group: DoorPivot
Mesh: DoorPanel
局部位置: 0.2, 0.0, 0.0
世界位置: 11.2, 0.0, 0.0
部件标识: door-main
映射命中: truetraverse 的回调适合读取与收集节点,不要在遍历过程中直接增删当前场景树的子节点。节点多时可以先筛选 node.isMesh;这里同时列出 Group,是为了让枢轴和可见网格的区别更明确。
核对坐标和自定义元数据
panel.position 表示相对父级 DoorPivot 的局部位置,示例为 X=0.2;DoorPivot 相对根节点为 X=1,根节点 X=10,因此门板的世界 X=11.2。此处没有旋转和缩放,才能直接相加;真实模型有旋转或缩放时应使用 getWorldPosition(new Vector3()),不要手动累加位置。
同理,rotation 是局部欧拉角且使用弧度,scale 是局部缩放;需要世界姿态时可用 getWorldQuaternion 或 getWorldScale。模型尚未经历渲染更新时,先调用 root.updateMatrixWorld(true),可避免直接读取过时的 matrixWorld。
userData 是节点附加数据对象。这里约定 partId='door-main' 表示业务身份,而 name='DoorPanel' 用于在场景里定位。外部 glTF 资源可能通过节点 extras 提供自定义数据,但不能假设每个文件都已有 partId;必须查看实际导出内容。
在真实模型中稳定访问部件
在 GLTFLoader.loadAsync 成功返回后,将示例里的构造步骤替换为取得 gltf.scene,再执行遍历与查找;如果使用 load 回调,必须在成功回调内访问节点,不能在异步加载完成前查询。
- 先打印每个节点的
name、type和userData,核对导出后的实际命名;空名称不能作为可靠检索键。 - 对唯一命名节点用
getObjectByName('DoorPanel'),并检查?.isMesh;未找到返回undefined,同名多个节点时只返回第一个匹配项。 - 对大量可交互零件,统一约定不重复的
userData.partId,加载完成后一次遍历构建Map;重复 ID 立即报错,而不是悄悄覆盖。 - 操作整个门体的转轴时选择
DoorPivot组,修改门板材质时选择DoorPanel网格;不要把二者混用。重新加载模型后应重建映射,避免保留旧场景的对象引用。
验证标准是:门板节点类型为 Mesh、门轴节点类型为 Group、parts.get('door-main') 指向同一门板对象,局部坐标与世界坐标符合父子变换。只要这些检查通过,后续做零件高亮和开合动画就不必依赖易变的 children 下标。