Cesium 测试资产解析：Feature ID Texture 叠加 KHR_texture_transform 的 glTF 模型如何验证纹理变换

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 中如何把变换矩阵编译进片段着色器，并通过三处测试用例形成端到端验证闭环。

一、测试数据是什么：一个为回归测试而生的最小 glTF

README.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×3=189）。由此产生两条可验证的性质：

1. 基础颜色呈现“黑 → 红”的渐变；
2. Feature ID 的取值范围为[0 ... 189]。

更关键的是，纹理的两个使用点挂载了完全相同的 KHR_texture_transform：offset 为[0.25, 0.25]，scale 为[0.5, 0.5]。这正是该资产存在的目的——验证 Feature ID Texture 的纹理变换与基础颜色纹理的纹理变换行为一致。

资产目录包含四个文件：

二、glTF 结构剖析：同一张纹理、两处相同的变换

FeatureIdTextureWithTextureTransform.gltf 的关键部分值得逐项对照。

2.1 几何体：单位正方形

• accessors：索引为 SCALAR/UNSIGNED_SHORT（5123，6 个），POSITION 为 VEC3（4 个顶点，min/max 均为 [0,0,0]~[1,1,0]），NORMAL 为 VEC3，TEXCOORD_0 为 VEC2；
• bufferViews：索引视图 target 为 34963（ELEMENT_ARRAY_BUFFER），顶点视图 target 为 34962（ARRAY_BUFFER）；
• 单个 mesh primitive（mode: 4即 TRIANGLES），单节点、单场景，结构最小化。

2.2 采样器：NEAREST + CLAMP_TO_EDGE

"samplers": [ { "magFilter": 9728, // NEAREST "minFilter": 9728, // NEAREST "wrapS": 33071, // CLAMP_TO_EDGE "wrapT": 33071 // CLAMP_TO_EDGE } ]

采样器显式声明了 CLAMP_TO_EDGE（33071）而非默认的 REPEAT。这一点在后文 GltfLoaderSpec 的 wrap mode 测试中会被专门断言——Cesium 会对 Feature ID Texture 强制最近邻过滤，但必须原样保留资产显式声明的 wrap 模式。

2.3 材质：baseColorTexture 上的 KHR_texture_transform

"materials": [ { "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)、near=0.01/far=5.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});`;

三个要点：

1. 只有非单位矩阵才注入 uniform：Matrix3.equals(transform, Matrix3.IDENTITY)的短路判断意味着无变换的资产不会付出多余的 uniform 开销，这也是 FeatureIdPipelineStageSpec 中 microcosm 用例断言着色器里没有 transform uniform 的原因；
2. 变换以 mat3 uniform 形式传入片段着色器，命名约定为u_featureIdTexture_nTransform；
3. UV 采样前先用齐次坐标做一次矩阵乘法（vec3(v_texCoord_0, 1.0)），最终 ID 仍由czm_unpackUint从单通道展开。

五、三处测试用例构成的验证闭环

仓库中有三个测试文件引用了该资产（路径均相对仓库根目录），分别覆盖着色器生成、端到端渲染与纹理采样参数三个层面：

5.1 着色器生成层：FeatureIdPipelineStageSpec

FeatureIdPipelineStageSpec.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 端到端渲染层：ModelSpec

ModelSpec.js 的 “transforms feature ID textures with KHR_texture_transform” 用例（L823–L888）即第三节描述的 CustomShader 颜色判据测试，它验证的是“变换真正生效”这一最终用户可观察的行为。

5.3 采样参数层：GltfLoaderSpec

GltfLoaderSpec.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_0），Cesium 已将其解析为 int；
• featureCount 与 ID 值域的区分：该资产featureCount声明为 64，但红色分量按[0...64)*3编码，展开后的 ID 实际落在[0, 189]——featureCount 只声明 feature 数量上限，不约束像素值的编码方式，这是构造此类测试纹理时的常见细节；
• 变换一致性是核心回归点：baseColorTexture 与 featureId texture 挂相同变换，意味着任何一处（材质或 feature ID）丢失变换支持，都会表现为“颜色对了但 feature ID 查询错位”或反之，该资产让两类问题都能被上述三个测试分别捕获。

七、参考文件汇总

从这套“最小资产 + 三层测试”的组合可以看出，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