s3m-three 0.4.18 → 0.4.20

package/dist/render/TextureFactory.js

@@ -24,6 +24,15 @@ export function setMaxAnisotropy(n, cap = Infinity) {
     maxAnisotropy = Math.max(1, n | 0);
     anisotropyCap = Number.isFinite(cap) && cap > 0 ? Math.max(1, cap) : Infinity;
 }
+/**
+ * 单独调各向异性上限（只影响之后创建的纹理）。
+ * supermap 预设会设成 1 —— 官方 iClient3D 不开各向异性，斜视角直接采高 mip
+ * 平均成纯色；我们默认拉满（Infinity）是为了倾斜摄影立面清晰度，代价是
+ * 米制平铺纹理的远处高频纹（点阵/砖缝）被硬保下来，怎么调光照都"不像官方"。
+ */
+export function setAnisotropyCap(cap) {
+    anisotropyCap = Number.isFinite(cap) && cap > 0 ? Math.max(1, cap) : Infinity;
+}
 /**
  * 纹理长边像素上限（默认 Infinity = 不限制）。
  * 只作用于非图集的 RGBA / WebP 产物，见 `core/TextureDecode.ts` 的 `maxSize`。
@@ -59,6 +68,21 @@ async function decodeTexture(tex, compressed, maxSize) {
     }
     return decodeTextureData(tex, { compressed, maxSize });
 }
+/**
+ * 纹理是否做 sRGB→linear 解码。
+ *
+ * 默认 true（three 线性 PBR 管线的正确姿势）。`lightingPreset: 'supermap'` 会关掉它：
+ * 官方 iClient3D 把贴图字节值**不解码**直接进 shader、在 sRGB 数值空间做 Lambert 直乘，
+ * 要逐像素对齐就得让字节值原样进来（输出端由 StyleMaterial 的 S3M_DIRECT_COLOR 抵消）。
+ */
+let srgbTextureDecode = true;
+/** 切换纹理解码（只影响之后创建的纹理，已上传 GPU 的不受影响） */
+export function setSrgbTextureDecode(v) {
+    srgbTextureDecode = v;
+}
+export function getSrgbTextureDecode() {
+    return srgbTextureDecode;
+}
 function configure(tex, srgb = true) {
     tex.wrapS = THREE.RepeatWrapping;
     tex.wrapT = THREE.RepeatWrapping;
@@ -67,7 +91,7 @@ function configure(tex, srgb = true) {
     tex.generateMipmaps = true;
     // 各向异性过滤对斜视角立面清晰度的提升比提高分辨率更直接
     tex.anisotropy = anisotropyCap === Infinity ? maxAnisotropy : Math.min(maxAnisotropy, anisotropyCap);
-    if (srgb)
+    if (srgb && srgbTextureDecode)
         tex.colorSpace = THREE.SRGBColorSpace;
     tex.flipY = false;
     tex.needsUpdate = true;
@@ -115,10 +139,14 @@ export async function createTexture(tex) {
     }
     else if (data.blocks && data.blockFormat) {
         // DXT 块直传：GPU 硬件解压，省 4~8 倍上传带宽与显存。压缩纹理不能 generateMipmaps
-        // （WebGL 限制），远处靠 LinearFilter 兜底；s3mHasAlpha 走 alphaTest 的 DXT1 1bit
-        // alpha 历史上没开过，DXT5 的 hasAlpha 由 decodeTextureData 判定
+        // （WebGL 限制）——所以**数据自带的内联 mip 链**（官方 iClient3D 逐层上传的那条）
+        // 必须切出来一起传，否则远处只有 level0 可采，高频纹/点阵全保留，永远"糊"不出
+        // 官方那种平均色；s3mHasAlpha 走 alphaTest 的 DXT1 1bit alpha 历史上没开过，
+        // DXT5 的 hasAlpha 由 decodeTextureData 判定
         const format = data.blockFormat === 'dxt1' ? THREE.RGB_S3TC_DXT1_Format : THREE.RGBA_S3TC_DXT5_Format;
-        texture = new THREE.CompressedTexture([{ data: data.blocks, width: data.width, height: data.height }], data.width, data.height, format, THREE.UnsignedByteType);
+        texture = new THREE.CompressedTexture(data.mipmaps && data.mipmaps.length > 1
+            ? data.mipmaps.map((m) => ({ data: m.data, width: m.width, height: m.height }))
+            : [{ data: data.blocks, width: data.width, height: data.height }], data.width, data.height, format, THREE.UnsignedByteType);
     }
     else {
         const dt = new THREE.DataTexture(data.rgba, data.width, data.height, THREE.RGBAFormat, THREE.UnsignedByteType);
@@ -130,7 +158,9 @@ export async function createTexture(tex) {
     const configured = isAtlas ? configureAtlas(texture) : configure(texture);
     if (data.blocks) {
         configured.generateMipmaps = false;
-        configured.minFilter = THREE.LinearFilter;
+        // 带链 → 三线性取链上高层级（官方同款平均效果）；纯 level0 才退回 Linear 兜底
+        configured.minFilter =
+            data.mipmaps && data.mipmaps.length > 1 ? THREE.LinearMipmapLinearFilter : THREE.LinearFilter;
     }
     // flipY 为真即 S3MBLOCK 图集（见 core/types.ts），必须无 mip
     return { texture: configured, decoded: data.kind };

package/dist/render/TextureFactory.js.map

@@ -1 +1 @@
-{"version":3,"file":"TextureFactory.js","sourceRoot":"","sources":["../../src/render/TextureFactory.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAE/B,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAG7D,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAEvD,4CAA4C;AAC5C,IAAI,aAAa,GAAG,CAAC,CAAC;AAEtB;;;;;;GAMG;AACH,IAAI,aAAa,GAAG,QAAQ,CAAC;AAE7B,MAAM,UAAU,gBAAgB,CAAC,CAAS,EAAE,GAAG,GAAG,QAAQ;IACxD,aAAa,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACnC,aAAa,GAAG,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC;AAChF,CAAC;AAED;;;GAGG;AACH,IAAI,cAAc,GAAG,QAAQ,CAAC;AAE9B,MAAM,UAAU,iBAAiB,CAAC,CAAS;IACzC,cAAc,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC;AAC/D,CAAC;AAED;;;;;GAKG;AACH,IAAI,2BAA2B,GAAG,KAAK,CAAC;AAExC,MAAM,UAAU,8BAA8B,CAAC,CAAU;IACvD,2BAA2B,GAAG,CAAC,CAAC;AAClC,CAAC;AAQD;;;;GAIG;AACH,IAAI,eAAe,GAER,IAAI,CAAC;AAEhB,MAAM,UAAU,yBAAyB,CACvC,EAA2G;IAE3G,eAAe,GAAG,EAAE,CAAC;AACvB,CAAC;AAED,KAAK,UAAU,aAAa,CAC1B,GAAe,EACf,UAAmB,EACnB,OAAe;IAEf,IAAI,eAAe,EAAE,CAAC;QACpB,MAAM,SAAS,GAAG,MAAM,eAAe,CAAC,GAAG,EAAE,UAAU,EAAE,OAAO,CAAC,CAAC;QAClE,IAAI,SAAS;YAAE,OAAO,SAAS,CAAC;IAClC,CAAC;IACD,OAAO,iBAAiB,CAAC,GAAG,EAAE,EAAE,UAAU,EAAE,OAAO,EAAE,CAAC,CAAC;AACzD,CAAC;AAED,SAAS,SAAS,CAA0B,GAAM,EAAE,IAAI,GAAG,IAAI;IAC7D,GAAG,CAAC,KAAK,GAAG,KAAK,CAAC,cAAc,CAAC;IACjC,GAAG,CAAC,KAAK,GAAG,KAAK,CAAC,cAAc,CAAC;IACjC,GAAG,CAAC,SAAS,GAAG,KAAK,CAAC,YAAY,CAAC;IACnC,GAAG,CAAC,SAAS,GAAG,KAAK,CAAC,wBAAwB,CAAC;IAC/C,GAAG,CAAC,eAAe,GAAG,IAAI,CAAC;IAC3B,8BAA8B;IAC9B,GAAG,CAAC,UAAU,GAAG,aAAa,KAAK,QAAQ,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,aAAa,EAAE,aAAa,CAAC,CAAC;IACrG,IAAI,IAAI;QAAE,GAAG,CAAC,UAAU,GAAG,KAAK,CAAC,cAAc,CAAC;IAChD,GAAG,CAAC,KAAK,GAAG,KAAK,CAAC;IAClB,GAAG,CAAC,WAAW,GAAG,IAAI,CAAC;IACvB,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;;;;GAOG;AACH,SAAS,cAAc,CAA0B,GAAM;IACrD,SAAS,CAAC,GAAG,CAAC,CAAC;IACf,GAAG,CAAC,KAAK,GAAG,KAAK,CAAC,mBAAmB,CAAC;IACtC,GAAG,CAAC,KAAK,GAAG,KAAK,CAAC,mBAAmB,CAAC;IACtC,GAAG,CAAC,SAAS,GAAG,KAAK,CAAC,YAAY,CAAC;IACnC,GAAG,CAAC,eAAe,GAAG,KAAK,CAAC;IAC5B,GAAG,CAAC,UAAU,GAAG,CAAC,CAAC;IACnB,GAAG,CAAC,WAAW,GAAG,IAAI,CAAC;IACvB,OAAO,GAAG,CAAC;AACb,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,GAAkC;IACpE,IAAI,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,IAAI,CAAC,GAAG,CAAC,MAAM;QAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC;IAElF,iEAAiE;IACjE,sDAAsD;IACtD,MAAM,OAAO,GAAG,GAAG,CAAC,MAAM,KAAK,IAAI,IAAI,GAAG,CAAC,KAAK,KAAK,IAAI,IAAI,GAAG,CAAC,QAAQ,KAAK,IAAI,CAAC;IAEnF,uDAAuD;IACvD,MAAM,cAAc,GAAG,2BAA2B,IAAI,CAAC,OAAO,CAAC;IAC/D,kCAAkC;IAClC,MAAM,OAAO,GAAG,OAAO,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,cAAc,CAAC;IACpD,MAAM,IAAI,GAAG,MAAM,aAAa,CAAC,GAAG,EAAE,cAAc,EAAE,OAAO,CAAC,CAAC;IAE/D,IAAI,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,MAAM,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;QAC/C,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;YACf,6BAA6B;YAC7B,OAAO,CAAC,IAAI,CAAC,iBAAiB,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC;QAC9C,CAAC;QACD,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC;IAC/C,CAAC;IAED,IAAI,OAAsB,CAAC;IAC3B,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;QAChB,OAAO,GAAG,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAC3C,CAAC;SAAM,IAAI,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;QAC3C,yDAAyD;QACzD,qEAAqE;QACrE,sDAAsD;QACtD,MAAM,MAAM,GACV,IAAI,CAAC,WAAW,KAAK,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,oBAAoB,CAAC,CAAC,CAAC,KAAK,CAAC,qBAAqB,CAAC;QACzF,OAAO,GAAG,IAAI,KAAK,CAAC,iBAAiB,CACnC,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,MAAM,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC,EAC/D,IAAI,CAAC,KAAK,EACV,IAAI,CAAC,MAAM,EACX,MAAM,EACN,KAAK,CAAC,gBAAgB,CACvB,CAAC;IACJ,CAAC;SAAM,CAAC;QACN,MAAM,EAAE,GAAG,IAAI,KAAK,CAAC,WAAW,CAAC,IAAI,CAAC,IAAK,EAAE,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,MAAM,EAAE,KAAK,CAAC,UAAU,EAAE,KAAK,CAAC,gBAAgB,CAAC,CAAC;QAChH,IAAI,IAAI,CAAC,QAAQ;YAAE,EAAE,CAAC,QAAQ,CAAC,WAAW,GAAG,IAAI,CAAC;QAClD,OAAO,GAAG,EAAE,CAAC;IACf,CAAC;IACD,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC;IAC3B,MAAM,UAAU,GAAG,OAAO,CAAC,CAAC,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;IAC1E,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;QAChB,UAAU,CAAC,eAAe,GAAG,KAAK,CAAC;QACnC,UAAU,CAAC,SAAS,GAAG,KAAK,CAAC,YAAY,CAAC;IAC5C,CAAC;IACD,iDAAiD;IACjD,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC;AACrD,CAAC"}
+{"version":3,"file":"TextureFactory.js","sourceRoot":"","sources":["../../src/render/TextureFactory.ts"],"names":[],"mappings":"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"}

package/dist/render/lightingPreset.d.ts

@@ -0,0 +1,53 @@
+/**
+ * 光照预设。
+ *
+ * 默认那套（ambient 0.4 / hemi 0.8 / key 1.0 / fill 0.35）是为「线性 PBR 管线」
+ * 调的，亮部线性总量约 2.55。超图官方 iClient3D 走的是完全不同的着色模型
+ * （`S3MTiles/Shaders/S3MTilesFS.js`）：
+ *
+ * ```glsl
+ * const vec3 SunLightColor     = vec3(0.8);
+ * const vec3 AmbientLightColor = vec3(0.7);
+ * return uDiffuseColor.rgb * (SunLightColor * max(dot(n, L), 0.0) + AmbientLightColor * uAmbientColor.rgb);
+ * ```
+ *
+ * 也就是**在 sRGB 数值空间里直接做 Lambert**，因子范围 0.7 ~ 1.5，没有 gamma 编码、
+ * 没有 tonemap。我们在线性空间乘、最后再做 linear→sRGB，同一个中间灰（sRGB 0.5）：
+ *
+ * | | 官方 | 我们（默认） |
+ * |---|---|---|
+ * | 背光 | 0.5 × 0.7 = 0.35 | (0.214 × 0.8)^(1/2.2) ≈ 0.455 |
+ * | 受光 | 0.5 × 1.5 = 0.75 | (0.214 × 2.55)^(1/2.2) ≈ 0.76 |
+ *
+ * 暗部被 gamma 抬亮 30%，动态范围被压到 0.7~1.0，于是「发灰、饱和度低」。
+ *
+ * `'supermap'` 预设把线性光照总量重新压到与官方 sRGB 因子等效的区间：
+ * 0.7^2.2 ≈ 0.46（背光）到 1.5^2.2 ≈ 2.44（受光）。这不是逐像素复刻官方的
+ * sRGB 直乘（那需要放弃 PBR、改 `outputColorSpace = LinearSRGB`），
+ * 而是只动光源、可逆、不碰材质。
+ */
+export type LightingPreset = 'default' | 'supermap';
+export interface PresetLightIntensities {
+    ambientIntensity: number;
+    hemisphereIntensity: number;
+    keyLightIntensity: number;
+    fillLightIntensity: number;
+}
+/** 现有默认值，一字节不改 */
+export declare const DEFAULT_LIGHT_PRESET: PresetLightIntensities;
+/**
+ * 对齐官方观感：几乎只留平行光 + 极低环境光。
+ *
+ * 背光总和 = 0.12 + 0.20 + 0.15 = 0.47（≈ 0.7^2.2）
+ * 受光总和 = 0.47 + 1.95       = 2.42（≈ 1.5^2.2）
+ */
+export declare const SUPERMAP_LIGHT_PRESET: PresetLightIntensities;
+export declare const LIGHT_PRESETS: Record<LightingPreset, PresetLightIntensities>;
+/** 预设名 → 强度组合；未知值回落默认，避免拼错名字把场景变全黑 */
+export declare function resolveLightingPreset(preset?: string | null): PresetLightIntensities;
+/** 线性总辐照度（供测试与调试：受光面 / 背光面） */
+export declare function presetLinearRange(p: PresetLightIntensities): {
+    shadow: number;
+    lit: number;
+};
+//# sourceMappingURL=lightingPreset.d.ts.map

package/dist/render/lightingPreset.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lightingPreset.d.ts","sourceRoot":"","sources":["../../src/render/lightingPreset.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,MAAM,cAAc,GAAG,SAAS,GAAG,UAAU,CAAC;AAEpD,MAAM,WAAW,sBAAsB;IACrC,gBAAgB,EAAE,MAAM,CAAC;IACzB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,kBAAkB,EAAE,MAAM,CAAC;CAC5B;AAED,kBAAkB;AAClB,eAAO,MAAM,oBAAoB,EAAE,sBAKlC,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,EAAE,sBAKnC,CAAC;AAEF,eAAO,MAAM,aAAa,EAAE,MAAM,CAAC,cAAc,EAAE,sBAAsB,CAGxE,CAAC;AAEF,sCAAsC;AACtC,wBAAgB,qBAAqB,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,sBAAsB,CAKpF;AAED,+BAA+B;AAC/B,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,sBAAsB,GAAG;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAG5F"}

package/dist/render/lightingPreset.js

@@ -0,0 +1,36 @@
+/** 现有默认值，一字节不改 */
+export const DEFAULT_LIGHT_PRESET = {
+    ambientIntensity: 0.4,
+    hemisphereIntensity: 0.8,
+    keyLightIntensity: 1.0,
+    fillLightIntensity: 0.35,
+};
+/**
+ * 对齐官方观感：几乎只留平行光 + 极低环境光。
+ *
+ * 背光总和 = 0.12 + 0.20 + 0.15 = 0.47（≈ 0.7^2.2）
+ * 受光总和 = 0.47 + 1.95       = 2.42（≈ 1.5^2.2）
+ */
+export const SUPERMAP_LIGHT_PRESET = {
+    ambientIntensity: 0.12,
+    hemisphereIntensity: 0.2,
+    keyLightIntensity: 1.95,
+    fillLightIntensity: 0.15,
+};
+export const LIGHT_PRESETS = {
+    default: DEFAULT_LIGHT_PRESET,
+    supermap: SUPERMAP_LIGHT_PRESET,
+};
+/** 预设名 → 强度组合；未知值回落默认，避免拼错名字把场景变全黑 */
+export function resolveLightingPreset(preset) {
+    if (preset && Object.prototype.hasOwnProperty.call(LIGHT_PRESETS, preset)) {
+        return LIGHT_PRESETS[preset];
+    }
+    return DEFAULT_LIGHT_PRESET;
+}
+/** 线性总辐照度（供测试与调试：受光面 / 背光面） */
+export function presetLinearRange(p) {
+    const shadow = p.ambientIntensity + p.hemisphereIntensity + p.fillLightIntensity;
+    return { shadow, lit: shadow + p.keyLightIntensity };
+}
+//# sourceMappingURL=lightingPreset.js.map

package/dist/render/lightingPreset.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lightingPreset.js","sourceRoot":"","sources":["../../src/render/lightingPreset.ts"],"names":[],"mappings":"AAqCA,kBAAkB;AAClB,MAAM,CAAC,MAAM,oBAAoB,GAA2B;IAC1D,gBAAgB,EAAE,GAAG;IACrB,mBAAmB,EAAE,GAAG;IACxB,iBAAiB,EAAE,GAAG;IACtB,kBAAkB,EAAE,IAAI;CACzB,CAAC;AAEF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAA2B;IAC3D,gBAAgB,EAAE,IAAI;IACtB,mBAAmB,EAAE,GAAG;IACxB,iBAAiB,EAAE,IAAI;IACvB,kBAAkB,EAAE,IAAI;CACzB,CAAC;AAEF,MAAM,CAAC,MAAM,aAAa,GAAmD;IAC3E,OAAO,EAAE,oBAAoB;IAC7B,QAAQ,EAAE,qBAAqB;CAChC,CAAC;AAEF,sCAAsC;AACtC,MAAM,UAAU,qBAAqB,CAAC,MAAsB;IAC1D,IAAI,MAAM,IAAI,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,aAAa,EAAE,MAAM,CAAC,EAAE,CAAC;QAC1E,OAAO,aAAa,CAAC,MAAwB,CAAC,CAAC;IACjD,CAAC;IACD,OAAO,oBAAoB,CAAC;AAC9B,CAAC;AAED,+BAA+B;AAC/B,MAAM,UAAU,iBAAiB,CAAC,CAAyB;IACzD,MAAM,MAAM,GAAG,CAAC,CAAC,gBAAgB,GAAG,CAAC,CAAC,mBAAmB,GAAG,CAAC,CAAC,kBAAkB,CAAC;IACjF,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,CAAC,iBAAiB,EAAE,CAAC;AACvD,CAAC"}

package/dist/render/materialAlpha.d.ts

@@ -0,0 +1,51 @@
+/**
+ * S3MB 材质透明判定。
+ *
+ * 官方把 alphaMode 定义成三个**小写**枚举（`S3MTiles/Enum/AlphaMode.js`）：
+ * ```
+ * OPAQUE: 'opaque'   BLEND: 'blend'   MASK: 'mask'
+ * ```
+ * 而 S3M 规范文档里写的是 `AM_OPAQUE / AM_BLEND / AM_MASK`。线上数据用的是前者
+ * （`3D-BIMbuilding-2` 的 `WhiteMaterial_1` 就是 `"alphaMode": "blend"`），
+ * 所以两种写法都要认，否则 blend 材质会被当成不透明 —— 表现就是「透明度不见了」。
+ *
+ * 另外还有一条官方没写进规范、但数据里真实存在的透明度来源：**顶点色 alpha**。
+ * SMID 4421 的材质无纹理、`diffuse.a = 1`，顶点色是 u8 `(0,128,192,63)`，
+ * 也就是 alpha ≈ 0.247。官方片元 `outColor = baseColorWithAlpha * uDiffuseColor`
+ * 里 `baseColorWithAlpha = vColor`（vec4），alpha 就靠这条路传下去。
+ */
+export type S3MAlphaMode = 'opaque' | 'blend' | 'mask';
+/** 归一化 alphaMode：兼容小写枚举与规范里的 `AM_` 前缀，未知值一律按不透明处理 */
+export declare function resolveAlphaMode(raw: unknown): S3MAlphaMode;
+export interface MaterialAlphaInput {
+    /** 材质原始 alphaMode（'blend' / 'AM_BLEND' / 'mask' / 'opaque' …） */
+    alphaMode?: unknown;
+    /** 材质 diffuse.a，缺省视为 1 */
+    diffuseAlpha?: number;
+    /** 材质 transparentsorting（配置开启透明度优化时官方也按透明处理） */
+    transparentSorting?: boolean;
+    /** 该几何顶点色 alpha 的最小值：<1 说明有半透明顶点 */
+    vertexAlphaMin?: number;
+    /** 内置水面材质且块里没有像素（我们自己的兜底上色） */
+    isWaterWithoutMap?: boolean;
+}
+/**
+ * 是否走透明（alpha 混合）管线。
+ *
+ * - `blend`：官方 `isTransparent = true`，进 TRANSLUCENT pass；
+ * - `mask`：官方也算透明，但它是**镂空**语义（alphaTest）。我们保持不透明队列 +
+ *   alphaTest，否则树叶/栏杆之间会因 `depthWrite: false` 互相穿透；
+ * - 顶点色 alpha < 1：4421 这类"材质不透明但顶点半透明"的数据必须走混合。
+ */
+export declare function isTransparentMaterial(input: MaterialAlphaInput): boolean;
+/**
+ * 顶点色 alpha 的最小值：材质要不要开混合，取决于这块几何里有没有半透明顶点。
+ *
+ * 顶点数在几千到几万量级，一次线性扫描即可；只在建材质时算一次（每个 primitive 一次）。
+ * 没有 alpha 分量（老数据的 RGB）按 1 处理 —— 不能因为读不到就当成 0，那会整片全透明。
+ */
+export declare function minVertexAlpha(color: {
+    array: ArrayLike<number>;
+    components?: number;
+} | undefined): number;
+//# sourceMappingURL=materialAlpha.d.ts.map

package/dist/render/materialAlpha.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"materialAlpha.d.ts","sourceRoot":"","sources":["../../src/render/materialAlpha.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,OAAO,GAAG,MAAM,CAAC;AAEvD,qDAAqD;AACrD,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,OAAO,GAAG,YAAY,CAG3D;AAED,MAAM,WAAW,kBAAkB;IACjC,iEAAiE;IACjE,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,0BAA0B;IAC1B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,gDAAgD;IAChD,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,oCAAoC;IACpC,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,+BAA+B;IAC/B,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,kBAAkB,GAAG,OAAO,CASxE;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE;IAAE,KAAK,EAAE,SAAS,CAAC,MAAM,CAAC,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,GAAG,MAAM,CAW3G"}

package/dist/render/materialAlpha.js

@@ -0,0 +1,68 @@
+/**
+ * S3MB 材质透明判定。
+ *
+ * 官方把 alphaMode 定义成三个**小写**枚举（`S3MTiles/Enum/AlphaMode.js`）：
+ * ```
+ * OPAQUE: 'opaque'   BLEND: 'blend'   MASK: 'mask'
+ * ```
+ * 而 S3M 规范文档里写的是 `AM_OPAQUE / AM_BLEND / AM_MASK`。线上数据用的是前者
+ * （`3D-BIMbuilding-2` 的 `WhiteMaterial_1` 就是 `"alphaMode": "blend"`），
+ * 所以两种写法都要认，否则 blend 材质会被当成不透明 —— 表现就是「透明度不见了」。
+ *
+ * 另外还有一条官方没写进规范、但数据里真实存在的透明度来源：**顶点色 alpha**。
+ * SMID 4421 的材质无纹理、`diffuse.a = 1`，顶点色是 u8 `(0,128,192,63)`，
+ * 也就是 alpha ≈ 0.247。官方片元 `outColor = baseColorWithAlpha * uDiffuseColor`
+ * 里 `baseColorWithAlpha = vColor`（vec4），alpha 就靠这条路传下去。
+ */
+/** 归一化 alphaMode：兼容小写枚举与规范里的 `AM_` 前缀，未知值一律按不透明处理 */
+export function resolveAlphaMode(raw) {
+    const s = String(raw ?? '').trim().toLowerCase().replace(/^am_/, '');
+    return s === 'blend' || s === 'mask' ? s : 'opaque';
+}
+/**
+ * 是否走透明（alpha 混合）管线。
+ *
+ * - `blend`：官方 `isTransparent = true`，进 TRANSLUCENT pass；
+ * - `mask`：官方也算透明，但它是**镂空**语义（alphaTest）。我们保持不透明队列 +
+ *   alphaTest，否则树叶/栏杆之间会因 `depthWrite: false` 互相穿透；
+ * - 顶点色 alpha < 1：4421 这类"材质不透明但顶点半透明"的数据必须走混合。
+ */
+export function isTransparentMaterial(input) {
+    const mode = resolveAlphaMode(input.alphaMode);
+    if (mode === 'blend')
+        return true;
+    if (mode === 'mask')
+        return false;
+    if (input.transparentSorting === true)
+        return true;
+    if (input.isWaterWithoutMap === true)
+        return true;
+    if ((input.diffuseAlpha ?? 1) < 0.999)
+        return true;
+    if ((input.vertexAlphaMin ?? 1) < 0.999)
+        return true;
+    return false;
+}
+/**
+ * 顶点色 alpha 的最小值：材质要不要开混合，取决于这块几何里有没有半透明顶点。
+ *
+ * 顶点数在几千到几万量级，一次线性扫描即可；只在建材质时算一次（每个 primitive 一次）。
+ * 没有 alpha 分量（老数据的 RGB）按 1 处理 —— 不能因为读不到就当成 0，那会整片全透明。
+ */
+export function minVertexAlpha(color) {
+    if (!color || !color.array || color.array.length === 0)
+        return 1;
+    const comp = color.components ?? 4;
+    if (comp < 4)
+        return 1;
+    let min = 1;
+    for (let i = 3; i < color.array.length; i += comp) {
+        const a = color.array[i];
+        if (a < min)
+            min = a;
+        if (min <= 0.999)
+            return min; // 已经确定要透明，提前退出
+    }
+    return min;
+}
+//# sourceMappingURL=materialAlpha.js.map

package/dist/render/materialAlpha.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"materialAlpha.js","sourceRoot":"","sources":["../../src/render/materialAlpha.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAIH,qDAAqD;AACrD,MAAM,UAAU,gBAAgB,CAAC,GAAY;IAC3C,MAAM,CAAC,GAAG,MAAM,CAAC,GAAG,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IACrE,OAAO,CAAC,KAAK,OAAO,IAAI,CAAC,KAAK,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC;AACtD,CAAC;AAeD;;;;;;;GAOG;AACH,MAAM,UAAU,qBAAqB,CAAC,KAAyB;IAC7D,MAAM,IAAI,GAAG,gBAAgB,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;IAC/C,IAAI,IAAI,KAAK,OAAO;QAAE,OAAO,IAAI,CAAC;IAClC,IAAI,IAAI,KAAK,MAAM;QAAE,OAAO,KAAK,CAAC;IAClC,IAAI,KAAK,CAAC,kBAAkB,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IACnD,IAAI,KAAK,CAAC,iBAAiB,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAClD,IAAI,CAAC,KAAK,CAAC,YAAY,IAAI,CAAC,CAAC,GAAG,KAAK;QAAE,OAAO,IAAI,CAAC;IACnD,IAAI,CAAC,KAAK,CAAC,cAAc,IAAI,CAAC,CAAC,GAAG,KAAK;QAAE,OAAO,IAAI,CAAC;IACrD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,KAAoE;IACjG,IAAI,CAAC,KAAK,IAAI,CAAC,KAAK,CAAC,KAAK,IAAI,KAAK,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,CAAC,CAAC;IACjE,MAAM,IAAI,GAAG,KAAK,CAAC,UAAU,IAAI,CAAC,CAAC;IACnC,IAAI,IAAI,GAAG,CAAC;QAAE,OAAO,CAAC,CAAC;IACvB,IAAI,GAAG,GAAG,CAAC,CAAC;IACZ,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC,IAAI,IAAI,EAAE,CAAC;QAClD,MAAM,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,CAAE,CAAC;QAC1B,IAAI,CAAC,GAAG,GAAG;YAAE,GAAG,GAAG,CAAC,CAAC;QACrB,IAAI,GAAG,IAAI,KAAK;YAAE,OAAO,GAAG,CAAC,CAAC,eAAe;IAC/C,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/render/viewer/EdgeDecorator.d.ts

@@ -0,0 +1,206 @@
+/**
+ * 棱线装饰：折边线 / 外推 / 背面外扩轮廓 / GPU 后处理描边。
+ *
+ * 从 `S3MViewer` 整体搬出来的最大一块。它只碰 `mesh.userData`（`edges` / `edgeHull` /
+ * `nativeEdges`）与共享 uniform，不碰拾取表、不碰瓦片生命周期 —— 所以能独立成模块。
+ *
+ * ## 为什么外观 uniform 要共享
+ *
+ * 棱线材质必须**逐网格一份**（各绑各的单体状态纹理），但外观（颜色 / 粗细 / 透明度 /
+ * 外推距离）必须全局统一。做法是外观 uniform 用同一批对象，`syncStyle()` 改一次全部生效，
+ * 棱线淡入淡出也只改一个 `uEdgeFade` —— 新建瓦片自动继承当前进度。
+ *
+ * ## 三种画法的成本
+ *
+ * - `line` / `offset`：CPU 现算 EdgesGeometry，按 8ms 一帧切片建，几十万面不会卡死；
+ * - `hull`：不建几何，把同一块网格沿法线外扩再画一遍，只画背面；
+ * - `gpu`：零几何、零额外 pass 的片元描边，线宽约 1 像素。
+ */
+import * as THREE from 'three';
+import type { Animator, TransitionOptions } from '../../anim/Animator.js';
+import type { AuthenticateFn } from '../../core/AuthFetch.js';
+import type { StyleUniforms } from '../../core/types.js';
+import { type EdgeModes, type EdgesOption } from '../StyleMaterial.js';
+import { type LineSharedUniforms, type ThickLineMaterial } from '../EdgeLines.js';
+import { GpuEdgePass } from '../GpuEdgePass.js';
+import type { S3MDatasetEntry } from '../DatasetManager.js';
+/** 宿主需要提供的东西。只列真正用到的，避免模块偷偷依赖整只 viewer */
+export interface EdgeHost {
+    readonly uniforms: StyleUniforms;
+    /** 当前**显示**的样式（动画推进中会逐帧变） */
+    readonly style: {
+        edges: EdgesOption;
+        forceCpuEdges?: boolean;
+        edgeColor: string;
+        edgeWidth?: number;
+        edgeOpacity?: number;
+        edgeOffset?: number;
+        edgeHullWidth?: number;
+        edgeThreshold?: number;
+        opacity?: number;
+    };
+    /** 用户想要的样式（`setEdges` 要同步写回，`getStyle()` 才拿得到） */
+    readonly styleTarget: {
+        edges: EdgesOption;
+    };
+    readonly animator: Animator;
+    readonly pickables: Map<number, {
+        mesh: THREE.Mesh;
+    }>;
+    scene: THREE.Scene | null;
+    renderer: THREE.WebGLRenderer | null;
+    camera: THREE.Camera | null;
+    readonly authenticate: AuthenticateFn | undefined;
+    requestRepaint(): void;
+}
+export declare class EdgeDecorator {
+    private readonly host;
+    /** 等宽线共享的分辨率 uniform（全局棱线 + 选中棱线共用） */
+    readonly lineShared: LineSharedUniforms;
+    /** 全局棱线材质（外观 uniform 的持有者，逐网格棱线材质共享它的对象） */
+    readonly edgeMaterial: ThickLineMaterial;
+    /** 选中棱线材质（同上，选中棱线的逐网格材质共享它的对象） */
+    readonly selectionEdgeMaterial: ThickLineMaterial;
+    private readonly _edgeStyleUniforms;
+    private readonly _selEdgeStyleUniforms;
+    private readonly _hullStyleUniforms;
+    private _enabled;
+    private _modes;
+    /** 预制棱线缓存（Crease Cache）：外部载入的全局统一 LineSegments */
+    private _creaseLines;
+    /** 数据自带的棱线对象：改颜色时只刷这些，不再全场景 traverse */
+    private readonly _nativeLines;
+    /** GPU 描边后处理（深度 + 法线），只在 edges 含 'gpu' 时按帧执行 */
+    private _gpuEdge;
+    /** 给 GPU 描边传色用的临时 Color，避免每帧 new */
+    private readonly _gpuEdgeColor;
+    constructor(host: EdgeHost);
+    /** 当前是否开启棱线 */
+    get enabled(): boolean;
+    /** 当前生效的画法 */
+    get modes(): EdgeModes;
+    /** 数据自带棱线包在当前画法下还算不算数 */
+    useNativeEdges(hasNative: boolean): boolean;
+    /** 登记数据自带的棱线（注册瓦片时调） */
+    registerNativeLine(lines: THREE.LineSegments, visible: boolean): void;
+    /** 注销数据自带的棱线（瓦片淘汰时调） */
+    unregisterNativeLine(lines: THREE.LineSegments): void;
+    /** 新瓦片是否要自动补棱线装饰（受全局开关 / 数据集开关 / 关键字跳过三道控制） */
+    autoDecorate(mesh: THREE.Mesh, entry: S3MDatasetEntry, hasNativeEdges: boolean): void;
+    /** 释放全部装饰与后处理资源（unmount 时调） */
+    disposeAll(): void;
+    /** @internal GPU 描边实例，单测会替换成假对象观察 dispose */
+    get gpuEdge(): GpuEdgePass | null;
+    set gpuEdge(v: GpuEdgePass | null);
+    /** GPU 描边资源单独释放（换上下文时调，下一帧按需重建） */
+    disposeGpuEdge(): void;
+    /** 一帧的 GPU 描边，必须画在主场景之后（依赖本帧已写好的深度） */
+    renderGpuEdges(canvas: HTMLCanvasElement): void;
+    /** 建逐网格棱线材质；`selection` 为真时用选中棱线那套外观 uniform */
+    createPerMeshEdgeMaterial(mesh: THREE.Mesh, selection?: boolean): ThickLineMaterial;
+    /**
+     * 全局棱线开关。
+     *
+     * 取值是 `boolean | EdgeStyle | EdgeStyle[]`（见 resolveEdgeModes）：
+     *   - `true` / `'line'`   折边线（旧口径）
+     *   - `'offset'`          折边线 + 沿边法线外推 `edgeOffset` 米
+     *   - `'hull'`            背面外扩轮廓（选中侧 outlineStyle:'hull' 的整场景版）
+     *   - `'gpu'`             纯片元描边：零几何、零额外 pass，线宽约 1 像素
+     *   - 数组                叠加，例如 `['line', 'hull']`
+     *
+     * 数据自带棱线包（primitiveType 13）时直接用，成本为零；`style.forceCpuEdges`
+     * 可以无视它，改由 CPU 现算 —— 那是 CPU 端的活，几十万面一次性建会卡住主线程
+     * （实测 20 个网格 1.9s），所以按 8ms 一帧切片，边建边出。
+     *
+     * 棱线本身用「屏幕空间等宽线」画（见 EdgeLines.ts）：WebGL 的 lineWidth 基本无效，
+     * 只有摊成面向屏幕的四边形，`edgeWidth` 才能真正调粗。
+     *
+     * 带 `transition` 时做「淡入 / 淡出」，**不对几何做插值**（几何没法插值）：
+     * 开：立刻置位 + 开始分片建线，同时 `uEdgeFade` 0→1 —— 建好一块亮一块，视觉上是渐显；
+     * 关：`uEdgeFade` 1→0，淡完才 dispose，避免棱线「啪」一下消失。
+     */
+    setEdges(edges: EdgesOption, transition?: TransitionOptions): void;
+    /** 直接写棱线淡入乘子（不走动画通道） */
+    private _setEdgeFade;
+    /** 释放所有现算棱线几何 */
+    private _disposeEdges;
+    /**
+     * 挂载预制棱线缓存（Crease Cache）。
+     *
+     * 直接把 `source-creases.f32` 这类 Float32Array 缓冲载入为一组全局统一的
+     * LineSegments —— 相比逐 Mesh 现算 EdgesGeometry，性能高一个量级，视觉也最干净。
+     * 坐标按「场景本地坐标」（相对场景锚点的米）处理，与瓦片几何同一坐标系。
+     *
+     * @param url  棱线缓存地址（二进制 Float32 序列：x,y,z,x,y,z,… 成对成段）
+     */
+    loadCreases(url: string): Promise<void>;
+    /** 移除并释放预制棱线缓存 */
+    clearCreases(): void;
+    /**
+     * 让全局棱线材质跟上 style.edgeColor / edgeWidth / edgeOpacity / edgeOffset。
+     *
+     * 全程 O(1)：只有一份共享 edgeMaterial（所有逐 mesh 棱线都用它）+ 一份预制缓存
+     * + 一批共享外观对象的轮廓壳，所以棱线淡入淡出只要改一个 uniform，
+     * 新建瓦片自动继承当前进度。
+     */
+    private _syncEdgeStyle;
+    /** 让数据自带的棱线跟着 style.edgeColor / opacity 走（这些是 LineBasicMaterial，改不了粗细） */
+    private _styleEdgeLine;
+    /**
+     * 刷新所有棱线外观。
+     *
+     * 数据自带的棱线是逐对象的 LineBasicMaterial，改颜色只能一个个写；但原来每次都要
+     * 遍历整个数据集树（几千个节点），颜色动画逐帧跑就是灾难。改成只刷注册时收集好的
+     * 那批 LineSegments，复杂度降到 O(棱线条数)。
+     */
+    private _refreshEdgeLines;
+    /** 地形 / 绿地 / 道路 / 地面铺装等不参与自动描边（数据自带棱线包另说） */
+    /** 数据集级别的棱线开关：enableEdges 优先，否则跟随全局 style.edges */
+    private _datasetEdgesEnabled;
+    /** 该 mesh 是否命中「跳过自动描边」的关键字（skeletonName / 数据集名） */
+    private _shouldSkipAutoEdges;
+    /**
+     * 这块网格还缺哪种棱线装饰（缺就建，齐了就不动）。
+     *
+     * setEdges 的分片建线靠它筛「还没建完的」，注册新瓦片也靠它决定要不要动手。
+     */
+    private _needsEdgeDecoration;
+    /** 按当前画法补齐这块网格的棱线装饰 */
+    private _ensureEdgeDecoration;
+    private _ensureEdges;
+    /**
+     * 给一块网格挂「背面外扩轮廓」（整场景版）。
+     *
+     * 复用选中侧那套 `createOutlineMaterial`：顶点沿法线鼓 `edgeHullWidth` 米、只画背面，
+     * 于是被本体挡住的部分不显示，露出来的那圈就是描边。与折边线的差别在于——
+     * 这里**不建任何新几何**，成本只是把同一块网格多画一遍，折边判定那套 CPU 活全省了。
+     *
+     * 实例化几何拿不到逐实例变换（轮廓壳是 mesh 的子节点，不吃 instanceMatrix），
+     * 直接跳过：宁可这栋没描边，也不要所有实例的壳叠在原点。
+     */
+    private _ensureHull;
+    /**
+     * 给一块网格造专属的棱线材质。
+     *
+     * 棱线材质必须逐网格一份，因为它要绑定**这个网格**的单体状态纹理；但外观
+     * （颜色 / 粗细 / 透明度）必须全局统一——所以外观 uniform 直接复用
+     * `_edgeStyleUniforms` 里的对象，`_syncEdgeStyle()` 改一次全部生效，
+     * program 也因为着色器相同而只编译一次。
+     */
+    /** 选中棱线的逐网格材质，道理同上 */
+    private _createSelectionEdgeMaterial;
+    private _removeEdges;
+    /** 让全局棱线材质跟上当前 style（颜色 / 粗细 / 透明度 / 外推距离），O(1) */
+    syncStyle(): void;
+    /** 刷新所有棱线外观：共享材质 + 数据自带的那批 LineSegments */
+    refreshLines(): void;
+    /** 释放所有现算棱线几何（临界角 / 画法变了要重建，见 setEdges） */
+    disposeEdgeGeometry(): void;
+    /** @internal 给一块网格补折边线（单测直接调，观察顶点焊合 / 临界角） */
+    ensureEdges(mesh: THREE.Mesh): void;
+    /** 拆掉一块网格的棱线与外扩壳（瓦片淘汰时调） */
+    removeEdges(mesh: THREE.Mesh): void;
+    /** 选中棱线的逐网格材质 */
+    createSelectionEdgeMaterial(mesh: THREE.Mesh): ThickLineMaterial;
+}
+//# sourceMappingURL=EdgeDecorator.d.ts.map

package/dist/render/viewer/EdgeDecorator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EdgeDecorator.d.ts","sourceRoot":"","sources":["../../../src/render/viewer/EdgeDecorator.ts"],"names":[],"mappings":"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"}