s3m-three 0.3.9 → 0.3.11

package/src/render/GPUPathManager.ts

@@ -0,0 +1,306 @@
+/**
+ * GPU 路径动画管理器
+ *
+ * 负责：
+ * 1. 注册与管理多条三维离散路径（Path）
+ * 2. 将空间折线等弧长采样并烘焙为 Float32Array 格式的 2D 数据纹理 (uPathTex)：
+ *    - Width: SAMPLES_PER_PATH (默认 256)
+ *    - Height: max(pathCount, 1)
+ *    - Format: RGBAFormat, FloatType
+ *    - 像素通道:
+ *      - R: X 坐标 (米)
+ *      - G: Y 坐标 (米)
+ *      - B: Z 坐标 (米)
+ *      - A: 切线偏航角 yaw (弧度, atan2(dy, dx), 经过连续角度展开 unwrap)
+ * 3. 硬件双线性插值 (LinearFilter) 支持：
+ *    GPU 在顶点着色器中按归一化进度 t (0~1) 采样，硬件自动插值获得平滑轨迹与朝向
+ */
+import * as THREE from 'three';
+import { Path } from '../anim/Path.js';
+
+export const SAMPLES_PER_PATH = 256;
+
+export interface GPUPathInfo {
+  id: number;
+  name?: string;
+  path: Path;
+}
+
+export class GPUPathManager {
+  private _paths: Map<number, GPUPathInfo> = new Map();
+  private _nextId = 0;
+  private _texture: THREE.DataTexture | null = null;
+  private _data: Float32Array | null = null;
+  private _dirty = false;
+
+  /** 默认空纹理，防止 WebGL 未绑定报错 */
+  static readonly DUMMY_PATH_TEX: THREE.DataTexture = (() => {
+    const data = new Float32Array(SAMPLES_PER_PATH * 1 * 4);
+    const tex = new THREE.DataTexture(data, SAMPLES_PER_PATH, 1, THREE.RGBAFormat, THREE.FloatType);
+    tex.minFilter = THREE.LinearFilter;
+    tex.magFilter = THREE.LinearFilter;
+    tex.wrapS = THREE.ClampToEdgeWrapping;
+    tex.wrapT = THREE.ClampToEdgeWrapping;
+    tex.needsUpdate = true;
+    return tex;
+  })();
+
+  constructor() {}
+
+  /**
+   * 注册一条路径到 GPU 路径库
+   * @param pointsOrPath 折线点数组或现有的 Path 实例
+   * @param opts 注册选项（可指定固定 id 或 name）
+   * @returns 分配的路径 ID (从 0 开始的连续或离散索引)
+   */
+  registerPath(
+    pointsOrPath: Path | ArrayLike<number> | Array<[number, number, number]>,
+    opts: { id?: number; name?: string; closed?: boolean } = {}
+  ): number {
+    const path =
+      pointsOrPath instanceof Path
+        ? pointsOrPath
+        : new Path(pointsOrPath, { closed: opts.closed });
+
+    let id = opts.id;
+    if (id == null) {
+      id = this._nextId++;
+      while (this._paths.has(id)) {
+        id = this._nextId++;
+      }
+    } else {
+      if (id >= this._nextId) {
+        this._nextId = id + 1;
+      }
+    }
+
+    this._paths.set(id, { id, name: opts.name, path });
+    this._dirty = true;
+    return id;
+  }
+
+  /**
+   * 注销一条路径
+   */
+  unregisterPath(id: number): boolean {
+    const removed = this._paths.delete(id);
+    if (removed) {
+      this._dirty = true;
+    }
+    return removed;
+  }
+
+  /**
+   * 获取指定 ID 的路径对象
+   */
+  getPath(id: number): Path | undefined {
+    return this._paths.get(id)?.path;
+  }
+
+  /**
+   * 是否存在指定 ID 的路径
+   */
+  hasPath(id: number): boolean {
+    return this._paths.has(id);
+  }
+
+  /**
+   * 获取所有已注册的路径 ID
+   */
+  getPathIds(): number[] {
+    return Array.from(this._paths.keys()).sort((a, b) => a - b);
+  }
+
+  /**
+   * 清空所有已注册的路径
+   */
+  clear(): void {
+    if (this._paths.size > 0) {
+      this._paths.clear();
+      this._nextId = 0;
+      this._dirty = true;
+    }
+  }
+
+  /**
+   * 当前注册的有效路径数量
+   */
+  get count(): number {
+    return this._paths.size;
+  }
+
+  /**
+   * 获取 GPU 路径数据纹理，若有变动会自动触发重新烘焙
+   */
+  getTexture(): THREE.DataTexture {
+    if (this._dirty || !this._texture) {
+      this._bake();
+    }
+    return this._texture ?? GPUPathManager.DUMMY_PATH_TEX;
+  }
+
+  /**
+   * 将当前路径纹理与 uniform 状态同步到材质 uniform 字典
+   */
+  updateUniforms(uniforms: Record<string, any>): void {
+    const tex = this.getTexture();
+    const active = this._paths.size > 0 ? 1 : 0;
+    const maxId = this._getMaxPathId();
+    const height = Math.max(maxId + 1, 1);
+
+    if (uniforms.uPathTex) uniforms.uPathTex.value = tex;
+    if (uniforms.uPathCount) uniforms.uPathCount.value = height;
+    if (uniforms.uPathTexActive) uniforms.uPathTexActive.value = active;
+  }
+
+  /**
+   * 烘焙路径数据到纹理
+   */
+  private _bake(): void {
+    this._dirty = false;
+    if (this._paths.size === 0) {
+      if (this._texture && this._texture !== GPUPathManager.DUMMY_PATH_TEX) {
+        this._texture.dispose();
+      }
+      this._texture = GPUPathManager.DUMMY_PATH_TEX;
+      this._data = null;
+      return;
+    }
+
+    const maxId = this._getMaxPathId();
+    const height = Math.max(maxId + 1, 1);
+    const totalPixels = SAMPLES_PER_PATH * height;
+    const bufferLength = totalPixels * 4;
+
+    if (!this._data || this._data.length !== bufferLength) {
+      if (this._texture && this._texture !== GPUPathManager.DUMMY_PATH_TEX) {
+        this._texture.dispose();
+      }
+      this._data = new Float32Array(bufferLength);
+      this._texture = new THREE.DataTexture(
+        this._data,
+        SAMPLES_PER_PATH,
+        height,
+        THREE.RGBAFormat,
+        THREE.FloatType
+      );
+      this._texture.minFilter = THREE.LinearFilter;
+      this._texture.magFilter = THREE.LinearFilter;
+      this._texture.wrapS = THREE.ClampToEdgeWrapping;
+      this._texture.wrapT = THREE.ClampToEdgeWrapping;
+    } else {
+      this._data.fill(0);
+    }
+
+    const scratchA = [0, 0, 0];
+    const scratchB = [0, 0, 0];
+    const N = SAMPLES_PER_PATH;
+
+    for (const [id, info] of this._paths) {
+      if (id < 0 || id >= height) continue;
+      const path = info.path;
+      const rowOffset = id * N * 4;
+
+      // 提取 N 个等弧长采样点位置与航向切线角
+      let lastYaw = 0;
+      for (let i = 0; i < N; i++) {
+        const t = i / (N - 1);
+        path.sampleAt(t, scratchA);
+
+        // 计算切线方向：取一个极小的前向步长
+        let yaw = lastYaw;
+        if (path.length > 1e-4) {
+          const deltaT = Math.min(1.0, t + 1e-3);
+          path.sampleAt(deltaT, scratchB);
+          let dx = scratchB[0] - scratchA[0];
+          let dy = scratchB[1] - scratchA[1];
+          if (dx * dx + dy * dy < 1e-8 && t > 0) {
+            // 前向位移过小则尝试后向差分
+            const prevT = Math.max(0.0, t - 1e-3);
+            path.sampleAt(prevT, scratchB);
+            dx = scratchA[0] - scratchB[0];
+            dy = scratchA[1] - scratchB[1];
+          }
+          if (dx * dx + dy * dy >= 1e-8) {
+            yaw = Math.atan2(dy, dx);
+          }
+        }
+
+        // 连续角度展开 (Angle Unwrap)：避免在 ±PI 处发生 360° 线性插值回旋
+        if (i > 0) {
+          let diff = yaw - lastYaw;
+          while (diff > Math.PI) {
+            yaw -= 2 * Math.PI;
+            diff = yaw - lastYaw;
+          }
+          while (diff < -Math.PI) {
+            yaw += 2 * Math.PI;
+            diff = yaw - lastYaw;
+          }
+        }
+        lastYaw = yaw;
+
+        const pIdx = rowOffset + i * 4;
+        this._data[pIdx + 0] = scratchA[0];
+        this._data[pIdx + 1] = scratchA[1];
+        this._data[pIdx + 2] = scratchA[2];
+        this._data[pIdx + 3] = yaw;
+      }
+    }
+
+    if (this._texture) {
+      this._texture.needsUpdate = true;
+    }
+  }
+
+  private _getMaxPathId(): number {
+    let max = 0;
+    for (const id of this._paths.keys()) {
+      if (id > max) max = id;
+    }
+    return max;
+  }
+
+  /**
+   * 纯数学模拟采样烘焙纹理（用于单测验证硬件线性插值精度）
+   */
+  sampleBaked(pathId: number, t: number): { position: [number, number, number]; yaw: number } {
+    if (!this._data || !this._paths.has(pathId)) {
+      return { position: [0, 0, 0], yaw: 0 };
+    }
+    const maxId = this._getMaxPathId();
+    if (pathId < 0 || pathId > maxId) {
+      return { position: [0, 0, 0], yaw: 0 };
+    }
+
+    const N = SAMPLES_PER_PATH;
+    const clampedT = Math.min(1.0, Math.max(0.0, t));
+    const sampleCoord = clampedT * (N - 1);
+    const i0 = Math.floor(sampleCoord);
+    const i1 = Math.min(N - 1, i0 + 1);
+    const frac = sampleCoord - i0;
+
+    const rowOffset = pathId * N * 4;
+    const idx0 = rowOffset + i0 * 4;
+    const idx1 = rowOffset + i1 * 4;
+
+    const x = this._data[idx0 + 0] * (1 - frac) + this._data[idx1 + 0] * frac;
+    const y = this._data[idx0 + 1] * (1 - frac) + this._data[idx1 + 1] * frac;
+    const z = this._data[idx0 + 2] * (1 - frac) + this._data[idx1 + 2] * frac;
+    const yaw = this._data[idx0 + 3] * (1 - frac) + this._data[idx1 + 3] * frac;
+
+    return { position: [x, y, z], yaw };
+  }
+
+  /**
+   * 释放纹理与显存
+   */
+  dispose(): void {
+    if (this._texture && this._texture !== GPUPathManager.DUMMY_PATH_TEX) {
+      this._texture.dispose();
+      this._texture = null;
+    }
+    this._data = null;
+    this._paths.clear();
+  }
+}

package/src/render/S3MViewer.ts

@@ -41,6 +41,8 @@ import type { Channel, TransitionOptions } from '../anim/Animator.js';
 import { Path } from '../anim/Path.js';
 import type { EasingFn, EasingName } from '../anim/easing.js';
 import type { LineSharedUniforms, ThickLineMaterial, ThickLineStyleUniforms } from './EdgeLines.js';
+import { GPUPathManager } from './GPUPathManager.js';
+import type { GPUPathOptions } from './FeatureStyleManager.js';
 import {
   buildFeatureEdgeSegments,
   buildPositionBatchMap,
@@ -370,6 +372,9 @@ export class S3MViewer {
   private readonly _datasetManager = new DatasetManager();
   /** 单体样式、专题着色与状态纹理管理器 */
   private readonly _featureStyleManager: FeatureStyleManager;
+  /** GPU 路径动画管理器 */
+  readonly gpuPathManager: GPUPathManager = new GPUPathManager();
+  private _customPathTime = false;
 
   /** 兼容 datasets 映射表暴露 */
   get datasets(): Map<string, S3MDatasetEntry> {
@@ -540,6 +545,9 @@ export class S3MViewer {
     // 这里按 style 实际值调一次 setEdges，让开关真正生效（与 setEdges 后来的手工调用一致）。
     this.setEdges(!!this.style.edges);
 
+    // 初始化图层整体不透明度：确保共享 uniform uOpacity、材质混合开关与棱线外观与初始 style.opacity 严格一致
+    this._applyOpacity();
+
     this._fps.last = performance.now();
     this._datasetQueue = this._normalizeDatasets(options);
     if (options.attributes) this.attributeQuery = new AttributeQuery(options.attributes);
@@ -1132,6 +1140,96 @@ export class S3MViewer {
     this.animator.unregister(key);
     this._pathSpecs.delete(key);
   }
+
+  /**
+   * 注册 GPU 路径到路径库
+   * @param points 折线点数组或 Path 实例
+   * @param opts 选项（可指定路径 ID 或闭合）
+   * @returns 路径 ID
+   */
+  registerGPUPath(
+    points: Path | ArrayLike<number> | Array<[number, number, number]>,
+    opts: { id?: number; name?: string; closed?: boolean } = {}
+  ): number {
+    const id = this.gpuPathManager.registerPath(points, opts);
+    this.gpuPathManager.updateUniforms(this.uniforms);
+    return id;
+  }
+
+  /**
+   * 注销 GPU 路径
+   */
+  unregisterGPUPath(id: number): boolean {
+    const res = this.gpuPathManager.unregisterPath(id);
+    this.gpuPathManager.updateUniforms(this.uniforms);
+    return res;
+  }
+
+  /**
+   * 获取 GPUPathManager 实例
+   */
+  getGPUPathManager(): GPUPathManager {
+    return this.gpuPathManager;
+  }
+
+  /**
+   * 将单体绑定到 GPU 路径动画（智慧交通车流 / 大批量巡检无人机）
+   * @param smid 单体 ID
+   * @param path 路径 ID 或新的路径折线
+   * @param options 动画配置（速度、相位、循环模式、自动朝向等）
+   */
+  bindGPUPath(
+    smid: number,
+    path: number | Path | ArrayLike<number> | Array<[number, number, number]>,
+    options: Omit<GPUPathOptions, 'pathId'> = {}
+  ): number {
+    let pathId: number;
+    if (typeof path === 'number') {
+      pathId = path;
+    } else {
+      pathId = this.registerGPUPath(path);
+    }
+    const meshes = this._meshesOf([smid]);
+    this._featureStyleManager.bindGPUPath(smid, pathId, options, meshes);
+    for (const mesh of meshes) mesh.frustumCulled = false;
+    this.gpuPathManager.updateUniforms(this.uniforms);
+    return pathId;
+  }
+
+  /**
+   * 解绑单体的 GPU 路径动画
+   */
+  unbindGPUPath(smid: number): void {
+    const meshes = this._meshesOf([smid]);
+    this._featureStyleManager.unbindGPUPath(smid, meshes);
+    this.gpuPathManager.updateUniforms(this.uniforms);
+  }
+
+  /**
+   * 手动设置单体在 GPU 路径上的归一化进度（0.0 ~ 1.0）
+   */
+  setGPUPathProgress(smid: number, progress: number): void {
+    const meshes = this._meshesOf([smid]);
+    this._featureStyleManager.setGPUPathProgress(smid, progress, meshes);
+    for (const mesh of meshes) mesh.frustumCulled = false;
+  }
+
+  /**
+   * 设置全局 GPU 路径时间（秒）
+   */
+  setGPUPathTime(time: number, autoAdvance = false): void {
+    if (this.uniforms.uPathTime) {
+      this.uniforms.uPathTime.value = time;
+    }
+    this._customPathTime = !autoAdvance;
+  }
+
+  /**
+   * 获取全局 GPU 路径时间（秒）
+   */
+  getGPUPathTime(): number {
+    return this.uniforms.uPathTime?.value ?? 0;
+  }
   /**
    * 单体样式过渡：颜色 / 抬高 / 透明度 / 平移可以任意组合。
    *
@@ -1584,7 +1682,8 @@ export class S3MViewer {
           const o = Math.min(1, Math.max(0.05, this.style.opacity ?? 1));
           // 不写 mat.opacity：全局透明度走共享 uOpacity，材质自身 opacity 保留模型自带 alpha
           mat.transparent = o < 0.999;
-          mat.depthWrite = 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;
           this._featureStyleManager.applyOverridesToMesh(mesh);
@@ -1639,7 +1738,7 @@ export class S3MViewer {
         // 淡入期间强制开了 transparent + depthWrite，结束时不能自己拍板关掉——
         // 图层可能本来就半透明、单体也可能还有淡化。交给淡化流程重新裁决一次。
         this._featureStyleManager.applyOverridesToMesh(mesh);
-        if (!mat.transparent) mat.depthWrite = true;
+        mat.depthWrite = this.style.depthWrite !== false;
         this._requestRepaint();
       },
     });
@@ -2010,6 +2109,9 @@ export class S3MViewer {
     if (u.uAmbientGain && s.ambientGain != null) {
       u.uAmbientGain.value = s.ambientGain;
     }
+    if (u.uOpacity && s.opacity != null) {
+      u.uOpacity.value = Math.min(1, Math.max(0.05, s.opacity));
+    }
     if (this.outlineMaterial) {
       if (this.outlineMaterial.uniforms.uElevation && s.selectElevation != null) {
         this.outlineMaterial.uniforms.uElevation.value = s.selectElevation;
@@ -2452,6 +2554,10 @@ export class S3MViewer {
           uBatchMix: this.uniforms.uBatchMix,
           uBatchTexWidth: styled.userData.uBatchTexWidth,
           uBatchTexActive: styled.userData.uBatchTexActive,
+          uPathTex: this.uniforms.uPathTex,
+          uPathCount: this.uniforms.uPathCount,
+          uPathTexActive: this.uniforms.uPathTexActive,
+          uPathTime: this.uniforms.uPathTime,
         }
       : undefined;
     return createThickLineMaterial(this.lineShared, {}, this._edgeStyleUniforms, batch);
@@ -2467,6 +2573,10 @@ export class S3MViewer {
           uBatchMix: this.uniforms.uBatchMix,
           uBatchTexWidth: styled.userData.uBatchTexWidth,
           uBatchTexActive: styled.userData.uBatchTexActive,
+          uPathTex: this.uniforms.uPathTex,
+          uPathCount: this.uniforms.uPathCount,
+          uPathTexActive: this.uniforms.uPathTexActive,
+          uPathTime: this.uniforms.uPathTime,
         }
       : undefined;
     return createThickLineMaterial(this.lineShared, {}, this._selEdgeStyleUniforms, batch);
@@ -3284,6 +3394,12 @@ export class S3MViewer {
       this.uniforms.uTime.value += 0.016 * (this.style.speed ?? 1);
     }
 
+    this.gpuPathManager.updateUniforms(this.uniforms);
+    const gpuPathActive = (this.uniforms.uPathTexActive?.value ?? 0) > 0;
+    if (gpuPathActive && !this._customPathTime && this.uniforms.uPathTime) {
+      this.uniforms.uPathTime.value += 0.016;
+    }
+
     this._updateLights();
 
     // 等宽棱线按设备像素撑开，分辨率每帧同步一次
@@ -3306,6 +3422,7 @@ export class S3MViewer {
     return (
       animating ||
       this.style.mode === STYLE.DYNAMIC ||
+      gpuPathActive ||
       this.stats.loading > 0 ||
       tilesetChanged
     );