s3m-three 0.4.26 → 0.4.28

package/src/render/S3MViewer.ts

@@ -41,6 +41,7 @@ import type {
   PickResult,
   PickableRef,
   PathFollowOptions,
+  DepthMode,
   MeshUserData,
 } from './viewer/types.js';
 import { decodeTextureWithWorker } from '../worker/S3MWorkerClient.js';
@@ -114,6 +115,7 @@ import type {
 } from '../core/types.js';
 
 import { lngLatFromWorld, worldFromLngLat, type GeoAdapter } from './GeoAdapter.js';
+import { computeTilePlacement } from './tilePlacement.js';
 
 import {
   DatasetManager,
@@ -176,9 +178,17 @@ export type {
   S3MViewerOptions,
   PickableRef,
   PathFollowOptions,
+  DepthMode,
 } from './viewer/types.js';
 export type { MotionBlurOptions, MotionBlurConfig } from './MotionBlurPass.js';
 
+/** 稳健归一化 depthMode 入参，默认 'scene' */
+export function normalizeDepthMode(mode?: unknown): DepthMode {
+  if (mode === 'clear') return 'clear';
+  if (mode === 'auto') return 'auto';
+  return 'scene';
+}
+
 function styledMaterialOf(mesh: THREE.Mesh): StyledMaterial | null {
   const m = Array.isArray(mesh.material) ? mesh.material[0] : mesh.material;
   const styled = m as StyledMaterial | undefined;
@@ -205,6 +215,12 @@ function clampOpacity(v: number | null | undefined): number {
 /** 低于这个透明度就当作完全不可见：跳过绘制，避免全透明物体写深度 */
 const OPACITY_EPS = 1e-3;
 
+/**
+ * 拾取反解瓦片级放置时的临时矩阵。命中点→规范 ENU 是一次独立查询（鼠标事件），
+ * 复用一个实例避免每次分配；不可重入（`_toCanonicalScene` 内部不递归调用）。
+ */
+const _tilePlacementInverse = new THREE.Matrix4();
+
 /* ------------------------------------------------------------------ 可动画的样式键 */
 
 /**
@@ -297,6 +313,8 @@ export class S3MViewer {
    * 传了值就只认自己，多图层同页各用各的，互不覆盖。
    */
   private _materialQuality: MaterialQuality | undefined;
+  private _lodTransition: 'binary' | 'incremental';
+  private _fallbackOffset?: { factor?: number; units?: number };
   /**
    * 本图层的颜色管线。
    *
@@ -322,11 +340,32 @@ export class S3MViewer {
   }
 
   /** 场景主锚点（ENU 原点对应的世界坐标） */
-  get sceneAnchor(): { x: number; y: number; z: number; meterInMercator: number; altitude?: number } | null {
+  get sceneAnchor(): {
+    x: number;
+    y: number;
+    z: number;
+    meterInMercatorEast?: number;
+    meterInMercatorNorth?: number;
+    meterInMercatorUp?: number;
+    meterInMercator: number;
+    altitude?: number;
+  } | null {
     return this._datasetManager.sceneAnchor;
   }
-  set sceneAnchor(val: { x: number; y: number; z: number; meterInMercator: number; altitude?: number } | null) {
+  set sceneAnchor(
+    val: {
+      x: number;
+      y: number;
+      z: number;
+      meterInMercatorEast?: number;
+      meterInMercatorNorth?: number;
+      meterInMercatorUp?: number;
+      meterInMercator: number;
+      altitude?: number;
+    } | null
+  ) {
     this._datasetManager.sceneAnchor = val;
+    this._reapplyTilePlacements();
   }
 
   /** 拾取表 / pickId 池 / 射线求交（见 viewer/PickService.ts） */
@@ -402,6 +441,13 @@ export class S3MViewer {
    */
   private _motionBlurCfg: MotionBlurConfig | null = null;
   private _motionBlur: MotionBlurPass | null = null;
+  /**
+   * 瓦片级放置（默认关）。关时 `_registerTile` 完全不碰瓦片矩阵，代码路径与改动前
+   * 逐字一致；开时每块瓦片用自己的中心纬度算尺度，见 `tilePlacement.ts`。
+   */
+  private readonly _perTilePlacement: boolean;
+  /** 本层绘制前深度缓冲的处理策略：'scene' | 'clear' | 'auto'，默认 'scene' */
+  private _depthMode: DepthMode = 'scene';
 
   /** 宿主请求重画（MapLibre 传 triggerRepaint，纯 three 宿主传自己的渲染循环） */
   private _requestRepaint(): void {
@@ -418,6 +464,10 @@ export class S3MViewer {
     this._lodRangeScale = options.lodRangeScale ?? 1.0;
     this._unsupported = options.unsupported ?? 'warn';
     this._lodPixelRatioCap = options.lodPixelRatioCap ?? Infinity;
+    // 瓦片级放置默认开启：旧行为是拿单一常量切平面拟合随纬度变化的墨卡托比例，属于 bug 修复，
+    // 所以默认值跟着改（见 AGENTS.md 不变式 ①）。显式传 false 仍可回退。
+    this._perTilePlacement = options.perTilePlacement !== false;
+    this._depthMode = normalizeDepthMode(options.depthMode);
     setTextureSizeCap(options.maxTextureSize ?? Infinity);
     // 运动模糊：默认关闭；开了也只在 renderFrame 里按需接管「场景→屏幕」这一步
     this._motionBlurCfg = normalizeMotionBlur(options.motionBlur);
@@ -426,6 +476,11 @@ export class S3MViewer {
     this._materialQuality = normalizeMaterialQuality(options.materialQuality);
     // 之后 addDataset 的数据集按这个默认建材质（数据集自己指定则用自己的）
     this._datasetManager.defaultMaterialQuality = this._materialQuality;
+    this._lodTransition = options.lodTransition ?? 'binary';
+    this._fallbackOffset = options.fallbackOffset;
+    this._datasetManager.defaultLodTransition = this._lodTransition;
+    this._datasetManager.defaultFallbackOffset = this._fallbackOffset;
+    this._datasetManager.defaultBakeMercator = options.bakeMercator;
     if (options.totalMaxTiles) {
       this._datasetManager.totalMaxTiles = options.totalMaxTiles;
     }
@@ -507,6 +562,7 @@ export class S3MViewer {
         return self._smidMeshes;
       },
       lngLatFromWorld: (x, y) => self._lngLatFromWorld(x, y),
+      toCanonicalScene: (p, mesh) => self._toCanonicalScene(p, mesh),
       gpuPathPoseAt: (smid) => self._gpuPathPoseAt(smid),
       isFeatureHidden: (smid, batchId) => self._isFeatureHidden(smid, batchId),
     });
@@ -762,7 +818,15 @@ export class S3MViewer {
         .filter((d) => !!d?.configUrl)
         .map((d) => ({ ...d, polygonOffset: d.polygonOffset ?? options.polygonOffset }));
     if (options.configUrl)
-      return [{ id: 'default', name: '默认数据集', configUrl: options.configUrl, useWorker: options.useWorker, polygonOffset: options.polygonOffset }];
+      return [{
+        id: 'default',
+        name: '默认数据集',
+        configUrl: options.configUrl,
+        useWorker: options.useWorker,
+        polygonOffset: options.polygonOffset,
+        lodTransition: options.lodTransition,
+        fallbackOffset: options.fallbackOffset,
+      }];
     return [];
   }
 
@@ -770,7 +834,12 @@ export class S3MViewer {
   async addDataset(ds: S3MDatasetOptions): Promise<S3MDatasetEntry> {
     if (!this.scene) throw new Error('[s3m] 图层尚未 addLayer，不能添加数据集');
     // 图层级默认值：数据集自己指定了就用自己的，见 `S3MViewerOptions.unsupported`
-    const merged: S3MDatasetOptions = { ...ds, unsupported: ds.unsupported ?? this._unsupported };
+    const merged: S3MDatasetOptions = {
+      ...ds,
+      unsupported: ds.unsupported ?? this._unsupported,
+      lodTransition: ds.lodTransition ?? this._lodTransition,
+      fallbackOffset: ds.fallbackOffset ?? this._fallbackOffset,
+    };
     const entry = await this._datasetManager.addDataset(
       merged,
       this.scene,
@@ -828,6 +897,8 @@ export class S3MViewer {
   /** 当地图 CRS 投影切换或宿主 map 挂载后，重新计算场景锚点与各数据集 offset */
   recomputeAnchors(): void {
     this._datasetManager.recomputeAnchors(this.geo);
+    // 锚点变了 → 每块瓦片的 k 与 position 都要重算（关这项功能时是空转，一次遍历都不做）
+    this._reapplyTilePlacements();
     this._heights.refreshAll();
     this._requestRepaint();
   }
@@ -1665,6 +1736,32 @@ export class S3MViewer {
   /* ---------------------------------------------------------------- 瓦片注册 */
 
   private _registerTile(node: TileNode, entry: S3MDatasetEntry): void {
+    // 必须在 add / updateMatrixWorld 之前设置：后者会拿当前 matrix 算 matrixWorld 并缓存
+    //
+    // ★ 触发条件**不能**是「有没有包围球」。S3M 1.x 的叶子瓦片 XML 是
+    //   `<PageLods><Geode>`（外面没有 `<PagedLOD>` 包装），`parseXmlLods` 解析出来
+    //   pageLods 为空 → sphere 为 null。而 `entry.root` 上挂着 align 算出来的整体偏移
+    //   （索菲亚教堂是 heightRange.min = 119.84），那个偏移是靠 placement 里的
+    //   `- datasetOffset` 抵消的。少摆一块，这块就带着偏移显示 —— 实测 L23 整层
+    //   因此沉到地下 120 m，且 `localZ - worldZ` 恒等于偏移量。
+    //   缺球时用几何包围盒中心兜底；连几何都没有就退回旧口径。
+    const center = node.sphere?.center ?? this._localCenterOf(node.group);
+    if (this._perTilePlacement && center) {
+      this._applyTilePlacement(node.group, center, entry);
+    }
+    // 上面没摆成（关掉本功能 / 缺锚点 / 几何为空）时 matrixAutoUpdate 仍是 true，走旧口径
+    if (node.group.matrixAutoUpdate) {
+      const sceneAnchor = this.sceneAnchor;
+      if (sceneAnchor) {
+        const sEast = sceneAnchor.meterInMercatorEast ?? sceneAnchor.meterInMercator;
+        const sNorth = sceneAnchor.meterInMercatorNorth ?? sceneAnchor.meterInMercator;
+        const sUp = sceneAnchor.meterInMercatorUp ?? sEast;
+        const c = node.sphere
+          ? ([node.sphere.center.x, node.sphere.center.y, node.sphere.center.z] as const)
+          : ([0, 0, 0] as const);
+        this._updateTileUniforms(node.group, c, [1.0 / sEast, 1.0 / sNorth, 1.0 / sUp]);
+      }
+    }
     entry.root.add(node.group);
     node.group.updateMatrixWorld(true);
 
@@ -1736,6 +1833,152 @@ export class S3MViewer {
     }
   }
 
+  /**
+   * 瓦片几何在**数据集局部 ENU** 里的包围盒中心，给没有包围球的瓦片兜底。
+   *
+   * 调用时机固定在 `entry.root.add()` 之前：此时 group 还没挂到 root 上、matrix 还是
+   * 单位阵，`setFromObject` 得到的就是顶点自己的坐标系，正好是摆放要的枢轴。
+   * 挂上 root 之后再算会带上 root 的 offset，枢轴就偏了。
+   */
+  private _localCenterOf(group: THREE.Object3D): { x: number; y: number; z: number } | null {
+    if (!group.children.length) return null;
+    const box = new THREE.Box3().setFromObject(group);
+    if (box.isEmpty()) return null;
+    const c = box.getCenter(new THREE.Vector3());
+    if (!Number.isFinite(c.x) || !Number.isFinite(c.y) || !Number.isFinite(c.z)) return null;
+    return { x: c.x, y: c.y, z: c.z };
+  }
+
+  /**
+   * 把一块瓦片摆到「用它自己中心纬度算出的尺度」上（`perTilePlacement` 开启时才走）。
+   *
+   * 矩阵是 `T(position) · S(k) · T(-pivot)`，展开后即 `v ↦ position + k·(v - pivot)`。
+   * 直接用 `makeScale + setPosition` 一次写好，省掉两个临时矩阵：
+   * `T(t)·S(k)·T(-c)` 的元素其实就是对角 `k` 加平移 `t - k·c`。
+   *
+   * 只写 `matrix`，不碰 `rotation / position / scale` —— three 在
+   * `matrixAutoUpdate = false` 时直接使用 `matrix`，那些字段留着无害，
+   * 但别让 `updateMatrix()` 有机会覆盖回来。
+   */
+  private _applyTilePlacement(
+    group: THREE.Object3D,
+    center: { x: number; y: number; z: number },
+    entry: S3MDatasetEntry,
+  ): void {
+    const sceneAnchor = this.sceneAnchor;
+    if (!sceneAnchor || !entry.anchor) return;
+
+    const p = computeTilePlacement({
+      center,
+      datasetAnchor: entry.anchor,
+      sceneAnchor,
+      datasetOffset: entry.offset,
+      geo: this.geo,
+    });
+    if (!p) return;
+
+    const kEast = p.scaleEast ?? p.scale;
+    const kNorth = p.scaleNorth ?? p.scale;
+    const kUp = kEast;
+    group.matrixAutoUpdate = false;
+    group.matrix.makeScale(kEast, kNorth, kUp);
+    group.matrix.setPosition(
+      p.position[0] - kEast * p.pivot[0],
+      p.position[1] - kNorth * p.pivot[1],
+      p.position[2] - kUp * p.pivot[2],
+    );
+    group.matrixWorldNeedsUpdate = true;
+    // 重锚点后要能重算：中心只属于注册那一刻，存到 group 上，不依赖 tileset 内部结构
+    (group.userData as { tileCenter?: { x: number; y: number; z: number } }).tileCenter = {
+      x: center.x,
+      y: center.y,
+      z: center.z,
+    };
+    // 逆矩阵缓存：_toCanonicalScene 常态路径无需每次拾取反复求逆，失效点仅在瓦片放置或重锚点
+    const inv = ((group.userData as { placementInverse?: THREE.Matrix4 }).placementInverse ??= new THREE.Matrix4());
+    inv.copy(group.matrix).invert();
+
+    const sSceneEast = sceneAnchor.meterInMercatorEast ?? sceneAnchor.meterInMercator;
+    const sSceneNorth = sceneAnchor.meterInMercatorNorth ?? sceneAnchor.meterInMercator;
+    const sSceneUp = sceneAnchor.meterInMercatorUp ?? sSceneEast;
+    const invScale = p.invTileScale ?? [1.0 / (sSceneEast * kEast), 1.0 / (sSceneNorth * kNorth), 1.0 / (sSceneUp * kUp)];
+    this._updateTileUniforms(group, p.pivot, invScale);
+  }
+
+  private _updateTileUniforms(
+    group: THREE.Object3D,
+    pivot: readonly [number, number, number],
+    invTileScale: readonly [number, number, number]
+  ): void {
+    group.traverse((obj) => {
+      const mesh = obj as THREE.Mesh;
+      if (((obj as any).isMesh || (obj as any).isPoints) && (obj as any).material) {
+        const mats = Array.isArray(mesh.material) ? mesh.material : [mesh.material];
+        for (const m of mats) {
+          const uPivot = (m as any).userData?.uTilePivot;
+          const uScale = (m as any).userData?.uInvTileScale;
+          if (uPivot?.value) {
+            uPivot.value.set(pivot[0], pivot[1], pivot[2]);
+          }
+          if (uScale?.value) {
+            uScale.value.set(invTileScale[0], invTileScale[1], invTileScale[2]);
+          }
+        }
+      }
+    });
+  }
+
+  /**
+   * 世界坐标 → **规范**场景 ENU：把瓦片级放置的缩放反解掉。
+   *
+   * `perTilePlacement` 开启后，瓦片几何是「绕自身中心缩放 k 倍、再摆到精确位置」的，
+   * 所以命中点的世界坐标不再等于数据本身的 ENU。拾取要报的是**坐标本身**——
+   * 一个屋顶的经纬度不该因为我们怎么缩放它而改变，否则同一个点在 20 km 外会比
+   * 1 km 内偏出几米，量算、贴地、外部标注全都跟着漂。
+   *
+   * 反解只需要一次矩阵求逆：父级 `entry.root` 只有平移（`layoutDataset` 只写
+   * `position`），所以世界坐标 `p` 对应的瓦片局部坐标是
+   *
+   * ```
+   * v = group.matrix⁻¹ · (p − root.position)
+   * canonical = root.position + v
+   * ```
+   *
+   * 关掉本功能、或网格不在已放置的瓦片里时**原样返回同一个对象**，
+   * 默认路径一次矩阵运算都不做。
+   */
+  private _toCanonicalScene(p: THREE.Vector3, mesh?: THREE.Object3D | null): THREE.Vector3 {
+    if (!this._perTilePlacement || !mesh) return p;
+    // 网格直接挂在瓦片 group 下（`_registerTile` 就是遍历 node.group.children）；
+    // 往上找到第一个带 tileCenter 的祖先，避免依赖层级深度
+    let group: THREE.Object3D | null = mesh.parent;
+    while (group && !(group.userData as { tileCenter?: unknown }).tileCenter) group = group.parent;
+    if (!group) return p;
+    const root = group.parent;
+    if (!root) return p;
+
+    return p
+      .clone()
+      .sub(root.position)
+      .applyMatrix4((group.userData as { placementInverse?: THREE.Matrix4 }).placementInverse ?? _tilePlacementInverse.copy(group.matrix).invert())
+      .add(root.position);
+  }
+
+  /**
+   * 场景锚点变了（`recomputeAnchors`）之后，所有已注册瓦片的放置都要重算 ——
+   * `k` 与 `position` 都依赖场景锚点。没存 `tileCenter` 的（未开启本功能时注册的）
+   * 一律跳过，保证默认路径不产生任何副作用。
+   */
+  private _reapplyTilePlacements(): void {
+    for (const entry of this._datasetManager.values()) {
+      if (!entry.anchor) continue;
+      for (const child of entry.root.children) {
+        const c = (child.userData as { tileCenter?: { x: number; y: number; z: number } }).tileCenter;
+        if (c) this._applyTilePlacement(child, c, entry);
+      }
+    }
+  }
+
   /**
    * 新瓦片淡入。
    *
@@ -2200,6 +2443,17 @@ export class S3MViewer {
   }
 
   /** 当前材质质感档位（本图层指定了就用本图层的，否则是模块级默认） */
+  get lodTransition(): 'binary' | 'incremental' {
+    return this._lodTransition;
+  }
+
+  setLodTransition(mode: 'binary' | 'incremental'): void {
+    if (this._lodTransition === mode) return;
+    this._lodTransition = mode;
+    this._datasetManager.setDefaultLodTransition(mode);
+    this.triggerRepaint();
+  }
+
   get materialQuality(): MaterialQuality {
     return this._materialQuality ?? getMaterialQuality();
   }
@@ -2222,6 +2476,54 @@ export class S3MViewer {
   }
 
   /** 当前运动模糊配置（归一化后的副本）；null = 关闭 */
+  /**
+   * 运行时修改深度处理策略（'scene' | 'clear' | 'auto'）。
+   */
+  setDepthMode(mode: DepthMode): void {
+    const next = normalizeDepthMode(mode);
+    if (this._depthMode !== next) {
+      this._depthMode = next;
+      this.triggerRepaint();
+    }
+  }
+
+  /** 当前深度策略（'scene' | 'clear' | 'auto'，默认 'scene'） */
+  get depthMode(): DepthMode {
+    return this._depthMode;
+  }
+
+  /**
+   * 当前帧实际生效的深度处理模式（'scene' | 'clear'）。
+   * - 'clear': 显式指定 clear，或 auto 模式下命中地面覆盖/倾斜摄影/DEM等地面类数据
+   * - 'scene': 显式指定 scene，或 auto 模式下无地面类数据
+   */
+  resolveDepthMode(): 'scene' | 'clear' {
+    if (this._depthMode === 'clear') return 'clear';
+    if (this._depthMode === 'scene') return 'scene';
+
+    // 'auto': 按数据集与地面覆盖特征推断
+    if (this.groundManager && this.groundManager.mode !== 'none') {
+      return 'clear';
+    }
+
+    for (const entry of this._datasetManager.datasets.values()) {
+      if (!entry.visible) continue;
+      if (entry.options.depthMode === 'clear') return 'clear';
+      if (entry.options.depthMode === 'scene') continue;
+      if (entry.tileset?.isS3MV1) return 'clear';
+      const cfg = entry.tileset?.config as Record<string, unknown> | null | undefined;
+      if (cfg) {
+        const typeStr = `${cfg.fileType ?? ''} ${cfg.dataType ?? ''} ${cfg.datasetType ?? ''} ${cfg.cacheType ?? ''} ${cfg.fileExtentName ?? ''}`;
+        if (/osgb|oblique|ground|dem|tin|terrain/i.test(typeStr)) return 'clear';
+      }
+      if (entry.options.configUrl && /osgb|oblique/i.test(entry.options.configUrl)) {
+        return 'clear';
+      }
+    }
+
+    return 'scene';
+  }
+
   get motionBlur(): MotionBlurOptions | null {
     return this._motionBlurCfg ? { ...this._motionBlurCfg } : null;
   }
@@ -2530,10 +2832,11 @@ export class S3MViewer {
   private _sceneFromLngLat(p: LngLatAlt): Vec3 {
     const anchor = this.sceneAnchor;
     if (!anchor) return [0, 0, 0];
-    const s = anchor.meterInMercator;
+    const sEast = anchor.meterInMercatorEast ?? anchor.meterInMercator;
+    const sNorth = anchor.meterInMercatorNorth ?? anchor.meterInMercator;
     const w = worldFromLngLat(this.geo, p.lng, p.lat, p.altitude);
     // 注意 y 取反：three 的 y 向上，墨卡托 y 向下（与 PickService.pickPosition 互逆）
-    return [(w.x - anchor.x) / s, -(w.y - anchor.y) / s, p.altitude - (anchor.altitude ?? 0)];
+    return [(w.x - anchor.x) / sEast, -(w.y - anchor.y) / sNorth, p.altitude - (anchor.altitude ?? 0)];
   }
 
   /**
@@ -2556,8 +2859,9 @@ export class S3MViewer {
   private _lngLatFromScene(v: Vec3): LngLatAlt {
     const anchor = this.sceneAnchor;
     if (!anchor) return { lng: 0, lat: 0, altitude: v[2] };
-    const s = anchor.meterInMercator;
-    const [lng, lat] = lngLatFromWorld(this.geo, v[0] * s + anchor.x, -v[1] * s + anchor.y);
+    const sEast = anchor.meterInMercatorEast ?? anchor.meterInMercator;
+    const sNorth = anchor.meterInMercatorNorth ?? anchor.meterInMercator;
+    const [lng, lat] = lngLatFromWorld(this.geo, v[0] * sEast + anchor.x, -v[1] * sNorth + anchor.y);
     return { lng, lat, altitude: v[2] + (anchor.altitude ?? 0) };
   }
 
@@ -3053,13 +3357,15 @@ export class S3MViewer {
     this.flushOverrides();
 
     const canvas = this.canvas;
-    const s = this.sceneAnchor.meterInMercator;
+    const sEast = this.sceneAnchor.meterInMercatorEast ?? this.sceneAnchor.meterInMercator;
+    const sNorth = this.sceneAnchor.meterInMercatorNorth ?? this.sceneAnchor.meterInMercator;
+    const sUp = this.sceneAnchor.meterInMercatorUp ?? sEast;
 
     // ENU → 世界坐标：x 向东，y 向北（墨卡托 y 朝南，所以取负），z 向上
     this._enuMatrix.set(
-      s, 0, 0, this.sceneAnchor.x,
-      0, -s, 0, this.sceneAnchor.y,
-      0, 0, s, this.sceneAnchor.z,
+      sEast, 0, 0, this.sceneAnchor.x,
+      0, -sNorth, 0, this.sceneAnchor.y,
+      0, 0, sUp, this.sceneAnchor.z,
       0, 0, 0, 1
     );
 
@@ -3117,6 +3423,19 @@ export class S3MViewer {
     setSplatViewport(canvas.width, canvas.height);
 
     this.renderer.setViewport(0, 0, canvas.width, canvas.height);
+    const effectiveDepthMode = (this.uniforms.uOpacity?.value ?? 1) > OPACITY_EPS
+      ? this.resolveDepthMode()
+      : 'scene';
+    if (effectiveDepthMode === 'clear' && gl) {
+      // gl.clear 受 depthMask 约束。上一帧若以 depthWrite=false 的材质收尾（棱线、半透明
+      // 地表覆盖、半透明点云、泼溅），GL 的 depthMask 会停在 false —— three 帧末不恢复它，
+      // 而 resetState 排在 clear 之后，救不了这一步。不自己打开就是一次静默的空操作：
+      // 画面上的 z-fighting 原样保留，且没有任何报错可查。
+      gl.depthMask(true);
+      // 只清深度，不清颜色 —— 颜色是 MapLibre 已经画好的底图
+      gl.clear(gl.DEPTH_BUFFER_BIT);
+    }
+    // 清完之后必须让 three 知道状态被外部改过，否则它的状态缓存会认为自己仍然正确
     this.renderer.resetState();
     // 完全透明时什么都不画：透明物体照样写深度，画了会在底图上挖出一个洞。
     // 这里跳过的是「本层的绘制」，宿主自己的清屏 / 底图照旧。
@@ -3129,7 +3448,10 @@ export class S3MViewer {
       }
       // GPU 描边必须画在主场景之后：它的全屏 quad 参与宿主深度测试，
       // 依赖本帧已经写好的深度（被地形挡住的地方不该描边）
-      this._edges.renderGpuEdges(canvas);
+      // clear 模式下宿主深度已清除，描边会穿透地形产生伪影，故只在非 clear 时画。
+      if (effectiveDepthMode !== 'clear') {
+        this._edges.renderGpuEdges(canvas);
+      }
     }
 
     this._frame++;

package/src/render/StyleMaterial.ts

@@ -446,6 +446,11 @@ export function createSharedUniforms(): StyleUniforms {
   };
 }
 const VERT_PARS = /* glsl */ `
+  #ifdef S3M_BAKED_MERCATOR
+    attribute vec3 aMercatorOffset;
+    uniform vec3 uTilePivot;
+    uniform vec3 uInvTileScale;
+  #endif
   attribute float aBatchId;
   // vec4：alpha 是「材质不透明、顶点半透明」这类数据的唯一透明度来源（官方 baseColorWithAlpha = vColor）
   attribute vec4 aColor;
@@ -624,6 +629,13 @@ const VERT_SETUP = /* glsl */ `
 `;
 
 const VERT_ELEVATION = /* glsl */ `
+  #ifdef S3M_BAKED_MERCATOR
+    transformed = uTilePivot + vec3(
+      aMercatorOffset.x * uInvTileScale.x,
+      -aMercatorOffset.y * uInvTileScale.y,
+      aMercatorOffset.z * uInvTileScale.z
+    );
+  #endif
   float s3mBatchElev = s3mBatchRaw();
   if ( uBatchTexActive > 0 && s3mBatchElev >= 0.0 ) {
     float s3mU = ( s3mBatchElev + 0.5 ) / uBatchTexWidth;
@@ -1142,6 +1154,11 @@ export interface StyledMaterialOptions {
    * 与 `materialQuality` 同一套：图层把自己的 profile 透传进来，同页互不污染。
    */
   colorPipeline?: ColorPipeline;
+  bakeMercator?: boolean;
+  /** 瓦片变换中心在 object space 的位置，供烘焙着色器恢复绝对位置 */
+  tilePivot?: THREE.Vector3;
+  /** 逐瓦片逆尺度 (1 / sTileEast, 1 / sTileNorth, 1 / sTileUp)，供烘焙着色器抵消各向异性缩放 */
+  invTileScale?: THREE.Vector3;
 }
 
 /**
@@ -1246,12 +1263,19 @@ export function createStyledMaterial(opts: StyledMaterialOptions): StyledMateria
   // supermap 完整版：官方 sRGB 直乘管线（配合 setSrgbTextureDecode(false)）
   const direct = (opts.colorPipeline ?? colorPipeline) === 'direct';
   if (direct) mat.defines = { ...mat.defines, S3M_DIRECT_COLOR: '' };
+  const bakeMercator = !!opts.bakeMercator;
+  if (bakeMercator) mat.defines = { ...(mat.defines as Record<string, string>), S3M_BAKED_MERCATOR: '' };
   // 官方 uTextureDim = (base宽, base高, bake宽, bake高)，取实际绑定纹理的像素尺寸
   const uAtlasDim = { value: new THREE.Vector2(opts.map?.image?.width || 1, opts.map?.image?.height || 1) };
   const uAtlasDim1 = { value: new THREE.Vector2(secMap?.image?.width || 1, secMap?.image?.height || 1) };
 
+  const uTilePivot = { value: opts.tilePivot ? opts.tilePivot.clone() : new THREE.Vector3(0, 0, 0) };
+  const uInvTileScale = { value: opts.invTileScale ? opts.invTileScale.clone() : new THREE.Vector3(1, 1, 1) };
+
   mat.onBeforeCompile = (shader) => {
     Object.assign(shader.uniforms, uniforms, {
+      uTilePivot,
+      uInvTileScale,
       uSelBatch,
       uSelWhole,
       uFlatShading,
@@ -1349,6 +1373,8 @@ export function createStyledMaterial(opts: StyledMaterialOptions): StyledMateria
   mat.userData.uTileFade = uTileFade;
   // 平面 / 平滑着色开关：S3MViewer._applyShading 翻它，不触发重编译
   mat.userData.uFlatShading = uFlatShading;
+  mat.userData.uTilePivot = uTilePivot;
+  mat.userData.uInvTileScale = uInvTileScale;
   // 记录创建参数：materialQuality 运行时切换时按原参数重建材质（换类不换外观）
   mat.userData.s3mOpts = opts;
   // 记录实际生效的档位：重建 / 排查时不用再猜当时读的是哪一层设置