2023空间三维模型瓦片数据格式.docx

空间三维模型瓦片数据格式 目次前言V引言VI1 范围12 规范性引用文件13 术语和定义14 符号和缩略语24.1 缩略语24.2 UML 图示符号34.3 UML 图多样性描述35 基本规定35.1 基本数据类型35.2 字符串类型45.3 数组类型45.4 JSON 格式存储45.5 日期与时间表示46 总体结构46.1 瓦片树结构46.2 数据的文件组成57 文件存储格式67.1 描述文件67.2 数据文件97.3 索引树文件357.4 属性描述文件367.5 属性数据文件37附录 A（资料性）应用示例39A.1 应用示例概述39 A.2 基于 C+读写 SDK 的数据读写示例39 A.3 osgb 格式转换为 s3mb 格式的示例40 A.4 3D Tiles 数据转换为 s3mb 数据的示例40 A. 5 obj 格式转换为 s3mb 格式的示例41附录 B（资料性）文件内容示例42B. 1 描述文件示例42 B.2 材质内容示例44 B.3 索引树文件示例48 B.4 属性描述文件示例50 B.5 属性数据文件示例51附录 C（资料性）MongoDB 存储示例53II C.1 MongoDB 存储概述53 C.2 存储结构设计53 C.3 数据示例56附录 D（规范性）采用几何压缩技术的骨架对象62D.1 存储结构62 D.2 二进制流描述62参考文献64 图 1 TileTree 结构示意图5图 2 TileTree 的 UML 图5图 3 Config 对象的 UML 图7图 4 Tile 对象的 UML 图10图 5 LODPackage 对象的 UML 图11图 6 Patch 对象的 UML 图12图 7 Animation 对象的UML 图13图 8 动画时间示例图15图 9 ModelElements 对象的 UML 图15图 10 无压缩的 Skeleton 对象的 UML 图16图 11 CommonPass 对象的 UML 图20图 12 PBRPass 对象的 UML 图23图 13 Texture 对象的 UML 图26图 14 IDInfo 对象的 UML 图27图 15 非实例化数据存储示例28图 16 实例化数据存储示例29图 17 数据文件二进制数据包29图 18 属性数据文件二进制流结构37 表 1 UML 图示符号对照表3 表 2 UML 图多样性描述3 表 3 基本数据类型规定3 表 4 文件组织形式6 表 5 Config 对象各标签含义7 表 6 Rect 对象各标签含义8 表 7 HeightRange 对象各标签含义8 表 8 CategoryDescript 对象各标签含义8 表 9 Range 对象各标签含义9 表 10 Position 对象各标签含义9 表 11 Point3D 对象各标签含义9 表 12 TileTreeInfo 对象各标签含义9 表 13 BoundingBox 对象各标签含义9 表 14 Tile 对象各属性含义10 表 15 LODPackage 对象各属性含义11 表 16 RangeMode 对象各枚举值含义11 表 17 BoundingSphere 对象各属性含义11 表 18 Patch 对象各属性含义12 表 19 Matrix4D 对象各属性含义12 表 20 Animation 对象各标签含义13 表 21 AnimationNode 对象各标签含义13 表 22 AnimationSkin 对象各标签含义14 表 23 AnimationContent 对象各标签含义14 表 24 KeyframeAnimation 对象各标签含义14 表 25 SkinnedWeight_0 对象各属性含义14 表 26 SkinnedJoint_0 对象各属性含义15 表 27 ModelElements 对象各属性含义15 表 28 无压缩的 Skeleton 对象各属性含义17 表 29 VertexDataPackage 对象各属性含义17 表 30 TextureCoord 对象各属性含义18 表 31 InstanceInfo 对象各属性含义18 表 32 InstanceObject 对象各属性含义18 表 33 VertexAttributeExtension 对象各属性含义18 表 34 VertexAttribute 对象各属性含义18 表 35 VertexAttributeType 对象各枚举含义19 表 36 IndexPackage 对象各属性含义19 表 37 VertexIndexType 对象各枚举值含义19 表 38 DrawPrimitiveType 对象各枚举值含义19 表 39 Material 对象各标签含义20 表 40 CommonPass 对象各标签含义20 表 41 ColorValue 对象各标签含义21 表 42 CullingMode 对象各枚举值含义21 表 43 AlphaMode 对象各枚举值含义21 表 44 TextureUnitState 对象各标签含义21 表 45 TextureAddressingMode 对象各枚举值含义22 表 46 FilterOptions 对象各枚举值含义22 表 47 PBRPass 对象各标签含义23 表 48 Vector4 对象各标签含义25 表 49 TextureMotionParameter 对象各标签含义25 表 50 Vector3 对象各标签含义25 表 51 Texture 对象各属性含义26 表 52 TextureData 对象各属性含义26 表 53 TextureCompressType 各枚举值含义26 表 54 PixelFormat 各枚举值含义27 表 55 IDInfo 对象各属性含义27 表 56 SkeletonIDInfo 对象各属性含义28 表 57 MonomerIDInfo 对象各属性含义28 表 58 SegmentIDInfo 对象各属性含义28 表 59 Extensions 对象各标签含义29 表 60 索引树文件各标签含义35 表 61 TileInfo 对象各标签含义35 表 62 Status 对象各标签含义36 IV 表 63 属性描述文件各标签含义36 表 64 LayerFieldInfo 对象各标签含义36 表 65 IDRange 对象各标签含义37 表 66 FieldInfo 对象各标签含义37 表 67 属性数据文件各标签含义37 表 68 LayerAttributeValue 对象各标签含义38 表 69 Record 对象各标签含义38 表 70 Value 对象各标签含义38 表 C.1 metadatas_s3m 集合的字段信息53 表 C.2 metadatas_s3m 集合 Name 字段取值及含义53 表 C.3 Position 对象各标签含义54 表 C.4 Rect 对象各标签含义54 表 C.5 HeightRange 对象各标签含义54 表 C.6 CategoryDescript 对象各标签含 义5 5 表 C.7 Range 对象各标签含义55 表 C.8 TileInfo 对象各标签含义55 表 C.9 Point3D 对象各标签含义55 表 C.10 BoundingBox 对象各标签含义55 表 C.11 Vector3 对象各标签含义55 表 C.12 数据集合的字段信息56 表 D.1 采用几何压缩技术的 Skeleton 对象各属性含义62 表 D.2 CompressedDataPackage 对象各属性含义62空间三维模型瓦片数据格式1 范围本文件规定了空间三维模型瓦片数据格式的基本规定、总体结构和文件存储格式。本文件适用于网络和离线环境下空间三维模型瓦片数据的存储、交换与共享。 2 规范性引用文件下列文件中的内容通过文中的规范性引用而构成本文件必不可少的条款。其中，注日期的引用文件， 仅该日期对应的版本适用于本文件；不注日期的引用文件，其最新版本（包括所有的修改单）适用于本文件。 GB/T 7408 数据元和交换格式 信息交换 日期和时间表示法GB/T 16831 基于坐标的地理点位置标准表示法 GB/T 30170 地理信息 基于坐标的空间参照GB/T 30320 地理空间数据访问接口 GB/T 33187.12016 地理信息 简单要素访问 第1部分：通用架构 3 术语和定义下列术语和定义适用于本文件。 3.1 3.1瓦片 tile按照指定的空间范围规则对空间数据进行划分形成的若干数据单元。空间相邻的瓦片之间空间范围可重叠。 3.2 3.2瓦片树 tiletree自上而下逐级划分的、多细节层次的树形空间数据结构，树形结构的每个节点表示一个瓦片（3.1）。 3.3 3.3根节点瓦片 root tile瓦片树（3.2）中的元素，是同一棵树中除本身外所有节点的祖先，没有父节点。一个瓦片树（3.2） 有且仅有一个根节点瓦片，其空间范围是所有子节点瓦片的并集。 3.4 3.4瓦片树集 tiletreeset57 由一个或多个瓦片树（3.2）构成的集合。 3.5 3.5细节层次数据包 LOD package构成瓦片（3.1）的数据组成单元，是细节层次切换的最小数据单元。一个瓦片（3.1）由一个或多个细节层次数据包构成。 3.6 3.6数据片 patch构成细节层次数据包（3.5）的数据组织单元。每个细节层次数据包（3.5）包含零个或多个数据片。 3.7 3.7模型元素 model element数据片 (3.6)的基本数据构成，包括骨架、材质、纹理三种元素类型。 3.8 3.8实例化 instancing 将有相同几何空间结构，但空间位置、大小和姿态不同的多个模型存储成一个可以被多次引用的模型对象的过程。 3.9 3.9语义纹理 semantic texture一张包含三维模型语义细节的纹理图片，用于存储像素级的语义信息。 3.10 3.10掩膜纹理 mask texture 一张通过不同颜色记录三维模型表面不同区域的纹理图片。 4 符号和缩略语4.1 缩略语下列缩略语适用于本文件。 BOM：字节顺序标记（Byte Order Mark） EPSG：欧洲石油调查组织(The European Petroleum Survey Group) HTML: 超文本标记语言（HyperText Markup Language） ID：身份标识号（IDentity） IETF：互联网工作任务组（Internet Engineering Task Force） JSON：JavaScript对象表示法（JavaScript Object Notation） LOD：细节层次（Level of Detail） PBR：基于物理的渲染（Physically-Based Rendering） RFC：请求评论（Request for Comments） s3mb：二进制空间三维模型（spatial 3D model binary） UML：统一建模语言（Unified Modelling Language） WKT：常用文本表示（Well-Known Text representation） 4.2 UML 图示符号本文件使用UML静态结构图呈现对象之间的逻辑结构。所有UML图示中符号表示的规定见表1。 表1UML 图示符号对照表符号 名称 说明 单向关联 表示A、B两个类之间的关联关系，A类知道B类的公共属性和方法，但B类不知道A类的公共属性和方法 聚合 A对象拥有B对象，A对象可以包含B对象，但B对象不是A对象的组成部分，二者生命周期可以不同 组合 A对象拥有B对象，是整体和部分的关系，且生命周期一致 依赖 A对象依赖于B对象，表示A对象使用B对象，B对象的改变有可能影响A对象 4.3 UML 图多样性描述UML图中多样性描述含义见表2。 表2UML 图多样性描述多样性 意义 0.1 0个或1个 1 只能1个 0.n 0个或多个 1.n 1个或多个 5 基本规定5.1 基本数据类型本文件涉及的计算机编程语言中的基本数据类型规定见表3。 表3基本数据类型规定类型 字节数 取值范围 描述 char 1 -128,127 字符型 wchar 2 -32768,32767 宽字符类型 byte 1 0,255 无符号单字节 bool 1 0|1 布尔型 int16 2 -32768,32767 短整型 uint16 2 0,65535 无符号短整型 int32 4 -2147483648,2147483647 整型 uint32 4 0,4294967295 无符号整型 表3基本数据类型规定（续）类型 字节数 取值范围 描述 int64 8 -263,(263-1) 长整型 uint64 8 0,(264-1) 无符号长整型 float 4 -3.40×1038,3.40×1038 单精度浮点型 double 8 -1.79×10308,1.79×10308 双精度浮点型 5.2 字符串类型字符串数据类型应用String对象描述，采用Unicode编码，字符集规定为UTF-8。UTF-8的相关信息见RFC 3629。 String int32 length; / 字 节 数byte strlength;/ 数 据 内 容 5.3 数组类型数组类型应用Array<Type>对象描述，Type为数组中元素的数据类型。 5.4 JSON 格式存储JSON格式应按UTF-8编码方式存储，不包含BOM文件头。JSON格式的相关信息见RFC 8259。 5.5 日期与时间表示日期与时间数据类型的表示应符合GB/T 7408的规定。 6 总体结构6.1 瓦片树结构本文件采用树形数据结构组织地理空间数据。一份数据通过瓦片树集（TileTreeSet）来组织，TileTreeSet可包含一个或多个瓦片树（TileTree）。TileTree结构示意如图1所示。 注1：以四叉树为例，A0为根节点瓦片（RootTile），B0、B1、B2、B3为A0的子节点Tile，CO、C1、C2、C3为B0的子节点Tile，其他以此类推。 注2：AO由四个细节层次数据包（LODPackage）构成，每个LODPackage由多个数据片（Patch）构成。注3：LODPackage0挂接了一个child tile，指向下一层级的Tile B0。 图1TileTree 结构示意图TileTree的UML图见图2，具体如下： a) TileTree 采用树形数据结构来组织，可包含一个或多个瓦片（Tile），父节点 Tile 的空间范围是所有子节点 Tile 空间范围的并集； b) 每个 Tile 可包含一个或多个细节层次数据包（LODPackage）； 1.nchild tile0.11.n0.nPatchLODPackageTileTileTreec) 一个 LODPackage 可包含零个或多个数据片（Patch），Patch 是该 LODPackage 的实际数据存储单元。每个 LODPackage 可挂接零个或一个 child tile，指向下一层级的 Tile。 图2TileTree 的 UML 图6.2 数据的文件组成6.2.1 必备文件必备文件包括： a) 描述文件。应包含 TileTreeSet 的描述信息，如版本号、数据的地理范围以及 TileTree 中RootTile 路径等； b) 数据文件。应包含 Tile 的数据信息。 6.2.2 可选文件可选文件包括： a) 索引树文件。描述 TileTree 中各 LOD 层的文件信息，应包含各 Tile 的包围盒、LOD 切换信息、挂接的子节点文件路径等； b) 属性描述文件。应包含 TileTreeSet 中各数据集属性描述信息。数据集描述应符合 GB/T 30320的规定； c) 属性数据文件。应包含 TileTree 中所有对象的属性数据。 6.2.3 文件的组织形式各类文件的组织形式见表4。数据示例见附录B。数据可存储在多种数据库中，宜采用键值对(Key-Value)的结构存储，相关示例见附录C。 表4文件组织形式文件类型 文件命名 说明 必备或可选 描述文件 TileTreeSet.json TileTreeSet对应一个描述文件 必备 数据文件 *.s3mb 一个Tile对应一个数据文件 必备 索引树文件 *.json 一个TileTree对应一个或多个索引树文件 与TileTree的RootTile同级目录 可选 属性描述文件 attribute.json TileTreeSet对应一个属性描述文件 与描述文件同级目录 可选 属性数据文件 *.s3md 一个TileTree对应一个属性数据文件 与TileTree的RootTile同级目录 可选 注：*表示文件名可自定义，其中，索引树文件名和属性描述文件名与RootTile名相同。 7 文件存储格式7.1 描述文件7.1.1 描述文件概述描述文件（Config对象）用于描述数据的基本信息，Config对象的UML图见图3。描述文件示例见附录B.1。 图3Config 对象的 UML 图7.1.2 描述文件标签信息描述文件，即Config对象，各标签含义见表5。 表5Config 对象各标签含义标签名 类型 描述 asset String 数据的基本信息，如生产单位等 version String 版本号 dataType String 地理空间数据的类型 取值范围：ArtificialModel,RealityMesh, PointCloud, BIM,Vector,Network，InstanceModel 分别对应：人工模型，倾斜摄影三维模型，点云，BIM，矢量数据网络数据和外挂模型 pyramidSplitType String 数据的空间划分类型 取值范围：QuadTree,Octree,RTree,K-DTree,Grid,BinarySpacePartitioningTree ,UnorderedTree分别对应：四叉树，八叉树，R树，K-D树，网格，BSP树，自由树lodType String LOD切换到精细层时，精细层Tile数据的处理方式 取值范围：Add,Replace 分别对应：添加到当前层，替换当前层 geoBounds Rect 数据的地理范围，用Rect对象表示,和crs标签的坐标系一致。Rect对象各标签含义见表6 heightRange HeightRange 数据的高度范围，用HeightRange对象表示，HeightRange对象各标签含义见表7 标签名 类型 描述 vertexAttributeDescriptArray<CategoryDescript>顶点扩展属性的含义描述信息和数值范围，用CategoryDescript对象构成的数组表示。CategoryDescript对象各标签含义见表8 顶点扩展属性记录用户自定义扩展的顶点属性，具体见表33 position Position 整个TileTreeSet放置的空间点坐标位置，用Position对象表示。Position对象各标签含义见表10 crs String 坐标系信息，可表述任何按照GB/T 30170所描述的坐标参照系类型 表示形式：crs:type:content，其中crs为关键字，type可以是epsg或wkt，content是字符串内容 epsg形式的表述格式示例：crs:epsg:4490 wkt形式的表述格式：crs:wkt: wktcontent wktcontent应符合GB/T 33187.12016中6.4的规定 rootTiles Array<TileTreeInfo> TileTreeSet中所有RootTile的信息，用TileTreeInfo对象构成的数组表示。TileTreeInfo对象各标签含义见表12 idFieldName String IDInfo中单体对象ID的属性字段名，单体对象ID见表57 对应属性描述文件（attribute.json）中FieldInfo里某个字段名FieldInfo见表66 compressedPackageType String 数据文件（.s3mb）的压缩类型 取值范围：None,Zip,Gzip 分别对应：无压缩、zip压缩、gzip压缩 extensions String 用户自定义的扩展信息 表5Config 对象各标签含义（续）。表6Rect 对象各标签含义标签名 类型 描述 left double 数据地理范围的左值 top double 数据地理范围的上值 right double 数据地理范围的右值 bottom double 数据地理范围的下值 表7HeightRange 对象各标签含义标签名 类型 描述 min double 最小值 max double 最大值 表8CategoryDescript 对象各标签含义标签名 类型 描述 category String 顶点扩展属性的含义描述信息 range Range 顶点扩展属性的数值范围，用 Range 对象表示。Range 对象各标签含义见表 9表9Range 对象各标签含义标签名 类型 描述 dimension uint16 数据的维度数 min Array<double> 每个维度的最小值构成的数组，数组长度等于 dimension max Array<double> 每个维度的最大值构成的数组，数组长度等于 dimension 表10Position 对象各标签含义标签名 类型 描述 point3D Point3D 空间点坐标值，用 Point3D 对象表示，经纬度的表示法应符合 GB/T 16831 的规定。Point3D 对象各标签含义见表 11 unit String 空间坐标值的单位 取值范围：Degree,Meter 分别对应：度、米 表11Point3D 对象各标签含义标签名 类型 描述 x double 空间点的 x 坐标值 y double 空间点的 y 坐标值 z double 空间点的 z 坐标值 表12TileTreeInfo 对象各标签含义标签名 类型 描述 url String RootTile 所在路径，可以是相对路径、绝对路径或网络路径。如果采用相对路径，则为相对于描述文件所在位置的路径 boundingBox BoundingBox RootTile 数据的空间范围，用 BoundingBox 对象表示。BoundingBox 对象各标签含义见表 13 表13BoundingBox 对象各标签含义标签名 类型 描述 center Point3D 包围盒中心点，用 Point3D 对象表示。Point3D 对象各标签含义见表 11 xExtent Vector3 包围盒 x 方向和长度，用Vector3 对象表示。Vector3 对象各标签含义见表 50 yExtent Vector3 包围盒 y 方向和长度，用Vector3 对象表示。Vector3 对象各标签含义见表 50 zExtent Vector3 包围盒 z 方向和长度，用Vector3 对象表示。Vector3 对象各标签含义见表 50 7.2 数据文件7.2.1 数据文件结构7.2.1.1 数据文件结构概述数据文件（Tile对象）是数据的主要组成部分，主要由LODPackage、ModelElements、IDInfo和Extensions四个对象构成。Tile对象的UML图见图4，对象各属性含义见表14。 图4Tile 对象的 UML 图 表14Tile 对象各属性含义属性名 类型 描述 options uint32 扩展标识信息，默认值为0。值为1时，表示Tile包含IDInfo对象lodPackageCount int32 Tile中LODPackage对象的个数 lodPackages Array<LODPackage> Tile中所有LODPackage的集合。LODPackage对象各属性含义见表15 modelElements ModelElements Tile 的模型元素信息集合， 用ModelElements 对象表示， ModelElements对象各属性含义见表27 idInfoRepresentationOption uint32 IDInfo对象表述格式的标识信息，取值为1时，表示IDInfo对象采用二进制流形式存储；取值为2时，表示IDInfo对象采用JSON格式表述 idInfo IDInfo Tile的模型ID信息，用IDInfo对象表示，IDInfo对象各属性含义见表55 extensions String 数据扩展信息字符串（JSON格式），extensions对象各标签含义见表59 7.2.1.2 细节层次数据包对象7.2.1.2.1 主要结构细节层次数据包（LODPackage）是细节层次切换的最小数据单元，应包括LOD切换模式、数据范围、挂接的子文件路径、数据片（Patch）等数据信息，可包含动画（Animation）信息。LODPackage对象的UML图见图5，对象各属性含义见表15。 图5LODPackage 对象的 UML 图 表15LODPackage 对象各属性含义属性名 类型 描述 rangeValue float LOD 切换的阈值因子，与 LOD 切换模式配合使用 rangeMode RangeMode LOD 切换模式，即 LOD 切换过程中基于该模式选取一个合适的 LOD，用RangeMode 对象表示，RangeMode 对象各枚举值含义见表 16 boundingSphere BoundingSphere 包围球，用 BoundingSphere 对象表示。BoundingSphere 对象各属性含义见表 17 boundingBox BoundingBox 包围盒，用 BoundingBox 对象表示。BoundingBox 对象各属性含义见表13 strChildTile String 挂接的下一层级的数据文件相对于当前文件的路径 patchCount int32 数据片的个数 patches Array<Patch> 数据片集合，用 Patch 对象构成的数组表示。Patch 对象各属性含义见表 18 animations String 动画字符串（JSON 格式）,用 Animation 对象表示，Animation 对象各标签含义见表 20 表16RangeMode 对象各枚举值含义枚举名 类型 含义 Distance_From_EyePoint int32 基于距离的LOD选取，距离通常是指瓦片与视点之间的距离 Pixel_Size_OnScreen int32 基于投影面积的LOD选取，投影面积通常是指瓦片投影在屏幕上的像素数 Geometric_Error int32 基于几何误差模式的LOD选取 表17BoundingSphere 对象各属性含义属性名 类型 描述 x double 包围球中心点的x坐标值 y double 包围球中心点的y坐标值 表17BoundingSphere 对象各属性含义（续）属性名 类型 描述 z double 包围球中心点的z坐标值 r double 包围球半径 7.2.1.2.2 数据片对象数据片（Patch）是构成LODPackage的数据组成单元。Patch与模型元素（ModelElement）存在聚合关系。Patch对象的UML图见图6，对象各属性含义见表18。 图6Patch 对象的 UML 图 表18Patch 对象各属性含义属性名 类型 描述 matrix4d Matrix4D 作用于骨架姿态的矩阵，应符合右手笛卡尔坐标系，用 Matrix4D 对象表示。Matrix4D 对象各属性含义见表 19 skeletonCount int32 Patch 中骨架对象的数量 skeletonNames Array<String> Patch 中骨架名字数组。骨架名字与 ModelElments 中的骨架名对应。当表 5 中 dataType 取值为 InstanceModel 时，该属性含义为外挂模型路径的数组 表19Matrix4D 对象各属性含义属性名 类型 描述 values Array<double> × 矩阵，16 个 double 值表示，行主序 7.2.1.2.3 动画对象动画（Animation）对象用于描述LODPackage中Patch数据的动画展示过程，可表达节点动画和骨骼动画。在节点动画中，通过平移、旋转模型来生成动画。在骨骼动画中，模型具有互相连接的“骨骼” 组成的骨架结构，通过改变骨骼的朝向和位置来为模型生成动画。 Animation 对象应采用JSON 格式表述， 包括动画节点（ AnimationNode ） 对象、动画蒙皮（AnimationSkin）对象以及动画内容（AnimationContent）对象。Animation对象的UML图见图7，对象各标签含义见表20。 AnimationSkin对象记录关节信息，与AnimationNode对象中记录的指定Patch中的蒙皮信息，共同确定骨骼动画的初始状态。AnimationContent对象控制动画的帧状态及动作时长等。 蒙皮包括权重和关节两部分数据，存储在顶点扩展属性extension对象中，存储格式应符合表29中extension的规定。蒙皮权重（SkinnedWe