3D Tiles Tools项目：解决CesiumJS中B3DM瓦片升级后的渲染问题

3D Tiles Tools项目：解决CesiumJS中B3DM瓦片升级后的渲染问题

问题背景

在使用CesiumJS 1.113版本加载纽约城市B3DM数据集时，开发者遇到了一个着色器编译错误。错误信息表明片段着色器无法编译，原因是维度不匹配——试图将2分量浮点向量赋值给3分量浮点向量。这通常与模型中的法线数据格式有关。

问题分析

经过深入调查，发现该问题源于几个技术层面的复杂因素：

1. 历史遗留问题：原始B3DM文件包含的是glTF 1.0格式的数据，其中使用了特殊的VEC2/BYTE八面体编码法线表示法。

2. CesiumJS版本兼容性：CesiumJS 1.97版本后进行了内部调整，不再支持某些非常旧的glTF 1.0特性，包括这种特殊的法线编码方式。

3. 升级工具限制：虽然3D Tiles Tools的升级功能可以将B3DM文件转换为GLB格式，但转换后的glTF 2.0数据仍然保留了八面体编码的法线数据，导致渲染错误。

解决方案

1. 使用3D Tiles Tools升级数据

首先需要使用3D Tiles Tools的升级功能将B3DM数据集升级到1.1版本：

npx ts-node src/main.ts upgrade -i ../NewYork/tileset.json -o ../upgradedNY --targetVersion 1.1

2. 修复法线数据

升级后的数据仍存在问题，需要额外处理法线数据。以下是解决方案的核心部分：

// 八面体解码函数（移植自CesiumJS的octDecode.glsl）
function octDecode(encoded: number[], range: number): number[] {
  // 解码逻辑实现
  // ...
}

// 访问器解码函数
function octDecodeAccessor(
  document: Document,
  encodedAccessor: Accessor,
  range: number
) {
  // 解码实现
  // ...
}

// 主转换函数
async function runConversion() {
  // 实现完整的转换流程
  // ...
}

这个脚本会：

1. 遍历所有网格图元
2. 检查NORMAL属性
3. 对使用VEC2/BYTE或VEC2/SHORT编码的法线进行解码
4. 转换为标准的VEC3/FLOAT格式法线

3. 构建和运行修复脚本

为确保脚本正常运行，需要：

1. 使用特定分支的3D Tiles Tools
2. 删除旧的node_modules和package-lock.json
3. 重新执行npm install和npm run build

技术要点

1. 八面体编码法线：这是一种压缩法线数据的技巧，将3D法线编码为2D表示，可以节省存储空间。

2. glTF版本兼容性：glTF 2.0不再支持某些glTF 1.0的特性，转换时需要注意数据格式的兼容性。

3. 批量处理：对于大规模3D瓦片数据，需要设计高效的批量处理方案，避免手动单个文件处理。

最佳实践建议

1. 版本控制：保持CesiumJS和3D Tiles Tools版本同步更新，避免兼容性问题。

2. 预处理检查：在使用旧版3D瓦片数据前，先检查数据格式和特性支持情况。

3. 测试验证：升级处理后，应在不同版本的CesiumJS中进行全面测试。

4. 文档记录：对数据处理流程进行详细记录，便于团队协作和后续维护。

结论

通过本文介绍的方法，开发者可以成功解决CesiumJS中因B3DM瓦片升级导致的渲染问题。这不仅是针对特定案例的解决方案，也为处理类似3D瓦片数据兼容性问题提供了参考思路。随着3D Tiles标准的演进和CesiumJS的更新，建议开发者持续关注相关工具链的发展，及时调整数据处理流程。