s3m-three 0.4.25 → 0.4.27

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';
 
@@ -195,6 +196,10 @@ export function parseConfigText(text: string): Record<string, unknown> {
 
     return {
       fileType: tagVal('FileType') ?? undefined,
+      // 地形/影像缓存的判别字段（见 classifyDatasetKind）：FileExtentName=Terrainz 是地形，
+      // <sml:Type>Image</sml:Type> 是影像（影像的 FileExtentName 是 jpg_png 这种扩展名样式，不可靠）
+      fileExtentName: tagVal('FileExtentName') ?? undefined,
+      cacheType: tagVal('Type') ?? undefined,
       position: { x: posX, y: posY, z: posZ, units: 'Degree' },
       geoBounds: { left, right, top, bottom },
       heightRange: Number.isFinite(minH) || Number.isFinite(maxH) ? { min: minH, max: maxH } : undefined,
@@ -205,6 +210,53 @@ export function parseConfigText(text: string): Record<string, unknown> {
   return JSON.parse(trimmed) as Record<string, unknown>;
 }
 
+/** config 能认出的数据集类别（判别规则见 classifyDatasetKind） */
+export type DatasetKind = 'model' | 'terrain' | 'imagery';
+
+/**
+ * 按 config 的类型标记识别数据集类别。
+ *
+ * 同一个 `…/datas/<名>/config` URL 底下可能是模型、地形、影像三种完全不同的缓存
+ * （FORMAT-NOTES 第二章）。地形/影像是按 Level0 金字塔寻址的栅格缓存，**没有瓦片清单**，
+ * 当模型加载只会一路走到「配置中缺少 root tile」，把「类型不支持」伪装成「配置缺字段」
+ * （issue #7：混合服务第一个数据集 beijingdem 是 Terrainz 地形缓存）。
+ *
+ * 判别字段取自实测（supermapol 3D-OlympicGreen_Plan，2026-10-30）：
+ *   地形 XML： FileExtentName = Terrainz
+ *   影像 XML： FileExtentName = jpg_png（扩展名样式，不可靠）+ Type = Image
+ *   模型 XML： FileType = OSGBFile / OSGBCacheFile，无 FileExtentName / Type
+ *
+ * 保守原则：只有认出确凿的非模型标记才判 terrain / imagery，其余（含 JSON 配置、
+ * 无标记的 XML）一律 'model' —— 保证「认不出」时行为与旧版一致（不变式 ①）。
+ */
+export function classifyDatasetKind(config: Record<string, unknown> | null | undefined): DatasetKind {
+  if (!config || typeof config !== 'object') return 'model';
+  if (String(config.fileExtentName ?? '').trim().toLowerCase() === 'terrainz') return 'terrain';
+  if (String(config.cacheType ?? '').trim().toLowerCase() === 'image') return 'imagery';
+  return 'model';
+}
+
+/** 拼一句能区分 config 形态的上下文（FileExtentName / Type / fileType / dataType），供报错使用 */
+function configTypeHint(config: Record<string, unknown>): string {
+  const parts: string[] = [];
+  if (config.fileExtentName) parts.push(`FileExtentName=${config.fileExtentName}`);
+  if (config.cacheType) parts.push(`Type=${config.cacheType}`);
+  if (config.fileType) parts.push(`fileType=${config.fileType}`);
+  if (config.dataType) parts.push(`dataType=${config.dataType}`);
+  return parts.length ? parts.join(', ') : '无类型标记';
+}
+
+/** 从 configUrl 里抠出数据集名（…/datas/<名>/config）；抠不出就原样返回，报错时能对上服务里的数据集 */
+function datasetNameOf(configUrl: string): string {
+  const m = /\/datas\/([^/?#]+)/i.exec(configUrl);
+  if (!m) return configUrl;
+  try {
+    return decodeURIComponent(m[1]!);
+  } catch {
+    return m[1]!;
+  }
+}
+
 export interface TileNode {
   url: string;
   tile: ParsedTile;
@@ -253,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;
@@ -337,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 };
 }
 
 /** 估算单个纹理占用的显存字节数 */
@@ -454,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 {
@@ -484,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;
@@ -499,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));
@@ -509,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;
@@ -539,11 +625,31 @@ export class S3MTileset {
     const text = await res.text();
     const config = parseConfigText(text);
     this.config = config;
+
+    // 地形/影像缓存（金字塔栅格，无瓦片清单）不能当模型加载：走到下面「缺少 root tile」
+    // 那步只会得到一句把「类型不支持」伪装成「配置缺字段」的报错（issue #7），
+    // 所以在锚点解析之前先按类型标记拒掉，把病因说清楚。
+    const kind = classifyDatasetKind(config);
+    if (kind !== 'model') {
+      const err = new Error(
+        `数据集 ${datasetNameOf(this.configUrl)} 是${kind === 'terrain' ? '地形' : '影像'}缓存（${configTypeHint(config)}），本层仅支持模型类 S3M 数据集`
+      ) as Error & { datasetKind: DatasetKind };
+      // 程序化判别用：调用方（如数据集列表 UI）可以据此标注/跳过该数据集
+      err.datasetKind = kind;
+      throw err;
+    }
+
     this.anchor = this._resolveAnchor(config);
 
     // iServer 的 realspace 配置用 rootTiles（可多棵树），桌面导出的用 tiles
     const roots = (config.rootTiles ?? config.tiles ?? []) as Array<{ url: string }>;
-    if (!roots.length) throw new Error('配置中缺少 root tile');
+    if (!roots.length) {
+      // 带上 config 的类型标记：地形/影像缓存（本应在前一步被拒）与「configUrl 误指向
+      // …/datas 清单」「桌面导出漏瓦片清单」是三种不同的病因，文案必须能区分
+      throw new Error(
+        `配置中缺少 root tile（${configTypeHint(config)}）——若是地形/影像数据集，或 configUrl 误指向 …/datas 数据集清单，本层仅支持模型类 S3M 数据集`
+      );
+    }
 
     this.rootUrls.length = 0;
     for (const r of roots) {
@@ -832,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;
@@ -941,7 +1050,7 @@ export class S3MTileset {
     }
     if (this._workerClient) {
       try {
-        return await this._workerClient.parseTile(buffer, true);
+        return await this._workerClient.parseTile(buffer, true, true, this.config?.vertexAttributeDescript);
       } catch (e) {
         if (e instanceof WorkerDeadError) {
           // 脚本加载失败 / 崩溃属于环境问题，永久退回主线程；瓦片本身的问题照常抛
@@ -951,7 +1060,7 @@ export class S3MTileset {
         }
       }
     }
-    return { tile: await parseS3MB(buffer) };
+    return { tile: await parseS3MB(buffer, { vertexAttributeDescript: this.config?.vertexAttributeDescript }) };
   }
 
   /**
@@ -1279,6 +1388,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,
@@ -1288,6 +1402,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 ?? {});
@@ -1499,10 +1616,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 树访问到的游离瓦片，全部隐藏
@@ -1512,6 +1640,9 @@ export class S3MTileset {
           node.group.visible = false;
           hasChanges = true;
         }
+        if (this.lodTransition === 'incremental') {
+          this._restoreNodePolygonOffset(node);
+        }
       }
     }
 
@@ -1603,6 +1734,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()) {

package/src/vendor/draco_decoder.module.d.ts

@@ -1,4 +1,4 @@
-/**
+/**
  * Draco 几何解码器（google/draco，wasm 内联）的类型声明
  *
  * 只声明 S3M 用到的部分。两个坑：
@@ -41,6 +41,11 @@ export interface DracoPointCloud {
   __destroy__(): void;
 }
 
+
+/** draco::Mesh - inherits from PointCloud, additionally provides face info (used for TRIANGULAR_MESH branch) */
+export interface DracoMesh extends DracoPointCloud {
+  num_faces(): number;
+}
 export interface DracoStatus {
   ok(): boolean;
   error_msg(): string;
@@ -54,6 +59,14 @@ export interface DracoDecoder {
     byteLength: number,
     out: DracoPointCloud
   ): DracoStatus;
+  /** 解码三角网格（TRIANGULAR_MESH 分支） */
+  DecodeArrayToMesh(
+    data: Uint8Array,
+    byteLength: number,
+    out: DracoMesh
+  ): DracoStatus;
+  /** 从已解码的 Mesh 取第 faceIndex 个面的 3 个顶点索引到 DracoInt32Array */
+  GetFaceFromMesh(mesh: DracoMesh, faceIndex: number, out: DracoInt32Array): boolean;
   /** 按属性在几何里的序号取 */
   GetAttribute(pc: DracoPointCloud, index: number): DracoPointAttribute;
   /** 按 unique_id 取；不存在时返回 null */
@@ -113,6 +126,7 @@ export interface DracoUInt32Array {
 export interface DracoModule {
   Decoder: new () => DracoDecoder;
   PointCloud: new () => DracoPointCloud;
+  Mesh: new () => DracoMesh;
   DracoFloat32Array: new () => DracoFloat32Array;
   DracoInt8Array: new () => DracoInt8Array;
   DracoUInt8Array: new () => DracoUInt8Array;

package/src/worker/S3MWorkerClient.ts

@@ -88,12 +88,17 @@ export class S3MWorkerClient {
    * 解析一块瓦片。buffer 会被 structured clone（不 transfer），主线程保留原 buffer 以便崩溃后降级重解。
    * assemble = true 时顺带在 Worker 里做纯数据几何组装，返回 { tile, geometry } 一次带回。
    */
-  parseTile(buffer: ArrayBuffer, assemble = false, batching = true): Promise<{ tile: ParsedTile; geometry?: TileGeometryData }> {
+  parseTile(
+    buffer: ArrayBuffer,
+    assemble = false,
+    batching = true,
+    vertexAttributeDescript?: unknown
+  ): Promise<{ tile: ParsedTile; geometry?: TileGeometryData }> {
     if (this.dead) return Promise.reject(new WorkerDeadError('s3m 解析 Worker 已终止'));
     const id = ++this._seq;
     return new Promise<{ tile: ParsedTile; geometry?: TileGeometryData }>((resolve, reject) => {
       this._pending.set(id, { resolve: resolve as (v: unknown) => void, reject });
-      this._worker.postMessage({ type: 'parse', id, buffer, assemble, batching });
+      this._worker.postMessage({ type: 'parse', id, buffer, assemble, batching, vertexAttributeDescript });
     });
   }
 

package/src/worker/s3mWorker.ts

@@ -28,6 +28,7 @@ type ParseRequest = {
   /** 解析后顺带做纯数据几何组装（解交错 / 法线 / 合批），一次往返带回 */
   assemble?: boolean;
   batching?: boolean;
+  vertexAttributeDescript?: unknown;
 };
 type TexRequest = { type: 'tex'; id: number; tex: S3MTexture; compressed?: boolean; maxSize?: number };
 type Request = ParseRequest | TexRequest;
@@ -52,10 +53,13 @@ ctx.onmessage = async (e: MessageEvent<Request>) => {
   const { id } = msg;
   try {
     if (msg.type === 'parse') {
-      const tile = await parseS3MB(msg.buffer);
+      const tile = await parseS3MB(msg.buffer, { vertexAttributeDescript: msg.vertexAttributeDescript });
       if (msg.assemble) {
         // 解析 + 组装一起做，避免 tile 回主线程后再整块克隆回来一次
-        const geometry = assembleTileGeometry(tile, { batching: msg.batching });
+        const geometry = assembleTileGeometry(tile, {
+          batching: msg.batching,
+          vertexAttributeDescript: msg.vertexAttributeDescript,
+        });
         ctx.postMessage(
           { id, ok: true, tile, geometry } satisfies ParseResponse,
           [...collectTransferables(tile), ...collectTransferables(geometry)]