s3m-three 0.4.26 → 0.4.28

package/src/tileset/S3MTileset.ts

@@ -32,6 +32,7 @@ import type {
 } from '../core/S3MBlockParser.js';
 import type { Anchor, ParsedTile, Stats, StyleUniforms } from '../core/types.js';
 import type { TileGeometryData } from '../core/TileGeometry.js';
+import { AUTO_BAKE_RADIUS_THRESHOLD } from '../core/BakeMercator.js';
 import type { TextureCreateOptions } from '../render/TextureFactory.js';
 import type { Group, Texture } from 'three';
 
@@ -304,10 +305,14 @@ export type BuildTileFn = (
     colorPipeline?: 'linear' | 'direct';
     /** 纹理创建参数（透传给 buildTileObjects → createTexture） */
     textureOptions?: TextureCreateOptions;
+  bakeMercator?: boolean;
+    tileAnchor?: { lon: number; lat: number; height?: number };
+    tileCenter?: { x: number; y: number; z?: number };
   }
 ) => Promise<{ group: Group; stats: Partial<Stats> }>;
 
 export interface S3MTilesetOptions {
+  bakeMercator?: boolean;
   configUrl: string;
   maxTiles?: number;
   maxConcurrent?: number;
@@ -388,6 +393,18 @@ export interface S3MTilesetOptions {
    *   'silent' —— 只记录到 `stats.degradations`，由 UI 自己决定怎么提示。
    */
   unsupported?: UnsupportedPolicy;
+  /**
+   * LOD 细化过渡策略：
+   * - 'binary'（默认）：整节点二值切换。所有子瓦片全部就绪或失败后，父瓦片整块隐藏、子瓦片整块接替。
+   * - 'incremental'：增量细化（primary / fallback 双列表 + LEQUAL 深度推移）。
+   *   子瓦片就绪一个显示一个，未就绪区域由父级（fallback）兜底填充，消除整块跳变与慢 child 阻塞。
+   */
+  lodTransition?: 'binary' | 'incremental';
+  /**
+   * 增量细化模式下 fallback 兜底瓦片的材质深度偏移系数。
+   * 默认 { factor: 1, units: 2 }，通过向远处推移深度配合 gl.LEQUAL 消除共面 z-fighting。
+   */
+  fallbackOffset?: { factor?: number; units?: number };
 }
 
 /** 估算单个纹理占用的显存字节数 */
@@ -505,6 +522,10 @@ export class S3MTileset {
    */
   maxMemory: number;
   lodRangeScale: number;
+  lodTransition: 'binary' | 'incremental';
+  fallbackOffset: { factor: number; units: number };
+  readonly primaryNodes = new Set<string>();
+  readonly fallbackNodes = new Set<string>();
 
   /** 数据集配置声明的高度范围（米），若配置未声明则返回 null */
   get heightRange(): { min: number; max: number } | null {
@@ -535,8 +556,16 @@ export class S3MTileset {
   /** 请求量的硬上限（软上限 maxTiles 的超额余量），见构造函数注释 */
   hardCap = 96;
   /** 本数据集是 S3M 1.x（SuperMapCache，.s3m）：子瓦地址规则与 3.x 不同 */
-  private isS3MV1 = false;
+  isS3MV1 = false;
   private _buildTile: BuildTileFn | null;
+  private _bakeMercator?: boolean;
+  rootRadius?: number;
+
+  shouldBakeMercator(radius?: number): boolean {
+    if (this._bakeMercator !== undefined) return this._bakeMercator;
+    const r = radius ?? this.rootRadius ?? 0;
+    return r > AUTO_BAKE_RADIUS_THRESHOLD;
+  }
   private readonly _polygonOffset: { factor: number; units: number } | undefined;
   private _materialQuality: 'pbr' | 'lambert' | undefined;
   private _colorPipeline: 'linear' | 'direct' | undefined;
@@ -550,6 +579,11 @@ export class S3MTileset {
   constructor(options: S3MTilesetOptions) {
     this.configUrl = options.configUrl;
     this.lodRangeScale = options.lodRangeScale ?? 3.0;
+    this.lodTransition = options.lodTransition ?? 'binary';
+    this.fallbackOffset = {
+      factor: options.fallbackOffset?.factor ?? 1,
+      units: options.fallbackOffset?.units ?? 2,
+    };
     this._onTile = options.onTile ?? (() => {});
     this._onTileRemoved = options.onTileRemoved ?? (() => {});
     this._onError = options.onError ?? ((e) => console.warn(e));
@@ -560,6 +594,7 @@ export class S3MTileset {
 
     // 渲染层可注入：Node 环境下不需要 three，也能跑 URL / 解析链路
     this._buildTile = options.buildTile ?? null;
+    this._bakeMercator = options.bakeMercator;
     this._polygonOffset = options.polygonOffset;
     this._materialQuality = options.materialQuality;
     this._colorPipeline = options.colorPipeline;
@@ -903,6 +938,9 @@ export class S3MTileset {
       if (refined !== allowRefined) continue;
       // 正在显示且没有可见子瓦接手 → 踢了就是洞
       if (!allowUncovered && node.group.visible) {
+        if (this.lodTransition === 'incremental') {
+          continue;
+        }
         const covered = childUrls.some((u) => {
           const c = this.nodes.get(u);
           return !!c && c.group.visible;
@@ -913,6 +951,15 @@ export class S3MTileset {
         victim = node;
         continue;
       }
+      // 可见性优先于时间戳：没有包围球的瓦片算不出距离，`lastSeen` 天然比别的瓦片旧，
+      // 只看时间戳会把「正在显示」的那块先踢掉（开洞 → 回补 → 再踢 = 闪）。
+      // 只有不可见的候选分不出来时，才轮到 lastSeen / distance 决定。
+      const nodeVisible = node.group.visible ? 1 : 0;
+      const victimVisible = victim.group.visible ? 1 : 0;
+      if (nodeVisible !== victimVisible) {
+        if (nodeVisible < victimVisible) victim = node;
+        continue;
+      }
       const a = node.lastSeen ?? -1;
       const b = victim.lastSeen ?? -1;
       if (a < b || (a === b && (node.distance ?? 0) > (victim.distance ?? 0))) victim = node;
@@ -1350,6 +1397,11 @@ export class S3MTileset {
       // 解析成功但能力不完整的（目前只有 3DGS），在花力气建几何之前先决定处置
       this._noteDegradations(tile);
 
+            const lodForBake = this._pickLod(tile);
+      if (this.rootRadius === undefined && lodForBake?.boundingSphere?.radius) {
+        this.rootRadius = lodForBake.boundingSphere.radius;
+      }
+      const shouldBake = this.shouldBakeMercator(lodForBake?.boundingSphere?.radius);
       const build = await this._builder();
       const buildRes = await build(tile, {
         textureCache: this.textureCache,
@@ -1359,6 +1411,9 @@ export class S3MTileset {
         materialQuality: this._materialQuality,
         colorPipeline: this._colorPipeline,
         textureOptions: this._textureOptions,
+        bakeMercator: shouldBake,
+        tileAnchor: this.anchor,
+        tileCenter: lodForBake?.boundingSphere?.center,
       });
       const { group, stats } = buildRes;
       const texKeys = (buildRes as any).textureKeys ?? (group.userData?.textureKeys as string[] | undefined) ?? Object.keys(tile.textures ?? {});
@@ -1467,6 +1522,11 @@ export class S3MTileset {
 
     for (const node of this.nodes.values()) {
       if (!node.sphere) {
+        // 没有包围球（S3M 1.x 叶子瓦片：XML 是 `<PageLods><Geode>`，没有 PagedLOD）时
+        // 算不出距离，但**仍要记「最近用过」**：`lastSeen` 恒为 undefined 会让它在
+        // `_pickVictim` 里永远排最前（`?? -1`），硬上限一触发 `allowUncovered`，
+        // 第一块被踢掉的就是正在显示的那块 —— 画面立刻一个洞，下一帧又加载回来。
+        node.lastSeen = this._frame;
         node.needRefine = false;
         continue;
       }
@@ -1570,10 +1630,21 @@ export class S3MTileset {
       if (!p || !this.nodes.has(p)) roots.add(url);
     }
 
-    for (const rootUrl of roots) {
-      if (this._updateNodeVisibility(rootUrl, true, visited)) {
+    if (this.lodTransition === 'incremental') {
+      if (this._updateVisibilityIncremental(roots, visited)) {
         hasChanges = true;
       }
+    } else {
+      for (const rootUrl of roots) {
+        if (this._updateNodeVisibility(rootUrl, true, visited)) {
+          hasChanges = true;
+        }
+      }
+      this.primaryNodes.clear();
+      for (const [url, node] of this.nodes) {
+        if (node.group.visible) this.primaryNodes.add(url);
+      }
+      this.fallbackNodes.clear();
     }
 
     // 防御：若有任何未被 root 树访问到的游离瓦片，全部隐藏
@@ -1583,6 +1654,9 @@ export class S3MTileset {
           node.group.visible = false;
           hasChanges = true;
         }
+        if (this.lodTransition === 'incremental') {
+          this._restoreNodePolygonOffset(node);
+        }
       }
     }
 
@@ -1674,6 +1748,169 @@ export class S3MTileset {
     return changed;
   }
 
+
+  getLodTransition(): 'binary' | 'incremental' {
+    return this.lodTransition;
+  }
+
+  setLodTransition(mode: 'binary' | 'incremental'): void {
+    if (this.lodTransition === mode) return;
+    this.lodTransition = mode;
+    if (mode === 'binary') {
+      for (const node of this.nodes.values()) {
+        this._restoreNodePolygonOffset(node);
+      }
+      this.fallbackNodes.clear();
+    }
+  }
+
+  private _applyNodeFallbackPolygonOffset(node: TileNode, depth: number): boolean {
+    const factor = this.fallbackOffset.factor;
+    const units = Math.max(2, (10 - Math.min(depth, 8)) * this.fallbackOffset.units);
+    let changed = false;
+
+    node.group.traverse((obj) => {
+      const target = obj as { isMesh?: boolean; isPoints?: boolean; isLine?: boolean; material?: any };
+      if ((target.isMesh || target.isPoints || target.isLine) && target.material) {
+        const materials = Array.isArray(target.material) ? target.material : [target.material];
+        for (const mat of materials) {
+          if (!mat) continue;
+          if (!mat.userData) mat.userData = {};
+          if (!mat.userData._basePolygonOffset) {
+            mat.userData._basePolygonOffset = {
+              polygonOffset: mat.polygonOffset === true,
+              factor: mat.polygonOffsetFactor ?? 0,
+              units: mat.polygonOffsetUnits ?? 0,
+            };
+          }
+          const base = mat.userData._basePolygonOffset;
+          const targetFactor = base.factor + factor;
+          const targetUnits = base.units + units;
+          if (
+            mat.polygonOffset !== true ||
+            mat.polygonOffsetFactor !== targetFactor ||
+            mat.polygonOffsetUnits !== targetUnits
+          ) {
+            mat.polygonOffset = true;
+            mat.polygonOffsetFactor = targetFactor;
+            mat.polygonOffsetUnits = targetUnits;
+            changed = true;
+          }
+        }
+      }
+    });
+    return changed;
+  }
+
+  private _restoreNodePolygonOffset(node: TileNode): boolean {
+    let changed = false;
+    node.group.traverse((obj) => {
+      const target = obj as { isMesh?: boolean; isPoints?: boolean; isLine?: boolean; material?: any };
+      if ((target.isMesh || target.isPoints || target.isLine) && target.material) {
+        const materials = Array.isArray(target.material) ? target.material : [target.material];
+        for (const mat of materials) {
+          if (mat?.userData?._basePolygonOffset) {
+            const base = mat.userData._basePolygonOffset;
+            if (
+              mat.polygonOffset !== base.polygonOffset ||
+              mat.polygonOffsetFactor !== base.factor ||
+              mat.polygonOffsetUnits !== base.units
+            ) {
+              mat.polygonOffset = base.polygonOffset;
+              mat.polygonOffsetFactor = base.factor;
+              mat.polygonOffsetUnits = base.units;
+              changed = true;
+            }
+          }
+        }
+      }
+    });
+    return changed;
+  }
+
+  private _updateVisibilityIncremental(roots: Iterable<string>, visited: Set<string>): boolean {
+    const nextPrimary = new Set<string>();
+    const nextFallback = new Set<string>();
+    const nodeDepths = new Map<string, number>();
+
+    const traverse = (url: string, depth: number) => {
+      if (visited.has(url)) return;
+      visited.add(url);
+      nodeDepths.set(url, depth);
+
+      const node = this.nodes.get(url);
+      if (!node) return;
+
+      const childUrls = node.childUrls ?? (node.childUrl ? [node.childUrl] : []);
+      const hasChildren = childUrls.length > 0;
+      const readyChildren = childUrls.filter((cUrl) => this.nodes.has(cUrl));
+      const missingChildren = childUrls.filter(
+        (cUrl) => !this.nodes.has(cUrl) && !this.failed.has(cUrl)
+      );
+
+      const canRefine = !!node.needRefine && hasChildren && readyChildren.length > 0;
+
+      if (canRefine) {
+        if (missingChildren.length > 0) {
+          nextFallback.add(url);
+        }
+        for (const cUrl of readyChildren) {
+          traverse(cUrl, depth + 1);
+        }
+      } else {
+        nextPrimary.add(url);
+      }
+    };
+
+    for (const rootUrl of roots) {
+      traverse(rootUrl, 0);
+    }
+
+    let changed = false;
+
+    for (const [url, node] of this.nodes) {
+      if (!visited.has(url)) continue;
+
+      if (nextPrimary.has(url)) {
+        if (!node.group.visible) {
+          node.group.visible = true;
+          changed = true;
+        }
+        const depth = nodeDepths.get(url) ?? 0;
+        const targetOrder = 100 + depth;
+        if (node.group.renderOrder !== targetOrder) {
+          node.group.renderOrder = targetOrder;
+          changed = true;
+        }
+        if (this._restoreNodePolygonOffset(node)) changed = true;
+      } else if (nextFallback.has(url)) {
+        if (!node.group.visible) {
+          node.group.visible = true;
+          changed = true;
+        }
+        const depth = nodeDepths.get(url) ?? 0;
+        const targetOrder = depth;
+        if (node.group.renderOrder !== targetOrder) {
+          node.group.renderOrder = targetOrder;
+          changed = true;
+        }
+        if (this._applyNodeFallbackPolygonOffset(node, depth)) changed = true;
+      } else {
+        if (node.group.visible) {
+          node.group.visible = false;
+          changed = true;
+        }
+        if (this._restoreNodePolygonOffset(node)) changed = true;
+      }
+    }
+
+    this.primaryNodes.clear();
+    for (const u of nextPrimary) this.primaryNodes.add(u);
+    this.fallbackNodes.clear();
+    for (const u of nextFallback) this.fallbackNodes.add(u);
+
+    return changed;
+  }
   dispose(): void {
     this._workerClient?.dispose();
     for (const node of this.nodes.values()) {