3D Tiles tileset.jso 数据格式

根据 Cesium 3D Tiles 规范，tileset.json 是瓦片集的入口文件，描述了整个 3D 数据集的层次结构、空间范围和元数据。以下是我为您梳理的完整格式说明：

一、基本结构

{
  "asset": {
    "version": "1.0",
    "tilesetVersion": "v1.2"
  },
  "geometricError": 500,
  "root": {
    "boundingVolume": {},
    "geometricError": 500,
    "refine": "REPLACE",
    "content": {},
    "children": []
  }
}

二、核心字段详解

1. asset（资产信息，必需）

描述数据集的基本元信息。

"asset": {
  "version": "1.0",                 // 3D Tiles 规范版本
  "tilesetVersion": "v1.2",         // 瓦片集版本
  "gltfUpAxis": "Z"                 // 可选：Z-up 或 Y-up
}

2. geometricError（几何误差，必需）

根节点的几何误差（单位：米），用于 LOD 切换。值越大表示该节点可接受误差越大，更容易被粗粒度瓦片替代。

3. root（根节点，必需）

瓦片树的根节点，包含以下关键字段：

3.1 boundingVolume（包围体，必需）

定义节点的空间范围，支持三种类型：

① region（经纬度范围，最常用）

"boundingVolume": {
  "region": [
    -1.319720, 0.698842,  // 西经 (radians)
    -1.319659, 0.698905,  // 东经 (radians)
    0.0, 100.0           // 最小高度, 最大高度 (米)
  ]
}

② box（盒子）

"boundingVolume": {
  "box": [
    0, 0, 0,        // 中心点 [x, y, z]
    100, 0, 0,       // x 轴方向与半长
    0, 100, 0,       // y 轴方向与半长
    0, 0, 100        // z 轴方向与半长
  ]
}

③ sphere（球体）

"boundingVolume": {
  "sphere": [
    0, 0, 0,  // 中心点 [x, y, z]
    100       // 半径
  ]
}

3.2 content（内容，可选）

指向实际的瓦片数据文件。

"content": {
  "uri": "0.pnts",           // 点云瓦片文件
  "boundingVolume": { ... }  // 可选：内容的精确包围盒
}

3.3 children（子节点，可选）

嵌套的子节点数组，构成树状结构。

"children": [
  {
    "boundingVolume": { ... },
    "geometricError": 250,
    "refine": "ADD",
    "content": { "uri": "1.pnts" },
    "children": [ ... ]  // 可继续嵌套
  }
]

3.4 refine（细化方式，可选）

• "REPLACE"：完全替换父节点
• "ADD"：在父节点基础上添加细节

三、点云（pnts）瓦片示例

典型的点云瓦片集结构如下：

{
  "asset": {
    "version": "1.0",
    "tilesetVersion": "1.0.0-2023"
  },
  "geometricError": 100.0,
  "root": {
    "boundingVolume": {
      "region": [
        -1.3197, 0.6988,
        -1.3196, 0.6989,
        0.0, 100.0
      ]
    },
    "geometricError": 100.0,
    "refine": "ADD",
    "content": {
      "uri": "0.pnts",
      "boundingVolume": {
        "region": [
          -1.3197, 0.6988,
          -1.3196, 0.6989,
          0.0, 50.0
        ]
      }
    },
    "children": [
      {
        "boundingVolume": {
          "region": [
            -1.3197, 0.6988,
            -1.31965, 0.69885,
            0.0, 100.0
          ]
        },
        "geometricError": 50.0,
        "content": { "uri": "1.pnts" }
      },
      {
        "boundingVolume": {
          "region": [
            -1.31965, 0.69885,
            -1.3196, 0.6989,
            0.0, 100.0
          ]
        },
        "geometricError": 50.0,
        "content": { "uri": "2.pnts" }
      }
    ]
  }
}

四、高级特性

1. 变换矩阵（transform）

节点级别的坐标变换。

"transform": [
  1, 0, 0, 0,  // 4x4 矩阵，行主序
  0, 1, 0, 0,
  0, 0, 1, 0,
  0, 0, 0, 1
]

2. 扩展（extensions）

自定义元数据。

"extensions": {
  "3DTILES_metadata": {
    "class": "building",
    "properties": {
      "name": "Main Building"
    }
  }
}

3. 元数据（metadata）

标准化的属性信息。

"metadata": {
  "properties": {
    "height": { "minimum": 0, "maximum": 100 }
  }
}

五、工具生成示例

通过工具生成的典型瓦片集结构（8 叉树）：

{
  "asset": { "version": "1.0" },
  "geometricError": 1000,
  "root": {
    "boundingVolume": { "region": [...] },
    "geometricError": 1000,
    "refine": "REPLACE",
    "children": [
      {
        "boundingVolume": { "region": [...] },
        "geometricError": 500,
        "refine": "ADD",
        "content": { "uri": "r.pnts" },
        "children": [
          { "boundingVolume": {...}, "geometricError": 250, "content": { "uri": "r0.pnts" } },
          { "boundingVolume": {...}, "geometricError": 250, "content": { "uri": "r1.pnts" } },
          // ... 共 8 个子节点
        ]
      }
    ]
  }
}

六、验证与调试

1. 格式验证

// 在 Cesium 中加载时自动验证
try {
    const tileset = await Cesium.Cesium3DTileset.fromUrl('tileset.json');
} catch (error) {
    console.error('tileset.json 格式错误:', error.message);
}

2. 常见错误

• 404 错误 ：uri 路径不正确
• LOD 不生效 ：geometricError 设置不合理
• 内存溢出：节点层次过深或叶节点数据量过大
• 坐标错误 ：region 范围定义错误（需使用弧度制）

七、最佳实践

1. 层次结构：保持平衡的树结构，每层 2-8 个子节点
2. 几何误差：子节点应是父节点的 1/2 到 1/4
3. 瓦片大小：单个 pnts 文件建议 50-200MB
4. 路径引用：使用相对路径，避免跨域问题
5. 版本控制 ：在 asset.tilesetVersion 中标记版本

---

文档未详述的点（基于我的知识补充） ：实际上，tileset.json 还支持 viewerRequestVolume 字段用于定义视点相关的加载条件，以及 content.groupMetadata 用于分组元数据管理，但这些在基础点云场景中较少使用。