# 3d-tiles-validator 中文文档

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

版本：0\.6\.1
npm 元数据更新时间：2026-01-25T14:12:20.962Z
中文译文更新时间：2026-11-05T23:55:32.617Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：2.7 MB，587 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=18\.0\.0
- 运行依赖：10 个
- 首次发布：2022-11-29T18:02:52.558Z
- 最新版本发布：2026-01-25T14:12:20.852Z
- 近 30 天下载量：8750（2026-10-04 至 2026-11-02，npm 官方下载统计）
- 已发布版本数：9（近 12 个月 1 个）

## 中文简介

用于验证 三维平面砖的工具 .

## 安装

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

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

## README

# 三维平面校验器

用于 [三维平面](https://github.com/CesiumGS/3d-tiles)。 。 。 .

> **关于储存库结构的说明**
> 
> 这个存储库最初包含多个项目. 现在,这些项目被保存在单独的储存库中:
> 
> -   这个 `3d-tiles-tools` 可见于 [页:1 `3d-tiles-tools` 仓库](https://github.com/CesiumGS/3d-tiles-tools)
> -   这个 `3d-tiles-samples-generator` 可见于 [页:1 `3d-tiles-samples-generator` 仓库](https://github.com/CesiumGS/3d-tiles-samples-generator)

## 概览

3D平面可以用来验证3D平面平面及其相联的平面内容数据. 它支持1.0版本和1.1版本的3D平地规格. 校验器可以用作命令行工具,也可以用作库.

**说明**:一些执行和接口可能仍然会改变. 这指的是源代码以及命令行接口和报告格式的细节.

### 已执行特征

-   鉴定《公约》的JSON结构 `tileset.json` 文件
-   3D 梯子的验证 [平板格式](https://github.com/CesiumGS/3d-tiles/tree/main/specification/TileFormats)
    -   支持的平板格式为: Batched 三维模型(`b3dm`),实例三维模型(`i3dm`),点云(`pnts`),综合(`cmpt`(中文(简体) )
    -   glTF 瓦片内容被验证为 [glTF 验证器](https://github.com/KhronosGroup/glTF-Validator)
-   验证所隐含的瓦片
-   三维梯形元数据验证
    -   这包括验证元数据JSON结构,以及基于JSON的表示和存储在属性表中的二进制元数据元数据的结构和范围
-   基本审定 [`3DTILES_bounding_volume_S2` 扩展](https://github.com/CesiumGS/3d-tiles/tree/main/extensions/3DTILES_bounding_volume_S2)
-   3D 平面包文件( 3TZ 和 3DTILES 文件) 所包含平面板的校验

## 安装

要将本地验证器安装到目录中, 请运行

```
npm install 3d-tiles-validator
```

(如果你想直接与 Git 存储器的克隆工作,请参见 [开发者设置](https://npmcn.com/package/3d-tiles-validator/#readme-developer-setup)(中文(简体) )

## 命令行使用量

#### 验证单个平板文件

```
npx 3d-tiles-validator --tilesetFile specs/data/Samples/SparseImplicitQuadtree/tileset.json
```

输入文件可以是平板JSON文件,也可以是已知平板包文件之一. 已知的包文件格式有3TZ(基于ZIP的包格式)和3DTILES(基于SQLite的包格式). 输入类型由文件扩展名决定,该扩展名可以是 `.3tz` 或者说 `.3dtiles` (案件不敏感). 例如,要验证一个 3TZ 文件:

```
npx 3d-tiles-validator --tilesetFile ./specs/data/tilesets/packages/validTilesetPackage.3tz
```

#### 验证一组平板文件

```
npx 3d-tiles-validator --tilesetsDirectory specs/data/Samples/
```

这将验证给定目录中的所有平板文件及其所有子目录 。 通过将文件名与 glob 模式相匹配来识别平板文件 `**/*tileset*.json`。可以配置图案 `tilesetGlobPattern` 参数。 例如,为了将所有.json文件作为平板文件处理:

```
npx 3d-tiles-validator --tilesetsDirectory specs/data/Samples/ --tilesetGlobPattern **/*.json
```

#### 验证一个平板内容文件

```
npx 3d-tiles-validator --tileContentFile specs/data/gltfExtensions/FeatureIdAttributeAndPropertyTableFeatureIdNotInRange.gltf
```

输入文件可以是任何由验证器支持的内容类型. 这包括B3DM,I3DM,PNTS,CMPT,和glTF/GLB文件. 将确定文件的类型,如果不是已知的类型,则会创建验证警告.

### 报表文件

默认情况下,验证报告会被打印到控制台.

当验证一个文件时, 然后 `reportFile` 参数可用于为验证报告指定输出文件。 例如:

```
npx 3d-tiles-validator --tilesetFile specs/data/Samples/TilesetWithFullMetadata/tileset.json --reportFile MY_REPORT.json
```

或者,当验证多个文件时 `writeReports` 参数可用于将报告文件写入与输入文件相同的目录。 报告文件的名称将取自输入文件名.

```
npx 3d-tiles-validator --tilesetsDirectory specs/data/Samples/ --writeReports
```

### 选项文件

校验过程的选项可以在通过 `--optionsFile` 参数 :

```
npx 3d-tiles-validator --optionsFile exampleOptions.json
```

选项代表 `ValidationOptions` 课。 例如,使用下列方法 `exampleOptions.json` 文件,然后验证器将只验证平板 JSON 结构,但 _没有_ 平板内容数据 :

```JSON
{
  "validateContentData": false
}
```

下列选项将会导致验证符 _包含_ 验证过程中的B3DM-和GLB文件,但忽略了所有其他内容类型:

```JSON
{
  "includeContentTypes": [ "CONTENT_TYPE_B3DM", "CONTENT_TYPE_GLB" ]
}
```

下列选项将会导致验证符 _排除_ 校验期间的平板文件(即外部平板) :

```JSON
{
  "excludeContentTypes": [ "CONTENT_TYPE_TILESET" ]
}
```

选项也可以是配置文件的一部分,如下一节所描述.

### 配置文件

校验器运行的命令行参数可以在配置文件中摘要列出 `--configFile` 参数。 例如,当使用

```
npx 3d-tiles-validator --configFile exampleConfig.json
```

使用下列方法 `exampleConfig.json` 文件

```JSON
{
  "tilesetsDirectory": "specs/data/tilesets",
  "tilesetGlobPattern": "**/*.json"
}
```

然后验证器将验证给定目录中符合给定的 glob 模式的所有文件.

配置也可以包含 `options` 对象。 此对象概括了验证选项, 如 [选项文件](https://npmcn.com/package/3d-tiles-validator/#readme-option-files) 节。 例如:

```JSON
{
  "tilesetsDirectory": "specs/data/tilesets",
  "tilesetGlobPattern": "**/*.json",
  "options": {
    "includeContentTypes": [ "CONTENT_TYPE_B3DM", "CONTENT_TYPE_GLB" ]
  }
}
```

这将让验证器验证指定目录中所有JSON文件,但在验证过程中只考虑B3DM-和GLB平板内容数据.

### 自定义元数据语义

这个 [三维元数据规格](https://github.com/CesiumGS/3d-tiles/tree/main/specification/Metadata) 允许定义自定义 _语义_ 用于元数据属性。 内置语义在 [3D 元数据语义参考](https://github.com/CesiumGS/3d-tiles/tree/main/specification/Metadata/Semantics)对于其他语义,验证器默认会生成一个 `METADATA_SEMANTIC_UNKNOWN` 问题.

为了避免这些警告,客户端可以在元数据schema文件中定义自己的语义,以便在验证过程中将其考虑在内. 这一进程的一些细节可能仍然会改变(见A/CONF.96/11) [`3d-tiles/issues/643`](https://github.com/CesiumGS/3d-tiles/issues/643) (供讨论)。 但此处描述了3D平面验证器中元数据语义学验证的支持现状.

#### 元数据语义Schema

"语义学计划"是一个 [三维元数据Schema](https://github.com/CesiumGS/3d-tiles/tree/main/specification/Metadata#schema) 描述 _语义_ 可能出现在另一个元数据计划中。 在一个语义学计划中,属性名称只是语义学的名称. 例如,当客户端想要定义类类的语义时 `ExampleClass`,这个语义有这个名字 `EXAMPLE_SEMANTIC`,那么这个结构可以在语义学 schema文件中被表示如下:

**`exampleSemanticsSchema.json`数字 :**

```json
{
  "id": "Example-Semantics-0.0.0",
  "description": "A metadata schema where each class property has a name that represents one possible semantic of a metadata property, and that is used for validating semantics, by passing it in as one of the 'semanticSchemaFileNames' of the validation options",
  "classes": {
    "ExampleClassSemantics": {
      "description": "A class where each property is a semantic for a property of the 'ExampleClass'",
      "properties": {
        "EXAMPLE_SEMANTIC": {
          "name": "The 'EXAMPLE_SEMANTIC' structure",
          "description": "The structure that a property must have so that it can have the 'EXAMPLE_SEMANTIC'",
          "type": "SCALAR",
          "componentType": "FLOAT32"
        }
      }
    }
  }
}
```

> 说明:
> 
> 这个计划文件包含详细的名字和描述. 在技术层面上,这些是可选的。 等效的策略文件是
> 
> ```json
> {
>   "id": "Example-Semantics-0.0.0",
>   "classes": {
>     "ExampleClassSemantics": {
>       "properties": {
>         "EXAMPLE_SEMANTIC": {
>           "type": "SCALAR",
>           "componentType": "FLOAT32"
>         }
>       }
>     }
>   }
> }
> ```
> 
> 但强烈建议为文献目的增加名字和说明.

#### 元数据语义Schema 注册

为了在验证过程中包含一个"语义学 schema",该 schema 文件的名称可以传递给验证器,作为验证选项的一部分:

**`exampleOptions.json`数字 :**

```json
{
  "semanticSchemaFileNames": ["exampleSemanticsSchema.json"]
}
```

注释: `semanticSchemaFileNames` 矩阵相对于选项文件的目录解决( name`--optionsFile`(中文(简体) )

此选项文件可以传递给验证器 :

```
npx 3d-tiles-validator --optionsFile exampleOptions.json -t ./data/exampleTileset.json
```

校验器随后将验证在tileset JSON中被定义的语义与语义学计划中被定义的结构相对.

## 开发者设置

当验证器不是作为国家防范机制的软件包安装的,而是应该直接用于被克隆的数据库时,那么命令行的使用如下:

-   将仓库切入当前目录 :
    
    ```
    git clone https://github.com/CesiumGS/3d-tiles-validator
    ```
    
-   更改为克隆寄存器的目录 :
    
    ```
    cd 3d-tiles-validator
    ```
    
-   安装验证符及其所有依存 :
    
    ```
    npm install
    ```
    

在这之后, `ts-node` 可用于直接执行验证符,使用上述相同的命令行选项——例如,验证一个单一的平板文件:

```
npx ts-node src/main.ts --tilesetFile specs/data/Samples/SparseImplicitQuadtree/tileset.json
```

## 图书馆的使用

校验器作为库的基本用途如下:

```JavaScript
const { Validators } = require("3d-tiles-validator");

const resultPromise = Validators.validateTilesetFile("example.json");
resultPromise.then((result) => {
  console.log(result.serialize());
});
```

这个 `Validators.validateTilesetFile` 收到文件名,然后返回对 `ValidationResult`,然后可以打印到控制台。 第二个(可选)参数是a `ValidationOptions` 对象,可归纳验证进程的选项(另见 [选项文件](https://npmcn.com/package/3d-tiles-validator/#readme-option-files)) (中文(简体) ).

### 校验结果过滤

客户端可以在 `ValidationResult`,以便去除低于一定严重程度的验证问题,或者在某种应用上预期到的警告.

例如,给定的验证结果可以过滤到

-   包括严重性的验证问题 `ERROR`
-   排除具有该类型的验证问题 `EXTENSION_NOT_SUPPORTED`

将这种过滤器应用到特定验证结果的例子如下:

```JavaScript
const { Validators, ValidationIssueFilters, ValidationIssueSeverity } = require("3d-tiles-validator");

const resultPromise = Validators.validateTilesetFile("example.json");
resultPromise.then((result) => {
  const filteredResult = result
    .filter(ValidationIssueFilters.byIncludedSeverities(ValidationIssueSeverity.ERROR))
    .filter(ValidationIssueFilters.byExcludedTypes("EXTENSION_NOT_SUPPORTED"));
  console.log(filteredResult.serialize());
});
```

**说明**编号: `type` 用于描述和分类验证问题的字符串不属于核心API的一部分. 这些字符串可能会在小版本或补丁版本之间发生改变. 但变化日志中会指出变化.

## 执行情况说明

见 [`IMPLEMENTATION.md`](https://npmcn.com/package/3d-tiles-validator/IMPLEMENTATION.md) 用于执行说明.

## 常见问题

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

用于验证 三维平面砖的工具 \.

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

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

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

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

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

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

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

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

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

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

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

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

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

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