s3m-three 0.4.15 → 0.4.17

package/dist/render/S3MViewer.js

@@ -23,11 +23,12 @@
 import * as THREE from 'three';
 import { usableGeoBounds } from '../tileset/S3MTileset.js';
 import { setMaxAnisotropy, setCompressedTexturesSupported, setTextureOffThreadDecode, setMaxTextureSize as setTextureSizeCap } from './TextureFactory.js';
-import { setMaterialQuality } from './StyleMaterial.js';
+import { getMaterialQuality, setMaterialQuality } from './StyleMaterial.js';
 import { decodeTextureWithWorker } from '../worker/S3MWorkerClient.js';
-import { STYLE, STYLE_LABELS, SELECT_MODE, DEFAULT_STYLE, createSharedUniforms, createOutlineMaterial, } from './StyleMaterial.js';
+import { STYLE, STYLE_LABELS, SELECT_MODE, DEFAULT_STYLE, createSharedUniforms, createStyledMaterial, createOutlineMaterial, resolveEdgeModes, sameEdgeModes, } from './StyleMaterial.js';
 import { applyPointCloudStyle, isOwnedPointCloudMaterial } from './PointCloudMaterial.js';
 import { Picker } from './Picker.js';
+import { GpuEdgePass } from './GpuEdgePass.js';
 import { Animator } from '../anim/Animator.js';
 import { Path } from '../anim/Path.js';
 import { GPUPathManager } from './GPUPathManager.js';
@@ -82,6 +83,8 @@ const STYLE_SCALAR_KEYS = [
     'ambientGain',
     'edgeWidth',
     'edgeOpacity',
+    'edgeOffset',
+    'edgeHullWidth',
     'outlineWidth',
 ];
 /** 能逐帧插值的颜色键（在线性空间插值，与 shader 消费端一致） */
@@ -120,6 +123,8 @@ export class S3MViewer {
     _edgeStyleUniforms;
     /** 选中棱线的外观 uniform */
     _selEdgeStyleUniforms;
+    /** 全局外扩轮廓的外观 uniform：逐网格轮廓壳共享这些对象 */
+    _hullStyleUniforms;
     /** 3D 物理地表面 / 基坑开挖管理器 */
     groundManager;
     /** 多数据集生命周期与锚点管理器 */
@@ -157,6 +162,12 @@ export class S3MViewer {
     _selectionEdges = null;
     _selectionEdgeMeshes = [];
     _edgesEnabled = false;
+    /** 当前生效的棱线画法（line / offset / hull / gpu），决定要不要建 / 拆哪种装饰 */
+    _edgeModes = resolveEdgeModes(false);
+    /** GPU 描边后处理（深度 + 法线），只在 edges 含 'gpu' 时按帧执行 */
+    _gpuEdge = null;
+    /** 给 GPU 描边传色用的临时 Color，避免每帧 new */
+    _gpuEdgeColor = new THREE.Color();
     /** 瓦片淡入通道的自增序号（不用 pickId：pickId 会被回收复用） */
     _tileFadeSeq = 0;
     /** setMode 编排的代次，用来作废被新调用顶掉的旧编排 */
@@ -281,6 +292,7 @@ export class S3MViewer {
             uColor: { value: new THREE.Color(this.style.edgeColor) },
             uWidth: { value: Math.max(0.1, this.style.edgeWidth ?? 1.5) },
             uOpacity: { value: 0.6 },
+            uOffset: { value: this.style.edgeOffset ?? 0.15 },
         };
         this.edgeMaterial = createThickLineMaterial(this.lineShared, {}, this._edgeStyleUniforms);
         this._selEdgeStyleUniforms = {
@@ -290,10 +302,16 @@ export class S3MViewer {
             uElevation: { value: this.style.selectElevation ?? 0 },
         };
         this.selectionEdgeMaterial = createThickLineMaterial(this.lineShared, {}, this._selEdgeStyleUniforms);
+        // 全局外扩轮廓的外观 uniform：逐网格轮廓壳复用这几个对象，改一次全场景生效
+        this._hullStyleUniforms = {
+            uColor: { value: new THREE.Color(this.style.edgeColor) },
+            uWidth: { value: Math.max(0, this.style.edgeHullWidth ?? 0.9) },
+            uOpacity: { value: 0.6 },
+        };
         // 关键：style.edges 是个开关，但构造函数从没据此启用过棱线，导致
         // `style: { edges: true }` 形同虚设、_edgesEnabled 永远是 false。
         // 这里按 style 实际值调一次 setEdges，让开关真正生效（与 setEdges 后来的手工调用一致）。
-        this.setEdges(!!this.style.edges);
+        this.setEdges(this.style.edges);
         // 初始化图层整体不透明度：确保共享 uniform uOpacity、材质混合开关与棱线外观与初始 style.opacity 严格一致
         this._applyOpacity();
         this._fps.last = performance.now();
@@ -371,6 +389,9 @@ export class S3MViewer {
         this._syncTextureCapabilities(gl);
         this.picker?.dispose();
         this.picker = new Picker(this.renderer);
+        // GPU 描边的 RT / 材质绑定在旧上下文上，整体丢弃，下一帧按需重建
+        this._gpuEdge?.dispose();
+        this._gpuEdge = null;
         // 共享 uniform / 材质引用不变，three 重新编译着色器时会自然接管；
         // 这里只确保下一帧尽快驱动一次渲染。
         this._requestRepaint();
@@ -384,6 +405,8 @@ export class S3MViewer {
         this.picker?.dispose();
         this.picker = null;
         this.outlineMaterial.dispose();
+        this._gpuEdge?.dispose();
+        this._gpuEdge = null;
         this.edgeMaterial.dispose();
         this.selectionEdgeMaterial.dispose();
         this.scene?.clear();
@@ -1302,11 +1325,16 @@ export class S3MViewer {
         entry.root.add(node.group);
         node.group.updateMatrixWorld(true);
         const hasNativeEdges = node.group.userData.hasNativeEdges === true;
+        // forceCpuEdges：无视数据自带的棱线包，改由 CPU 现算。native 是 1px 的
+        // LineBasicMaterial，edgeWidth / 外扩 / 单体跟随全都吃不上。
+        // gpu 画法由 shader 自己描边，native 线段包同样不能留
+        const useNativeEdges = hasNativeEdges && this.style.forceCpuEdges !== true && !this._edgeModes.gpu;
         for (const child of node.group.children) {
             // 数据自带的棱线包：只跟着 edges 开关显示，不参与拾取、不参与着色
             if (child.isLineSegments && child.userData.isEdgeLines) {
-                child.visible = this._edgesEnabled;
+                // 一律登记进 _nativeEdgeLines：forceCpuEdges 之后又关掉时还要能把它们放出来
                 this._nativeEdgeLines.add(child);
+                child.visible = useNativeEdges && this._edgesEnabled;
                 this._styleEdgeLine(child);
                 continue;
             }
@@ -1320,7 +1348,8 @@ export class S3MViewer {
             const ud = mesh.userData;
             ud.pickId = this._allocPickId();
             ud.datasetId = entry.id;
-            ud.nativeEdges = hasNativeEdges;
+            ud.nativeEdges = useNativeEdges;
+            ud.nativeEdgesRaw = hasNativeEdges;
             this._pickables.set(ud.pickId, {
                 datasetId: entry.id,
                 mesh,
@@ -1332,8 +1361,13 @@ export class S3MViewer {
             // 点云没有「棱」：给一堆孤立点建 EdgesGeometry 又慢又没意义
             // 点云没有「棱」：给一堆孤立点建 EdgesGeometry 又慢又没意义。
             // 自动描边受三道开关控制：全局 style.edges / 数据集 enableEdges / 地形绿地等关键字跳过。
-            if (!hasNativeEdges && !isPoints && this._datasetEdgesEnabled(entry) && !this._shouldSkipAutoEdges(ud, entry.name)) {
-                this._ensureEdges(mesh);
+            if (!useNativeEdges && !isPoints && this._datasetEdgesEnabled(entry) && !this._shouldSkipAutoEdges(ud, entry.name)) {
+                // 数据集强制开启（enableEdges: true）时全局画法可能还是关的，退回默认折边线；
+                // 但 gpu 画法本来就不建几何，别在这里多此一举
+                if (this._edgeModes.line || this._edgeModes.hull)
+                    this._ensureEdgeDecoration(mesh);
+                else if (!this._edgeModes.gpu)
+                    this._ensureEdges(mesh);
             }
             // 新瓦片要继承当前的不透明度与着色方式
             if (isPoints) {
@@ -1347,8 +1381,11 @@ export class S3MViewer {
                     mat.transparent = o < 0.999;
                     const keepDepth = this.style.depthWrite !== false;
                     mat.depthWrite = mat.transparent ? keepDepth : (this.style.depthWrite !== false);
-                    mat.flatShading = this.style.shading !== 'smooth';
-                    mat.needsUpdate = true;
+                    // shading 走共享 uniform（uFlatShading），不写 mat.flatShading / needsUpdate——
+                    // transparent / depthWrite 也不是 program 决定项，整套样式继承零重编译
+                    if (mat.userData.uFlatShading) {
+                        mat.userData.uFlatShading.value = this.style.shading !== 'smooth' ? 1 : 0;
+                    }
                     this._featureStyleManager.applyOverridesToMesh(mesh);
                     this._startTileFade(mesh, mat);
                 }
@@ -1571,7 +1608,7 @@ export class S3MViewer {
         if ('edges' in patch) {
             const { edges, ...others } = patch;
             rest = others;
-            this.setEdges(!!edges, wantAnim ? transition : undefined);
+            this.setEdges(edges, wantAnim ? transition : undefined);
             if (Object.keys(rest).length === 0) {
                 this._requestRepaint();
                 return;
@@ -1682,7 +1719,11 @@ export class S3MViewer {
             return;
         }
         this._applyStyleUniforms();
-        if (key === 'edgeColor' || key === 'edgeWidth' || key === 'edgeOpacity') {
+        if (key === 'edgeColor' ||
+            key === 'edgeWidth' ||
+            key === 'edgeOpacity' ||
+            key === 'edgeOffset' ||
+            key === 'edgeHullWidth') {
             this._refreshEdgeLines();
         }
     }
@@ -1717,11 +1758,17 @@ export class S3MViewer {
         // 临界角变了要重建 CPU 棱线（EdgesGeometry 的参数），开 / 关走 setEdges 整体刷新。
         // 必须先 _disposeEdges()：setEdges 只挑「还没有棱线」的网格来建，
         // 不先拆掉的话已经建好的会被全部跳过，临界角改了等于没改。
-        if ('edgeThreshold' in patch && this._edgesEnabled) {
+        if (('edgeThreshold' in patch || 'forceCpuEdges' in patch) && this._edgesEnabled) {
             this._disposeEdges();
-            this.setEdges(true);
-        }
-        else if ('edgeColor' in patch || 'edgeWidth' in patch || 'opacity' in patch || 'edgeOpacity' in patch) {
+            this.setEdges(this.style.edges);
+        }
+        else if ('edgeColor' in patch ||
+            'edgeWidth' in patch ||
+            'opacity' in patch ||
+            'edgeOpacity' in patch ||
+            'edgeOffset' in patch ||
+            'edgeHullWidth' in patch) {
+            // 颜色 / 粗细 / 外推距离 / 外扩厚度都只是 uniform，拖着滑块逐帧改也不重建几何
             this._refreshEdgeLines();
         }
         if (this._selection) {
@@ -1837,26 +1884,74 @@ export class S3MViewer {
     }
     /** 平面/平滑着色：FLAT_SHADED 是编译期宏，改它必须重编译 */
     _applyShading() {
-        const flat = this.style.shading !== 'smooth';
+        // shading 现在是共享 uniform（uFlatShading）驱动的运行期分支，不再是
+        // flatShading define：翻一个 float 就完成切换，零重编译、零卡顿。
+        const target = this.style.shading !== 'smooth' ? 1 : 0;
         for (const p of this._pickables.values()) {
             const m = styledMaterialOf(p.mesh);
-            if (!m || m.flatShading === flat)
+            const u = m?.userData.uFlatShading;
+            if (!u || u.value === target)
                 continue;
-            m.flatShading = flat;
-            m.needsUpdate = true;
+            u.value = target;
         }
         this._requestRepaint();
     }
     /**
-     * 预热另一种 `shading` 变体，让首次切换不再同步编译着色器。
+     * 运行时切换材质质感（`'pbr'` | `'lambert'`）。
      *
-     * 做法是「把材质翻到另一种变体 → 编译 → 翻回来」：three 的 program 缓存按
-     * cacheKey（含 flatShading / defines）分桶，编译一次就留在缓存里，之后
-     * `_applyShading()` 切过去只是取缓存。
+     * 档位是模块级设置（影响之后新建的材质）；已加载瓦片的材质在这里**原位重建**：
+     * 不重拉瓦片、不重建几何，按创建时记录的参数（`userData.s3mOpts`）换一个
+     * 新材质实例，并保留逐材质状态（选中编号、瓦片淡入、批量状态纹理）。
+     * 切换后 program 需要重新编译一次（lambert / pbr 是不同着色器），这是唯一开销。
+     */
+    setMaterialQuality(q) {
+        setMaterialQuality(q);
+        this._rebuildStyledMaterials();
+        this._requestRepaint();
+    }
+    /** 当前材质质感档位 */
+    get materialQuality() {
+        return getMaterialQuality();
+    }
+    /** 按创建参数原位重建所有 styled 材质（materialQuality 切换用） */
+    _rebuildStyledMaterials() {
+        // 逐材质 own uniform 的状态要在重建时搬过去，否则选中高亮 / 瓦片淡入会闪没
+        const PRESERVED = [
+            'uSelBatch',
+            'uSelWhole',
+            'uBatchTex',
+            'uBatchTex2',
+            'uBatchTexWidth',
+            'uBatchTexActive',
+            'uTileFade',
+        ];
+        for (const p of this._pickables.values()) {
+            const mesh = p.mesh;
+            const raw = mesh.material;
+            if (Array.isArray(raw))
+                continue; // styled 材质恒为单材质；数组材质（点云等）不归这里管
+            const old = raw;
+            if (!old?.userData?.isStyled || !old.userData?.s3mOpts)
+                continue;
+            const opts = old.userData.s3mOpts;
+            const fresh = createStyledMaterial({ ...opts, uniforms: this.uniforms });
+            for (const key of PRESERVED) {
+                const src = old.userData[key];
+                const dst = fresh.userData[key];
+                if (src && dst)
+                    dst.value = src.value;
+            }
+            mesh.material = fresh;
+            old.dispose();
+        }
+    }
+    /**
+     * 预热着色 program，避免首帧同步编译。
      *
-     * 翻转期间材质是「错误变体」，所以用 `_prewarming` 让 renderFrame 跳过渲染——
-     * 少画一两帧看不出来，把平滑的楼画成平面的就很明显。
-     * 优先用 `compileAsync`（KHR_parallel_shader_compile），没有就退回同步 `compile`。
+     * shading 改为 `uFlatShading` 共享 uniform 驱动后（见 `_applyShading`），
+     * flat / smooth 共用同一个 program，不再存在「另一种变体」，也不需要
+     * 「翻变体 → 编译 → 翻回来」的那套流程与 `_prewarming` 跳帧。这里只把当前
+     * 唯一的 program 编一次（优先 `compileAsync`，KHR_parallel_shader_compile）。
      */
     async prewarmShading() {
         if (this._shadingPrewarmed || this._prewarming)
@@ -1866,24 +1961,17 @@ export class S3MViewer {
         const camera = this.camera;
         if (!r || !scene || !camera)
             return;
-        const mats = [];
-        const seen = new Set();
+        // 场上还没有材质就没必要预热：program 会在首个材质出现时编译
+        let hasMaterial = false;
         for (const p of this._pickables.values()) {
-            const m = styledMaterialOf(p.mesh);
-            if (!m || seen.has(m))
-                continue;
-            seen.add(m);
-            mats.push(m);
+            if (styledMaterialOf(p.mesh)) {
+                hasMaterial = true;
+                break;
+            }
         }
-        if (mats.length === 0)
+        if (!hasMaterial)
             return;
         this._shadingPrewarmed = true;
-        this._prewarming = true;
-        // 当前是 smooth（flatShading = false）就预热 flat，反之预热 smooth
-        const target = this.style.shading === 'smooth';
-        const saved = mats.map((m) => m.flatShading);
-        for (const m of mats)
-            m.flatShading = target;
         try {
             const anyR = r;
             if (typeof anyR.compileAsync === 'function')
@@ -1892,16 +1980,9 @@ export class S3MViewer {
                 r.compile(scene, camera);
         }
         catch {
-            // 预热失败不影响主流程：最坏情况退回「首次切换时编译一次」
-        }
-        finally {
-            for (let i = 0; i < mats.length; i++) {
-                mats[i].flatShading = saved[i];
-                mats[i].needsUpdate = true;
-            }
-            this._prewarming = false;
-            this._requestRepaint();
+            // 预热失败不影响主流程：最坏情况退回「首次渲染时编译一次」
         }
+        this._requestRepaint();
     }
     /**
      * 高度范围增量维护。
@@ -2004,8 +2085,15 @@ export class S3MViewer {
     /**
      * 全局棱线开关。
      *
-     * 数据自带棱线包（primitiveType 13）时直接用，成本为零；
-     * 没有的话才用 EdgesGeometry 现算 —— 那是 CPU 端的活，几十万面一次性建会卡住主线程
+     * 取值是 `boolean | EdgeStyle | EdgeStyle[]`（见 resolveEdgeModes）：
+     *   - `true` / `'line'`   折边线（旧口径）
+     *   - `'offset'`          折边线 + 沿边法线外推 `edgeOffset` 米
+     *   - `'hull'`            背面外扩轮廓（选中侧 outlineStyle:'hull' 的整场景版）
+     *   - `'gpu'`             纯片元描边：零几何、零额外 pass，线宽约 1 像素
+     *   - 数组                叠加，例如 `['line', 'hull']`
+     *
+     * 数据自带棱线包（primitiveType 13）时直接用，成本为零；`style.forceCpuEdges`
+     * 可以无视它，改由 CPU 现算 —— 那是 CPU 端的活，几十万面一次性建会卡住主线程
      * （实测 20 个网格 1.9s），所以按 8ms 一帧切片，边建边出。
      *
      * 棱线本身用「屏幕空间等宽线」画（见 EdgeLines.ts）：WebGL 的 lineWidth 基本无效，
@@ -2015,23 +2103,33 @@ export class S3MViewer {
      * 开：立刻置位 + 开始分片建线，同时 `uEdgeFade` 0→1 —— 建好一块亮一块，视觉上是渐显；
      * 关：`uEdgeFade` 1→0，淡完才 dispose，避免棱线「啪」一下消失。
      */
-    setEdges(enabled, transition) {
+    setEdges(edges, transition) {
         const wantAnim = !!transition && ((transition.duration ?? 0) > 0 || !!transition.spring);
-        this._edgesEnabled = enabled;
-        this.style.edges = enabled;
-        this._styleTarget.edges = enabled;
-        // 数据自带的棱线：直接切可见性
-        for (const entry of this.datasets.values()) {
-            entry.root.traverse((o) => {
-                const ud = o.userData;
-                if (ud.isEdgeLines) {
-                    o.visible = enabled;
-                    this._styleEdgeLine(o);
-                }
-            });
+        const modes = resolveEdgeModes(edges);
+        // 换画法（line ↔ hull ↔ offset）是结构变更：旧装饰必须拆掉再建，
+        // 否则会出现「切到 hull 了折边线还留着」这种叠影。
+        // 同一画法重复调用（滑块逐帧 setEdges(true)）不重建，几何是复用的。
+        const modesChanged = !sameEdgeModes(this._edgeModes, modes);
+        this._edgeModes = modes;
+        this._edgesEnabled = modes.enabled;
+        this.style.edges = edges;
+        this._styleTarget.edges = edges;
+        // 数据自带的棱线：直接切可见性（forceCpuEdges 时永远收起，改由 CPU 现算）。
+        // 只遍历注册时收集好的那批 LineSegments —— 全数据集 traverse 在几千节点下太贵。
+        // gpu 模式下 shader 自己描边，native 线段包必须收起，否则叠成双线
+        const nativeVisible = modes.enabled && !modes.gpu && this.style.forceCpuEdges !== true;
+        for (const lines of this._nativeEdgeLines) {
+            lines.visible = nativeVisible;
+            this._styleEdgeLine(lines);
         }
         this._syncEdgeStyle();
-        if (!enabled) {
+        // 关掉 gpu 画法就把后处理资源还回去（整屏 RT 白占显存没意义）。
+        // 必须放在「整体关闭」的早退之前，否则关棱线时永远轮不到它。
+        if (!modes.gpu && this._gpuEdge) {
+            this._gpuEdge.dispose();
+            this._gpuEdge = null;
+        }
+        if (!modes.enabled) {
             if (wantAnim) {
                 this.animator.to('style.edgeFade', 0, {
                     ...transition,
@@ -2049,18 +2147,25 @@ export class S3MViewer {
             this._requestRepaint();
             return;
         }
+        if (modesChanged)
+            this._disposeEdges();
         const pending = [...this._pickables.values()]
             .map((p) => p.mesh)
             .filter((m) => {
             const ud = m.userData;
             // 点云没有棱可描
-            return !ud.edges && !ud.nativeEdges && !isPointCloudObject(m);
+            if (isPointCloudObject(m))
+                return false;
+            // native 棱线还算不算数，取决于**当前**的 forceCpuEdges（它可以在运行中切换），
+            // 所以这里按注册时记下的原始标记重算，而不是沿用注册那一刻的结论。
+            ud.nativeEdges = ud.nativeEdgesRaw === true && this.style.forceCpuEdges !== true;
+            return !ud.nativeEdges && this._needsEdgeDecoration(ud);
         });
         let i = 0;
         const step = () => {
             const t0 = performance.now();
             while (i < pending.length && performance.now() - t0 < 8)
-                this._ensureEdges(pending[i++]);
+                this._ensureEdgeDecoration(pending[i++]);
             if (i < pending.length)
                 setTimeout(step, 0);
             else
@@ -2133,10 +2238,11 @@ export class S3MViewer {
         this._requestRepaint();
     }
     /**
-     * 让全局棱线材质跟上 style.edgeColor / edgeWidth / edgeOpacity。
+     * 让全局棱线材质跟上 style.edgeColor / edgeWidth / edgeOpacity / edgeOffset。
      *
-     * 全程 O(1)：只有一份共享 edgeMaterial（所有逐 mesh 棱线都用它）+ 一份预制缓存，
-     * 所以棱线淡入淡出只要改一个 uniform，新建瓦片自动继承当前进度。
+     * 全程 O(1)：只有一份共享 edgeMaterial（所有逐 mesh 棱线都用它）+ 一份预制缓存
+     * + 一批共享外观对象的轮廓壳，所以棱线淡入淡出只要改一个 uniform，
+     * 新建瓦片自动继承当前进度。
      */
     _syncEdgeStyle() {
         const s = this.style;
@@ -2148,6 +2254,14 @@ export class S3MViewer {
         u.uColor.value.set(s.edgeColor);
         u.uWidth.value = Math.max(0.1, s.edgeWidth ?? 1.5);
         u.uOpacity.value = opacity;
+        // 外推距离只在 offset 画法下非 0；其它画法把线钉在面上（与改动前一致）
+        u.uOffset.value = this._edgeModes.offset ? Math.max(0, s.edgeOffset ?? 0.15) : 0;
+        // 外扩轮廓壳与折边线共用颜色 / 透明度，厚度是米制的单独一项
+        const h = this._hullStyleUniforms;
+        h.uColor.value.set(s.edgeColor);
+        h.uWidth.value = Math.max(0, s.edgeHullWidth ?? 0.9);
+        h.uOpacity.value = opacity;
+        // GPU 描边（edges: 'gpu'）是后处理，参数每帧从 style 现取，这里不用同步 uniform
         // 预制棱线缓存（LineBasicMaterial）同步颜色 / 不透明度
         if (this._creaseLines) {
             const m = this._creaseLines.material;
@@ -2205,6 +2319,25 @@ export class S3MViewer {
         const hay = `${ud.skeletonName ?? ''} ${datasetName}`.toLowerCase();
         return S3MViewer._EDGE_SKIP_KEYWORDS.some((k) => hay.includes(k));
     }
+    /**
+     * 这块网格还缺哪种棱线装饰（缺就建，齐了就不动）。
+     *
+     * setEdges 的分片建线靠它筛「还没建完的」，注册新瓦片也靠它决定要不要动手。
+     */
+    _needsEdgeDecoration(ud) {
+        if (this._edgeModes.line && !ud.edges)
+            return true;
+        if (this._edgeModes.hull && !ud.edgeHull)
+            return true;
+        return false;
+    }
+    /** 按当前画法补齐这块网格的棱线装饰 */
+    _ensureEdgeDecoration(mesh) {
+        if (this._edgeModes.line)
+            this._ensureEdges(mesh);
+        if (this._edgeModes.hull)
+            this._ensureHull(mesh);
+    }
     _ensureEdges(mesh) {
         const ud = mesh.userData;
         if (ud.edges || ud.nativeEdges || !mesh.geometry)
@@ -2225,11 +2358,23 @@ export class S3MViewer {
         const welded = mergeVerticesByPosition(mesh.geometry, 0.005);
         // 2. 调大临界角（默认 55°，可在 style.edgeThreshold 调），过滤浅坡与曲面细分，只保留真正的棱。
         const thresholdAngle = this.style.edgeThreshold ?? 55;
-        const source = new THREE.EdgesGeometry(welded, thresholdAngle);
+        // 'offset' 画法要额外带一条「边法线」才知道往哪推，所以走本地实现（它本来就算好了
+        // 相邻两面法线）；其余画法保持 EdgesGeometry 这条老路，几何输出与改动前逐字一致。
+        let segments;
+        let normals;
+        if (this._edgeModes.offset) {
+            const raw = [];
+            segments = buildFeatureEdgeSegments(welded, null, thresholdAngle, raw);
+            if (raw.length > 0)
+                normals = new Float32Array(raw);
+        }
+        else {
+            const source = new THREE.EdgesGeometry(welded, thresholdAngle);
+            const attr = source.getAttribute('position');
+            segments = attr ? attr.array : null;
+            source.dispose();
+        }
         welded.dispose();
-        const attr = source.getAttribute('position');
-        const segments = attr ? attr.array : null;
-        source.dispose();
         if (!segments || segments.length < 6)
             return;
         // 3. 回填每段棱线所属的单体 batchId。
@@ -2247,7 +2392,7 @@ export class S3MViewer {
                     batchMap.get(positionQuantKey(segments[s], segments[s + 1], segments[s + 2], 1 / TOL)) ?? -1;
             }
         }
-        const lines = new THREE.Mesh(buildThickLineGeometry(segments, batchIds), this._createEdgeMaterial(mesh));
+        const lines = new THREE.Mesh(buildThickLineGeometry(segments, batchIds, normals), this._createEdgeMaterial(mesh));
         lines.renderOrder = 2;
         // 屏幕空间外扩后可能超出原包围球，关掉剔除更稳
         lines.frustumCulled = false;
@@ -2256,6 +2401,44 @@ export class S3MViewer {
         ud.edges = lines;
         mesh.add(lines); // 作为子节点，自动继承 mesh 的世界变换
     }
+    /**
+     * 给一块网格挂「背面外扩轮廓」（整场景版）。
+     *
+     * 复用选中侧那套 `createOutlineMaterial`：顶点沿法线鼓 `edgeHullWidth` 米、只画背面，
+     * 于是被本体挡住的部分不显示，露出来的那圈就是描边。与折边线的差别在于——
+     * 这里**不建任何新几何**，成本只是把同一块网格多画一遍，折边判定那套 CPU 活全省了。
+     *
+     * 实例化几何拿不到逐实例变换（轮廓壳是 mesh 的子节点，不吃 instanceMatrix），
+     * 直接跳过：宁可这栋没描边，也不要所有实例的壳叠在原点。
+     */
+    _ensureHull(mesh) {
+        const ud = mesh.userData;
+        if (ud.edgeHull || !mesh.geometry)
+            return;
+        if (mesh.isInstancedMesh)
+            return;
+        // 地形 / 绿地 / 道路等不参与自动描边（即使全局开棱线也要跳过）
+        if (this._shouldSkipAutoEdges(ud, ''))
+            return;
+        // 逐网格一份材质（各绑各的单体状态纹理），外观 uniform 复用共享对象
+        const mat = createOutlineMaterial(this.uniforms, this.style.edgeHullWidth ?? 0.9, this._hullStyleUniforms, true);
+        // 整块几何都要外扩：选中侧靠 uSelBatch 只扩一栋，全局必须置 whole
+        mat.uniforms.uSelWhole.value = 1;
+        mat.uniforms.uSelBatch.value = -1;
+        const styled = styledMaterialOf(mesh);
+        if (styled?.userData?.uBatchTex) {
+            mat.uniforms.uBatchTex.value = styled.userData.uBatchTex.value;
+            mat.uniforms.uBatchTexWidth.value = styled.userData.uBatchTexWidth.value;
+            mat.uniforms.uBatchTexActive.value = styled.userData.uBatchTexActive.value;
+        }
+        const hull = new THREE.Mesh(mesh.geometry, mat);
+        hull.renderOrder = 2;
+        hull.frustumCulled = false;
+        hull.raycast = () => { };
+        hull.userData.isEdgeHull = true;
+        ud.edgeHull = hull;
+        mesh.add(hull); // 作为子节点，自动继承 mesh 的世界变换
+    }
     /**
      * 给一块网格造专属的棱线材质。
      *
@@ -2302,19 +2485,30 @@ export class S3MViewer {
     _removeEdges(mesh) {
         const ud = mesh.userData;
         const lines = ud.edges;
-        if (!lines)
-            return;
-        mesh.remove(lines);
-        lines.geometry?.dispose();
-        // 棱线材质现在是逐网格一份（要绑各自的 batch 纹理），得跟着释放
-        const mat = lines.material;
-        if (Array.isArray(mat)) {
-            mat.forEach((m) => m?.dispose?.());
-        }
-        else {
-            mat?.dispose?.();
+        if (lines) {
+            mesh.remove(lines);
+            lines.geometry?.dispose();
+            // 棱线材质现在是逐网格一份（要绑各自的 batch 纹理），得跟着释放
+            const mat = lines.material;
+            if (Array.isArray(mat)) {
+                mat.forEach((m) => m?.dispose?.());
+            }
+            else {
+                mat?.dispose?.();
+            }
+            ud.edges = null;
+        }
+        // 外扩壳的 geometry 是**复用主网格的**，只能释放材质，不能 dispose 几何
+        const hull = ud.edgeHull;
+        if (hull) {
+            mesh.remove(hull);
+            const hmat = hull.material;
+            if (Array.isArray(hmat))
+                hmat.forEach((m) => m?.dispose?.());
+            else
+                hmat?.dispose?.();
+            ud.edgeHull = null;
         }
-        ud.edges = null;
     }
     /* ---------------------------------------------------------------- 拾取 */
     /** 获取指定屏幕像素对应的场景射线（用于高精度求交与穿透拾取） */
@@ -3001,6 +3195,35 @@ export class S3MViewer {
         this._selectionEdges = null;
     }
     /* ---------------------------------------------------------------- 渲染 */
+    /**
+     * 执行一帧 GPU 描边（法线 + 深度后处理）。
+     *
+     * 参数全部来自 style，不缓存：`edgeWidth` 在这里是「采样偏移」，线宽 ≈ 2×它；
+     * `edgeThreshold` 是折边敏感度（夹角小于它不描），和 CPU 折边线同一口径。
+     */
+    _renderGpuEdges(canvas) {
+        if (!this.renderer || !this.scene || !this.camera)
+            return;
+        const s = this.style;
+        const fade = this.uniforms.uEdgeFade?.value ?? 1;
+        const opacity = Math.min(1, Math.max(0, s.edgeOpacity ?? 0.6)) * clampOpacity(s.opacity) * fade;
+        if (opacity <= 0.004)
+            return;
+        if (!this._gpuEdge)
+            this._gpuEdge = new GpuEdgePass();
+        if (!this._gpuEdge.supported(this.renderer))
+            return;
+        // 度数 → 归一化法线差（|Δn| = 2·sin(θ/2)），乘 0.6 让阈值落在「刚好能描出」的位置
+        const deg = Math.min(179, Math.max(1, s.edgeThreshold ?? 55));
+        const normalThreshold = 2 * Math.sin((deg * Math.PI) / 360) * 0.6;
+        this._gpuEdge.render(this.renderer, this.scene, this.camera, canvas.width, canvas.height, {
+            color: this._gpuEdgeColor.set(s.edgeColor),
+            opacity,
+            radius: Math.max(1, s.edgeWidth ?? 1.5),
+            normalThreshold,
+            depthThreshold: 0.08,
+        });
+    }
     /** 等宽线要按设备像素换算线宽：uResolution 用绘图缓冲尺寸，uDpr 是缓冲 / CSS 的比值 */
     _updateLineResolution(canvas) {
         const w = canvas.width || 1;
@@ -3223,6 +3446,10 @@ export class S3MViewer {
         // 这里跳过的是「本层的绘制」，宿主自己的清屏 / 底图照旧。
         if ((this.uniforms.uOpacity?.value ?? 1) > OPACITY_EPS) {
             this.renderer.render(this.scene, this.camera);
+            // GPU 描边必须画在主场景之后：它的全屏 quad 参与宿主深度测试，
+            // 依赖本帧已经写好的深度（被地形挡住的地方不该描边）
+            if (this._edgeModes.gpu)
+                this._renderGpuEdges(canvas);
         }
         this._frame++;
         const now = performance.now();
@@ -3257,6 +3484,10 @@ export class S3MViewer {
             vertices: 0,
             triangles: 0,
             datasets: this.datasets.size,
+            drawCalls: 0,
+            programs: 0,
+            textures: 0,
+            geometries: 0,
         };
         for (const entry of this.datasets.values()) {
             const s = entry.tileset?.stats;
@@ -3269,6 +3500,15 @@ export class S3MViewer {
             total.vertices += s.vertices;
             total.triangles += s.triangles;
         }
+        // GPU 侧预算观测：draw call / program / 显存驻留。没有渲染器（未 mount /
+        // 纯解析场景）时保持 0，不抛错。
+        const info = this.renderer?.info;
+        if (info) {
+            total.drawCalls = info.render.calls;
+            total.programs = info.programs?.length ?? 0;
+            total.textures = info.memory.textures;
+            total.geometries = info.memory.geometries;
+        }
         return total;
     }
     /** 所有数据集合并后的经纬度包围盒 */