s3m-three 0.4.25 → 0.4.27

package/dist/render/S3MViewer.js

@@ -35,6 +35,7 @@ import { decodeTextureWithWorker } from '../worker/S3MWorkerClient.js';
 import { STYLE, STYLE_LABELS, SELECT_MODE, DEFAULT_STYLE, createSharedUniforms, createStyledMaterial, createOutlineMaterial, restoreBaseBlendState, } from './StyleMaterial.js';
 import { applyPointCloudStyle, isOwnedPointCloudMaterial } from './PointCloudMaterial.js';
 import { Picker } from './Picker.js';
+import { MotionBlurPass, normalizeMotionBlur, autoMotionBlurDamp } from './MotionBlurPass.js';
 import { Animator } from '../anim/Animator.js';
 import { buildClipPlanes, lineOfSight as computeLineOfSight, measureSegment, polygonArea, polygonAreaHorizontal, polygonPerimeter, polylineLength, polylineLengthHorizontal, } from '../analysis/index.js';
 import { skylineFromDepth } from '../analysis/skyline.js';
@@ -44,10 +45,19 @@ import { Path } from '../anim/Path.js';
 import { GPUPathManager } from './GPUPathManager.js';
 import { AttributeQuery } from '../core/AttributeQuery.js';
 import { lngLatFromWorld, worldFromLngLat } from './GeoAdapter.js';
+import { computeTilePlacement } from './tilePlacement.js';
 import { DatasetManager, } from './DatasetManager.js';
 import { FeatureStyleManager, extractEulerAngles, } from './FeatureStyleManager.js';
 import { GroundManager, } from './GroundManager.js';
 export { GroundManager, DatasetManager, FeatureStyleManager };
+/** 稳健归一化 depthMode 入参，默认 'scene' */
+export function normalizeDepthMode(mode) {
+    if (mode === 'clear')
+        return 'clear';
+    if (mode === 'auto')
+        return 'auto';
+    return 'scene';
+}
 function styledMaterialOf(mesh) {
     const m = Array.isArray(mesh.material) ? mesh.material[0] : mesh.material;
     const styled = m;
@@ -70,6 +80,11 @@ function clampOpacity(v) {
 }
 /** 低于这个透明度就当作完全不可见：跳过绘制，避免全透明物体写深度 */
 const OPACITY_EPS = 1e-3;
+/**
+ * 拾取反解瓦片级放置时的临时矩阵。命中点→规范 ENU 是一次独立查询（鼠标事件），
+ * 复用一个实例避免每次分配；不可重入（`_toCanonicalScene` 内部不递归调用）。
+ */
+const _tilePlacementInverse = new THREE.Matrix4();
 /* ------------------------------------------------------------------ 可动画的样式键 */
 /**
  * 能逐帧插值的标量样式键。
@@ -152,6 +167,8 @@ export class S3MViewer {
      * 传了值就只认自己，多图层同页各用各的，互不覆盖。
      */
     _materialQuality;
+    _lodTransition;
+    _fallbackOffset;
     /**
      * 本图层的颜色管线。
      *
@@ -180,6 +197,7 @@ export class S3MViewer {
     }
     set sceneAnchor(val) {
         this._datasetManager.sceneAnchor = val;
+        this._reapplyTilePlacements();
     }
     /** 拾取表 / pickId 池 / 射线求交（见 viewer/PickService.ts） */
     _picks;
@@ -241,6 +259,19 @@ export class S3MViewer {
     _unsupported;
     /** LOD 判定屏幕高度的 DPR 上限。Infinity = 不截断（默认，行为同旧版） */
     _lodPixelRatioCap = Infinity;
+    /**
+     * 运动模糊配置（默认 null = 关闭）。归一化后的形状见 `normalizeMotionBlur`；
+     * pass 延迟到首帧才建（构造期 renderer 都还没有）。
+     */
+    _motionBlurCfg = null;
+    _motionBlur = null;
+    /**
+     * 瓦片级放置（默认关）。关时 `_registerTile` 完全不碰瓦片矩阵，代码路径与改动前
+     * 逐字一致；开时每块瓦片用自己的中心纬度算尺度，见 `tilePlacement.ts`。
+     */
+    _perTilePlacement;
+    /** 本层绘制前深度缓冲的处理策略：'scene' | 'clear' | 'auto'，默认 'scene' */
+    _depthMode = 'scene';
     /** 宿主请求重画（MapLibre 传 triggerRepaint，纯 three 宿主传自己的渲染循环） */
     _requestRepaint() {
         this._onRequestRepaint();
@@ -254,12 +285,23 @@ 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);
         // 只记本层的档位，**不写模块级全局**：以前这里 setMaterialQuality(...) 会把全局
         // 改掉，于是同页后创建的图层顺手把先创建的图层也打回去了（多层互相覆盖的根因）。
         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;
         }
@@ -334,6 +376,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),
         });
@@ -355,9 +398,18 @@ export class S3MViewer {
             styleTarget: this._styleTarget,
             animator: this.animator,
             pickables: this._picks.pickables,
-            scene: this.scene,
-            renderer: this.renderer,
-            camera: this.camera,
+            // mount() / restoreContext() 都会换掉 scene / renderer / camera，这里必须用
+            // getter 拿「当下」的实例 —— 拆分 EdgeDecorator 时曾误写成值快照，mount 之后
+            // host.renderer 恒为 null，GPU 描边（和 loadCreases 挂线）静默失效
+            get scene() {
+                return self.scene;
+            },
+            get renderer() {
+                return self.renderer;
+            },
+            get camera() {
+                return self.camera;
+            },
             authenticate: this._authenticate,
             requestRepaint: () => this.triggerRepaint(),
         });
@@ -482,6 +534,8 @@ export class S3MViewer {
         this._lights.dispose();
         this.outlineMaterial.dispose();
         this._edges.disposeGpuEdge();
+        this._motionBlur?.dispose();
+        this._motionBlur = null;
         this.edgeMaterial.dispose();
         this.selectionEdgeMaterial.dispose();
         this.scene?.clear();
@@ -553,7 +607,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 [];
     }
     /** 追加一个数据集。图层 addLayer 之前调用会抛错。 */
@@ -561,7 +623,12 @@ export class S3MViewer {
         if (!this.scene)
             throw new Error('[s3m] 图层尚未 addLayer，不能添加数据集');
         // 图层级默认值：数据集自己指定了就用自己的，见 `S3MViewerOptions.unsupported`
-        const merged = { ...ds, unsupported: ds.unsupported ?? this._unsupported };
+        const merged = {
+            ...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, this.geo, this.uniforms, this._lodRangeScale, this.options.buildTile, this.options.maxTiles ?? 64, this.options.maxConcurrent ?? 4, {
             onTile: (node, e) => {
                 this._registerTile(node, e);
@@ -603,6 +670,8 @@ export class S3MViewer {
     /** 当地图 CRS 投影切换或宿主 map 挂载后，重新计算场景锚点与各数据集 offset */
     recomputeAnchors() {
         this._datasetManager.recomputeAnchors(this.geo);
+        // 锚点变了 → 每块瓦片的 k 与 position 都要重算（关这项功能时是空转，一次遍历都不做）
+        this._reapplyTilePlacements();
         this._heights.refreshAll();
         this._requestRepaint();
     }
@@ -1338,6 +1407,20 @@ export class S3MViewer {
     }
     /* ---------------------------------------------------------------- 瓦片注册 */
     _registerTile(node, entry) {
+        // 必须在 add / updateMatrixWorld 之前设置：后者会拿当前 matrix 算 matrixWorld 并缓存
+        if (this._perTilePlacement && node.sphere) {
+            this._applyTilePlacement(node.group, node.sphere.center, entry);
+        }
+        else {
+            const sceneAnchor = this.sceneAnchor;
+            if (sceneAnchor) {
+                const sEast = sceneAnchor.meterInMercatorEast ?? sceneAnchor.meterInMercator;
+                const sNorth = sceneAnchor.meterInMercatorNorth ?? sceneAnchor.meterInMercator;
+                const sUp = sceneAnchor.meterInMercatorUp ?? sEast;
+                const center = node.sphere ? [node.sphere.center.x, node.sphere.center.y, node.sphere.center.z] : [0, 0, 0];
+                this._updateTileUniforms(node.group, center, [1.0 / sEast, 1.0 / sNorth, 1.0 / sUp]);
+            }
+        }
         entry.root.add(node.group);
         node.group.updateMatrixWorld(true);
         const hasNativeEdges = node.group.userData.hasNativeEdges === true;
@@ -1407,6 +1490,124 @@ export class S3MViewer {
             this._sel.replayOnto(mesh);
         }
     }
+    /**
+     * 把一块瓦片摆到「用它自己中心纬度算出的尺度」上（`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()` 有机会覆盖回来。
+     */
+    _applyTilePlacement(group, center, entry) {
+        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.tileCenter = {
+            x: center.x,
+            y: center.y,
+            z: center.z,
+        };
+        // 逆矩阵缓存：_toCanonicalScene 常态路径无需每次拾取反复求逆，失效点仅在瓦片放置或重锚点
+        const inv = (group.userData.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);
+    }
+    _updateTileUniforms(group, pivot, invTileScale) {
+        group.traverse((obj) => {
+            const mesh = obj;
+            if ((obj.isMesh || obj.isPoints) && obj.material) {
+                const mats = Array.isArray(mesh.material) ? mesh.material : [mesh.material];
+                for (const m of mats) {
+                    const uPivot = m.userData?.uTilePivot;
+                    const uScale = m.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
+     * ```
+     *
+     * 关掉本功能、或网格不在已放置的瓦片里时**原样返回同一个对象**，
+     * 默认路径一次矩阵运算都不做。
+     */
+    _toCanonicalScene(p, mesh) {
+        if (!this._perTilePlacement || !mesh)
+            return p;
+        // 网格直接挂在瓦片 group 下（`_registerTile` 就是遍历 node.group.children）；
+        // 往上找到第一个带 tileCenter 的祖先，避免依赖层级深度
+        let group = mesh.parent;
+        while (group && !group.userData.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.placementInverse ?? _tilePlacementInverse.copy(group.matrix).invert())
+            .add(root.position);
+    }
+    /**
+     * 场景锚点变了（`recomputeAnchors`）之后，所有已注册瓦片的放置都要重算 ——
+     * `k` 与 `position` 都依赖场景锚点。没存 `tileCenter` 的（未开启本功能时注册的）
+     * 一律跳过，保证默认路径不产生任何副作用。
+     */
+    _reapplyTilePlacements() {
+        for (const entry of this._datasetManager.values()) {
+            if (!entry.anchor)
+                continue;
+            for (const child of entry.root.children) {
+                const c = child.userData.tileCenter;
+                if (c)
+                    this._applyTilePlacement(child, c, entry);
+            }
+        }
+    }
     /**
      * 新瓦片淡入。
      *
@@ -1861,9 +2062,88 @@ export class S3MViewer {
         this._requestRepaint();
     }
     /** 当前材质质感档位（本图层指定了就用本图层的，否则是模块级默认） */
+    get lodTransition() {
+        return this._lodTransition;
+    }
+    setLodTransition(mode) {
+        if (this._lodTransition === mode)
+            return;
+        this._lodTransition = mode;
+        this._datasetManager.setDefaultLodTransition(mode);
+        this.triggerRepaint();
+    }
     get materialQuality() {
         return this._materialQuality ?? getMaterialQuality();
     }
+    /**
+     * 运行时开关运动模糊后处理；`null` / 非法入参 = 关闭并立即释放 RT 显存。
+     *
+     * 这是纯视觉补偿（见 `motionBlur` 选项），对渲染管线唯一的结构性影响是开启期间
+     * 「场景 → 屏幕」改走 RT 中转（合成 quad 会补回色调映射 / sRGB / 深度）。
+     * WebGL1 上开了也自动回退直渲。`damp: 'auto'` 每帧按实时 FPS 重新解析。
+     */
+    setMotionBlur(cfg) {
+        this._motionBlurCfg = normalizeMotionBlur(cfg);
+        if (!this._motionBlurCfg) {
+            this._motionBlur?.dispose();
+            this._motionBlur = null;
+        }
+        // 走公共 triggerRepaint：宿主 / 单测会覆盖前者来观察重绘（同其它 setter 的观测点）
+        this.triggerRepaint();
+    }
+    /** 当前运动模糊配置（归一化后的副本）；null = 关闭 */
+    /**
+     * 运行时修改深度处理策略（'scene' | 'clear' | 'auto'）。
+     */
+    setDepthMode(mode) {
+        const next = normalizeDepthMode(mode);
+        if (this._depthMode !== next) {
+            this._depthMode = next;
+            this.triggerRepaint();
+        }
+    }
+    /** 当前深度策略（'scene' | 'clear' | 'auto'，默认 'scene'） */
+    get depthMode() {
+        return this._depthMode;
+    }
+    /**
+     * 当前帧实际生效的深度处理模式（'scene' | 'clear'）。
+     * - 'clear': 显式指定 clear，或 auto 模式下命中地面覆盖/倾斜摄影/DEM等地面类数据
+     * - 'scene': 显式指定 scene，或 auto 模式下无地面类数据
+     */
+    resolveDepthMode() {
+        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;
+            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() {
+        return this._motionBlurCfg ? { ...this._motionBlurCfg } : null;
+    }
     /**
      * 运行时切换**本图层**的颜色管线（`'linear'` | `'direct'`）。
      *
@@ -2154,10 +2434,11 @@ export class S3MViewer {
         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)];
     }
     /**
      * 经纬度 + 绝对高程 → 场景 ENU 米制坐标。
@@ -2178,8 +2459,9 @@ export class S3MViewer {
         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) };
     }
     /**
@@ -2553,6 +2835,33 @@ export class S3MViewer {
     _sortSplats() {
         this._splats.sort(this.camera, this._pointClouds);
     }
+    /**
+     * 运动模糊路径（`_motionBlurCfg` 非空时接管「场景 → 屏幕」）。
+     *
+     * 返回 false = 不能用（WebGL1 / 尺寸非法），调用方回退直渲 —— 配置保留不丢，
+     * 上下文恢复成 WebGL2 后下一帧自动生效。
+     * `damp: 'auto'` 在这里按实时 FPS 解析（fps 为 0 的启动阶段按 60fps 保守取值），
+     * `maxOffset` 已在 `normalizeMotionBlur` 里归一化（默认 0.05，屏宽百分比）。
+     */
+    _renderMotionBlur(width, height) {
+        const renderer = this.renderer;
+        const scene = this.scene;
+        const camera = this.camera;
+        const cfg = this._motionBlurCfg;
+        if (!renderer || !scene || !camera || !cfg)
+            return false;
+        this._motionBlur ||= new MotionBlurPass();
+        if (!this._motionBlur.supported(renderer))
+            return false;
+        this._motionBlur.render(renderer, scene, camera, width, height, {
+            mode: cfg.mode,
+            damp: cfg.damp === 'auto' ? autoMotionBlurDamp(this.fps) : cfg.damp,
+            maxOffset: cfg.maxOffset,
+            mvp: this._frameMvp,
+            mvpInverse: camera.projectionMatrixInverse,
+        });
+        return true;
+    }
     /**
      * 渲染一帧。所有宿主相关量都由调用方喂进来，viewer 不碰任何地图 API：
      *
@@ -2578,9 +2887,11 @@ 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, 0, 0, 0, 1);
+        this._enuMatrix.set(sEast, 0, 0, this.sceneAnchor.x, 0, -sNorth, 0, this.sceneAnchor.y, 0, 0, sUp, this.sceneAnchor.z, 0, 0, 0, 1);
         // 正交模式由宿主在传入 mvp 前自行替换（见 s3m-maplibre 的 S3MLayer._applyOrtho），
         // 视图矩阵是从宿主输入反推的（P⁻¹×MVP），不会和宿主的 pan/zoom/pitch 错位。
         const mvp = this._frameMvp.fromArray(opts.mvp);
@@ -2627,15 +2938,36 @@ export class S3MViewer {
         // 泼溅的最小像素半径 / 抗锯齿低通同样要把 ndc 换算成像素
         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();
         // 完全透明时什么都不画：透明物体照样写深度，画了会在底图上挖出一个洞。
         // 这里跳过的是「本层的绘制」，宿主自己的清屏 / 底图照旧。
         if ((this.uniforms.uOpacity?.value ?? 1) > OPACITY_EPS) {
             this._sortSplats();
-            this.renderer.render(this.scene, this.camera);
+            if (this._motionBlurCfg && this._renderMotionBlur(canvas.width, canvas.height)) {
+                // 运动模糊接管了「场景 → 屏幕」：场景进 RT，合成 quad 补回色调映射 / sRGB / 深度
+            }
+            else {
+                this.renderer.render(this.scene, this.camera);
+            }
             // GPU 描边必须画在主场景之后：它的全屏 quad 参与宿主深度测试，
             // 依赖本帧已经写好的深度（被地形挡住的地方不该描边）
-            this._edges.renderGpuEdges(canvas);
+            // clear 模式下宿主深度已清除，描边会穿透地形产生伪影，故只在非 clear 时画。
+            if (effectiveDepthMode !== 'clear') {
+                this._edges.renderGpuEdges(canvas);
+            }
         }
         this._frame++;
         const now = performance.now();