s3m-three 0.4.18 → 0.4.19

package/src/render/TextureFactory.ts

@@ -31,6 +31,16 @@ export function setMaxAnisotropy(n: number, cap = Infinity): void {
   anisotropyCap = Number.isFinite(cap) && cap > 0 ? Math.max(1, cap) : Infinity;
 }
 
+/**
+ * 单独调各向异性上限（只影响之后创建的纹理）。
+ * supermap 预设会设成 1 —— 官方 iClient3D 不开各向异性，斜视角直接采高 mip
+ * 平均成纯色；我们默认拉满（Infinity）是为了倾斜摄影立面清晰度，代价是
+ * 米制平铺纹理的远处高频纹（点阵/砖缝）被硬保下来，怎么调光照都"不像官方"。
+ */
+export function setAnisotropyCap(cap: number): void {
+  anisotropyCap = Number.isFinite(cap) && cap > 0 ? Math.max(1, cap) : Infinity;
+}
+
 /**
  * 纹理长边像素上限（默认 Infinity = 不限制）。
  * 只作用于非图集的 RGBA / WebP 产物，见 `core/TextureDecode.ts` 的 `maxSize`。
@@ -86,6 +96,24 @@ async function decodeTexture(
   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: boolean): void {
+  srgbTextureDecode = v;
+}
+
+export function getSrgbTextureDecode(): boolean {
+  return srgbTextureDecode;
+}
+
 function configure<T extends THREE.Texture>(tex: T, srgb = true): T {
   tex.wrapS = THREE.RepeatWrapping;
   tex.wrapT = THREE.RepeatWrapping;
@@ -94,7 +122,7 @@ function configure<T extends THREE.Texture>(tex: T, srgb = true): T {
   tex.generateMipmaps = true;
   // 各向异性过滤对斜视角立面清晰度的提升比提高分辨率更直接
   tex.anisotropy = anisotropyCap === Infinity ? maxAnisotropy : Math.min(maxAnisotropy, anisotropyCap);
-  if (srgb) tex.colorSpace = THREE.SRGBColorSpace;
+  if (srgb && srgbTextureDecode) tex.colorSpace = THREE.SRGBColorSpace;
   tex.flipY = false;
   tex.needsUpdate = true;
   return tex;
@@ -145,12 +173,16 @@ export async function createTexture(tex: S3MTexture | null | undefined): Promise
     texture = new THREE.Texture(data.bitmap);
   } 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.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,
@@ -165,7 +197,9 @@ export async function createTexture(tex: S3MTexture | null | undefined): Promise
   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/src/render/lightingPreset.ts

@@ -0,0 +1,76 @@
+/**
+ * 光照预设。
+ *
+ * 默认那套（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 const DEFAULT_LIGHT_PRESET: PresetLightIntensities = {
+  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: PresetLightIntensities = {
+  ambientIntensity: 0.12,
+  hemisphereIntensity: 0.2,
+  keyLightIntensity: 1.95,
+  fillLightIntensity: 0.15,
+};
+
+export const LIGHT_PRESETS: Record<LightingPreset, PresetLightIntensities> = {
+  default: DEFAULT_LIGHT_PRESET,
+  supermap: SUPERMAP_LIGHT_PRESET,
+};
+
+/** 预设名 → 强度组合；未知值回落默认，避免拼错名字把场景变全黑 */
+export function resolveLightingPreset(preset?: string | null): PresetLightIntensities {
+  if (preset && Object.prototype.hasOwnProperty.call(LIGHT_PRESETS, preset)) {
+    return LIGHT_PRESETS[preset as LightingPreset];
+  }
+  return DEFAULT_LIGHT_PRESET;
+}
+
+/** 线性总辐照度（供测试与调试：受光面 / 背光面） */
+export function presetLinearRange(p: PresetLightIntensities): { shadow: number; lit: number } {
+  const shadow = p.ambientIntensity + p.hemisphereIntensity + p.fillLightIntensity;
+  return { shadow, lit: shadow + p.keyLightIntensity };
+}

package/src/render/materialAlpha.ts

@@ -0,0 +1,75 @@
+/**
+ * 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 function resolveAlphaMode(raw: unknown): S3MAlphaMode {
+  const s = String(raw ?? '').trim().toLowerCase().replace(/^am_/, '');
+  return s === 'blend' || s === 'mask' ? s : 'opaque';
+}
+
+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 function isTransparentMaterial(input: MaterialAlphaInput): boolean {
+  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: { array: ArrayLike<number>; components?: number } | undefined): number {
+  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;
+}

package/src/tileset/S3MTileset.ts

@@ -7,6 +7,9 @@
  *   命中阈值就请求 childTile，实现渐进式细化。
  */
 import { parseS3MB } from '../core/S3MBParser.js';
+import { planDegradations } from '../core/degradations.js';
+import { splatLodDecision } from '../core/SplatLod.js';
+import type { UnsupportedPolicy } from '../core/degradations.js';
 import { authFetch, type AuthenticateFn } from '../core/AuthFetch.js';
 import { getSharedS3MWorker, S3MWorkerClient, WorkerDeadError } from '../worker/S3MWorkerClient.js';
 import {
@@ -219,6 +222,14 @@ export interface TileNode {
   parentUrl?: string;
   /** 当前帧是否满足细化条件 */
   needRefine?: boolean;
+  /**
+   * 该瓦片高斯的最长轴中位长度（米）。非泼溅瓦片为 undefined。
+   * 有值时细化判据改走 core/SplatLod.ts —— 点云的各层 σ 恒定，
+   * 包围球像素误差那套判据对它无效（见该文件头部）。
+   */
+  splatSigma?: number;
+  /** 该瓦片的高斯实例数（泼溅瓦片才有） */
+  splatCount?: number;
   /** 该瓦片引用的纹理 key 清单，用于引用计数与显存释放 */
   textureKeys?: string[];
   /** 瓦片构建产生的统计信息，用于淘汰时准确扣减 stats */
@@ -233,6 +244,8 @@ export type BuildTileFn = (
     uniforms: StyleUniforms | null;
     /** Worker 侧已完成的纯数据几何组装（经典 .s3mb 路径），构建器直接包装成 three 对象 */
     assembled?: TileGeometryData;
+    /** 深度偏移配置（透传给 buildTileObjects），见 BuildTileOptions.polygonOffset */
+    polygonOffset?: { factor: number; units: number };
   }
 ) => Promise<{ group: Group; stats: Partial<Stats> }>;
 
@@ -243,6 +256,8 @@ export interface S3MTilesetOptions {
   /** 原始图像/子图集缓存上限（LRU），默认 128 */
   maxImageCache?: number;
   buildTile?: BuildTileFn | null;
+  /** 三角面材质深度偏移（共面摩尔纹 / 重合面归属），透传给 buildTileObjects */
+  polygonOffset?: { factor: number; units: number };
   /**
    * 是否用 Web Worker 解析经典 `.s3mb` 瓦片（默认开）。
    *
@@ -287,6 +302,17 @@ export interface S3MTilesetOptions {
    * 子图集）发出前过一遍，可改写 URL（加 `?token=`）或附加请求头。见 `AuthenticateFn`。
    */
   authenticate?: AuthenticateFn;
+  /**
+   * 遇到「解析得了但画不出该有的样子」的数据时怎么办。**默认 `'warn'`**。
+   *
+   * 目前只有一类：3DGS 数据按点渲染（`gsScale` / `gsRotation` 的量化格式未标定）。
+   *   'warn'   —— 首次遇到告警一次，照常出图。旧版没有这个开关，但也不告警，
+   *               所以这里的差异只有多一条日志，不传参时的渲染路径逐字未变。
+   *   'throw'  —— 直接拒绝这类瓦片（标 `permanent`，不重试）。给「宁可不显示，
+   *               也不要显示一个看不出是错的画面」的场景。
+   *   'silent' —— 只记录到 `stats.degradations`，由 UI 自己决定怎么提示。
+   */
+  unsupported?: UnsupportedPolicy;
 }
 
 export class S3MTileset {
@@ -341,6 +367,7 @@ export class S3MTileset {
     programs: 0,
     textures: 0,
     geometries: 0,
+    degradations: [],
   };
 
   maxConcurrent: number;
@@ -368,6 +395,8 @@ export class S3MTileset {
   private readonly _maxRetries: number;
   /** 鉴权适配函数；undefined = 不做任何改写（行为与旧版一致） */
   readonly authenticate: AuthenticateFn | undefined;
+  /** 能力降级的处置策略，默认 'warn'，见 `S3MTilesetOptions.unsupported` */
+  private readonly _unsupported: UnsupportedPolicy;
   /** 失败重试计数与下次可用时间，退避期间 _enqueue 会直接跳过 */
   private readonly _retryCount = new Map<string, number>();
   private readonly _retryAt = new Map<string, number>();
@@ -382,6 +411,7 @@ export class S3MTileset {
   /** 本数据集是 S3M 1.x（SuperMapCache，.s3m）：子瓦地址规则与 3.x 不同 */
   private isS3MV1 = false;
   private _buildTile: BuildTileFn | null;
+  private readonly _polygonOffset: { factor: number; units: number } | undefined;
   private readonly _uniforms: StyleUniforms | null;
   /** 经典 .s3mb 的 Worker 解析客户端；undefined = 尚未尝试创建，null = 不可用/已降级 */
   private _workerClient: S3MWorkerClient | null | undefined;  private readonly _useWorker: boolean;
@@ -397,9 +427,11 @@ export class S3MTileset {
     this._onProgress = options.onProgress ?? (() => {});
     this._maxRetries = Math.max(0, options.maxRetries ?? 2);
     this.authenticate = options.authenticate;
+    this._unsupported = options.unsupported ?? 'warn';
 
     // 渲染层可注入：Node 环境下不需要 three，也能跑 URL / 解析链路
     this._buildTile = options.buildTile ?? null;
+    this._polygonOffset = options.polygonOffset;
     // 着色器共享 uniform，由 S3MLayer 持有并传进来
     this._uniforms = options.uniforms ?? null;
     this._useWorker = options.useWorker !== false;
@@ -1039,6 +1071,23 @@ export class S3MTileset {
     return;
   }
 
+  /**
+   * 处置一块瓦片的降级项。
+   *
+   * 位置很讲究：必须在 `build` 之前。`'throw'` 策略下要在浪费一次几何组装
+   * （几十万面的解交错 + 合批）之前就拒绝，否则「拒绝」本身也成了开销。
+   *
+   * 抛出的错带 `permanent`，由 `_load` 的 catch 识别 → 不重试、直接进 failed。
+   */
+  private _noteDegradations(tile: ParsedTile): void {
+    const incoming = tile.degradations;
+    if (!incoming?.length) return;
+    const plan = planDegradations(incoming, this.stats.degradations, this._unsupported);
+    this.stats.degradations = plan.known;
+    for (const msg of plan.messages) console.warn(msg);
+    if (plan.error) throw plan.error;
+  }
+
   private async _load(url: string): Promise<void> {
     if (this.nodes.has(url) || this.pending.has(url) || this.failed.has(url)) return;
     this.pending.add(url);
@@ -1088,11 +1137,15 @@ export class S3MTileset {
         await this._upgradeAtlasLod(tile, baseUrl);
       }
 
+      // 解析成功但能力不完整的（目前只有 3DGS），在花力气建几何之前先决定处置
+      this._noteDegradations(tile);
+
       const build = await this._builder();
       const buildRes = await build(tile, {
         textureCache: this.textureCache,
         uniforms: this._uniforms,
         assembled,
+        polygonOffset: this._polygonOffset,
       });
       const { group, stats } = buildRes;
       const texKeys = (buildRes as any).textureKeys ?? (group.userData?.textureKeys as string[] | undefined) ?? Object.keys(tile.textures ?? {});
@@ -1130,6 +1183,8 @@ export class S3MTileset {
         childUrls,
         parentUrl: this._parentOf.get(url),
         state: 'ready',
+        ...(stats.splatSigma ? { splatSigma: stats.splatSigma } : {}),
+        ...(stats.splatCount ? { splatCount: stats.splatCount } : {}),
         stats: {
           meshes: stats.meshes ?? 0,
           vertices: stats.vertices ?? 0,
@@ -1242,7 +1297,29 @@ export class S3MTileset {
       const childUrls = node.childUrls ?? (node.childUrl ? [node.childUrl] : []);
       // 加入 8% 迟滞区间（Hysteresis Band），防止相机在 LOD 临界距离处发生父子瓦片逐帧来回横跳闪烁
       const hFactor = node.needRefine ? (byDistance ? 1.08 : 0.92) : 1.0;
-      const needRefine = childUrls.length > 0 && (byDistance ? metric < threshold * hFactor : metric > threshold * hFactor);
+
+      // 泼溅 / 点云瓦片走另一套判据：每层 σ 是同一个物理量、只有点数在涨，包围球
+      // 像素误差对它没有含义 —— 按上面那套算，metric 在任何距离都远大于阈值，等于
+      // 「永远细化到叶子」。
+      // 判据换成**屏幕上的高斯尺寸**（3σ 超过 SPLAT_REFINE_PX 就细化），见 core/SplatLod.ts。
+      // 别用覆盖率：主体那块根瓦片 32 万高斯、σ=13.5cm，覆盖率一上来就是 51，
+      // 当场停止细化，最后只画了总量 2.3% 的高斯 —— 柱子就是这么被糊掉的。
+      const splat =
+        node.splatSigma && node.sphere
+          ? splatLodDecision({
+              splats: node.splatCount ?? node.stats?.vertices ?? 0,
+              radius: node.sphere.radius,
+              distance: dist,
+              sigma: node.splatSigma,
+              screenHeight,
+              hasChild: childUrls.length > 0,
+            })
+          : null;
+
+      const needRefine = splat
+        ? splat.needRefine
+        : childUrls.length > 0 &&
+          (byDistance ? metric < threshold * hFactor : metric > threshold * hFactor);
       node.needRefine = needRefine;
 
       const dbgSeen = ((globalThis as { __S3M_LOD_SEEN?: Set<string> }).__S3M_LOD_SEEN ??= new Set<string>());

package/src/vendor/browser-node-stub.js

@@ -0,0 +1,10 @@
+/**
+ * 浏览器构建（iife）的 node 内建模块占位。
+ *
+ * vendor 里的 emscripten 解码器（draco / crunch）带 Node 环境分支：
+ * `if (ENVIRONMENT_IS_NODE) { fs = require('node:fs'); ... }`——浏览器里
+ * 这个分支永远不执行，这里只需要让解析器有个落点、消除
+ * 「Module "node:fs" has been externalized for browser compatibility」告警。
+ * Node 环境不走这份 iife 产物（走 tsc 的 ESM 产物），不受影响。
+ */
+export default {};