# 3d-tiles-tools 中文文档

规范地址：https://npmcn.com/package/3d-tiles-tools/

版本：0\.5\.4
npm 元数据更新时间：2026-07-15T13:39:56.306Z
中文译文更新时间：2026-11-05T22:34:11.741Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/3d-tiles-tools
原文对照：https://npmcn.com/package/3d-tiles-tools/?lang=original
项目主页：https://github.com/CesiumGS/3d-tiles-tools
源码仓库：https://github.com/CesiumGS/3d-tiles-tools

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：8 MB，1548 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=18\.0\.0
- 运行依赖：18 个
- 首次发布：2016-12-16T18:56:30.010Z
- 最新版本发布：2026-07-15T13:39:56.189Z
- 近 30 天下载量：11832（2026-10-04 至 2026-11-02，npm 官方下载统计）
- 已发布版本数：18（近 12 个月 3 个）

## 中文简介

三维平面工具

## 安装

```sh
npm install 3d-tiles-tools
```

也可以使用：`pnpm add 3d-tiles-tools`、`yarn add 3d-tiles-tools`、`bun add 3d-tiles-tools`

## README

# 三维平面工具

## 概览

3D平面工具是用于转换,优化,处理和分析3D平面数据的工具和公用工具的集合.

## 安装

将本地的 三维平面工具安装到目录中, 运行

```
npm install 3d-tiles-tools
```

如果您想直接与 Git 仓库的克隆工作, 请参见 [开发者设置](https://npmcn.com/package/3d-tiles-tools/#readme-developer-setup)。 。 。 .

## 命令行使用量

> **说明:** 三维平面工具的所有输入和输出路径 _区分大小写_尽管一些操作系统(如Windows)通常不区分大写和小写,但命令行给出的文件-和目录名称必须准确匹配实际名称.

#### 每个函数的共同命令行选项:

| 旗帜 | 说明 | 需求 |
| --- | --- | --- |
| `-i`, (中文(简体) ), `--input` | 输入文件或目录 | 对 |
| `-o`, (中文(简体) ), `--output` | 输出文件或目录 | 对 |
| `-f`, (中文(简体) ), `--force` | 如果输出存在, 则覆盖输出 | 不,默认 `false` |
| `--logLevel` | 日志级别。 有效值为 `trace`, (中文(简体) ), `debug`, (中文(简体) ), `info`, (中文(简体) ), `warn`, (中文(简体) ), `error`, (中文(简体) ), `fatal`,以及 `silent` | 不,默认 `info` |
| `--logJson` | 将日志信件打印为 JSON 而不是漂亮打印 | 不,默认 `false` |

### 瓦片的命令行工具

#### 齐普

Gzips 输入平板.

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

其它命令行选项 :

| 旗帜 | 说明 | 需求 |
| --- | --- | --- |
| `-t`, (中文(简体) ), `--tilesOnly` | 只有克兹克牌. | 不,默认 `false` |

(注:所覆盖的文件的确切组数 `tilesOnly` 尚未指定)

#### 乌齐普

解开输入平板.

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

#### 组合

将所有外接瓦片组合为一个单瓦片.

> **说明** 关于差异 `merge` 财务报告和审定财务报表 `combine`编号: `combine` 命令需要已经使用的平板 _参考_ 改为 _外部_ 瓷砖 它创造了一个新的平板 在那里,前者 _外部_ 瓷砖是"内嵌"的. 因此结果将是一个单一的平板,没有外部引用.

示例

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

#### 合并

将多块瓦片合并为一个单块,将输入瓦片称为外部瓦片.

> **说明** 关于差异 `merge` 财务报告和审定财务报表 `combine`编号: `merge` 命令创建一个 _新设_ 砖头 _参考_ 以给定者为 _外部_ . 这意味着产生的平板不全 _无_ b. 用于为《京都议定书》 `merge` 命令.

示例

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

#### 合并杰森

将多块瓦片合并为一个单一的平板 JSON 文件,其中将输入瓦片称为外部瓦片.

这与 `merge` 命令,因为它不将输入的平板电脑复制到输出目录中,而只为合并的平板电脑创建JSON文件,它使用相对路径来指代输入的平板电脑。 用于此的常用例是在特定目录中创建一个平板 JSON 文件,输入的平板位于子目录中.

示例

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

#### 合并 Json3tz

将任何数量被包装为3TZ文件的平板块合并为一个平板 JSON .

这将不会复制或重新包装输入文件 。 它只会创建一个使用 `MAXAR_content_3tz` 扩展以引用使用相对路径的输入文件。 如果任何输入都是目录名称, 那么全部 `.3tz` 来自此目录的文件将被视为输入文件,递归.

示例

```
npx 3d-tiles-tools mergeJson3tz -i ./example/tilesetA.3tz -i ./example/tilesetB.3tz -o ./example/tileset.json
```

#### 升级

将一个平板升级到最新的 三维平板版 .

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

其它命令行选项 :

| 旗帜 | 说明 | 需求 |
| --- | --- | --- |
| `--targetVersion` | 目标版本要升级到. 也许是 `1.0` 或者说 `1.1`。 。 。 . | 没有 默认 : `1.0` |
| `--options` | 此旗上的所有参数都被 gltf- pipeline 所消耗 . | 没有 |

默认情况下,这将更新遗留的瓦片,以遵守3D平面1.0规格.

这些升级包括:

-   资产版本将设定为 `'1.0'`。 。 。 .
-   使用一个 `url` 将升级为使用 `uri`。 。 。 .
-   这个 `refine` 值将转换为全部值.
-   b3DM或I3DM中的glTF 1.0模型将升级为glTF 2.0.

> 执行情况说明:
> 
> 内部将glTF 1.0资产转换为glTF 2.0资产是通过处理 GLB 数据实现的,使用 [`gltf-pipeline`](https://github.com/CesiumGS/gltf-pipeline/)这将包括尝试转换与该设备一起提供的材料 `KHR_technique_webgl` 扩展为 PBR 材料。 选项 `--options` 参数传递到 `gltf-pipeline`。这些选项可能包括统一变量的名称,这些变量应表明某种纹理是否被用作一个PRB材料的"基色"纹理. 例如,当一个平面图中包含含有 GLB 的 B3DM 或 I3DM 数据时 `KHR_technique_webgl` 统一名称中的扩展名 `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` 以遵守三维平面图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(间接)包含多个已经使用此程序的 glTF 资产时 `EXT_structural_metadata` 扩展名。 今后可以更明确地规定转换的条件.

#### 转换

(这个取代 `databaseToTileset` 财务报告和审定财务报表 `tilesetToDatabase` 命令)

在平板和平板套件格式之间转换.

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

其它命令行选项 :

| 旗帜 | 说明 | 需求 |
| --- | --- | --- |
| `--inputTilesetJsonFileName` | 应该被视为顶级平板JSON文件的输入文件名称 | 没有 |

此命令的输入和输出参数可能是:

-   包含一个 `tileset.json` 文件(或 tileset JSON 文件的全部路径)
-   一个名字 `.3tz` 文件
-   一个名字 `.3dtiles` 文件

投入也可能是: `.zip` 包含一个 `tileset.json` 文档.

当输入是 `.zip` 文件或包含多块平板 JSON 文件的目录, 没有一个被调用 `tileset.json`,然后是 `--inputTilesetJsonFileName` 参数可以用来定义JSON文件,该文件应当被认为是顶级平板JSON. 例如,当有 `ambiguous.zip` 包含两个 JSON 文件的平板 `tilesetA.json` 财务报告和审定财务报表 `tilesetB.json`,以下命令可用于指定 `tilesetA.json` 作为顶级平板 JSON 文件 :

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

#### 数据库到Tileset

堕地. 这一功能现在通过下列方式提供: `convert` 命令.

#### 平板到数据库

堕地. 这一功能现在通过下列方式提供: `convert` 命令.

### 瓦片内容的命令行工具

#### glbToB3dm (英语)

从 glb 创建一个 b3dm,并带有一个空的批量表格.

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

#### glbToI3dm (英语)

从 glb 创建 i3dm, 位置为单个实例 `[0, 0, 0]` 和一个空的批量表.

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

#### b3dm 主题

从 b3dm 提取 glb .

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

#### i3dm 托克勒布

从 i3dm 中提取 glb .

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

#### cmptToGlb (英语)

从平板砖取出 glb 模型。 如果找到多个模型, 将会在输出文件名后附加一个数字 .

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

#### 分块

将一平板砖分入内砖. 每个内砖块的输出文件名将通过在给定的输出文件名中附加一个数字来决定,以及取决于内砖块数据类型的扩展名.

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

对于输入文件 `compositeOfComposite.cmpt` 这将生成文件 `inner_0.b3dm` 财务报告和审定财务报表 `inner_1.i3dm` 在输出目录中.

其它命令行选项 :

| 旗帜 | 说明 | 需求 |
| --- | --- | --- |
| `--recursive` | 是否将分块操作应用于复合的内砖块 | 不, 默认 : `false` |

#### 转换B3dmToGlb

将 b3dm 文件转换为 glTF 资产,该资产使用 glTF 扩展来代表批量和特征表信息.

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

#### 转换PntsToGlb

将 pnts 文件转换为 glTF 资产,该资产使用 glTF 扩展来代表点属性以及批量和特征表信息.

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

#### 转换I3dmToGlb

将 i3dm 文件转换为 glTF 资产,该资产使用 glTF 扩展来代表批量和特征表信息. 如果输入 i3dm 的 GLB 包含动画, 此转换可能会丢失 .

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

#### 优化B3dm

使用 b3dm 优化 [gltf-管线](https://github.com/CesiumGS/gltf-pipeline/blob/main/README.md)。 。 。 .

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

其它命令行选项 :

| 旗帜 | 说明 | 需求 |
| --- | --- | --- |
| `--options` | 此旗上的所有参数都被 gltf- pipeline 所消耗 . | 没有 |

**实例**数字 :

要使用 Draco 压缩,请通过 [`draco` 旗帜](https://github.com/CesiumGS/gltf-pipeline/blob/main/README.md#command-line-flags)

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

这个例子优化了b3dm,并用Draco来压缩 meshes,压缩级别高.

#### 优化 I3dm (时分)

使用 i3dm 优化 i3dm [gltf-管线](https://github.com/CesiumGS/gltf-pipeline/blob/main/README.md)。 。 。 .

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

见 [优化B3dm](https://npmcn.com/package/3d-tiles-tools/#readme-optimizeb3dm) 其他例子.

#### 更新对齐

更新一个B3DM、I3DM、PNTS或CMPT文件,以确保对齐要求 对于批量和特征表以及整块地块数据,则予以满足。 关于《议定书》/《公约》缔约方会议 瓦片数据,内出瓦片的数据会进行递归更新.

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

#### 分析

分析输入文件,并将结果写入输出目录.

```
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的输出目录. 这主要是为了调试和分析瓷砖数据. 因此,生成的输出文件的确切命名和内容没有被指定.

#### 创建TilesetJson

从一个给定的平板内容文件创建一个平板 JSON 文件 .

其它命令行选项 :

| 旗帜 | 说明 | 需求 |
| --- | --- | --- |
| `--cartographicPositionDegrees` | 由两个或三个值组成的阵列,它们是目标位置的(经度,纬度)或(经度,纬度,高度). 经度和纬度以度来表示,高度以米来表示. | 没有 |
| `--rotationDegrees` | 由三个值组成的阵列,这些值是目标位置的(头,投出,滚出)旋转,以度为单位. | 没有 |

如果输入是一个单一文件,那么这将产生一个以输入文件为瓦片内容的单一(root)瓦片. 如果输入是一个目录,那么这个目录中的所有内容文件都将被作为平板内容,递归使用. 未指定被视为"瓷质内容"的文件类型的确切集,但它将包括GLB,B3DM,PNTS,I3DM,以及CMPT等文件.

实例:

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

这就创建了指定的平板JSON文件,该文件将把给定输入目录中的所有平板内容文件称为平板内容. 砖块的根节点将有一个变换,将它放在给定的制图位置上,并带有指定的旋转.

### 服务器

这个 `3d-tiles-tools` 可以作为平板电脑的服务器。 这些瓦片可以作为文件存储在目录中,也可以是 `.3tz` 或者说 `.3dtiles` 文档。 这些文件的内容将由服务器直接交付,而不必完全取出相应的文件. 例如,为了启动一个提供3TZ文件内容的服务器:

`npx 3d-tiles-tools serve --cors --input ./data/example.3tz`

命令接受额外的 `--host` 财务报告和审定财务报表 `--port` 参数,默认为 `localhost` 财务报告和审定财务报表 `8003`分别是:.

### 管道

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

> **说明:** 管道执行特征是初步的. 管道定义的许多方面,包括JSON的表示和作为管道部件而支持的确切的一套操作,可能会在未来的释放中发生变化.

以下是管道JSON文件的基本结构:

-   管道有一个 `input` 财务报告和审定财务报表 `output`,这些是平板目录或软件包的名称
-   管道有一系列的"平分相"
-   瓷砖阶段有一个 `name` (单位:千美元) `description`
-   平板化阶段可以包含它应用到的内容类型的信息
-   平面相间有一组“ 内容相间 ”
-   一个内容阶段有一个 `name` (单位:千美元) `description`

因此,一个简单的示例 ipline 可能像这样:

```
{
  "input": "./specs/data/TilesetOfTilesetsWithUris",
  "output": "./output/TilesetOfTilesetsWithUris.3tz",
  "tilesetStages": [
    {
      "name": "_b3dmToGlb",
      "description": "Convert B3DM to GLB",
      "contentStages": [
        {
          "name": "b3dmToGlb",
          "description": "Convert each B3DM content into 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`: 优化 GLB 瓷砖内容,使用 `gltf-pipeline`
    -   `optimizeB3dm`: 优化B3DM瓦片含量的GLB有效载荷,使用 `gltf-pipeline`
    -   `optimizeI3dm`: 优化I3DM瓦片内装的GLB有效载荷,使用 `gltf-pipeline`

将多个操作序列组合在一起的管线实例如下: [`examplePipeline.json`](https://npmcn.com/package/3d-tiles-tools/specs/data/pipelines/examplePipeline.json)。 。 。 .

## 开发者设置

当这些工具不是作为国家防范机制的软件包安装的,而是应该直接用于被克隆的存储库时,那么命令行的使用如下:

-   将仓库切入当前目录 :
    
    ```
    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/
```

见 [执行说明](https://npmcn.com/package/3d-tiles-tools/IMPLEMENTATION.md) 项目结构细节.

## 常见问题

### 3d-tiles-tools 是什么？

三维平面工具

### 如何安装 3d-tiles-tools？

在项目目录运行 npm install 3d-tiles-tools，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 3d-tiles-tools，可以用 npx 3d-tiles-tools 直接运行。

### 3d-tiles-tools 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### 3d-tiles-tools 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### 3d-tiles-tools 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=18\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### 3d-tiles-tools 可以商用吗？

3d-tiles-tools 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### 3d-tiles-tools 的下载量有多少？

根据 npm 官方下载统计，3d-tiles-tools 在 2026/10/04 – 2026/11/02 这 30 天内被下载 11,832 次，日均约 394 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### 3d-tiles-tools 还在维护吗？

最新版本 0\.5\.4 发布于 2026/07/15（3 个月前）；至今共发布 18 个版本，其中过去 12 个月发布了 3 个；首次发布于 2016/12/17。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。