s3m-three 0.3.2 → 0.3.4

package/src/render/S3MViewer.ts

@@ -21,6 +21,7 @@
  * MapLibre / Mapbox 的胶水层在 s3m-maplibre 包的 S3MLayer.ts。
  */
 import * as THREE from 'three';
+import * as BufferGeometryUtils from 'three/examples/jsm/utils/BufferGeometryUtils.js';
 import { S3MTileset, usableGeoBounds } from '../tileset/S3MTileset.js';
 import type { BuildTileFn, TileNode } from '../tileset/S3MTileset.js';
 import { setMaxAnisotropy } from './TextureFactory.js';
@@ -321,6 +322,8 @@ export class S3MViewer {
   private _selectionEdges: THREE.Mesh | null = null;
   private _selectionEdgeMeshes: THREE.Mesh[] = [];
   private _edgesEnabled = false;
+  /** 预制棱线缓存（Crease Cache）：从外部 source-creases 载入的全局统一 LineSegments，性能最高、视觉最干净 */
+  private _creaseLines: THREE.LineSegments | null = null;
 
   /** 业务属性查询（可选，配了 `attributes` 才有） */
   attributeQuery: AttributeQuery | null = null;
@@ -413,6 +416,11 @@ export class S3MViewer {
       width: this.style.outlineWidthPx ?? 3,
     });
 
+    // 关键：style.edges 是个开关，但构造函数从没据此启用过棱线，导致
+    // `style: { edges: true }` 形同虚设、_edgesEnabled 永远是 false。
+    // 这里按 style 实际值调一次 setEdges，让开关真正生效（与 setEdges 后来的手工调用一致）。
+    this.setEdges(!!this.style.edges);
+
     this._fps.last = performance.now();
     this._datasetQueue = this._normalizeDatasets(options);
     if (options.attributes) this.attributeQuery = new AttributeQuery(options.attributes);
@@ -424,19 +432,25 @@ export class S3MViewer {
    * 绑定宿主画布与 WebGL 上下文，建场景并启动数据集队列。
    * MapLibre 宿主由 S3MLayer 在 onAdd 里调用；纯 three 宿主直接传自己的 canvas / gl。
    */
-  mount(canvas: HTMLCanvasElement, gl: WebGLRenderingContext | WebGL2RenderingContext): void {
-    this.canvas = canvas;
-
-    this.renderer = new THREE.WebGLRenderer({
+  /** 创建并配置一个绑定到给定 gl 上下文的 three renderer（mount 与上下文恢复共用） */
+  private _createRenderer(canvas: HTMLCanvasElement, gl: WebGLRenderingContext | WebGL2RenderingContext): THREE.WebGLRenderer {
+    const r = new THREE.WebGLRenderer({
       canvas,
       context: gl as WebGLRenderingContext,
       antialias: true,
     });
-    this.renderer.autoClear = false;
-    this.renderer.setPixelRatio(1);
+    r.autoClear = false;
+    r.setPixelRatio(1);
     // 白模 albedo 接近 1，不做色调映射会过曝成一片纯白、丢失明暗关系
-    this.renderer.toneMapping = THREE.ACESFilmicToneMapping;
-    this.renderer.toneMappingExposure = 1.0;
+    r.toneMapping = THREE.ACESFilmicToneMapping;
+    r.toneMappingExposure = 1.0;
+    return r;
+  }
+
+  mount(canvas: HTMLCanvasElement, gl: WebGLRenderingContext | WebGL2RenderingContext): void {
+    this.canvas = canvas;
+
+    this.renderer = this._createRenderer(canvas, gl);
     setMaxAnisotropy(this.renderer.capabilities.getMaxAnisotropy());
 
     this.scene = new THREE.Scene();
@@ -454,9 +468,42 @@ export class S3MViewer {
     this._recomputeAnchors();
   }
 
+  /**
+   * WebGL 上下文恢复后原地换新 renderer，保留已经加载好的场景与瓦片。
+   *
+   * MapLibre 在 `webglcontextlost` 时会销毁 style 并丢弃自定义图层（自定义图层
+   * 无法序列化进 style，所以恢复后不会自动加回）。但自定义图层的 `onRemove` 不会被
+   * 调用，因此我们的 scene / 几何体 / 材质 / 纹理 / 已加载瓦片都还在内存里。
+   *
+   * three 的 GPU 状态是按 renderer 实例缓存的，所以只需把 renderer / picker 换成
+   * 绑在新 gl 上的新实例，下一帧渲染时 three 会自动把现存的几何体、材质、纹理
+   * 重新上传到新上下文 —— 不需要重建场景，也不需要重新拉瓦片。
+   */
+  restoreContext(gl: WebGLRenderingContext | WebGL2RenderingContext): void {
+    if (!this.canvas) {
+      // 理论不会走到：没 mount 过就没有上下文可恢复
+      console.warn('[s3m] restoreContext 调用过早（尚未 mount），按首次挂载处理');
+      return;
+    }
+    try {
+      // 旧上下文已失效，dispose 可能抛错，忽略即可
+      this.renderer?.dispose();
+    } catch {
+      /* noop */
+    }
+    this.renderer = this._createRenderer(this.canvas, gl);
+    setMaxAnisotropy(this.renderer.capabilities.getMaxAnisotropy());
+    this.picker?.dispose();
+    this.picker = new Picker(this.renderer);
+    // 共享 uniform / 材质引用不变，three 重新编译着色器时会自然接管；
+    // 这里只确保下一帧尽快驱动一次渲染。
+    this._requestRepaint();
+  }
+
   /** 解绑场景并释放全部 GPU 资源。对应 MapLibre 图层的 onRemove()。 */
   unmount(): void {
     for (const id of [...this.datasets.keys()]) this.removeDataset(id);
+    this.clearCreases();
     this.groundManager.dispose();
     this.picker?.dispose();
     this.picker = null;
@@ -958,7 +1005,11 @@ export class S3MViewer {
       this._indexMeshSmids(mesh);
       this._addMeshHeight(mesh);
       // 点云没有「棱」：给一堆孤立点建 EdgesGeometry 又慢又没意义
-      if (this._edgesEnabled && !hasNativeEdges && !isPoints) this._ensureEdges(mesh);
+      // 点云没有「棱」：给一堆孤立点建 EdgesGeometry 又慢又没意义。
+      // 自动描边受三道开关控制：全局 style.edges / 数据集 enableEdges / 地形绿地等关键字跳过。
+      if (!hasNativeEdges && !isPoints && this._datasetEdgesEnabled(entry) && !this._shouldSkipAutoEdges(ud, entry.name)) {
+        this._ensureEdges(mesh);
+      }
 
       // 新瓦片要继承当前的不透明度与着色方式
       if (isPoints) {
@@ -1128,8 +1179,12 @@ export class S3MViewer {
     // 点云不走 StyleMaterial 的 uMode，模式切换要单独同步它的材质
     if ('mode' in patch) this._applyPointCloudStyles();
     if ('shading' in patch) this._applyShading();
-    if ('edges' in patch) this.setEdges(!!this.style.edges);
-    else if ('edgeColor' in patch || 'edgeWidth' in patch || 'opacity' in patch || 'edgeOpacity' in patch) {
+    // 临界角变了要重建 CPU 棱线（EdgesGeometry 参数），开/关走 setEdges 整体刷新
+    if ('edgeThreshold' in patch && this._edgesEnabled) {
+      this.setEdges(true);
+    } else if ('edges' in patch) {
+      this.setEdges(!!this.style.edges);
+    } else if ('edgeColor' in patch || 'edgeWidth' in patch || 'opacity' in patch || 'edgeOpacity' in patch) {
       this._refreshEdgeLines();
     }
     if (this._selection) {
@@ -1371,14 +1426,66 @@ export class S3MViewer {
     step();
   }
 
+  /**
+   * 挂载预制棱线缓存（Crease Cache）。
+   *
+   * 直接把 `source-creases.f32` 这类 Float32Array 缓冲载入为一组全局统一的
+   * LineSegments —— 相比逐 Mesh 现算 EdgesGeometry，性能高一个量级，视觉也最干净。
+   * 坐标按「场景本地坐标」（相对场景锚点的米）处理，与瓦片几何同一坐标系。
+   *
+   * @param url  棱线缓存地址（二进制 Float32 序列：x,y,z,x,y,z,… 成对成段）
+   */
+  async loadCreases(url: string): Promise<void> {
+    const resp = await fetch(url);
+    if (!resp.ok) throw new Error(`[s3m] 棱线缓存加载失败: ${resp.status} ${url}`);
+    const buf = await resp.arrayBuffer();
+    const arr = new Float32Array(buf);
+    if (arr.length < 6) return;
+
+    const geo = new THREE.BufferGeometry();
+    geo.setAttribute('position', new THREE.BufferAttribute(arr, 3));
+    const s = this.style;
+    const mat = new THREE.LineBasicMaterial({
+      color: new THREE.Color(s.edgeColor),
+      transparent: true,
+      opacity: Math.min(1, Math.max(0, s.edgeOpacity ?? 0.6)) * Math.min(1, Math.max(0.05, s.opacity ?? 1)),
+      depthWrite: false,
+    });
+    const lines = new THREE.LineSegments(geo, mat);
+    lines.renderOrder = 2;
+    lines.frustumCulled = false;
+    lines.raycast = () => {};
+
+    this.clearCreases();
+    this._creaseLines = lines;
+    this.scene?.add(lines);
+    this._requestRepaint();
+  }
+
+  /** 移除并释放预制棱线缓存 */
+  clearCreases(): void {
+    if (!this._creaseLines) return;
+    this.scene?.remove(this._creaseLines);
+    this._creaseLines.geometry.dispose();
+    (this._creaseLines.material as THREE.Material)?.dispose?.();
+    this._creaseLines = null;
+    this._requestRepaint();
+  }
+
   /** 让全局棱线材质跟上 style.edgeColor / edgeWidth / edgeOpacity */
   private _syncEdgeStyle(): void {
     const s = this.style;
     const u = this.edgeMaterial.uniforms;
     u.uColor.value.set(s.edgeColor);
-    u.uWidth.value = Math.max(0.1, s.edgeWidth ?? 1.2);
+    u.uWidth.value = Math.max(0.1, s.edgeWidth ?? 1.5);
     u.uOpacity.value =
-      Math.min(1, Math.max(0, s.edgeOpacity ?? 0.45)) * Math.min(1, Math.max(0.05, s.opacity ?? 1));
+      Math.min(1, Math.max(0, s.edgeOpacity ?? 0.6)) * Math.min(1, Math.max(0.05, s.opacity ?? 1));
+    // 预制棱线缓存（LineBasicMaterial）同步颜色 / 不透明度
+    if (this._creaseLines) {
+      const m = this._creaseLines.material as THREE.LineBasicMaterial;
+      m.color.set(s.edgeColor);
+      m.opacity = Math.min(1, Math.max(0, s.edgeOpacity ?? 0.6)) * Math.min(1, Math.max(0.05, s.opacity ?? 1));
+    }
   }
 
   /** 让数据自带的棱线跟着 style.edgeColor / opacity 走（这些是 LineBasicMaterial，改不了粗细） */
@@ -1386,7 +1493,7 @@ export class S3MViewer {
     const mat = lines.material as THREE.LineBasicMaterial;
     if (!mat || !mat.color) return;
     mat.color.set(this.style.edgeColor);
-    const baseOpacity = this.style.edgeOpacity ?? 0.45;
+    const baseOpacity = this.style.edgeOpacity ?? 0.6;
     mat.opacity = baseOpacity * Math.min(1, Math.max(0.05, this.style.opacity ?? 1));
     mat.transparent = true;
     mat.polygonOffset = true;
@@ -1404,14 +1511,46 @@ export class S3MViewer {
     }
   }
 
+  /** 地形 / 绿地 / 道路 / 地面铺装等不参与自动描边（数据自带棱线包另说） */
+  private static readonly _EDGE_SKIP_KEYWORDS = [
+    'terrain', 'ground', 'vegetation', 'green', 'road', 'dem',
+    '绿地', '道路', '地面', '地形', '植被', '铺装',
+  ];
+
+  /** 数据集级别的棱线开关：enableEdges 优先，否则跟随全局 style.edges */
+  private _datasetEdgesEnabled(entry: S3MDatasetEntry): boolean {
+    const opt = entry.options?.enableEdges;
+    if (opt === true) return true;
+    if (opt === false) return false;
+    return this._edgesEnabled;
+  }
+
+  /** 该 mesh 是否命中「跳过自动描边」的关键字（skeletonName / 数据集名） */
+  private _shouldSkipAutoEdges(ud: MeshUserData, datasetName: string): boolean {
+    const hay = `${ud.skeletonName ?? ''} ${datasetName}`.toLowerCase();
+    return S3MViewer._EDGE_SKIP_KEYWORDS.some((k) => hay.includes(k));
+  }
+
   private _ensureEdges(mesh: THREE.Mesh): void {
     const ud = mesh.userData as MeshUserData;
     if (ud.edges || ud.nativeEdges || !mesh.geometry) return;
-    const indexCount = mesh.geometry.index?.count ?? 0;
+    // 地形 / 绿地 / 道路等不参与自动描边（即使全局开棱线也要跳过）
+    if (this._shouldSkipAutoEdges(ud, '')) return;
+
+    const posAttr = mesh.geometry.getAttribute('position');
+    const indexCount = mesh.geometry.index?.count ?? (posAttr ? posAttr.count : 0);
     // 棱线是 CPU 端建的，超大几何直接跳过，避免拖慢加载
     if (indexCount > 120000) return;
 
-    const source = new THREE.EdgesGeometry(mesh.geometry, 40);
+    // 1. 先做顶点容差焊合，让相邻三角形正确共享边索引。
+    //    S3M 几何常为「每面独立顶点」，不焊合的话 EdgesGeometry 会把每条三角形边都当成边界，棱线爆炸。
+    //    tolerance 取米级模型下的 5mm，足以合并重合顶点又不会误并真实相邻面。
+    const welded = BufferGeometryUtils.mergeVertices(mesh.geometry, 0.005);
+    // 2. 调大临界角（默认 55°，可在 style.edgeThreshold 调），过滤浅坡与曲面细分，只保留真正的棱。
+    const thresholdAngle = this.style.edgeThreshold ?? 55;
+    const source = new THREE.EdgesGeometry(welded, thresholdAngle);
+    welded.dispose();
+
     const attr = source.getAttribute('position') as THREE.BufferAttribute | undefined;
     const segments = attr ? (attr.array as Float32Array) : null;
     source.dispose();
@@ -2132,6 +2271,9 @@ export class S3MViewer {
     canvasHeight: number;
   }): boolean {
     if (!this.renderer || !this.scene || !this.camera || !this.sceneAnchor || !this.canvas) return false;
+    // 上下文丢失期间（丢失→恢复之间）不要尝试渲染，否则会刷一堆 GL 错误
+    const gl = this.renderer.getContext() as WebGLRenderingContext | null;
+    if (gl && typeof gl.isContextLost === 'function' && gl.isContextLost()) return false;
 
     // 脏标记正常由微任务刷掉；这里再兜一次底，保证「本帧画出来的」一定是最新样式
     this.flushOverrides();

package/src/render/StyleMaterial.ts

@@ -110,6 +110,8 @@ export interface S3MStyle {
   edgeWidth?: number;
   edgeColor: string;
   edgeOpacity?: number;
+  /** 棱线临界角（度）：相邻面法线夹角超过该值才描边，过滤掉浅坡与曲面细分。默认 55° */
+  edgeThreshold?: number;
   roofThreshold?: number;
   /** 是否与模型原色贴图叠加混合（0 = 纯色覆盖，1 = 叠乘原色贴图） */
   texMix?: number;
@@ -139,9 +141,10 @@ export const DEFAULT_STYLE: S3MStyle = {
   outlineWidth: 0.9,
   outlineWidthPx: 3,
   edges: false,
-  edgeWidth: 1.2,
+  edgeWidth: 1.5,
   edgeColor: '#334155',
-  edgeOpacity: 0.45,
+  edgeOpacity: 0.6,
+  edgeThreshold: 55,
   roofThreshold: 0.65,
   texMix: 0,
   depthWrite: true,