3D Tiles 工具

概述

3D Tiles 工具是一组用于转换、优化、处理和分析 3D Tiles 数据的工具和实用程序。

安装

要在本地目录中安装 3D Tiles 工具，请运行以下命令：

npm install 3d-tiles-tools

如果想直接使用 Git 仓库的克隆版本，请参阅开发者设置。

命令行用法

注意： 所有 3D Tiles 工具的输入和输出路径都是_区分大小写_的。即使某些操作系统（如 Windows）通常不区分大小写，命令行中提供的文件名和目录名也必须与实际名称完全匹配。

每个功能的通用命令行选项：

瓦片集的命令行工具

gzip

对输入的瓦片集进行 Gzip 压缩。

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

附加命令行选项：

^{（注意：使用 tilesOnly 的确切文件集尚未指定）}

ungzip

解压输入的瓦片集。

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

combine

将所有外部瓦片集合并为一个单一瓦片集。

注意 关于 merge 和 combine 的区别：combine 命令接受一个已经引用了_外部_瓦片集的瓦片集，并创建一个新的瓦片集，其中原来的_外部_瓦片集被“内联”。结果是一个没有外部引用的单一瓦片集。

示例：

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

merge

将多个瓦片集合并为一个，该瓦片集将输入的瓦片集作为外部瓦片集引用。

注意 关于 merge 和 combine 的区别：merge 命令创建一个_新_瓦片集，该瓦片集将给定的瓦片集作为_外部_瓦片集引用。这意味着生成的瓦片集在没有那些作为 merge 命令输入的瓦片集时是不完整的。

示例：

npx 3d-tiles-tools merge -i ./specs/data/mergeTilesets/TilesetA -i ./specs/data/mergeTilesets/sub/TilesetA -o ./specs/data/mergeTilesets/output

mergeJson

将多个瓦片集合并为一个单一瓦片集 JSON 文件，该文件将输入的瓦片集作为外部瓦片集引用。

这与 merge 命令的不同之处在于它不会将输入瓦片集复制到输出目录，而只是创建合并瓦片集的 JSON 文件，该文件使用相对路径引用输入瓦片集。常见的用例是在某个目录中创建瓦片集 JSON 文件，而输入瓦片集位于子目录中。

示例：

npx 3d-tiles-tools mergeJson -i ./example/TilesetA/tileset.json -i ./example/TilesetB/tileset.json -o ./example/mergedTileset.json

upgrade

将瓦片集升级到最新的 3D Tiles 版本。

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

附加命令行选项：

默认情况下，这会将旧版瓦片集升级以符合 3D Tiles 1.0 规范。

这些升级包括：

• 资产版本将设置为 '1.0'。
• 使用 url 的瓦片内容将升级为使用 uri。
• refine 值将转换为全大写。
• B3DM 或 I3DM 中的 glTF 1.0 模型将升级为 glTF 2.0。

实现说明：

内部，glTF 1.0 资产转换为 glTF 2.0 资产是通过使用 gltf-pipeline 处理 GLB 数据来完成的。这将包括尝试将使用 KHR_technique_webgl 扩展的材质转换为 PBR 材质。在 --options 参数之后给出的选项将传递给 gltf-pipeline。这些选项可能包括应指示特定纹理是否应作为 PRB 材质的基础颜色纹理的统一变量名称。例如，当瓦片集中包含带 KHR_technique_webgl 扩展的 B3DM 或 I3DM 数据，且统一变量名称 u_diff_tex 和 u_diffuse 表明某个纹理应为基础颜色纹理时，可以使用以下命令行：

npx 3d-tiles-tools upgrade -i ./input/tileset.json -o ./output/tileset.json --options --baseColorTextureNames u_diff_tex --baseColorTextureNames u_diffuse

当指定了 --targetVersion 1.1 时，这将把旧版瓦片集升级以符合 3D Tiles 1.1 规范，_包括_尝试将 PNTS、B3DM 和 I3DM 瓦片内容转换为 glTF 资产。升级内容还包括：

• 资产版本将设置为 '1.1'。
• 使用 url 的瓦片内容将升级为使用 uri。
• refine 值将转换为全大写。
• B3DM 或 I3DM 中的 glTF 1.0 模型将升级为 glTF 2.0。
• 3DTILES_content_gltf 扩展声明将被移除。
• PNTS、B3DM、I3DM 和 CMPT 内容将被转换为 glTF。

实现说明：

将旧版瓦片格式转换为 glTF 应被视为_预览功能_。在某些极端情况下，这种转换不可能通用地完成——例如，当 I3DM 瓦片内容包含带有动画的 glTF 数据，或当 CMPT（间接）包含多个已经使用 EXT_structural_metadata 扩展的 glTF 资产时。未来可能会更明确地指定转换可能的条件。

convert

^{（此命令替代了 databaseToTileset 和 tilesetToDatabase 命令）}

在瓦片集和瓦片集包格式之间进行转换。

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

附加命令行选项：

此命令的输入和输出参数可以是：

• 包含 tileset.json 文件的目录名称（或完整路径至瓦片集 JSON 文件）
• .3tz 文件名
• .3dtiles 文件名

输入也可以是包含 tileset.json 文件的 .zip 文件。

当输入是包含多个瓦片集 JSON 文件的 .zip 文件或目录，且其中没有任何文件名为 tileset.json 时，可以使用 --inputTilesetJsonFileName 参数定义哪个 JSON 文件应被视为顶级瓦片集 JSON 文件。例如，当有一个包含两个 JSON 文件 tilesetA.json 和 tilesetB.json 的 ambiguous.zip 文件时，可以使用以下命令指定 tilesetA.json 为顶级瓦片集 JSON 文件：

npx 3d-tiles-tools convert -i ./specs/data/convert/ambiguous.zip -o ./output/ambiguous.3tz --inputTilesetJsonFileName tilesetA.json

databaseToTileset

已弃用。此功能现在通过 convert 命令提供。

tilesetToDatabase

已弃用。此功能现在通过 convert 命令提供。

瓦片内容的命令行工具

glbToB3dm

从 glb 创建一个带有空批次表的 b3dm。

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

glbToI3dm

从 glb 创建一个带有单个实例（位置 [0, 0, 0]）和空批次表的 i3dm。

npx 3d-tiles-tools glbToI3dm -i ./specs/data/CesiumTexturedBox/CesiumTexturedBox.glb -o ./output/CesiumTexturedBox.i3dm

b3dmToGlb

从 b3dm 提取 glb。

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

i3dmToGlb

从 i3dm 提取 glb。

npx 3d-tiles-tools i3dmToGlb -i ./specs/data/instancedWithBatchTableBinary.i3dm -o ./output/extracted.glb

cmptToGlb

从 cmpt 瓦片提取 glb 模型。如果找到多个模型，将在输出文件名后追加数字。

npx 3d-tiles-tools cmptToGlb -i ./specs/data/composite.cmpt -o ./output/extracted.glb

splitCmpt

将 cmpt 瓦片拆分为其内部瓦片。每个内部瓦片的输出文件名将通过在给定输出文件名后追加数字和取决于内部瓦片数据类型的扩展名来确定。

npx 3d-tiles-tools splitCmpt -i ./specs/data/compositeOfComposite.cmpt -o ./output/inner --recursive

对于包含一个复合瓦片的 compositeOfComposite.cmpt 输入文件，该复合瓦片包含一个 B3DM 和一个 I3DM 内容，这将在输出目录中生成文件 inner_0.b3dm 和 inner_1.i3dm。

附加命令行选项：

convertB3dmToGlb

将 b3dm 文件转换为使用 glTF 扩展表示批次和特性表信息的 glTF 资产。

npx 3d-tiles-tools convertB3dmToGlb -i ./data/example.b3dm -o ./data/example.glb

convertPntsToGlb

将 pnts 文件转换为使用 glTF 扩展表示点属性及批次和特性表信息的 glTF 资产。

npx 3d-tiles-tools convertPntsToGlb -i ./data/example.pnts -o ./data/example.glb

convertI3dmToGlb

将 i3dm 文件转换为使用 glTF 扩展表示批次和特性表信息的 glTF 资产。如果输入 i3dm 的 GLB 包含动画，此转换可能是有损的。

npx 3d-tiles-tools convertI3dmToGlb -i ./data/example.i3dm -o ./data/example.glb

optimizeB3dm

使用 gltf-pipeline 优化 b3dm。

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

附加命令行选项：

示例：

要使用 Draco 压缩，传递 draco 标志

npx 3d-tiles-tools optimizeB3dm -i ./specs/data/Textured/batchedTextured.b3dm -o ./output/optimized.b3dm --options --draco.compressMeshes --draco.compressionLevel=9

此示例优化了 b3dm 并使用 Draco 高压缩级别压缩网格。

optimizeI3dm

使用 gltf-pipeline 优化 i3dm。

npx 3d-tiles-tools optimizeI3dm -i ./specs/data/instancedWithBatchTableBinary.i3dm -o ./output/optimized.i3dm

有关更多示例，请参见 optimizeB3dm。

updateAlignment

更新 B3DM、I3DM、PNTS 或 CMPT 文件以确保批次和特性表以及整个瓦片数据的对齐要求得到满足。对于 CMPT 瓦片数据，将递归更新内部瓦片的数据。

npx 3d-tiles-tools updateAlignment -i ./specs/data/updateAlignment/testComposite.cmpt -o ./output/testCompositeFixed.cmpt

analyze

分析输入文件，并将结果写入输出目录。

npx 3d-tiles-tools analyze -i ./specs/data/batchedWithBatchTableBinary.b3dm -o ./output/analyzed/

这将接受 B3DM、I3DM、PNTS、CMPT 和 GLB 文件（无论是 glTF 1.0 还是 glTF 2.0），并在输出目录中写入包含特性表、批次表、布局信息、GLB 和 GLB JSON 的文件。这主要用于调试和分析瓦片数据。因此，生成的输出文件的确切命名和内容未指定。

createTilesetJson

从给定的一组瓦片内容文件创建瓦片集 JSON 文件。

附加命令行选项：

如果输入是单个文件，则结果将是具有该输入文件作为瓦片内容的单个（根）瓦片。如果输入是目录，则该目录中的所有内容文件将作为瓦片内容递归使用。被视为“瓦片内容”的确切文件类型集未指定，但将包括 GLB、B3DM、PNTS、I3DM 和 CMPT 文件。

示例：

npx 3d-tiles-tools createTilesetJson -i ./input/ -o ./output/tileset.json --cartographicPositionDegrees -75.152 39.94 10

这将创建指定的瓦片集 JSON 文件，该文件将引用给定输入目录中的所有瓦片内容文件作为其瓦片内容。瓦片集的根节点将具有一个变换，将其放置在给定的地心坐标位置上。

流水线

执行在 JSON 文件中描述的操作序列。

注意： 流水线执行功能是初步的。流水线定义的许多方面，包括 JSON 表示形式和流水线中支持的操作的确切集合，可能会在未来版本中发生变化。

流水线 JSON 文件的基本结构总结如下：

• 流水线具有一个 input 和 output，它们是瓦片集目录或包的名称
• 流水线具有一个“瓦片集阶段”数组
• 瓦片集阶段具有一个 name 和 description
• 瓦片集阶段可以携带关于其应用内容类型的信息
• 瓦片集阶段具有一个“内容阶段”数组
• 内容阶段具有一个 name 和 description

一个简单的示例流水线可能如下所示：

{
  "input": "./specs/data/TilesetOfTilesetsWithUris",
  "output": "./output/TilesetOfTilesetsWithUris.3tz",
  "tilesetStages": [
    {
      "name": "_b3dmToGlb",
      "description": "将 B3DM 转换为 GLB",
      "contentStages": [
        {
          "name": "b3dmToGlb",
          "description": "将每个 B3DM 内容转换为 GLB"
        }
      ]
    }
  ]
}

瓦片集阶段或内容阶段的 name 可以引用一组预定义的操作，这些操作可以执行。如果 name 不是已知操作之一，它应以 _ 下划线开头。

瓦片集阶段或内容阶段的 description 旨在作为人类可读的摘要，用作日志输出。

预定义的操作大致对应于命令行功能。

已知的瓦片集阶段包括：

• 修改：
  • upgrade：将输入瓦片集升级到最新版本。关于这意味着什么的详细信息在此省略。
  • combine：合并输入瓦片集的所有外部瓦片集，以创建一个单一瓦片集
• 压缩：
  • gzip：对所有文件应用 GZIP 压缩（可选过滤器）
  • ungzip：解压所有使用 GZIP 压缩的文件

已知的内容阶段包括：

• 转换：

  • glbToB3dm：将所有 GLB 瓦片内容转换为 B3DM
  • glbToI3dm：将所有 GLB 瓦片内容转换为 I3DM（GLB 作为唯一实例）
  • b3dmToGlb：将所有 B3DM 瓦片内容转换为 GLB（假设 B3DM 仅是 GLB 的包装器）
  • i3dmToGlb：将所有 I3DM 瓦片内容转换为 GLB（假设 I3DM 仅是 GLB 的包装器）
  • separateGltf：将所有 GLB 瓦片内容转换为带有外部资源的 .gltf 文件

• 优化：

  这些操作接收一个 options 对象，这是一个未经类型化的对象，携带传递给 gltf-pipeline 用于优化的选项。

  • optimizeGlb：使用 gltf-pipeline 优化 GLB 瓦片内容
  • optimizeB3dm：使用 gltf-pipeline 优化 B3DM 瓦片内容的 GLB 负载
  • optimizeI3dm：使用 gltf-pipeline 优化 I3DM 瓦片内容的 GLB 负载

展示一系列多个操作流水线的示例见 examplePipeline.json。

开发者设置

当工具不是从 NPM 安装的包，而是直接在克隆的仓库中使用时，命令行用法如下：

• 将仓库克隆到当前目录：

  git clone https://github.com/CesiumGS/3d-tiles-tools
  

• 切换到克隆仓库的目录：

  cd 3d-tiles-tools
  

• 安装工具及其所有依赖项：

  npm install
  

之后，可以使用与上述相同的命令行选项执行工具，例如：

npx ts-node .\src\cli\main.ts gzip -i ./specs/data/TilesetOfTilesets/ -o ./output/TilesetOfTilesets-gzipped/

有关项目结构的详细信息，请参阅实现说明。