3D Tiles Tools 使用教程

项目概述

3D Tiles Tools 是一个用于处理和优化 3D Tiles 数据的开源工具集，由 Cesium GS 公司开发和维护。该工具集提供了丰富的命令行工具，用于转换、优化、处理和分析 3D Tiles 数据。

安装方法

通过 NPM 安装

要将 3D Tiles Tools 安装到本地目录，请运行：

npm install 3d-tiles-tools

从源码安装

如果想直接使用 Git 仓库的源码，请按照以下步骤操作：

1. 克隆仓库到当前目录：

git clone https://gitcode.com/gh_mirrors/3d/3d-tiles-tools

2. 进入克隆的仓库目录：

cd 3d-tiles-tools

3. 安装工具和所有依赖：

npm install

项目结构

3D Tiles Tools 的项目结构清晰，主要包含以下重要目录：

• bin/: 包含可执行文件，主要是 CLI 入口文件
• demos/: 包含演示和示例代码
• etc/: 包含额外的配置文件
• figures/: 包含项目文档中使用的图片
• specs/: 包含 3D Tiles 规范文件和测试数据
• src/: 包含所有源代码文件

配置文件说明

项目包含多个重要的配置文件：

• eslintrc.json: ESLint 配置文件，用于代码风格检查
• prettierrc.json: Prettier 配置文件，用于代码格式化
• tsconfig.json: TypeScript 配置文件，定义编译选项
• package.json: npm 包配置文件，包含项目依赖和脚本

命令行工具使用

通用命令行选项

所有命令都支持以下通用选项：

选项	描述	是否必需
-i, --input	输入文件或目录	是
-o, --output	输出文件或目录	是
-f, --force	覆盖已存在的输出	否，默认 false
--logLevel	日志级别，可选值：trace, debug, info, warn, error, fatal, silent	否，默认 info
--logJson	以 JSON 格式输出日志消息	否，默认 false

Tileset 处理工具

gzip 压缩

对输入的 tileset 进行 GZIP 压缩：

npx 3d-tiles-tools gzip -i ./specs/data/TilesetOfTilesets/ -o ./output/TilesetOfTilesets-gzipped/

ungzip 解压缩

解压缩 GZIP 压缩的 tileset：

npx 3d-tiles-tools ungzip -i ./specs/data/TilesetOfTilesets-gzipped/ -o ./output/TilesetOfTilesets-ungzipped/

combine 合并

将所有外部 tileset 合并为单个 tileset：

npx 3d-tiles-tools combine -i ./specs/data/combineTilesets/input -o ./specs/data/combineTilesets/output

upgrade 升级

将 tileset 升级到最新的 3D Tiles 版本：

npx 3d-tiles-tools upgrade -i ./specs/data/TilesetOfTilesets/tileset.json -o ./output/upgraded

瓦片内容处理工具

glbToB3dm 转换

从 GLB 文件创建带有空批处理表的 B3DM：

npx 3d-tiles-tools glbToB3dm -i ./specs/data/CesiumTexturedBox/CesiumTexturedBox.glb -o ./output/CesiumTexturedBox.b3dm

b3dmToGlb 提取

从 B3DM 中提取 GLB 内容：

npx 3d-tiles-tools b3dmToGlb -i ./specs/data/batchedWithBatchTableBinary.b3dm -o ./output/extracted.glb

optimizeB3dm 优化

使用 gltf-pipeline 优化 B3DM：

npx 3d-tiles-tools optimizeB3dm -i ./specs/data/batchedWithBatchTableBinary.b3dm -o ./output/optimized.b3dm

开发脚本

项目提供了丰富的 npm 脚本用于开发：

• npm run build: 编译 TypeScript 代码
• npm run test: 运行单元测试
• npm run eslint: 代码风格检查
• npm run prettier: 代码格式化
• npm run coverage: 计算测试覆盖率

使用示例

完整的处理流程

以下是一个完整的 tileset 处理流程示例：

# 1. 升级 tileset 到最新版本
npx 3d-tiles-tools upgrade -i input/tileset.json -o upgraded/

# 2. 优化所有 B3DM 内容
npx 3d-tiles-tools optimizeB3dm -i upgraded/ -o optimized/ --options --draco.compressMeshes

# 3. 打包为 3TZ 格式
npx 3d-tiles-tools convert -i optimized/tileset.json -o output.3tz

注意事项

• 所有输入和输出路径都区分大小写
• 使用 --force 选项时要谨慎，它会覆盖现有文件
• 对于大型数据集，建议使用较高的日志级别以减少输出

3D Tiles Tools 提供了强大的 3D Tiles 数据处理能力，无论是简单的格式转换还是复杂的优化流程，都能满足各种应用场景的需求。