Cesium 测试资产解析Feature ID Texture 叠加 KHR_texture_transform 的 glTF 模型如何验证纹理变换【免费下载链接】cesiumAn open-source JavaScript library for world-class 3D globes and maps :earth_americas:项目地址: https://gitcode.com/GitHub_Trending/ce/cesium本篇围绕 Cesium 仓库中的测试数据Specs/Data/Models/glTF-2.0/FeatureIdTextureWithTextureTransform/glTF/展开。它是一组为验证 glTF 资产中 EXT_mesh_features 的 Feature ID Texture 支持 KHR_texture_transform 扩展而构造的最小化测试模型对应 Cesium issue #11731。读完本文你将理解这个“单位正方形 8×8 红色渐变纹理”资产的结构设计意图、纹理变换 offset/scale 如何影响采样区域以及 Cesium 在 FeatureIdPipelineStage.js 中如何把变换矩阵编译进片段着色器并通过三处测试用例形成端到端验证闭环。一、测试数据是什么一个为回归测试而生的最小 glTFREADME.md 明确说明这是针对 Cesium issue #11731 的测试数据资产本身只包含一个单位正方形unit square核心设计是让同一张纹理同时承担两种职责作为 PBR 材质的 base color texture基础颜色作为 EXT_mesh_features 的 Feature ID Texture属性纹理。纹理是一张 8×8 像素的图仅红色分量从 0 开始递增取值为[0 ... 64) * 3即 0、3、6、……、189右下角像素红色值为 63×3189。由此产生两条可验证的性质基础颜色呈现“黑 → 红”的渐变Feature ID 的取值范围为[0 ... 189]。更关键的是纹理的两个使用点挂载了完全相同的 KHR_texture_transformoffset 为[0.25, 0.25]scale 为[0.5, 0.5]。这正是该资产存在的目的——验证 Feature ID Texture 的纹理变换与基础颜色纹理的纹理变换行为一致。资产目录包含四个文件文件作用FeatureIdTextureWithTextureTransform.gltfglTF 2.0 描述文件generator 标注为 glTF-Transform v3.6.0FeatureIdTextureWithTextureTransform_data.bin二进制缓冲140 字节索引 位置/法线/UVFeatureIdTextureWithTextureTransform_img0.png8×8 红色渐变纹理README.md测试数据说明二、glTF 结构剖析同一张纹理、两处相同的变换FeatureIdTextureWithTextureTransform.gltf 的关键部分值得逐项对照。2.1 几何体单位正方形accessors索引为 SCALAR/UNSIGNED_SHORT51236 个POSITION 为 VEC34 个顶点min/max 均为 [0,0,0]~[1,1,0]NORMAL 为 VEC3TEXCOORD_0 为 VEC2bufferViews索引视图 target 为 34963ELEMENT_ARRAY_BUFFER顶点视图 target 为 34962ARRAY_BUFFER单个 mesh primitivemode: 4即 TRIANGLES单节点、单场景结构最小化。2.2 采样器NEAREST CLAMP_TO_EDGEsamplers: [ { magFilter: 9728, // NEAREST minFilter: 9728, // NEAREST wrapS: 33071, // CLAMP_TO_EDGE wrapT: 33071 // CLAMP_TO_EDGE } ]采样器显式声明了 CLAMP_TO_EDGE33071而非默认的 REPEAT。这一点在后文 GltfLoaderSpec 的 wrap mode 测试中会被专门断言——Cesium 会对 Feature ID Texture 强制最近邻过滤但必须原样保留资产显式声明的 wrap 模式。2.3 材质baseColorTexture 上的 KHR_texture_transformmaterials: [ { doubleSided: true, pbrMetallicRoughness: { metallicFactor: 0, baseColorTexture: { index: 0, extensions: { KHR_texture_transform: { offset: [0.25, 0.25], scale: [0.5, 0.5] } } } } } ]2.4 图元EXT_mesh_features 中挂同一纹理、同一变换extensions: { EXT_mesh_features: { featureIds: [ { featureCount: 64, texture: { channels: [0], // 只读 R 通道 index: 0, // 与 baseColorTexture 同一张纹理 extensions: { KHR_texture_transform: { offset: [0.25, 0.25], scale: [0.5, 0.5] } } } } ] } }注意extensionsUsed包含KHR_texture_transform与EXT_mesh_features而extensionsRequired只列了KHR_texture_transform——即纹理变换是必须正确理解的扩展否则采样区域就会算错。三、变换如何改变采样结果这个设计的“判据”8×8 纹理共 64 个像素红色分量依次为0*3, 3*3, …, 63*3。未应用变换时UV ∈ [0,1) 会覆盖整张纹理feature ID 取值覆盖[0, 189]应用offset [0.25, 0.25] scale [0.5, 0.5]后实际采样 UV 被限制在[0.25, 0.75)也就是纹理中间区域跳过首尾两“行”像素块。ModelSpec.js 中的端到端测试正是利用这一点设计了一个可观察判据注入一个 CustomShader当fsInput.featureIds.featureId_0小于16*3对应纹理前两行像素或大于等于48*3对应最后两行像素时输出纯红色否则输出黑色——const customShader new CustomShader({ fragmentShaderText: void fragmentMain(FragmentInput fsInput, inout czm_modelMaterial material) { int id fsInput.featureIds.featureId_0; if (id 16 * 3) { material.diffuse vec3(1.0, 0.0, 0.0); } else if (id 48 * 3) { material.diffuse vec3(1.0, 0.0, 0.0); } else { material.diffuse vec3(0.0, 0.0, 0.0); } } , });然后以相机对准平面中心点 (0.1, 0.1)、near0.01/far5.0 渲染并断言三个颜色通道都小于 50即画面必须接近黑色。逻辑闭环是若 KHR_texture_transform 被正确应用采样区域只会命中纹理中部像素ID 介于 48 与 144 之间CustomShader 输出黑色若变换被忽略UV 会扫到纹理首尾像素画面出现红色测试失败。测试还特意传入incrementallyLoadTextures: false确保 feature ID 纹理在渲染前已完全加载——这一点在注释中被强调为必要前提。四、源码级实现变换矩阵如何进入着色器Cesium 的处理逻辑集中在 FeatureIdPipelineStage.js。为 Feature ID Texture 生成着色器代码时约 L350–L422它为每个 feature ID 纹理创建sampler2Duniform如u_featureIdTexture_0随后检查纹理读取器上解析出的KHR_texture_transform// Check if the texture defines a transform from a KHR_texture_transform const transform textureReader.transform; if (defined(transform) !Matrix3.equals(transform, Matrix3.IDENTITY)) { // Add a uniform for the transformation matrix const transformUniformName ${uniformName}Transform; shaderBuilder.addUniform(mat3, transformUniformName, ShaderDestination.FRAGMENT); uniformMap[transformUniformName] function () { return transform; }; // Update the expression for the texture coordinates texCoordVariableExpression vec2(${transformUniformName} * vec3(${texCoordVariable}, 1.0)); } // Read one or more channels from the texture const textureRead texture(${uniformName}, ${texCoordVariableExpression}).${channels}; const initializationLine featureIds.${variableName} czm_unpackUint(${textureRead});;三个要点只有非单位矩阵才注入 uniformMatrix3.equals(transform, Matrix3.IDENTITY)的短路判断意味着无变换的资产不会付出多余的 uniform 开销这也是 FeatureIdPipelineStageSpec 中 microcosm 用例断言着色器里没有 transform uniform 的原因变换以 mat3 uniform 形式传入片段着色器命名约定为u_featureIdTexture_nTransformUV 采样前先用齐次坐标做一次矩阵乘法vec3(v_texCoord_0, 1.0)最终 ID 仍由czm_unpackUint从单通道展开。五、三处测试用例构成的验证闭环仓库中有三个测试文件引用了该资产路径均相对仓库根目录分别覆盖着色器生成、端到端渲染与纹理采样参数三个层面5.1 着色器生成层FeatureIdPipelineStageSpecFeatureIdPipelineStageSpec.js 的 “adds feature ID texture transforms to the shader” 用例L504–L581加载资产后调用FeatureIdPipelineStage.process精确断言片段着色器包含uniform sampler2D u_featureIdTexture_0; uniform mat3 u_featureIdTexture_0Transform; // 且初始化行为 featureIds.featureId_0 czm_unpackUint(texture(u_featureIdTexture_0, vec2(u_featureIdTexture_0Transform * vec3(v_texCoord_0, 1.0))).r);即同时验证了 uniform 声明与采样表达式的文本形态与上文源码实现一一对应。5.2 端到端渲染层ModelSpecModelSpec.js 的 “transforms feature ID textures with KHR_texture_transform” 用例L823–L888即第三节描述的 CustomShader 颜色判据测试它验证的是“变换真正生效”这一最终用户可观察的行为。5.3 采样参数层GltfLoaderSpecGltfLoaderSpec.js 的 “keeps the wrap mode a feature ID texture declares explicitly” 用例L1316–L1330断言该资产显式声明的 CLAMP_TO_EDGE 被原样保留TextureWrap.CLAMP_TO_EDGE而最近邻过滤仍按 Cesium 对 feature ID 纹理的策略强制生效。对照组是同文件的 microcosm 用例——未声明采样器时按 glTF 默认 REPEAT 处理验证“强制最近邻过滤不得顺带篡改 wrap 模式”。六、实际项目中的使用方式与要点如果你的 3D Tiles / glTF 数据同样在 Feature ID Texture 上使用了 KHR_texture_transform可参照该测试资产的组织方式构造验证用例加载要点如下// 通过 Model.fromGltfAsync 加载 glTF 资产 const model await Model.fromGltfAsync({ url: FeatureIdTextureWithTextureTransform.gltf, // 测试中统一关闭纹理增量加载保证 feature ID 纹理 // 在首帧渲染前已就绪 incrementallyLoadTextures: false, }); const primitive model.nodes[0].primitives[0]; // primitive.featureIds[0].textureReader.texture 即为 Feature ID 纹理读取 feature ID在自定义着色器中通过fsInput.featureIds.featureId_n读取测试中为featureId_0Cesium 已将其解析为 intfeatureCount 与 ID 值域的区分该资产featureCount声明为 64但红色分量按[0...64)*3编码展开后的 ID 实际落在[0, 189]——featureCount 只声明 feature 数量上限不约束像素值的编码方式这是构造此类测试纹理时的常见细节变换一致性是核心回归点baseColorTexture 与 featureId texture 挂相同变换意味着任何一处材质或 feature ID丢失变换支持都会表现为“颜色对了但 feature ID 查询错位”或反之该资产让两类问题都能被上述三个测试分别捕获。七、参考文件汇总路径说明README.md测试数据设计说明8×8 红色渐变纹理、双重纹理用途、统一变换参数FeatureIdTextureWithTextureTransform.gltf资产描述sampler、KHR_texture_transform、EXT_mesh_featuresFeatureIdPipelineStage.js变换矩阵注入 mat3 uniform 并改写 UV 采样表达式的核心实现约 L392–L416FeatureIdPipelineStageSpec.js着色器生成断言L504–L581ModelSpec.jsCustomShader 颜色判据的端到端渲染测试L823–L888GltfLoaderSpec.jsCLAMP_TO_EDGE wrap 模式保留断言L1316–L1330从这套“最小资产 三层测试”的组合可以看出Cesium 对 KHR_texture_transform 在 Feature ID Texture 上的支持验证是从 JSON 解析、着色器代码生成到最终像素输出的全链路保障。【免费下载链接】cesiumAn open-source JavaScript library for world-class 3D globes and maps :earth_americas:项目地址: https://gitcode.com/GitHub_Trending/ce/cesium创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Cesium 测试资产解析Feature ID Texture 叠加 KHR_texture_transform 的 glTF 模型如何验证纹理变换【免费下载链接】cesiumAn open-source JavaScript library for world-class 3D globes and maps :earth_americas:项目地址: https://gitcode.com/GitHub_Trending/ce/cesium本篇围绕 Cesium 仓库中的测试数据Specs/Data/Models/glTF-2.0/FeatureIdTextureWithTextureTransform/glTF/展开。它是一组为验证 glTF 资产中 EXT_mesh_features 的 Feature ID Texture 支持 KHR_texture_transform 扩展而构造的最小化测试模型对应 Cesium issue #11731。读完本文你将理解这个“单位正方形 8×8 红色渐变纹理”资产的结构设计意图、纹理变换 offset/scale 如何影响采样区域以及 Cesium 在 FeatureIdPipelineStage.js 中如何把变换矩阵编译进片段着色器并通过三处测试用例形成端到端验证闭环。一、测试数据是什么一个为回归测试而生的最小 glTFREADME.md 明确说明这是针对 Cesium issue #11731 的测试数据资产本身只包含一个单位正方形unit square核心设计是让同一张纹理同时承担两种职责作为 PBR 材质的 base color texture基础颜色作为 EXT_mesh_features 的 Feature ID Texture属性纹理。纹理是一张 8×8 像素的图仅红色分量从 0 开始递增取值为[0 ... 64) * 3即 0、3、6、……、189右下角像素红色值为 63×3189。由此产生两条可验证的性质基础颜色呈现“黑 → 红”的渐变Feature ID 的取值范围为[0 ... 189]。更关键的是纹理的两个使用点挂载了完全相同的 KHR_texture_transformoffset 为[0.25, 0.25]scale 为[0.5, 0.5]。这正是该资产存在的目的——验证 Feature ID Texture 的纹理变换与基础颜色纹理的纹理变换行为一致。资产目录包含四个文件文件作用FeatureIdTextureWithTextureTransform.gltfglTF 2.0 描述文件generator 标注为 glTF-Transform v3.6.0FeatureIdTextureWithTextureTransform_data.bin二进制缓冲140 字节索引 位置/法线/UVFeatureIdTextureWithTextureTransform_img0.png8×8 红色渐变纹理README.md测试数据说明二、glTF 结构剖析同一张纹理、两处相同的变换FeatureIdTextureWithTextureTransform.gltf 的关键部分值得逐项对照。2.1 几何体单位正方形accessors索引为 SCALAR/UNSIGNED_SHORT51236 个POSITION 为 VEC34 个顶点min/max 均为 [0,0,0]~[1,1,0]NORMAL 为 VEC3TEXCOORD_0 为 VEC2bufferViews索引视图 target 为 34963ELEMENT_ARRAY_BUFFER顶点视图 target 为 34962ARRAY_BUFFER单个 mesh primitivemode: 4即 TRIANGLES单节点、单场景结构最小化。2.2 采样器NEAREST CLAMP_TO_EDGEsamplers: [ { magFilter: 9728, // NEAREST minFilter: 9728, // NEAREST wrapS: 33071, // CLAMP_TO_EDGE wrapT: 33071 // CLAMP_TO_EDGE } ]采样器显式声明了 CLAMP_TO_EDGE33071而非默认的 REPEAT。这一点在后文 GltfLoaderSpec 的 wrap mode 测试中会被专门断言——Cesium 会对 Feature ID Texture 强制最近邻过滤但必须原样保留资产显式声明的 wrap 模式。2.3 材质baseColorTexture 上的 KHR_texture_transformmaterials: [ { doubleSided: true, pbrMetallicRoughness: { metallicFactor: 0, baseColorTexture: { index: 0, extensions: { KHR_texture_transform: { offset: [0.25, 0.25], scale: [0.5, 0.5] } } } } } ]2.4 图元EXT_mesh_features 中挂同一纹理、同一变换extensions: { EXT_mesh_features: { featureIds: [ { featureCount: 64, texture: { channels: [0], // 只读 R 通道 index: 0, // 与 baseColorTexture 同一张纹理 extensions: { KHR_texture_transform: { offset: [0.25, 0.25], scale: [0.5, 0.5] } } } } ] } }注意extensionsUsed包含KHR_texture_transform与EXT_mesh_features而extensionsRequired只列了KHR_texture_transform——即纹理变换是必须正确理解的扩展否则采样区域就会算错。三、变换如何改变采样结果这个设计的“判据”8×8 纹理共 64 个像素红色分量依次为0*3, 3*3, …, 63*3。未应用变换时UV ∈ [0,1) 会覆盖整张纹理feature ID 取值覆盖[0, 189]应用offset [0.25, 0.25] scale [0.5, 0.5]后实际采样 UV 被限制在[0.25, 0.75)也就是纹理中间区域跳过首尾两“行”像素块。ModelSpec.js 中的端到端测试正是利用这一点设计了一个可观察判据注入一个 CustomShader当fsInput.featureIds.featureId_0小于16*3对应纹理前两行像素或大于等于48*3对应最后两行像素时输出纯红色否则输出黑色——const customShader new CustomShader({ fragmentShaderText: void fragmentMain(FragmentInput fsInput, inout czm_modelMaterial material) { int id fsInput.featureIds.featureId_0; if (id 16 * 3) { material.diffuse vec3(1.0, 0.0, 0.0); } else if (id 48 * 3) { material.diffuse vec3(1.0, 0.0, 0.0); } else { material.diffuse vec3(0.0, 0.0, 0.0); } } , });然后以相机对准平面中心点 (0.1, 0.1)、near0.01/far5.0 渲染并断言三个颜色通道都小于 50即画面必须接近黑色。逻辑闭环是若 KHR_texture_transform 被正确应用采样区域只会命中纹理中部像素ID 介于 48 与 144 之间CustomShader 输出黑色若变换被忽略UV 会扫到纹理首尾像素画面出现红色测试失败。测试还特意传入incrementallyLoadTextures: false确保 feature ID 纹理在渲染前已完全加载——这一点在注释中被强调为必要前提。四、源码级实现变换矩阵如何进入着色器Cesium 的处理逻辑集中在 FeatureIdPipelineStage.js。为 Feature ID Texture 生成着色器代码时约 L350–L422它为每个 feature ID 纹理创建sampler2Duniform如u_featureIdTexture_0随后检查纹理读取器上解析出的KHR_texture_transform// Check if the texture defines a transform from a KHR_texture_transform const transform textureReader.transform; if (defined(transform) !Matrix3.equals(transform, Matrix3.IDENTITY)) { // Add a uniform for the transformation matrix const transformUniformName ${uniformName}Transform; shaderBuilder.addUniform(mat3, transformUniformName, ShaderDestination.FRAGMENT); uniformMap[transformUniformName] function () { return transform; }; // Update the expression for the texture coordinates texCoordVariableExpression vec2(${transformUniformName} * vec3(${texCoordVariable}, 1.0)); } // Read one or more channels from the texture const textureRead texture(${uniformName}, ${texCoordVariableExpression}).${channels}; const initializationLine featureIds.${variableName} czm_unpackUint(${textureRead});;三个要点只有非单位矩阵才注入 uniformMatrix3.equals(transform, Matrix3.IDENTITY)的短路判断意味着无变换的资产不会付出多余的 uniform 开销这也是 FeatureIdPipelineStageSpec 中 microcosm 用例断言着色器里没有 transform uniform 的原因变换以 mat3 uniform 形式传入片段着色器命名约定为u_featureIdTexture_nTransformUV 采样前先用齐次坐标做一次矩阵乘法vec3(v_texCoord_0, 1.0)最终 ID 仍由czm_unpackUint从单通道展开。五、三处测试用例构成的验证闭环仓库中有三个测试文件引用了该资产路径均相对仓库根目录分别覆盖着色器生成、端到端渲染与纹理采样参数三个层面5.1 着色器生成层FeatureIdPipelineStageSpecFeatureIdPipelineStageSpec.js 的 “adds feature ID texture transforms to the shader” 用例L504–L581加载资产后调用FeatureIdPipelineStage.process精确断言片段着色器包含uniform sampler2D u_featureIdTexture_0; uniform mat3 u_featureIdTexture_0Transform; // 且初始化行为 featureIds.featureId_0 czm_unpackUint(texture(u_featureIdTexture_0, vec2(u_featureIdTexture_0Transform * vec3(v_texCoord_0, 1.0))).r);即同时验证了 uniform 声明与采样表达式的文本形态与上文源码实现一一对应。5.2 端到端渲染层ModelSpecModelSpec.js 的 “transforms feature ID textures with KHR_texture_transform” 用例L823–L888即第三节描述的 CustomShader 颜色判据测试它验证的是“变换真正生效”这一最终用户可观察的行为。5.3 采样参数层GltfLoaderSpecGltfLoaderSpec.js 的 “keeps the wrap mode a feature ID texture declares explicitly” 用例L1316–L1330断言该资产显式声明的 CLAMP_TO_EDGE 被原样保留TextureWrap.CLAMP_TO_EDGE而最近邻过滤仍按 Cesium 对 feature ID 纹理的策略强制生效。对照组是同文件的 microcosm 用例——未声明采样器时按 glTF 默认 REPEAT 处理验证“强制最近邻过滤不得顺带篡改 wrap 模式”。六、实际项目中的使用方式与要点如果你的 3D Tiles / glTF 数据同样在 Feature ID Texture 上使用了 KHR_texture_transform可参照该测试资产的组织方式构造验证用例加载要点如下// 通过 Model.fromGltfAsync 加载 glTF 资产 const model await Model.fromGltfAsync({ url: FeatureIdTextureWithTextureTransform.gltf, // 测试中统一关闭纹理增量加载保证 feature ID 纹理 // 在首帧渲染前已就绪 incrementallyLoadTextures: false, }); const primitive model.nodes[0].primitives[0]; // primitive.featureIds[0].textureReader.texture 即为 Feature ID 纹理读取 feature ID在自定义着色器中通过fsInput.featureIds.featureId_n读取测试中为featureId_0Cesium 已将其解析为 intfeatureCount 与 ID 值域的区分该资产featureCount声明为 64但红色分量按[0...64)*3编码展开后的 ID 实际落在[0, 189]——featureCount 只声明 feature 数量上限不约束像素值的编码方式这是构造此类测试纹理时的常见细节变换一致性是核心回归点baseColorTexture 与 featureId texture 挂相同变换意味着任何一处材质或 feature ID丢失变换支持都会表现为“颜色对了但 feature ID 查询错位”或反之该资产让两类问题都能被上述三个测试分别捕获。七、参考文件汇总路径说明README.md测试数据设计说明8×8 红色渐变纹理、双重纹理用途、统一变换参数FeatureIdTextureWithTextureTransform.gltf资产描述sampler、KHR_texture_transform、EXT_mesh_featuresFeatureIdPipelineStage.js变换矩阵注入 mat3 uniform 并改写 UV 采样表达式的核心实现约 L392–L416FeatureIdPipelineStageSpec.js着色器生成断言L504–L581ModelSpec.jsCustomShader 颜色判据的端到端渲染测试L823–L888GltfLoaderSpec.jsCLAMP_TO_EDGE wrap 模式保留断言L1316–L1330从这套“最小资产 三层测试”的组合可以看出Cesium 对 KHR_texture_transform 在 Feature ID Texture 上的支持验证是从 JSON 解析、着色器代码生成到最终像素输出的全链路保障。【免费下载链接】cesiumAn open-source JavaScript library for world-class 3D globes and maps :earth_americas:项目地址: https://gitcode.com/GitHub_Trending/ce/cesium创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
