Cesium 中的 glTF 属性纹理实战以 SimplePropertyTexture 测试资产解析 EXT_structural_metadata 扩展【免费下载链接】cesiumAn open-source JavaScript library for world-class 3D globes and maps :earth_americas:项目地址: https://gitcode.com/GitHub_Trending/ce/cesium本文以 Cesium 仓库中的测试资产SimplePropertyTexture为主体完整拆解如何用 glTF 的EXT_structural_metadata扩展把逐表面的物理属性如建筑内外温度、保温层厚度编码进一张 RGB 属性纹理Property Texture中并结合 Cesium 引擎源码与测试用例说明该资产在运行时如何被转译为着色器采样代码。读完后你将掌握属性纹理的完整数据结构、通道映射规则以及 Cesium 从加载 glTF 到生成片元着色器的整条消费链路。1. 样本资产定位与几何结构SimplePropertyTexture位于 Specs/Data/Models/glTF-2.0/SimplePropertyTexture/README.md 中是 Cesium 用于验证EXT_structural_metadata扩展属性纹理存储方式的官方测试资产。其 README 明确说明该资产演示如何使用属性纹理保存与图元primitive表面关联的属性值。资产包含一个单一网格图元的 glTF 资产SimplePropertyTexture.gltf。从文件内容可以确认网格是一个单位正方形quad由 2 个三角形、4 个顶点组成顶点带有标准的POSITION4 个 VEC3、NORMAL4 个 VEC3全部为 (0,0,1)和TEXCOORD_04 个 VEC2范围 [0,1]属性索引访问器为 6 个UNSIGNED_SHORTcomponentType 5123标量mode为 4TRIANGLES全部几何数据内嵌在一个 140 字节的 base64 缓冲中通过 4 个 bufferView 切分索引 target 为 34963其余为 34962。这个最小 quad UV 覆盖 0~1的几何设计非常典型属性纹理中的每个像素都可以通过TEXCOORD_0直接寻址到表面上的对应位置是验证表面属性语义的最小可行样本。2. 元数据结构buildingComponents 类定义按 README 描述元数据由EXT_structural_metadataschema 中的单个示例类构成。对照 glTF 文件该 schema 声明如下EXT_structural_metadata: { schema: { classes: { buildingComponents: { name: Building properties, properties: { insideTemperature: { name: Inside Temperature, type: SCALAR, componentType: UINT8 }, outsideTemperature: { name: Outside Temperature, type: SCALAR, componentType: UINT8 }, insulation: { name: Insulation Thickness, type: SCALAR, componentType: UINT8, normalized: true, default: 1 } } } } } }该类定义的是建筑立面的三个属性参数要点如下属性类型组件类型normalizeddefault取值语义insideTemperatureSCALARUINT8否—原始值 [0, 255] 即最终值outsideTemperatureSCALARUINT8否—原始值 [0, 255] 即最终值insulationSCALARUINT8是1原始值 [0, 255] 归一化到 [0.0, 1.0]两个要点值得强调温度属性是原始 UINT8README 指出两个温度值以 UINT8 给出覆盖 [0,255] 范围即着色器中读到的是未经缩放的整数insulation 是归一化 UINT8README 特别用斜体强调它是normalized值——原始 [0,255] 表示 [0.0,1.0] 区间的浮点值。这与 schema 中的normalized: true一一对应并在运行时决定了反解时的缩放因子见第 5 节insulation还携带default: 1Cesium 会为每个元数据属性生成包含defaultValue以及noData、minValue、maxValue字段的元数据类结构体测试用例中可见metadataClass.insulation.defaultValue float(1);的生成结果。3. 属性纹理RGB 通道承载三个属性这是本样本最核心的设计。README 指出README.md#L9-L11类属性值存放在一张属性纹理中纹理的红、绿、蓝通道分别存储insideTemperature、outsideTemperature、insulation的值。glTF 中通过propertyTextures数组声明这一映射并在图元级别引用propertyTextures: [ { class: buildingComponents, properties: { insideTemperature: { index: 1, texCoord: 0, channels: [0] }, outsideTemperature: { index: 1, texCoord: 0, channels: [1] }, insulation: { index: 1, texCoord: 0, channels: [2] } } } ]// 图元侧引用 primitives: [ { extensions: { EXT_structural_metadata: { propertyTextures: [0] } }, attributes: { POSITION: 1, NORMAL: 2, TEXCOORD_0: 3 }, material: 0, mode: 4 } ]参数含义index: 1指向 glTF 顶层textures数组的第 1 项其source为images[1]即内嵌的第二张 PNG——真正的属性纹理textures[0]则被材质用作baseColorTexture因此资产刻意区分了视觉贴图与数据贴图texCoord: 0指定采样使用的顶点纹理坐标集与几何上的TEXCOORD_0呼应channels用 0/1/2 表示 R/G/B 通道单标量属性各占一个通道顶层extensionsUsed声明了EXT_structural_metadata图元通过propertyTextures: [0]索引引用上面的属性纹理条目。从采样器配置看samplers[0]的magFilter与minFilter均为 9728即 GL 的 NEAREST。离散属性值用最近邻采样是合理的双线性插值会在相邻像素的属性值之间产生无物理意义的中间值。材质部分为标准的 PBR 配置baseColorTexture指向textures[0]、metallicFactor: 0、roughnessFactor: 1、alphaMode: OPAQUE、doubleSided: true与元数据扩展相互独立验证了数据通道与渲染通道解耦的资产设计。4. 运行时消费MetadataPipelineStage 如何生成着色器资产的意义在于被 Cesium 正确消费。引擎侧由元数据管线阶段负责把 schema 声明转译为着色器代码测试文件 packages/engine/Specs/Scene/Model/MetadataPipelineStageSpec.js 中的用例 Adds property textures to the shader约 L383-L471正是加载本资产并断言生成结果是理解消费链路最直接的证据。关键结论均由该测试的期望值确认属性纹理只进片元着色器。顶点端的元数据结构体为空字段initializeMetadata顶点函数体为空只有片元端生成了三个字段uint insideTemperature; uint outsideTemperature; float insulation;注意类型映射非归一化 UINT8 属性映射为uint归一化 UINT8insulation映射为float——与第 2 节的 schema 参数严格对应。采样与反解逻辑。片元端initializeMetadata生成的逐属性代码形如float insideTemperature_rawChannels texture(u_propertyTexture_1, attributes.texCoord_0).r; insideTemperature_rawBits czm_unpackTexture(insideTemperature_rawChannels); insideTemperature_unpackedValue ((insideTemperature_rawBits)); metadata.insideTemperature insideTemperature_unpackedValue;可见采样坐标正是几何上的TEXCOORD_0与 schema 中texCoord: 0对应czm_unpackTexture负责把 [0,1] 归一化的通道值还原为整数码raw bits。归一化属性的缩放。insulation的生成代码多出一行缩放insulation_unpackedValue float((insulation_rawBits)) * 0.00392156862745098; metadata.insulation insulation_unpackedValue; metadataClass.insulation.defaultValue float(1);其中0.00392156862745098即 1/255正是normalized: true的 UINT8 属性把 [0,255] 线性映射到 [0.0,1.0] 的因子。这也从实现层面验证了 README 中归一化 UINT8的语义描述。纹理绑定。声明的片元 uniform 为uniform sampler2D u_propertyTexture_1;下标 1 对应 glTFtextures数组索引且三个属性共享同一张纹理测试断言uniformMap.u_propertyTexture_1()与structuralMetadata.getPropertyTexture(0).getProperty(insulation).textureReader.texture指向同一 GPU 纹理对象。适用前提该用例以if (!context.webgl2) return;开头即属性纹理的着色器路径依赖 WebGL2 能力czm_unpackTexture依赖高内部精度格式的整型反解。5. 资产在测试体系中的另一处用途除着色器生成验证外本资产还作为统计口径的测试模型出现在 packages/engine/Specs/Scene/Model/PrimitiveStatisticsPipelineStageSpec.js 中L33-L34 声明了同样的 glTF 路径用于PrimitiveStatisticsPipelineStage对图元显存占用几何缓冲、纹理等的统计测试。从源码结构看这让属性纹理会额外计入纹理内存这一统计行为拥有了与本资产一致的验证数据。6. 在 Cesium 测试资产族中的位置SimplePropertyTexture是 Cesium 属性纹理测试家族中最简单的一档纯标量、单纹理、无变换。同目录下的姊妹资产可用于对照学习它们均位于 Specs/Data/Models/glTF-2.0/ 下PropertyTextureWithVectorProperties向量属性vec2、uvec3、数组占用多个通道的场景PropertyTextureWith32BitTypes用 RGBA 四通道打包更高精度32 位浮点属性的场景PropertyTextureWithTextureTransform带纹理变换矩阵uniformmat3 u_propertyTexture_0Transform的场景。这些资产与SimplePropertyTexture共用同一套 MetadataPipelineStageSpec.js 断言框架读者可先掌握本样本的单通道标量基线再横向对照多通道与高精度打包的实现差异。7. 小结资产结构SimplePropertyTexture用 4 顶点 quad 0~1 UV把 3 个 UINT8 建筑属性编码进一张 RGB 属性纹理R/G/B 分别对应insideTemperature/outsideTemperature/insulation归一化属性由 schema 的normalized: true声明数据解耦视觉贴图textures[0]与属性纹理textures[1]分开声明采样器使用 NEAREST 滤波保证离散值不被插值污染引擎链路Cesium 的MetadataPipelineStage在 WebGL2 下为每个属性生成采样u_propertyTexture_1→czm_unpackTexture反解 → 按需乘 1/255 归一化 → 写入metadata.*的片元着色器代码且属性纹理不产生顶点 varying验证方式以上行为均可由 MetadataPipelineStageSpec.js 中针对本 glTF 的着色器断言逐行复核测试数据与实现互相印证。该资产遵循 CC0 许可可作为理解 glTF 结构性元数据中表面属性存储范式的标准参考样本。【免费下载链接】cesiumAn open-source JavaScript library for world-class 3D globes and maps :earth_americas:项目地址: https://gitcode.com/GitHub_Trending/ce/cesium创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考