s3m-three 0.2.0 → 0.3.1

package/src/render/GroundManager.ts

@@ -9,6 +9,12 @@
  *    - 地表相交线（Z = 0）：出入口穿透地表处有清晰物理交线。
  * 3. 支持「基坑开挖模式（Excavate）」与「地下透视模式（Translucent）」，
  *    可开辟虚拟基坑井口或全域透视地表。
+ *
+ * 关于「遮挡」：地表能不能挡住建筑，只取决于有没有一块**先于建筑绘制、并且写了深度**的
+ * 几何进到同一深度缓冲里。半透明覆盖网格 `depthWrite = false` 且排在 transparent 队列末尾，
+ * 它只是画在上面的一层色，不参与遮挡；真正的遮挡由独立的**纯深度代理**（`_depthMesh`，
+ * `colorWrite = false` + `renderOrder` 负值）负责，可用 `occlude` 开关控制。
+ * 与 MapLibre terrain 共用同一深度缓冲，两者是「深度来源」的关系而非替代关系。
  */
 import * as THREE from 'three';
 
@@ -28,6 +34,28 @@ export interface GroundOptions {
   excavationBounds?: [number, number, number, number] | null;
   /** 地表范围大小（米，默认 6000） */
   size?: number;
+  /**
+   * 地表高度是否跟随主数据集的抬升量（`setDatasetHeight`），默认 `true`。
+   *
+   * `true` 服务贴地工作流：模型整体抬到地面高程时，切割面必须跟着抬到同一高程，
+   * 否则整个模型会被齐根切掉。
+   * `false` 把地表钉死在当前高度（默认场景 z=0）：高程调整只动模型不动切割面，
+   * 滑杆变成直观的「控制埋深 / 切掉多少」。
+   */
+  trackHeight?: boolean;
+  /**
+   * 地表是否作为深度遮挡源：开启后，位于地表以下的几何（地下站厅 / 隧道 / 管线）
+   * 会被地表真正切掉，而不是透过半透明地表显露。
+   *
+   * **与 mode 解耦**：`mode: 'none'` 时也可以单独开启 —— 不显示任何地表，
+   * 只留一块隐形地面把地面以下切掉。默认值取 `mode === 'excavate'`
+   * （开挖模式下坑外的地下部分本就该被土体挡住），`'translucent'` 下默认关闭
+   * —— 那一模式的全部意义就是「能看穿地表」。
+   *
+   * 实现上由一块 `colorWrite = false`、排在 opaque 队列最前的纯深度代理完成，
+   * 与 MapLibre terrain 写入的深度共用同一个深度缓冲，互不冲突（谁更近谁赢）。
+   */
+  occlude?: boolean;
 }
 
 export class GroundManager {
@@ -40,10 +68,20 @@ export class GroundManager {
   size: number;
   /** 物理地表网格的高度（米，场景 ENU Z 坐标），默认 0 */
   groundHeight = 0;
+  /** 地表是否作为深度遮挡源（见 `GroundOptions.occlude`） */
+  occlude: boolean;
+  /** 地表高度是否跟随主数据集抬升量（见 `GroundOptions.trackHeight`），默认 true */
+  trackHeight: boolean;
 
   readonly group: THREE.Group;
   private _mesh: THREE.Mesh | null = null;
   private _material: THREE.ShaderMaterial | null = null;
+  /** 纯深度代理：只写深度不写颜色，负责真正的遮挡 */
+  private _depthMesh: THREE.Mesh | null = null;
+  private _depthMaterial: THREE.ShaderMaterial | null = null;
+  private _geom: THREE.PlaneGeometry | null = null;
+  /** 用户显式指定过 occlude 后，setMode 不再自动改写它 */
+  private _occludeExplicit: boolean;
 
   constructor(options: GroundOptions = {}) {
     this.mode = options.mode ?? 'none';
@@ -53,14 +91,21 @@ export class GroundManager {
     this.gridSize = options.gridSize ?? 10.0;
     this.excavationBounds = options.excavationBounds ?? null;
     this.size = options.size ?? 6000;
+    this._occludeExplicit = options.occlude !== undefined;
+    this.occlude = options.occlude ?? this.mode === 'excavate';
+    this.trackHeight = options.trackHeight ?? true;
 
     this.group = new THREE.Group();
     this.group.name = 's3m-ground-surface';
     this._initMesh();
+    // 构造时就按当前 mode 应用一次：以前 depthWrite / 可见性只在 setMode 里改，
+    // 用 `{ mode: 'excavate' }` 建出来的实例会一直停在 depthWrite = false。
+    this._applyMode();
   }
 
   private _initMesh(): void {
     const geom = new THREE.PlaneGeometry(this.size, this.size, 1, 1);
+    this._geom = geom;
 
     // ENU 坐标系下，Z 为天（Up），PlaneGeometry 默认在 XY 平面上，正常法线正是 (0, 0, 1)！
     const material = new THREE.ShaderMaterial({
@@ -146,15 +191,96 @@ export class GroundManager {
 
     this._mesh = mesh;
     this._material = material;
-    this.group.visible = this.mode !== 'none';
+
+    // ---- 纯深度代理 ----
+    // 遮挡是「片元绘制那一刻」由深度测试决定的：覆盖网格排在 transparent 队列末尾，
+    // 房子早就画完了，它写不写深度都挡不住任何东西。所以单独放一块只写深度、
+    // 不写颜色、排进 opaque 队列最前的孪生网格，让后续所有片元在它后面被裁掉。
+    const depthMaterial = new THREE.ShaderMaterial({
+      // 关掉颜色写入但仍走 depthWrite ⇒ 只留一层「隐形墙」
+      colorWrite: false,
+      depthWrite: true,
+      depthTest: true,
+      transparent: false, // 必须是 opaque，才能靠 renderOrder 抢到全场景最前
+      // 只挡「从上方看下去」的方向：相机钻到地下时不该被自己这层地表糊住
+      side: THREE.FrontSide,
+      uniforms: {
+        // 基坑开挖时，坑口是「挖开的地方」，地下必须还能看见 ⇒ 代理也要在这里开洞
+        uPunchPit: { value: 0 },
+        uHasExcavation: { value: 0 },
+        uExcavationMin: { value: new THREE.Vector2(-9999, -9999) },
+        uExcavationMax: { value: new THREE.Vector2(9999, 9999) },
+      },
+      vertexShader: /* glsl */ `
+        varying vec2 vEnuPos;
+        void main() {
+          vec4 worldPos = modelMatrix * vec4(position, 1.0);
+          vEnuPos = worldPos.xy;
+          gl_Position = projectionMatrix * viewMatrix * worldPos;
+        }
+      `,
+      fragmentShader: /* glsl */ `
+        uniform int uPunchPit;
+        uniform int uHasExcavation;
+        uniform vec2 uExcavationMin;
+        uniform vec2 uExcavationMax;
+        varying vec2 vEnuPos;
+        void main() {
+          if (uPunchPit == 1 && uHasExcavation == 1 &&
+              vEnuPos.x >= uExcavationMin.x && vEnuPos.x <= uExcavationMax.x &&
+              vEnuPos.y >= uExcavationMin.y && vEnuPos.y <= uExcavationMax.y) {
+            discard;
+          }
+          gl_FragColor = vec4(1.0);
+        }
+      `,
+    });
+
+    const depthMesh = new THREE.Mesh(geom, depthMaterial);
+    // 比覆盖网格低 2cm：避免与它等深度打架（覆盖层 LEQUAL 时仍能画上去）
+    depthMesh.position.set(0, 0, -0.02);
+    depthMesh.renderOrder = -1000;
+    depthMesh.name = 's3m-ground-depth';
+    depthMesh.visible = false;
+    this.group.add(depthMesh);
+
+    this._depthMesh = depthMesh;
+    this._depthMaterial = depthMaterial;
+
     this._syncUniforms();
   }
 
   /**
-   * 每帧根据相机位置更新地表网格中心，实现地表随相机平移而无限延伸且网格线不漂移
+   * 把 mode / occlude 的状态一次性刷到材质和可见性上。
+   * 构造与 setMode / setOcclude 都走这里，避免出现「构造时漏设」的分叉。
+   *
+   * 覆盖网格与深度代理**各自独立控制**：
+   *   - 覆盖网格（视觉）只跟 mode 走；
+   *   - 深度代理（遮挡）只跟 occlude 走 —— mode 'none' 时也可以单独开一块
+   *     「隐形地面」把地面以下切掉，不显示任何地表。
+   */
+  private _applyMode(): void {
+    if (this._mesh) this._mesh.visible = this.mode !== 'none';
+    if (this._material) {
+      this._material.uniforms.uMode.value = this.mode === 'excavate' ? 2 : this.mode === 'translucent' ? 1 : 0;
+      // 覆盖网格排在最后，写深度的意义已经由代理接管，这里保留 excavate 的历史行为
+      this._material.depthWrite = this.mode === 'excavate';
+    }
+    if (this._depthMesh) {
+      this._depthMesh.visible = this.occlude;
+      if (this._depthMaterial) {
+        // 只有开挖模式才在坑口开洞；translucent / none + occlude 是「一刀切」语义
+        this._depthMaterial.uniforms.uPunchPit.value = this.mode === 'excavate' ? 1 : 0;
+      }
+    }
+  }
+
+  /**
+   * 每帧根据相机位置更新地表网格中心，实现地表随相机平移而无限延伸且网格线不漂移。
+   * 遮挡代理与地表模式已解耦，所以 mode 'none' 时也要跟着相机走。
    */
   update(camera?: THREE.Camera | null): void {
-    if (!camera || this.mode === 'none') return;
+    if (!camera) return;
     this.group.position.set(camera.position.x, camera.position.y, this.groundHeight);
   }
 
@@ -171,11 +297,21 @@ export class GroundManager {
 
   setMode(mode: GroundMode): void {
     this.mode = mode;
-    this.group.visible = mode !== 'none';
-    if (this._material) {
-      this._material.uniforms.uMode.value = mode === 'excavate' ? 2 : mode === 'translucent' ? 1 : 0;
-      this._material.depthWrite = mode === 'excavate';
-    }
+    // 没显式要过 occlude 的，跟着模式走：开挖模式才遮挡
+    if (!this._occludeExplicit) this.occlude = mode === 'excavate';
+    this._applyMode();
+  }
+
+  /**
+   * 开关「地表作为深度遮挡源」。
+   *
+   * 打开后地表以下的几何会被真正切掉（不再透过地表显露）；关闭后回到纯视觉覆盖。
+   * 与宿主是否开启 MapLibre terrain 无关：两者都在同一个深度缓冲里比深度，谁更近谁赢。
+   */
+  setOcclude(enabled: boolean): void {
+    this.occlude = enabled;
+    this._occludeExplicit = true;
+    this._applyMode();
   }
 
   setOpacity(opacity: number): void {
@@ -237,22 +373,40 @@ export class GroundManager {
   }
 
   private _syncUniforms(): void {
-    if (!this._material) return;
-    const u = this._material.uniforms;
-    if (this.excavationBounds) {
-      u.uHasExcavation.value = 1;
-      u.uExcavationMin.value.set(this.excavationBounds[0], this.excavationBounds[1]);
-      u.uExcavationMax.value.set(this.excavationBounds[2], this.excavationBounds[3]);
-    } else {
-      u.uHasExcavation.value = 0;
+    const bounds = this.excavationBounds;
+    if (this._material) {
+      const u = this._material.uniforms;
+      if (bounds) {
+        u.uHasExcavation.value = 1;
+        u.uExcavationMin.value.set(bounds[0], bounds[1]);
+        u.uExcavationMax.value.set(bounds[2], bounds[3]);
+      } else {
+        u.uHasExcavation.value = 0;
+      }
+    }
+    // 深度代理要和覆盖网格用同一套基坑参数，否则坑口会出现「看得见色块、却被挡住地下」
+    if (this._depthMaterial) {
+      const d = this._depthMaterial.uniforms;
+      if (bounds) {
+        d.uHasExcavation.value = 1;
+        d.uExcavationMin.value.set(bounds[0], bounds[1]);
+        d.uExcavationMax.value.set(bounds[2], bounds[3]);
+      } else {
+        d.uHasExcavation.value = 0;
+      }
     }
   }
 
   dispose(): void {
-    if (this._mesh) {
-      this._mesh.geometry.dispose();
-      this._material?.dispose();
-    }
+    // 两块网格共用同一份 geometry，只释放一次
+    this._geom?.dispose();
+    this._geom = null;
+    this._material?.dispose();
+    this._material = null;
+    this._depthMaterial?.dispose();
+    this._depthMaterial = null;
+    this._mesh = null;
+    this._depthMesh = null;
     this.group.clear();
   }
 }

package/src/render/Picker.ts

@@ -68,6 +68,9 @@ const PICK_VERT = /* glsl */ `
     #else
       gl_Position = projectionMatrix * modelViewMatrix * vec4( p, 1.0 );
     #endif
+    // 点云也用这条着色器：不写 gl_PointSize 时光栅化出来只有 1px，
+    // 跟显示尺寸（2px）不匹配，点云会很难点中。对 Mesh 图元这行被忽略。
+    gl_PointSize = 2.0;
   }
 `;
 
@@ -131,6 +134,11 @@ function createPickMaterial(objectId: number): THREE.ShaderMaterial {
   });
 }
 
+/** 点云是 THREE.Points 不是 Mesh，拾取链路要放行 */
+function isPointsObject(o: THREE.Object3D): o is THREE.Points {
+  return (o as unknown as THREE.Points).isPoints === true;
+}
+
 export class Picker {
   readonly renderer: THREE.WebGLRenderer;
   /** 拾取用的渲染目标边长（像素），默认 1 —— 只要点击点那一格 */
@@ -194,12 +202,13 @@ export class Picker {
     const prevClearAlpha = renderer.getClearAlpha();
 
     // ---- 换材质
-    const swapped: Array<[THREE.Mesh, THREE.Material | THREE.Material[]]> = [];
+    const swapped: Array<[THREE.Object3D, THREE.Material | THREE.Material[]]> = [];
     /** 这次拾取里哪些网格是实例化的（它们的 vBatch 编码的是实例序号） */
     const instancedPickIds = new Set<number>();
     scene.traverseVisible((o) => {
       const mesh = o as THREE.Mesh;
-      if (!mesh.isMesh) return;
+      // 点云是 THREE.Points，同样要参与拾取
+      if (!mesh.isMesh && !isPointsObject(mesh)) return;
       const ud = mesh.userData as PickUserData;
       if (ud.pickId === undefined) return;
       if (!ud.pickMaterial) ud.pickMaterial = createPickMaterial(ud.pickId);
@@ -236,7 +245,7 @@ export class Picker {
     const hidden: THREE.Object3D[] = [];
     scene.traverseVisible((o) => {
       const mesh = o as THREE.Mesh;
-      if (mesh.isMesh && (mesh.userData as PickUserData).pickId === undefined) {
+      if ((mesh.isMesh || isPointsObject(mesh)) && (mesh.userData as PickUserData).pickId === undefined) {
         hidden.push(mesh);
         mesh.visible = false;
       }
@@ -272,7 +281,7 @@ export class Picker {
           : { objectId, batchId: rawId };
       }
     } finally {
-      for (const [mesh, mat] of swapped) mesh.material = mat;
+      for (const [obj, mat] of swapped) (obj as THREE.Mesh).material = mat;
       for (const o of hidden) o.visible = true;
       renderer.setRenderTarget(prevTarget);
       renderer.setViewport(prevViewport);

package/src/render/PointCloudMaterial.ts

@@ -0,0 +1,174 @@
+/**
+ * 点云着色
+ *
+ * 点云没有法线、没有 uv、没有楼层概念，所以 StyleMaterial 那套按面着色的模式
+ * （顶/侧分色、按楼层、动态扫描…）对 `THREE.Points` 天然不适用。这里只做三种
+ * 点云真正能表达的模式，其余一律回退顶点色：
+ *
+ *   vertex  原色：顶点色上屏（Draco 点云在解析阶段已把分类码烘成分类色带）
+ *   solid   单色：整个点云一个颜色
+ *   height  按高度：顶点世界坐标 z 在 uColorA → uColorB 之间连续渐变
+ *   selected 选中高亮：整块点云混成 uSelColor（点云没有单体粒度，只能整块亮）
+ *
+ * 两个设计要点：
+ *   1. height / selected 的 ShaderMaterial 直接**引用**全局共享 uniform 对象
+ *      （`shared.uColorA` 等），所以 `_applyStyleUniforms()` 改一次颜色，
+ *      点云渐变自动跟着变，不需要额外同步。
+ *   2. 材质由本模块按 mode 创建并打上 `pcOwned` 标记，换 mode 时旧的自己
+ *      销毁；GeometryBuilder 里那个共享单例没有标记，替换时不碰它。
+ */
+import * as THREE from 'three';
+import { STYLE, type S3MStyle, type StyleMode } from './StyleMaterial.js';
+import type { StyleUniforms } from '../core/types.js';
+
+/** 点云实际持有的材质形态 */
+export type PointCloudKind = 'vertex' | 'solid' | 'height' | 'selected';
+
+/** 与 GeometryBuilder 里共享 PointsMaterial 保持同一个点尺寸（屏幕像素，不衰减） */
+const POINT_SIZE = 2;
+
+/** S3M 着色模式 → 点云形态。不适用于点云的模式统一回退顶点色。 */
+export function pointCloudKindOf(mode: StyleMode): 'vertex' | 'solid' | 'height' {
+  if (mode === STYLE.SOLID) return 'solid';
+  if (mode === STYLE.HEIGHT) return 'height';
+  return 'vertex';
+}
+
+/* ------------------------------------------------------------------ 着色器 */
+
+const POINT_VERT = /* glsl */ `
+  uniform float uPointSize;
+  varying float vWorldZ;
+  void main() {
+    vec4 world = modelMatrix * vec4( position, 1.0 );
+    vWorldZ = world.z;
+    gl_Position = projectionMatrix * viewMatrix * world;
+    gl_PointSize = uPointSize;
+  }
+`;
+
+const HEIGHT_FRAG = /* glsl */ `
+  uniform vec3 uColorA;
+  uniform vec3 uColorB;
+  uniform float uHeightMin;
+  uniform float uHeightMax;
+  uniform float uOpacity;
+  varying float vWorldZ;
+  void main() {
+    float h = clamp( ( vWorldZ - uHeightMin ) / max( uHeightMax - uHeightMin, 0.001 ), 0.0, 1.0 );
+    gl_FragColor = vec4( mix( uColorA, uColorB, h ), uOpacity );
+  }
+`;
+
+const SELECTED_FRAG = /* glsl */ `
+  uniform vec3 uSelColor;
+  uniform float uOpacity;
+  void main() {
+    gl_FragColor = vec4( uSelColor, uOpacity );
+  }
+`;
+
+function createPointCloudMaterial(
+  kind: PointCloudKind,
+  style: S3MStyle,
+  shared: StyleUniforms
+): THREE.Material {
+  let mat: THREE.Material;
+  if (kind === 'height') {
+    mat = new THREE.ShaderMaterial({
+      uniforms: {
+        // 直接引用共享 uniform 对象：换色不用重建材质
+        uColorA: shared.uColorA,
+        uColorB: shared.uColorB,
+        uHeightMin: shared.uHeightMin,
+        uHeightMax: shared.uHeightMax,
+        uPointSize: { value: POINT_SIZE },
+        uOpacity: { value: style.opacity ?? 1 },
+      },
+      vertexShader: POINT_VERT,
+      fragmentShader: HEIGHT_FRAG,
+      transparent: (style.opacity ?? 1) < 0.999,
+      depthWrite: (style.opacity ?? 1) >= 0.999,
+    });
+  } else if (kind === 'selected') {
+    mat = new THREE.ShaderMaterial({
+      uniforms: {
+        uSelColor: shared.uSelColor,
+        uPointSize: { value: POINT_SIZE },
+        uOpacity: { value: style.opacity ?? 1 },
+      },
+      vertexShader: POINT_VERT,
+      fragmentShader: SELECTED_FRAG,
+      transparent: (style.opacity ?? 1) < 0.999,
+      depthWrite: (style.opacity ?? 1) >= 0.999,
+    });
+  } else if (kind === 'solid') {
+    mat = new THREE.PointsMaterial({
+      size: POINT_SIZE,
+      sizeAttenuation: false,
+      color: new THREE.Color(style.colorA),
+      transparent: (style.opacity ?? 1) < 0.999,
+      opacity: style.opacity ?? 1,
+      depthWrite: (style.opacity ?? 1) >= 0.999,
+    });
+  } else {
+    mat = new THREE.PointsMaterial({
+      size: POINT_SIZE,
+      sizeAttenuation: false,
+      vertexColors: true,
+      transparent: (style.opacity ?? 1) < 0.999,
+      opacity: style.opacity ?? 1,
+      depthWrite: (style.opacity ?? 1) >= 0.999,
+    });
+  }
+  (mat.userData as { pcOwned?: boolean }).pcOwned = true;
+  return mat;
+}
+
+/**
+ * 把点云对象的材质同步到当前样式。
+ *
+ * kind 没变就只改不透明度 / 单色色值，不重建材质；变了才换，旧的自己销毁。
+ * 每次 setStyle 都会走到这里，代价是一次属性比较。
+ */
+export function applyPointCloudStyle(
+  points: THREE.Points,
+  style: S3MStyle,
+  shared: StyleUniforms,
+  selected = false
+): void {
+  const ud = points.userData as { pcKind?: PointCloudKind; pcTransparent?: boolean };
+  const want: PointCloudKind = selected ? 'selected' : pointCloudKindOf(style.mode);
+
+  if (ud.pcKind !== want) {
+    const prev = points.material as THREE.Material | undefined;
+    points.material = createPointCloudMaterial(want, style, shared);
+    // 只销毁自己创建的；GeometryBuilder 的共享单例没有 pcOwned 标记，不能碰
+    if (prev && (prev.userData as { pcOwned?: boolean } | undefined)?.pcOwned) prev.dispose();
+    ud.pcKind = want;
+    ud.pcTransparent = undefined;
+  } else if (want === 'solid') {
+    (points.material as THREE.PointsMaterial).color?.set(style.colorA);
+  }
+
+  const o = Math.min(1, Math.max(0.05, style.opacity ?? 1));
+  const transparent = o < 0.999;
+  const keepDepth = style.depthWrite !== false;
+  const mat = points.material as THREE.Material & { uniforms?: Record<string, { value: unknown }> };
+  mat.transparent = transparent;
+  mat.opacity = o;
+  mat.depthWrite = transparent ? keepDepth : true;
+  // ShaderMaterial 的 .opacity 不参与渲染，透明度走自己的 uniform
+  if (mat.uniforms?.uOpacity) mat.uniforms.uOpacity.value = o;
+  // 只有混合开关真变了才标记重编译，避免每次 setStyle 都重编一遍
+  if (ud.pcTransparent !== transparent) {
+    ud.pcTransparent = transparent;
+    mat.needsUpdate = true;
+  }
+}
+
+/** 点云对象是否由本模块持有材质（卸载时用来决定要不要 dispose） */
+export function isOwnedPointCloudMaterial(mat: THREE.Material | THREE.Material[] | undefined): boolean {
+  const m = Array.isArray(mat) ? mat[0] : mat;
+  return !!m && (m.userData as { pcOwned?: boolean } | undefined)?.pcOwned === true;
+}