s3m-three 0.3.9 → 0.3.10

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> {
@@ -1132,6 +1137,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;
+  }
   /**
    * 单体样式过渡：颜色 / 抬高 / 透明度 / 平移可以任意组合。
    *
@@ -2452,6 +2547,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 +2566,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 +3387,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 +3415,7 @@ export class S3MViewer {
     return (
       animating ||
       this.style.mode === STYLE.DYNAMIC ||
+      gpuPathActive ||
       this.stats.loading > 0 ||
       tilesetChanged
     );

package/src/render/StyleMaterial.ts

@@ -11,6 +11,7 @@
 import * as THREE from 'three';
 import type { StyleUniforms } from '../core/types.js';
 import { DEFAULT_FLOOR_HEIGHT } from '../core/FeatureInfo.js';
+import { GPUPathManager } from './GPUPathManager.js';
 
 /** 着色模式，数值与着色器里的 uMode 一一对应 */
 export const STYLE = {
@@ -188,8 +189,9 @@ const DUMMY_DATA = new Float32Array([
   1, 0, 0, 0,    // Row 2: rot row 0, pivot.x
   0, 1, 0, 0,    // Row 3: rot row 1, pivot.y
   0, 0, 1, 0,    // Row 4: rot row 2, pivot.z
+  -1, 0, 0, 0,   // Row 5: pathId (-1=none), speed, phase, modeFlag
 ]);
-export const DUMMY_BATCH_TEX = new THREE.DataTexture(DUMMY_DATA, 1, 5, THREE.RGBAFormat, THREE.FloatType);
+export const DUMMY_BATCH_TEX = new THREE.DataTexture(DUMMY_DATA, 1, 6, THREE.RGBAFormat, THREE.FloatType);
 DUMMY_BATCH_TEX.minFilter = THREE.NearestFilter;
 DUMMY_BATCH_TEX.magFilter = THREE.NearestFilter;
 DUMMY_BATCH_TEX.needsUpdate = true;
@@ -235,6 +237,14 @@ export function createSharedUniforms(): StyleUniforms {
     uAmbientGain: { value: 0 },
     /** 双纹理交叉淡化插值系数（0 = 纯 uBatchTex, 1 = 纯 uBatchTex2） */
     uBatchMix: { value: 0 },
+    /** GPU 路径数据采样纹理 */
+    uPathTex: { value: GPUPathManager.DUMMY_PATH_TEX },
+    /** GPU 路径纹理中包含的路径条数（高度） */
+    uPathCount: { value: 1 },
+    /** 是否激活 GPU 路径动画（0 = 未激活，1 = 激活） */
+    uPathTexActive: { value: 0 },
+    /** GPU 路径时间戳（秒） */
+    uPathTime: { value: 0 },
     /**
      * 图层整体透明度：在片元里乘进 diffuseColor.a。
      *
@@ -277,6 +287,10 @@ const VERT_PARS = /* glsl */ `
   uniform float uBatchMix;
   uniform float uBatchTexWidth;
   uniform int uBatchTexActive;
+  uniform sampler2D uPathTex;
+  uniform float uPathCount;
+  uniform float uPathTime;
+  uniform int uPathTexActive;
   varying float vBatchId;
   varying vec3 vVertColor;
   varying float vWorldZ;
@@ -341,22 +355,63 @@ const VERT_SETUP = /* glsl */ `
   float s3mBatchSetup = s3mBatchRaw();
   if ( uBatchTexActive > 0 && s3mBatchSetup >= 0.0 ) {
     float s3mU = ( s3mBatchSetup + 0.5 ) / uBatchTexWidth;
-    vec4 bState = s3mSampleBatchRow0( uBatchTex, uBatchTex2, vec2( s3mU, 0.1 ), uBatchMix );
+    vec4 bState = s3mSampleBatchRow0( uBatchTex, uBatchTex2, vec2( s3mU, 0.08333333 ), uBatchMix );
     if ( bState.a >= -0.5 ) {
-      vec4 bOffset = s3mSampleBatchRow1( uBatchTex, uBatchTex2, vec2( s3mU, 0.3 ), uBatchMix );
+      vec4 bOffset = s3mSampleBatchRow1( uBatchTex, uBatchTex2, vec2( s3mU, 0.25 ), uBatchMix );
       s3mCustomOffset = bOffset.xyz;
       if ( s3mCustomOffset.z == 0.0 && bState.a > 0.0 ) {
         s3mCustomOffset.z = bState.a;
       }
-      vec4 r2 = s3mSampleBatch( uBatchTex, uBatchTex2, vec2( s3mU, 0.5 ), uBatchMix );
-      vec4 r3 = s3mSampleBatch( uBatchTex, uBatchTex2, vec2( s3mU, 0.7 ), uBatchMix );
-      vec4 r4 = s3mSampleBatch( uBatchTex, uBatchTex2, vec2( s3mU, 0.9 ), uBatchMix );
+      vec4 r2 = s3mSampleBatch( uBatchTex, uBatchTex2, vec2( s3mU, 0.41666667 ), uBatchMix );
+      vec4 r3 = s3mSampleBatch( uBatchTex, uBatchTex2, vec2( s3mU, 0.58333333 ), uBatchMix );
+      vec4 r4 = s3mSampleBatch( uBatchTex, uBatchTex2, vec2( s3mU, 0.75 ), uBatchMix );
       s3mRot = mat3(
         vec3( r2.x, r3.x, r4.x ),
         vec3( r2.y, r3.y, r4.y ),
         vec3( r2.z, r3.z, r4.z )
       );
       s3mPivot = vec3( r2.w, r3.w, r4.w );
+
+      // Row 5: GPU 路径动画计算
+      if ( uPathTexActive > 0 ) {
+        vec4 r5 = s3mSampleBatch( uBatchTex, uBatchTex2, vec2( s3mU, 0.91666667 ), uBatchMix );
+        float pathId = r5.x;
+        float speed = r5.y;
+        float phase = r5.z;
+        float mode = r5.w;
+        if ( pathId >= 0.0 && mode > 0.5 && uPathCount > 0.0 ) {
+          float t = phase + uPathTime * speed;
+          bool autoHeading = true;
+          if ( mode >= 4.0 ) {
+            autoHeading = false;
+            mode -= 3.0;
+          }
+          if ( mode < 1.5 ) {
+            t = fract( t );
+          } else if ( mode < 2.5 ) {
+            t = clamp( t, 0.0, 1.0 );
+          } else {
+            t = mod( t, 2.0 );
+            t = ( t > 1.0 ) ? ( 2.0 - t ) : t;
+          }
+          float pathU = ( t * 255.0 + 0.5 ) / 256.0;
+          float pathV = ( pathId + 0.5 ) / uPathCount;
+          vec4 pathSample = texture2D( uPathTex, vec2( pathU, pathV ) );
+          vec3 pathPos = pathSample.xyz;
+          float pathYaw = pathSample.w;
+          if ( autoHeading ) {
+            float c = cos( pathYaw );
+            float s = sin( pathYaw );
+            mat3 rotHeading = mat3(
+              c, -s, 0.0,
+              s,  c, 0.0,
+              0.0, 0.0, 1.0
+            );
+            s3mRot = rotHeading * s3mRot;
+          }
+          s3mCustomOffset += pathPos;
+        }
+      }
     }
   }
   objectNormal = normalize( s3mRot * objectNormal );
@@ -366,7 +421,7 @@ const VERT_ELEVATION = /* glsl */ `
   float s3mBatchElev = s3mBatchRaw();
   if ( uBatchTexActive > 0 && s3mBatchElev >= 0.0 ) {
     float s3mU = ( s3mBatchElev + 0.5 ) / uBatchTexWidth;
-    vec4 bState = s3mSampleBatchRow0( uBatchTex, uBatchTex2, vec2( s3mU, 0.1 ), uBatchMix );
+    vec4 bState = s3mSampleBatchRow0( uBatchTex, uBatchTex2, vec2( s3mU, 0.08333333 ), uBatchMix );
     if ( bState.a < -0.5 ) {
       transformed = vec3( 0.0 );
     }
@@ -637,7 +692,7 @@ const FRAG_COLOR = /* glsl */ `
   if ( uBatchTexActive > 0 && s3mBid >= 0.0 ) {
     // 用取整后的 id 采样：否则逐像素的插值误差会让纹素在边界上来回跳，同样出彩色噪点
     float s3mU = ( s3mBid + 0.5 ) / uBatchTexWidth;
-    vec4 bState = s3mSampleBatchRow0( uBatchTex, uBatchTex2, vec2( s3mU, 0.1 ), uBatchMix );
+    vec4 bState = s3mSampleBatchRow0( uBatchTex, uBatchTex2, vec2( s3mU, 0.08333333 ), uBatchMix );
     if ( bState.a < -0.5 ) {
       discard; // 属于被过滤隐藏的单体
     }
@@ -648,7 +703,7 @@ const FRAG_COLOR = /* glsl */ `
     }
     // 单体独立透明度（状态纹理第 2 行 alpha，0 = 无覆盖）。
     // 与全局 uOpacity（diffuseColor.a 初值）和图集贴图自带 alpha 逐级叠乘
-    vec4 bOffset = s3mSampleBatchRow1( uBatchTex, uBatchTex2, vec2( s3mU, 0.3 ), uBatchMix );
+    vec4 bOffset = s3mSampleBatchRow1( uBatchTex, uBatchTex2, vec2( s3mU, 0.25 ), uBatchMix );
     if ( bOffset.a > 0.0 ) {
       diffuseColor.a *= bOffset.a;
     }
@@ -836,6 +891,10 @@ const OUTLINE_VERT = /* glsl */ `
   uniform float uBatchMix;
   uniform float uBatchTexWidth;
   uniform int uBatchTexActive;
+  uniform sampler2D uPathTex;
+  uniform float uPathCount;
+  uniform float uPathTime;
+  uniform int uPathTexActive;
   varying float vSel;
 
   vec4 s3mSampleBatch( sampler2D texA, sampler2D texB, vec2 uv, float mixVal ) {
@@ -852,24 +911,64 @@ const OUTLINE_VERT = /* glsl */ `
     vec3 s3mPivot = vec3( 0.0 );
     if ( uBatchTexActive > 0 && aBatchId >= 0.0 ) {
       float s3mU = ( aBatchId + 0.5 ) / uBatchTexWidth;
-      vec4 bState = s3mSampleBatch( uBatchTex, uBatchTex2, vec2( s3mU, 0.1 ), uBatchMix );
+      vec4 bState = s3mSampleBatch( uBatchTex, uBatchTex2, vec2( s3mU, 0.08333333 ), uBatchMix );
       if ( bState.a < -0.5 ) {
         vSel = 0.0; // 过滤隐藏的单体不显示描边
       } else {
-        vec4 bOffset = s3mSampleBatch( uBatchTex, uBatchTex2, vec2( s3mU, 0.3 ), uBatchMix );
+        vec4 bOffset = s3mSampleBatch( uBatchTex, uBatchTex2, vec2( s3mU, 0.25 ), uBatchMix );
         s3mCustomOffset = bOffset.xyz;
         if ( s3mCustomOffset.z == 0.0 && bState.a > 0.0 ) {
           s3mCustomOffset.z = bState.a;
         }
-        vec4 r2 = s3mSampleBatch( uBatchTex, uBatchTex2, vec2( s3mU, 0.5 ), uBatchMix );
-        vec4 r3 = s3mSampleBatch( uBatchTex, uBatchTex2, vec2( s3mU, 0.7 ), uBatchMix );
-        vec4 r4 = s3mSampleBatch( uBatchTex, uBatchTex2, vec2( s3mU, 0.9 ), uBatchMix );
+        vec4 r2 = s3mSampleBatch( uBatchTex, uBatchTex2, vec2( s3mU, 0.41666667 ), uBatchMix );
+        vec4 r3 = s3mSampleBatch( uBatchTex, uBatchTex2, vec2( s3mU, 0.58333333 ), uBatchMix );
+        vec4 r4 = s3mSampleBatch( uBatchTex, uBatchTex2, vec2( s3mU, 0.75 ), uBatchMix );
         s3mRot = mat3(
           vec3( r2.x, r3.x, r4.x ),
           vec3( r2.y, r3.y, r4.y ),
           vec3( r2.z, r3.z, r4.z )
         );
         s3mPivot = vec3( r2.w, r3.w, r4.w );
+
+        if ( uPathTexActive > 0 ) {
+          vec4 r5 = s3mSampleBatch( uBatchTex, uBatchTex2, vec2( s3mU, 0.91666667 ), uBatchMix );
+          float pathId = r5.x;
+          float speed = r5.y;
+          float phase = r5.z;
+          float mode = r5.w;
+          if ( pathId >= 0.0 && mode > 0.5 && uPathCount > 0.0 ) {
+            float t = phase + uPathTime * speed;
+            bool autoHeading = true;
+            if ( mode >= 4.0 ) {
+              autoHeading = false;
+              mode -= 3.0;
+            }
+            if ( mode < 1.5 ) {
+              t = fract( t );
+            } else if ( mode < 2.5 ) {
+              t = clamp( t, 0.0, 1.0 );
+            } else {
+              t = mod( t, 2.0 );
+              t = ( t > 1.0 ) ? ( 2.0 - t ) : t;
+            }
+            float pathU = ( t * 255.0 + 0.5 ) / 256.0;
+            float pathV = ( pathId + 0.5 ) / uPathCount;
+            vec4 pathSample = texture2D( uPathTex, vec2( pathU, pathV ) );
+            vec3 pathPos = pathSample.xyz;
+            float pathYaw = pathSample.w;
+            if ( autoHeading ) {
+              float c = cos( pathYaw );
+              float s = sin( pathYaw );
+              mat3 rotHeading = mat3(
+                c, -s, 0.0,
+                s,  c, 0.0,
+                0.0, 0.0, 1.0
+              );
+              s3mRot = rotHeading * s3mRot;
+            }
+            s3mCustomOffset += pathPos;
+          }
+        }
       }
     }
     vec3 p = position + ( s3mRot * normal ) * uWidth * vSel;
@@ -899,6 +998,10 @@ export interface OutlineMaterial extends THREE.ShaderMaterial {
     uBatchMix: { value: number };
     uBatchTexWidth: { value: number };
     uBatchTexActive: { value: number };
+    uPathTex: { value: unknown };
+    uPathCount: { value: number };
+    uPathTexActive: { value: number };
+    uPathTime: { value: number };
     uColor: { value: THREE.Color };
   };
 }
@@ -916,6 +1019,10 @@ export function createOutlineMaterial(shared: StyleUniforms, initialWidth = 0.9)
       uBatchMix: shared.uBatchMix ?? { value: 0 },
       uBatchTexWidth: { value: 1.0 },
       uBatchTexActive: { value: 0 },
+      uPathTex: shared.uPathTex ?? { value: GPUPathManager.DUMMY_PATH_TEX },
+      uPathCount: shared.uPathCount ?? { value: 1 },
+      uPathTexActive: shared.uPathTexActive ?? { value: 0 },
+      uPathTime: shared.uPathTime ?? { value: 0 },
       uColor: { value: shared.uSelColor.value.clone() },
     },
     vertexShader: OUTLINE_VERT,