s3m-three 0.4.26 → 0.4.28

package/dist/render/S3MViewer.js

@@ -45,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;
@@ -71,6 +80,11 @@ function clampOpacity(v) {
 }
 /** 低于这个透明度就当作完全不可见：跳过绘制，避免全透明物体写深度 */
 const OPACITY_EPS = 1e-3;
+/**
+ * 拾取反解瓦片级放置时的临时矩阵。命中点→规范 ENU 是一次独立查询（鼠标事件），
+ * 复用一个实例避免每次分配；不可重入（`_toCanonicalScene` 内部不递归调用）。
+ */
+const _tilePlacementInverse = new THREE.Matrix4();
 /* ------------------------------------------------------------------ 可动画的样式键 */
 /**
  * 能逐帧插值的标量样式键。
@@ -153,6 +167,8 @@ export class S3MViewer {
      * 传了值就只认自己，多图层同页各用各的，互不覆盖。
      */
     _materialQuality;
+    _lodTransition;
+    _fallbackOffset;
     /**
      * 本图层的颜色管线。
      *
@@ -181,6 +197,7 @@ export class S3MViewer {
     }
     set sceneAnchor(val) {
         this._datasetManager.sceneAnchor = val;
+        this._reapplyTilePlacements();
     }
     /** 拾取表 / pickId 池 / 射线求交（见 viewer/PickService.ts） */
     _picks;
@@ -248,6 +265,13 @@ export class S3MViewer {
      */
     _motionBlurCfg = null;
     _motionBlur = null;
+    /**
+     * 瓦片级放置（默认关）。关时 `_registerTile` 完全不碰瓦片矩阵，代码路径与改动前
+     * 逐字一致；开时每块瓦片用自己的中心纬度算尺度，见 `tilePlacement.ts`。
+     */
+    _perTilePlacement;
+    /** 本层绘制前深度缓冲的处理策略：'scene' | 'clear' | 'auto'，默认 'scene' */
+    _depthMode = 'scene';
     /** 宿主请求重画（MapLibre 传 triggerRepaint，纯 three 宿主传自己的渲染循环） */
     _requestRepaint() {
         this._onRequestRepaint();
@@ -261,6 +285,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);
@@ -269,6 +297,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;
         }
@@ -343,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),
         });
@@ -573,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 之前调用会抛错。 */
@@ -581,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);
@@ -623,6 +670,8 @@ export class S3MViewer {
     /** 当地图 CRS 投影切换或宿主 map 挂载后，重新计算场景锚点与各数据集 offset */
     recomputeAnchors() {
         this._datasetManager.recomputeAnchors(this.geo);
+        // 锚点变了 → 每块瓦片的 k 与 position 都要重算（关这项功能时是空转，一次遍历都不做）
+        this._reapplyTilePlacements();
         this._heights.refreshAll();
         this._requestRepaint();
     }
@@ -1358,6 +1407,32 @@ export class S3MViewer {
     }
     /* ---------------------------------------------------------------- 瓦片注册 */
     _registerTile(node, entry) {
+        // 必须在 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]
+                    : [0, 0, 0];
+                this._updateTileUniforms(node.group, c, [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;
@@ -1427,6 +1502,142 @@ export class S3MViewer {
             this._sel.replayOnto(mesh);
         }
     }
+    /**
+     * 瓦片几何在**数据集局部 ENU** 里的包围盒中心，给没有包围球的瓦片兜底。
+     *
+     * 调用时机固定在 `entry.root.add()` 之前：此时 group 还没挂到 root 上、matrix 还是
+     * 单位阵，`setFromObject` 得到的就是顶点自己的坐标系，正好是摆放要的枢轴。
+     * 挂上 root 之后再算会带上 root 的 offset，枢轴就偏了。
+     */
+    _localCenterOf(group) {
+        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()` 有机会覆盖回来。
+     */
+    _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);
+            }
+        }
+    }
     /**
      * 新瓦片淡入。
      *
@@ -1881,6 +2092,16 @@ 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();
     }
@@ -1901,6 +2122,55 @@ export class S3MViewer {
         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;
     }
@@ -2194,10 +2464,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 米制坐标。
@@ -2218,8 +2489,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) };
     }
     /**
@@ -2645,9 +2917,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);
@@ -2694,6 +2968,19 @@ 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();
         // 完全透明时什么都不画：透明物体照样写深度，画了会在底图上挖出一个洞。
         // 这里跳过的是「本层的绘制」，宿主自己的清屏 / 底图照旧。
@@ -2707,7 +2994,10 @@ export class S3MViewer {
             }
             // GPU 描边必须画在主场景之后：它的全屏 quad 参与宿主深度测试，
             // 依赖本帧已经写好的深度（被地形挡住的地方不该描边）
-            this._edges.renderGpuEdges(canvas);
+            // clear 模式下宿主深度已清除，描边会穿透地形产生伪影，故只在非 clear 时画。
+            if (effectiveDepthMode !== 'clear') {
+                this._edges.renderGpuEdges(canvas);
+            }
         }
         this._frame++;
         const now = performance.now();