s3m-three 0.3.0 → 0.3.2

package/dist/render/S3MViewer.js

@@ -21,8 +21,10 @@
  * MapLibre / Mapbox 的胶水层在 s3m-maplibre 包的 S3MLayer.ts。
  */
 import * as THREE from 'three';
+import { usableGeoBounds } from '../tileset/S3MTileset.js';
 import { setMaxAnisotropy } from './TextureFactory.js';
 import { STYLE, STYLE_LABELS, SELECT_MODE, DEFAULT_STYLE, createSharedUniforms, createOutlineMaterial, } from './StyleMaterial.js';
+import { applyPointCloudStyle, isOwnedPointCloudMaterial } from './PointCloudMaterial.js';
 import { Picker } from './Picker.js';
 import { buildFeatureEdgeSegments, buildThickLineGeometry, createLineSharedUniforms, createThickLineMaterial, } from './EdgeLines.js';
 import { resolveFeature, measureSegments, buildAttributes, buildInstanceLookup, pickEntryId, } from '../core/FeatureInfo.js';
@@ -38,6 +40,10 @@ function styledMaterialOf(mesh) {
     const styled = m;
     return styled?.userData?.isStyled ? styled : null;
 }
+/** 点云是 THREE.Points 不是 Mesh，样式 / 拾取 / 卸载链路都靠这个判定放行 */
+function isPointCloudObject(o) {
+    return o.isPoints === true;
+}
 /* ------------------------------------------------------------------ 图层 */
 export class S3MViewer {
     options;
@@ -103,8 +109,24 @@ export class S3MViewer {
     _needsRepaint = true;
     _frame = 0;
     _fps = { value: 0, last: 0 };
-    _keyLight = null;
-    _fillLight = null;
+    _ambientLight;
+    _hemiLight;
+    _keyLight;
+    _fillLight;
+    _lightOptions = {
+        ambientIntensity: 0.4,
+        ambientColor: 0xffffff,
+        hemisphereIntensity: 0.8,
+        hemisphereColor: 0xffffff,
+        hemisphereGroundColor: 0xb6c0cb,
+        keyLightIntensity: 1.0,
+        keyLightColor: 0xffffff,
+        fillLightIntensity: 0.35,
+        fillLightColor: 0xffffff,
+        mode: 'headlamp',
+        azimuth: 150,
+        altitude: 50,
+    };
     _datasetQueue;
     /** 宿主重画信号与地图朝向，构造时注入 */
     _onRequestRepaint = () => { };
@@ -114,10 +136,19 @@ export class S3MViewer {
     _requestRepaint() {
         this._onRequestRepaint();
     }
+    triggerRepaint() {
+        this._requestRepaint();
+    }
     constructor(options = {}) {
         this.options = options;
         this.pickable = options.pickable !== false;
         this._lodRangeScale = options.lodRangeScale ?? 1.0;
+        if (options.light) {
+            Object.assign(this._lightOptions, options.light);
+        }
+        if (options.totalMaxTiles) {
+            this._datasetManager.totalMaxTiles = options.totalMaxTiles;
+        }
         this._onRequestRepaint = options.onRequestRepaint ?? (() => { });
         this._getBearing = options.getBearing;
         this.onStats = options.onStats ?? (() => { });
@@ -125,6 +156,11 @@ export class S3MViewer {
         this.onPick = options.onPick ?? (() => { });
         this.onError = options.onError ?? ((e) => console.warn('[s3m]', e));
         this.groundManager = new GroundManager(options.ground);
+        if (!this.scene) {
+            this.scene = new THREE.Scene();
+            this.scene.add(this.groundManager.group);
+            this._addLights();
+        }
         this._featureStyleManager = new FeatureStyleManager(() => this.style.floorHeight, () => this._requestRepaint(), () => {
             if (this._selection)
                 this._syncSelectionStyle();
@@ -201,24 +237,64 @@ export class S3MViewer {
         this.renderer = null;
         this.canvas = null;
     }
+    _createLights() {
+        this._ambientLight = new THREE.AmbientLight(this._lightOptions.ambientColor, this._lightOptions.ambientIntensity);
+        this._hemiLight = new THREE.HemisphereLight(this._lightOptions.hemisphereColor, this._lightOptions.hemisphereGroundColor, this._lightOptions.hemisphereIntensity);
+        this._keyLight = new THREE.DirectionalLight(this._lightOptions.keyLightColor, this._lightOptions.keyLightIntensity);
+        this._fillLight = new THREE.DirectionalLight(this._lightOptions.fillLightColor, this._lightOptions.fillLightIntensity);
+        this._updateLights();
+    }
     _addLights() {
         if (!this.scene)
             return;
-        // 环境光与天光打底，保证背光面和折叠处不死黑
-        this.scene.add(new THREE.AmbientLight(0xffffff, 0.4));
-        this.scene.add(new THREE.HemisphereLight(0xffffff, 0xb6c0cb, 0.8));
-        // 主光 / 补光的方向每帧按地图朝向重算（见 _updateLights），
-        // 这样旋转视角时白模始终是亮的，不会转到背光面就一片死灰。
-        this._keyLight = new THREE.DirectionalLight(0xffffff, 1.0);
-        this._fillLight = new THREE.DirectionalLight(0xffffff, 0.35);
-        this.scene.add(this._keyLight, this._fillLight);
+        if (!this._ambientLight)
+            this._createLights();
+        this.scene.add(this._ambientLight, this._hemiLight, this._keyLight, this._fillLight);
+    }
+    _applyLightOptions() {
+        if (this._ambientLight) {
+            this._ambientLight.intensity = this._lightOptions.ambientIntensity;
+            this._ambientLight.color.set(this._lightOptions.ambientColor);
+        }
+        if (this._hemiLight) {
+            this._hemiLight.intensity = this._lightOptions.hemisphereIntensity;
+            this._hemiLight.color.set(this._lightOptions.hemisphereColor);
+            this._hemiLight.groundColor.set(this._lightOptions.hemisphereGroundColor);
+        }
+        if (this._keyLight) {
+            this._keyLight.intensity = this._lightOptions.keyLightIntensity;
+            this._keyLight.color.set(this._lightOptions.keyLightColor);
+        }
+        if (this._fillLight) {
+            this._fillLight.intensity = this._lightOptions.fillLightIntensity;
+            this._fillLight.color.set(this._lightOptions.fillLightColor);
+        }
+    }
+    /**
+     * 动态设置光照配置
+     */
+    setLight(options) {
+        Object.assign(this._lightOptions, options);
+        this._applyLightOptions();
+        this._updateLights();
+        this._needsRepaint = true;
+        this.triggerRepaint();
     }
     /**
-     * 让光照跟着地图朝向走：主光在镜头后上方偏左，补光在后上方偏右。
-     * 相当于一盏头灯，看到的立面永远是受光面。
+     * 获取当前光照配置快照
+     */
+    getLight() {
+        return { ...this._lightOptions };
+    }
+    /**
+     * 更新光照位置与方向：
+     * - 'headlamp': 随地图方位角 bearing 旋转，主光始终在镜头上方，受光面面向镜头；
+     * - 'fixed': 固定世界方位角（如模拟恒定日光）。
      */
     _updateLights() {
-        const bearing = ((this._getBearing?.() ?? 0) * Math.PI) / 180;
+        if (!this._keyLight || !this._fillLight)
+            return;
+        const bearing = this._lightOptions.mode === 'fixed' ? 0 : (((this._getBearing?.() ?? 0) * Math.PI) / 180);
         const place = (light, azOffsetDeg, elevDeg) => {
             if (!light)
                 return;
@@ -227,8 +303,8 @@ export class S3MViewer {
             const c = Math.cos(el);
             light.position.set(Math.sin(az) * c, Math.cos(az) * c, Math.sin(el)).multiplyScalar(1000);
         };
-        place(this._keyLight, 150, 50);
-        place(this._fillLight, 215, 30);
+        place(this._keyLight, this._lightOptions.azimuth, this._lightOptions.altitude);
+        place(this._fillLight, this._lightOptions.azimuth + 65, Math.max(10, this._lightOptions.altitude - 20));
     }
     /* ---------------------------------------------------------------- 数据集 */
     _normalizeDatasets(options) {
@@ -323,8 +399,12 @@ export class S3MViewer {
     /**
      * 物理地表网格的高度跟随「主数据集的应用层抬升量」，
      * 保证贴地后地表覆盖 / 地下透视的物理关系与被抬升的模型一致。
+     * `ground.trackHeight = false` 时不跟随：地表钉在当前高度，
+     * 高程调整只动模型不动切割面。
      */
     _syncGroundHeight() {
+        if (!this.groundManager.trackHeight)
+            return;
         const primaryId = this.datasets.keys().next().value;
         if (!primaryId)
             return;
@@ -455,6 +535,14 @@ export class S3MViewer {
         this.groundManager.setExcavationBounds(bounds);
         this._requestRepaint();
     }
+    /**
+     * 开关「物理地表作为深度遮挡源」：开启后地表以下的几何被真正切掉。
+     * 不依赖宿主是否开启 MapLibre terrain——深度缓冲是共用的，谁更近谁遮挡。
+     */
+    setGroundOcclude(enabled) {
+        this.groundManager.setOcclude(enabled);
+        this._requestRepaint();
+    }
     /* ---------------------------------------------------------------- 状态纹理同步 */
     _isFeatureHidden(smid, _batchId) {
         if (smid == null)
@@ -529,6 +617,8 @@ export class S3MViewer {
                 const styled = styledMaterialOf(mesh);
                 if (styled)
                     styled.dispose();
+                if (isOwnedPointCloudMaterial(mesh.material))
+                    mesh.material.dispose();
                 this._featureStyleManager.disposeMesh(mesh);
             });
         });
@@ -561,8 +651,10 @@ export class S3MViewer {
                 this._styleEdgeLine(child);
                 continue;
             }
+            // 点云是 THREE.Points 不是 Mesh，但同样要进拾取表、吃不透明度、跟着着色模式走
+            const isPoints = isPointCloudObject(child);
             const mesh = child;
-            if (!mesh.isMesh)
+            if (!mesh.isMesh && !isPoints)
                 continue;
             const ud = mesh.userData;
             ud.pickId = this._allocPickId();
@@ -576,42 +668,145 @@ export class S3MViewer {
             });
             this._indexMeshSmids(mesh);
             this._addMeshHeight(mesh);
-            if (this._edgesEnabled && !hasNativeEdges)
+            // 点云没有「棱」：给一堆孤立点建 EdgesGeometry 又慢又没意义
+            if (this._edgesEnabled && !hasNativeEdges && !isPoints)
                 this._ensureEdges(mesh);
             // 新瓦片要继承当前的不透明度与着色方式
-            const mat = styledMaterialOf(mesh);
-            if (mat) {
-                const o = Math.min(1, Math.max(0.05, this.style.opacity ?? 1));
-                mat.opacity = o;
-                mat.transparent = o < 0.999;
-                mat.depthWrite = o >= 0.999;
-                mat.flatShading = this.style.shading !== 'smooth';
-                mat.needsUpdate = true;
-                this._featureStyleManager.applyOverridesToMesh(mesh);
+            if (isPoints) {
+                this._applyPointCloudStyle(child);
+            }
+            else {
+                const mat = styledMaterialOf(mesh);
+                if (mat) {
+                    const o = Math.min(1, Math.max(0.05, this.style.opacity ?? 1));
+                    mat.opacity = o;
+                    mat.transparent = o < 0.999;
+                    mat.depthWrite = o >= 0.999;
+                    mat.flatShading = this.style.shading !== 'smooth';
+                    mat.needsUpdate = true;
+                    this._featureStyleManager.applyOverridesToMesh(mesh);
+                }
             }
+            // 选中状态也要跟着继承：LOD 细化 / 瓦片重载会换掉 mesh，
+            // 不重放就出现「点中的那栋楼一拉近就没高亮了」
+            this._replaySelectionOnto(mesh);
         }
     }
-    /** 瓦片被淘汰：从拾取表和场景里摘掉，并释放它自己的 GPU 资源 */
-    _unregisterTile(node, entry) {
-        for (const child of [...node.group.children]) {
-            const mesh = child;
-            if (!mesh.isMesh)
-                continue;
-            const ud = mesh.userData;
-            if (this._selection?.mesh === mesh || this._selectedMeshes.includes(mesh))
-                this.select(null);
-            if (ud.pickId != null) {
-                this._pickables.delete(ud.pickId);
-                this._releasePickId(ud.pickId);
-                ud.pickId = undefined;
+    /**
+     * 把「当前选中」重放到一块新登记的 mesh 上。
+     *
+     * 为什么需要：选中高亮是直接写在各 mesh 材质的 uSelBatch / uSelWhole 上的，
+     * 而 LOD 细化、瓦片重载、淘汰回补都会换掉 mesh —— 不重放的话，用户点中的那栋楼
+     * 一细化就失去高亮（状态还在 _selection.smid 里，只是没人往新 mesh 上刷）。
+     */
+    /**
+     * 判断一块无 SMID 单体化信息的网格（如倾斜摄影或白模整块）是否空间覆盖当前选中命中点
+     */
+    _isMeshCoveringSelection(mesh, sel) {
+        if (!sel.point)
+            return false;
+        const geom = mesh.geometry;
+        if (!geom)
+            return false;
+        if (!geom.boundingBox)
+            geom.computeBoundingBox();
+        if (!geom.boundingBox)
+            return false;
+        // 将选中的三维场景点转入网格局部坐标系进行包围盒检测
+        const pt = new THREE.Vector3(sel.point[0], sel.point[1], sel.point[2]);
+        mesh.updateWorldMatrix(true, false);
+        const inv = mesh.matrixWorld.clone().invert();
+        const localPt = pt.applyMatrix4(inv);
+        // 留出 0.5 米容差，避免刚好处于三角网格边缘缝隙时漏判
+        const box = geom.boundingBox.clone().expandByScalar(0.5);
+        return box.containsPoint(localPt);
+    }
+    _replaySelectionOnto(mesh) {
+        const sel = this._selection;
+        if (!sel)
+            return;
+        const mat = styledMaterialOf(mesh);
+        if (!mat)
+            return;
+        const ud = mesh.userData;
+        let batchId = -1;
+        if (sel.smid != null) {
+            const pickInfo = ud.geoRef?.pickInfo;
+            const entry = pickInfo?.[sel.smid] ?? pickInfo?.[String(sel.smid)];
+            batchId = entry ? pickEntryId(entry) : -1;
+        }
+        // 拾取命中的那块 mesh 用原始 batchId；同一 smid 散在别的几何里时按各自的区间算
+        if (mesh === sel.mesh)
+            batchId = sel.batchId;
+        // 这块几何里根本没有这个单体 → 不动它（否则会把无关瓦片一起点亮）
+        if (batchId < 0 && mesh !== sel.mesh) {
+            if (sel.smid == null && ud.datasetId === sel.datasetId && this._isMeshCoveringSelection(mesh, sel)) {
+                batchId = -1;
+            }
+            else {
+                return;
             }
-            this._unindexMeshSmids(mesh);
-            this._removeMeshHeight(mesh);
-            this._featureStyleManager.disposeMesh(mesh);
-            const styled = styledMaterialOf(mesh);
-            styled?.dispose?.();
-            mesh.geometry?.dispose?.();
         }
+        mat.userData.uSelBatch.value = batchId;
+        mat.userData.uSelWhole.value = batchId < 0 ? 1 : 0;
+        if (!this._selectedMeshes.includes(mesh))
+            this._selectedMeshes.push(mesh);
+        if (isPointCloudObject(mesh))
+            this._applyPointCloudStyle(mesh, true);
+        this.uniforms.uSelMix.value = 1;
+        this.uniforms.uDim.value = this.style.dimOthers ? 1 : 0;
+    }
+    /** 瓦片被淘汰：从拾取表和场景里摘掉，并深度彻底释放所有几何体与材质显存 */
+    _unregisterTile(node, entry) {
+        node.group.traverse((child) => {
+            const obj = child;
+            if (obj.userData?.pickId != null) {
+                this._pickables.delete(obj.userData.pickId);
+                this._releasePickId(obj.userData.pickId);
+                obj.userData.pickId = undefined;
+            }
+            if (obj.isMesh) {
+                const wasSelected = this._selectedMeshes.includes(obj);
+                if (wasSelected) {
+                    this._selectedMeshes = this._selectedMeshes.filter((m) => m !== obj);
+                }
+                const currentSel = this._selection;
+                if (currentSel && currentSel.mesh === obj) {
+                    const smid = currentSel.smid;
+                    const carrier = (smid != null
+                        ? [...(this._smidMeshes.get(smid) ?? [])].find((m) => m !== obj && m.parent)
+                        : this._selectedMeshes.find((m) => m !== obj && m.parent && m.parent.visible) ??
+                            this._selectedMeshes.find((m) => m !== obj && m.parent));
+                    if (carrier) {
+                        // 选中身份交给承载同一 smid 的另一块 mesh（通常是接替显示的子瓦）
+                        this._selection = { ...currentSel, mesh: carrier };
+                        this._replaySelectionOnto(carrier);
+                    }
+                    else {
+                        this.select(null);
+                    }
+                }
+                this._unindexMeshSmids(obj);
+                this._removeMeshHeight(obj);
+                this._featureStyleManager.disposeMesh(obj);
+                const styled = styledMaterialOf(obj);
+                styled?.dispose?.();
+            }
+            // 深度释放材质（点云、普通材质、材质数组）
+            if (isOwnedPointCloudMaterial(obj.material)) {
+                obj.material.dispose();
+            }
+            else if (obj.material) {
+                if (Array.isArray(obj.material)) {
+                    obj.material.forEach((m) => m?.dispose?.());
+                }
+                else {
+                    obj.material.dispose?.();
+                }
+            }
+            // 释放几何体显存缓冲
+            obj.geometry?.dispose?.();
+        });
         entry.root.remove(node.group);
     }
     /**
@@ -644,6 +839,9 @@ export class S3MViewer {
         this._applyStyleUniforms();
         if ('opacity' in patch || 'depthWrite' in patch)
             this._applyOpacity();
+        // 点云不走 StyleMaterial 的 uMode，模式切换要单独同步它的材质
+        if ('mode' in patch)
+            this._applyPointCloudStyles();
         if ('shading' in patch)
             this._applyShading();
         if ('edges' in patch)
@@ -718,6 +916,10 @@ export class S3MViewer {
         // 关键：若 depthWrite 开启（默认开启），即使半透明也保持深度写入，完美遮挡背面棱线，防止背面线条透出
         const keepDepth = this.style.depthWrite !== false;
         for (const p of this._pickables.values()) {
+            if (isPointCloudObject(p.mesh)) {
+                this._applyPointCloudStyle(p.mesh);
+                continue;
+            }
             const m = styledMaterialOf(p.mesh);
             if (!m)
                 continue;
@@ -727,6 +929,18 @@ export class S3MViewer {
         }
         this._requestRepaint();
     }
+    /** 单个点云对象同步当前样式（着色模式 + 不透明度 + 选中高亮） */
+    _applyPointCloudStyle(points, selected = this._selectedMeshes.includes(points)) {
+        applyPointCloudStyle(points, this.style, this.uniforms, selected);
+    }
+    /** 全部点云刷新：着色模式切换时用（uniform 是共享引用，改色不用走这里） */
+    _applyPointCloudStyles() {
+        for (const p of this._pickables.values()) {
+            if (isPointCloudObject(p.mesh))
+                this._applyPointCloudStyle(p.mesh);
+        }
+        this._requestRepaint();
+    }
     /** 平面/平滑着色：FLAT_SHADED 是编译期宏，改它必须重编译 */
     _applyShading() {
         const flat = this.style.shading !== 'smooth';
@@ -871,7 +1085,8 @@ export class S3MViewer {
             .map((p) => p.mesh)
             .filter((m) => {
             const ud = m.userData;
-            return !ud.edges && !ud.nativeEdges;
+            // 点云没有棱可描
+            return !ud.edges && !ud.nativeEdges && !isPointCloudObject(m);
         });
         let i = 0;
         const step = () => {
@@ -1379,8 +1594,13 @@ export class S3MViewer {
     select(result, { silent = false } = {}) {
         // 清掉上一次
         if (this._selection) {
-            for (const mesh of this._selectedMeshes) {
-                const mat = styledMaterialOf(mesh);
+            for (const obj of this._selectedMeshes) {
+                // 点云：恢复成当前着色模式（去掉选中混色）
+                if (isPointCloudObject(obj)) {
+                    this._applyPointCloudStyle(obj, false);
+                    continue;
+                }
+                const mat = styledMaterialOf(obj);
                 if (mat) {
                     mat.userData.uSelBatch.value = -1;
                     mat.userData.uSelWhole.value = 0;
@@ -1432,14 +1652,23 @@ export class S3MViewer {
             mat.userData.uSelWhole.value = batchId < 0 ? 1 : 0;
             this._selectedMeshes.push(mesh);
         }
+        // 点云没有单体粒度：整块混成 selectColor，让选中至少看得见
+        for (const mesh of this._selectedMeshes) {
+            if (isPointCloudObject(mesh))
+                this._applyPointCloudStyle(mesh, true);
+        }
         this.uniforms.uSelMix.value = 1;
         this.uniforms.uDim.value = this.style.dimOthers ? 1 : 0;
         if (this.style.outline) {
-            if ((this.style.outlineStyle ?? 'edges') === 'edges') {
-                this._addSelectionEdges(result, targetMeshes);
-            }
-            else {
-                this._addSelectionHull(result, targetMeshes);
+            // 棱线 / 外扩轮廓都是按「面」设计的，点云画不出来也不该画
+            const decoMeshes = [...targetMeshes].filter((m) => !isPointCloudObject(m));
+            if (decoMeshes.length) {
+                if ((this.style.outlineStyle ?? 'edges') === 'edges') {
+                    this._addSelectionEdges(result, decoMeshes);
+                }
+                else {
+                    this._addSelectionHull(result, decoMeshes);
+                }
             }
         }
         this._requestRepaint();
@@ -1706,7 +1935,8 @@ export class S3MViewer {
         let maxLon = -Infinity;
         let maxLat = -Infinity;
         for (const entry of this.datasets.values()) {
-            const b = entry.tileset?.config?.geoBounds;
+            // 同 DatasetManager.getBounds：退化 / 越界的 geoBounds 不参与，避免视角甩到 (0,0)
+            const b = usableGeoBounds(entry.tileset?.config?.geoBounds);
             if (!b)
                 continue;
             minLon = Math.min(minLon, b.left);