s3m-three 0.3.8 → 0.3.10

package/src/render/FeatureStyleManager.ts

@@ -21,6 +21,19 @@ import {
 import type { AttributeQuery, AttributeQueryOptions, AttributeRow } from '../core/AttributeQuery.js';
 import type { StyledMaterial } from './StyleMaterial.js';
 
+export interface GPUPathOptions {
+  /** 绑定的路径索引 ID（0, 1, 2...） */
+  pathId: number;
+  /** 进度的运动速率（归一化进度/秒，例如 0.05 即 20 秒一圈；为 0 则靠 progress/phase 驱动） */
+  speed?: number;
+  /** 初始相位 / 进度偏移（0.0 ~ 1.0） */
+  phase?: number;
+  /** 循环模式：'loop'（循环，默认） | 'pingpong'（往返） | 'clamp'（单次到达终点停止） */
+  loop?: 'loop' | 'pingpong' | 'clamp' | boolean;
+  /** 是否根据路径切线自动旋转朝向（偏航角 yaw，默认 true） */
+  autoHeading?: boolean;
+}
+
 export interface FeatureStyle {
   /** 自定义单体颜色 */
   color?: string;
@@ -32,6 +45,161 @@ export interface FeatureStyle {
   opacity?: number;
   /** 是否隐藏该单体 */
   hidden?: boolean;
+  /**
+   * 单体姿态旋转。
+   * 支持：
+   * 1. 纯数字：绕 Z 轴（朝天方向）旋转弧度（最常用的建筑朝向）
+   * 2. 数组 [rx, ry, rz]：欧拉角（弧度）
+   * 3. 数组 [x, y, z, w]：四元数
+   * 4. THREE.Euler | THREE.Quaternion | THREE.Matrix3 | THREE.Matrix4
+   */
+  rotation?:
+    | number
+    | [number, number, number]
+    | [number, number, number, number]
+    | THREE.Euler
+    | THREE.Quaternion
+    | THREE.Matrix3
+    | THREE.Matrix4;
+  /** 旋转中心轴心点 [px, py, pz]（局部坐标，默认 [0, 0, 0]） */
+  pivot?: [number, number, number];
+  /** GPU 路径动画配置 */
+  gpuPath?: GPUPathOptions;
+}
+
+export type RotationMatrix9 = [
+  number, number, number, // Row 0: R00, R01, R02
+  number, number, number, // Row 1: R10, R11, R12
+  number, number, number  // Row 2: R20, R21, R22
+];
+
+/**
+ * 将各类旋转表示统一解析为 3x3 行优先矩阵数组
+ */
+export function resolveRotationMatrix(
+  rot?:
+    | number
+    | [number, number, number]
+    | [number, number, number, number]
+    | THREE.Euler
+    | THREE.Quaternion
+    | THREE.Matrix3
+    | THREE.Matrix4
+    | null
+): RotationMatrix9 | null {
+  if (rot == null) return null;
+  if (typeof rot === 'number') {
+    const c = Math.cos(rot);
+    const s = Math.sin(rot);
+    return [
+      c, -s, 0,
+      s,  c, 0,
+      0,  0, 1,
+    ];
+  }
+  if (Array.isArray(rot)) {
+    if (rot.length === 3) {
+      const euler = new THREE.Euler(rot[0], rot[1], rot[2]);
+      const m = new THREE.Matrix4().makeRotationFromEuler(euler);
+      const e = m.elements;
+      return [
+        e[0], e[4], e[8],
+        e[1], e[5], e[9],
+        e[2], e[6], e[10],
+      ];
+    }
+    if (rot.length === 4) {
+      const q = new THREE.Quaternion(rot[0], rot[1], rot[2], rot[3]);
+      const m = new THREE.Matrix4().makeRotationFromQuaternion(q);
+      const e = m.elements;
+      return [
+        e[0], e[4], e[8],
+        e[1], e[5], e[9],
+        e[2], e[6], e[10],
+      ];
+    }
+  }
+  if (rot instanceof THREE.Euler) {
+    const m = new THREE.Matrix4().makeRotationFromEuler(rot);
+    const e = m.elements;
+    return [
+      e[0], e[4], e[8],
+      e[1], e[5], e[9],
+      e[2], e[6], e[10],
+    ];
+  }
+  if (rot instanceof THREE.Quaternion) {
+    const m = new THREE.Matrix4().makeRotationFromQuaternion(rot);
+    const e = m.elements;
+    return [
+      e[0], e[4], e[8],
+      e[1], e[5], e[9],
+      e[2], e[6], e[10],
+    ];
+  }
+  if (rot instanceof THREE.Matrix3) {
+    const e = rot.elements;
+    return [
+      e[0], e[3], e[6],
+      e[1], e[4], e[7],
+      e[2], e[5], e[8],
+    ];
+  }
+  if (rot instanceof THREE.Matrix4) {
+    const e = rot.elements;
+    return [
+      e[0], e[4], e[8],
+      e[1], e[5], e[9],
+      e[2], e[6], e[10],
+    ];
+  }
+  return null;
+}
+
+/**
+ * 提取欧拉角 [rx, ry, rz]（弧度）用于动画插值
+ */
+export function extractEulerAngles(
+  rot?:
+    | number
+    | [number, number, number]
+    | [number, number, number, number]
+    | THREE.Euler
+    | THREE.Quaternion
+    | THREE.Matrix3
+    | THREE.Matrix4
+    | null
+): [number, number, number] {
+  if (rot == null) return [0, 0, 0];
+  if (typeof rot === 'number') return [0, 0, rot];
+  if (Array.isArray(rot)) {
+    if (rot.length === 3) return [rot[0], rot[1], rot[2]];
+    if (rot.length === 4) {
+      const q = new THREE.Quaternion(rot[0], rot[1], rot[2], rot[3]);
+      const e = new THREE.Euler().setFromQuaternion(q);
+      return [e.x, e.y, e.z];
+    }
+  }
+  if (rot instanceof THREE.Euler) return [rot.x, rot.y, rot.z];
+  if (rot instanceof THREE.Quaternion) {
+    const e = new THREE.Euler().setFromQuaternion(rot);
+    return [e.x, e.y, e.z];
+  }
+  if (rot instanceof THREE.Matrix3) {
+    const m = new THREE.Matrix4().set(
+      rot.elements[0], rot.elements[3], rot.elements[6], 0,
+      rot.elements[1], rot.elements[4], rot.elements[7], 0,
+      rot.elements[2], rot.elements[5], rot.elements[8], 0,
+      0, 0, 0, 1
+    );
+    const e = new THREE.Euler().setFromRotationMatrix(m);
+    return [e.x, e.y, e.z];
+  }
+  if (rot instanceof THREE.Matrix4) {
+    const e = new THREE.Euler().setFromRotationMatrix(rot);
+    return [e.x, e.y, e.z];
+  }
+  return [0, 0, 0];
 }
 
 export interface ColorByFieldOptions {
@@ -173,7 +341,13 @@ export class FeatureStyleManager {
 
   private readonly _meshBatchTextures = new WeakMap<
     THREE.Mesh,
-    { texture: THREE.DataTexture; data: Float32Array; width: number }
+    {
+      texture: THREE.DataTexture;
+      data: Float32Array;
+      texture2?: THREE.DataTexture;
+      data2?: Float32Array;
+      width: number;
+    }
   >();
   private readonly _markedMeshes = new Set<THREE.Mesh>();
   private _dirtyAll = false;
@@ -216,11 +390,21 @@ export class FeatureStyleManager {
     return this.featureStyles.get(smid) ?? null;
   }
 
-  getFeatureEffectiveOffset(smid: number | null): { translation?: [number, number, number]; elevation?: number } {
+  getFeatureEffectiveOffset(smid: number | null): {
+    translation?: [number, number, number];
+    elevation?: number;
+    rotation?: FeatureStyle['rotation'];
+    pivot?: [number, number, number];
+  } {
     if (smid == null) return {};
     const st = this.featureStyles.get(smid);
     const elev = st?.elevation ?? this.thematicElevation.get(smid);
-    return { translation: st?.translation, elevation: elev };
+    return {
+      translation: st?.translation,
+      elevation: elev,
+      rotation: st?.rotation,
+      pivot: st?.pivot,
+    };
   }
 
   getFeatureStyles(): Map<number, FeatureStyle> {
@@ -551,72 +735,55 @@ export class FeatureStyleManager {
     return { smids: 0, batches, conflicts, conflictingSmids: involved.size };
   }
 
-  applyOverridesToMesh(mesh: THREE.Mesh): void {
-    const mat = styledMaterialOf(mesh);
-    if (!mat) return;
-
-    const ud = mesh.userData as any;
-    const pickInfo = ud.geoRef?.pickInfo;
-
-    const hasStyles =
-      this.featureStyles.size > 0 || this.thematicColors.size > 0 || this.thematicElevation.size > 0;
-    const filter = this.filter;
-    const hasFilter =
-      this.fieldFilter != null ||
-      (filter != null &&
-        ((filter.include?.length ?? 0) > 0 ||
-          (filter.exclude?.length ?? 0) > 0 ||
-          filter.predicate != null));
-
-    if (!hasStyles && !hasFilter) {
-      if (mat.userData.uBatchTexActive) {
-        mat.userData.uBatchTexActive.value = 0;
-      }
-      // 单体淡化清除后，把材质 transparent 还原成全局透明度语义
-      if (mat.transparent && !this._isLayerTransparent()) mat.transparent = false;
-      return;
-    }
-
-    if (!pickInfo || Object.keys(pickInfo).length === 0) {
-      if (mat.userData.uBatchTexActive) {
-        mat.userData.uBatchTexActive.value = 0;
-      }
-      if (mat.transparent && !this._isLayerTransparent()) mat.transparent = false;
-      return;
-    }
-
-    let maxBatch = 0;
-    for (const p of Object.values(pickInfo)) {
-      const id = pickEntryId(p as any);
-      if (id > maxBatch) maxBatch = id;
-    }
-    const width = Math.max(maxBatch + 1, 1);
-
-    let record = this._meshBatchTextures.get(mesh);
-    if (!record || record.width < width) {
-      const data = new Float32Array(width * 2 * 4);
-      const texture = new THREE.DataTexture(data, width, 2, THREE.RGBAFormat, THREE.FloatType);
-      texture.minFilter = THREE.NearestFilter;
-      texture.magFilter = THREE.NearestFilter;
-      record = { texture, data, width };
-      this._meshBatchTextures.set(mesh, record);
-      mat.userData.uBatchTex.value = texture;
-      mat.userData.uBatchTexWidth.value = width;
-    }
-
-    const { data, texture } = record;
-    const w = record.width;
+  private _bakeStylesIntoBuffer(
+    data: Float32Array,
+    width: number,
+    pickInfo: Record<string, unknown>,
+    mesh: THREE.Mesh,
+    styleMap: Map<number, FeatureStyle>
+  ): { hasActive: boolean; hasFade: boolean; conflicts: number } {
+    const w = width;
     for (let i = 0; i < w; i++) {
+      // Row 0: [R, G, B, elevation/hidden]
       data[i * 4 + 0] = -1;
       data[i * 4 + 1] = -1;
       data[i * 4 + 2] = -1;
       data[i * 4 + 3] = 0;
 
+      // Row 1: [translationX, translationY, translationZ, opacity]
       const r1 = (w + i) * 4;
       data[r1 + 0] = 0;
       data[r1 + 1] = 0;
       data[r1 + 2] = 0;
       data[r1 + 3] = 0;
+
+      // Row 2: [R00, R01, R02, pivot.x] (单位矩阵默认值)
+      const r2 = (w * 2 + i) * 4;
+      data[r2 + 0] = 1;
+      data[r2 + 1] = 0;
+      data[r2 + 2] = 0;
+      data[r2 + 3] = 0;
+
+      // Row 3: [R10, R11, R12, pivot.y]
+      const r3 = (w * 3 + i) * 4;
+      data[r3 + 0] = 0;
+      data[r3 + 1] = 1;
+      data[r3 + 2] = 0;
+      data[r3 + 3] = 0;
+
+      // Row 4: [R20, R21, R22, pivot.z]
+      const r4 = (w * 4 + i) * 4;
+      data[r4 + 0] = 0;
+      data[r4 + 1] = 0;
+      data[r4 + 2] = 1;
+      data[r4 + 3] = 0;
+
+      // Row 5: [pathId, speed, phase, modeFlag] (默认 -1 表示未绑定 GPU 路径)
+      const r5 = (w * 5 + i) * 4;
+      data[r5 + 0] = -1;
+      data[r5 + 1] = 0;
+      data[r5 + 2] = 0;
+      data[r5 + 3] = 0;
     }
 
     let hasActive = false;
@@ -624,13 +791,18 @@ export class FeatureStyleManager {
     const colorOfBatch = new Map<number, string>();
     const elevOfBatch = new Map<number, number>();
     const translationOfBatch = new Map<number, [number, number, number]>();
+    const rotationOfBatch = new Map<number, RotationMatrix9>();
+    const pivotOfBatch = new Map<number, [number, number, number]>();
+    const gpuPathOfBatch = new Map<number, GPUPathOptions>();
     const opacityOfBatch = new Map<number, number>();
     const ownersOfBatch = new Map<number, number>();
+    const filter = this.filter;
+    const ud = mesh.userData as any;
 
     for (const [smidStr, entry] of Object.entries(pickInfo)) {
       const smid = Number(smidStr);
       const bId = pickEntryId(entry as any);
-      if (bId < 0 || bId >= record.width) continue;
+      if (bId < 0 || bId >= w) continue;
       ownersOfBatch.set(bId, (ownersOfBatch.get(bId) ?? 0) + 1);
 
       let hidden = false;
@@ -669,7 +841,7 @@ export class FeatureStyleManager {
         }
       }
 
-      const st = this.featureStyles.get(smid);
+      const st = styleMap.get(smid);
       if (st?.hidden) {
         hiddenBatches.add(bId);
         continue;
@@ -694,6 +866,17 @@ export class FeatureStyleManager {
       if (st?.translation && !translationOfBatch.has(bId)) {
         translationOfBatch.set(bId, st.translation);
       }
+
+      if (st?.rotation != null && !rotationOfBatch.has(bId)) {
+        const rotMat = resolveRotationMatrix(st.rotation);
+        if (rotMat) rotationOfBatch.set(bId, rotMat);
+      }
+      if (st?.pivot && !pivotOfBatch.has(bId)) {
+        pivotOfBatch.set(bId, st.pivot);
+      }
+      if (st?.gpuPath && !gpuPathOfBatch.has(bId)) {
+        gpuPathOfBatch.set(bId, st.gpuPath);
+      }
     }
 
     for (const bId of hiddenBatches) {
@@ -737,17 +920,142 @@ export class FeatureStyleManager {
       hasFade = true;
     }
 
-    // 有淡化单体时整块材质要开混合才有透明效果；清除后还原为全局透明度语义
-    if (hasFade && !mat.transparent) mat.transparent = true;
-    else if (!hasFade && mat.transparent && !this._isLayerTransparent()) mat.transparent = false;
+    for (const [bId, rot] of rotationOfBatch) {
+      if (hiddenBatches.has(bId)) continue;
+      const piv = pivotOfBatch.get(bId) ?? [0, 0, 0];
+      const r2 = (w * 2 + bId) * 4;
+      data[r2 + 0] = rot[0];
+      data[r2 + 1] = rot[1];
+      data[r2 + 2] = rot[2];
+      data[r2 + 3] = piv[0];
+
+      const r3 = (w * 3 + bId) * 4;
+      data[r3 + 0] = rot[3];
+      data[r3 + 1] = rot[4];
+      data[r3 + 2] = rot[5];
+      data[r3 + 3] = piv[1];
+
+      const r4 = (w * 4 + bId) * 4;
+      data[r4 + 0] = rot[6];
+      data[r4 + 1] = rot[7];
+      data[r4 + 2] = rot[8];
+      data[r4 + 3] = piv[2];
+      hasActive = true;
+    }
+
+    for (const [bId, piv] of pivotOfBatch) {
+      if (rotationOfBatch.has(bId) || hiddenBatches.has(bId)) continue;
+      data[(w * 2 + bId) * 4 + 3] = piv[0];
+      data[(w * 3 + bId) * 4 + 3] = piv[1];
+      data[(w * 4 + bId) * 4 + 3] = piv[2];
+      hasActive = true;
+    }
+
+    // Row 5: 烘焙 GPU 路径动画参数 [pathId, speed, phase, modeFlag]
+    for (const [bId, gp] of gpuPathOfBatch) {
+      if (hiddenBatches.has(bId)) continue;
+      const r5 = (w * 5 + bId) * 4;
+      data[r5 + 0] = gp.pathId;
+      data[r5 + 1] = gp.speed ?? 0;
+      data[r5 + 2] = gp.phase ?? 0;
+
+      let mode = 1; // 1 = loop (默认)
+      if (gp.loop === 'clamp' || gp.loop === false) {
+        mode = 2;
+      } else if (gp.loop === 'pingpong') {
+        mode = 3;
+      }
+      if (gp.autoHeading === false) {
+        mode += 3; // 4=loop+noHeading, 5=clamp+noHeading, 6=pingpong+noHeading
+      }
+      data[r5 + 3] = mode;
+      hasActive = true;
+    }
 
     let conflicts = 0;
     for (const [bId, owners] of ownersOfBatch) {
       if (owners < 2) continue;
-      if (!hiddenBatches.has(bId) && !colorOfBatch.has(bId) && !elevOfBatch.has(bId)) continue;
+      if (
+        !hiddenBatches.has(bId) &&
+        !colorOfBatch.has(bId) &&
+        !elevOfBatch.has(bId) &&
+        !rotationOfBatch.has(bId) &&
+        !gpuPathOfBatch.has(bId)
+      ) {
+        continue;
+      }
       conflicts++;
     }
 
+    return { hasActive, hasFade, conflicts };
+  }
+
+  applyOverridesToMesh(mesh: THREE.Mesh): void {
+    const mat = styledMaterialOf(mesh);
+    if (!mat) return;
+
+    const ud = mesh.userData as any;
+    const pickInfo = ud.geoRef?.pickInfo;
+
+    const hasStyles =
+      this.featureStyles.size > 0 || this.thematicColors.size > 0 || this.thematicElevation.size > 0;
+    const filter = this.filter;
+    const hasFilter =
+      this.fieldFilter != null ||
+      (filter != null &&
+        ((filter.include?.length ?? 0) > 0 ||
+          (filter.exclude?.length ?? 0) > 0 ||
+          filter.predicate != null));
+
+    if (!hasStyles && !hasFilter) {
+      if (mat.userData.uBatchTexActive) {
+        mat.userData.uBatchTexActive.value = 0;
+      }
+      // 单体淡化清除后，把材质 transparent 还原成全局透明度语义
+      if (mat.transparent && !this._isLayerTransparent()) mat.transparent = false;
+      return;
+    }
+
+    if (!pickInfo || Object.keys(pickInfo).length === 0) {
+      if (mat.userData.uBatchTexActive) {
+        mat.userData.uBatchTexActive.value = 0;
+      }
+      if (mat.transparent && !this._isLayerTransparent()) mat.transparent = false;
+      return;
+    }
+
+    let maxBatch = 0;
+    for (const p of Object.values(pickInfo)) {
+      const id = pickEntryId(p as any);
+      if (id > maxBatch) maxBatch = id;
+    }
+    const width = Math.max(maxBatch + 1, 1);
+
+    let record = this._meshBatchTextures.get(mesh);
+    if (!record || record.width < width) {
+      const data = new Float32Array(width * 6 * 4);
+      const texture = new THREE.DataTexture(data, width, 6, THREE.RGBAFormat, THREE.FloatType);
+      texture.minFilter = THREE.NearestFilter;
+      texture.magFilter = THREE.NearestFilter;
+      record = { texture, data, width };
+      this._meshBatchTextures.set(mesh, record);
+      mat.userData.uBatchTex.value = texture;
+      mat.userData.uBatchTexWidth.value = width;
+    }
+
+    const { data, texture } = record;
+    const { hasActive, hasFade, conflicts } = this._bakeStylesIntoBuffer(
+      data,
+      record.width,
+      pickInfo,
+      mesh,
+      this.featureStyles
+    );
+
+    // 有淡化单体时整块材质要开混合才有透明效果；清除后还原为全局透明度语义
+    if (hasFade && !mat.transparent) mat.transparent = true;
+    else if (!hasFade && mat.transparent && !this._isLayerTransparent()) mat.transparent = false;
+
     if (conflicts > 0 && !this._batchConflictWarned) {
       this._batchConflictWarned = true;
       console.warn(
@@ -764,6 +1072,93 @@ export class FeatureStyleManager {
     }
   }
 
+  /**
+   * 准备双纹理交叉淡化：烘焙目标样式到第二纹理 (uBatchTex2)
+   */
+  prepareCrossFade(targetStyles: Map<number, FeatureStyle>, meshes: Iterable<THREE.Mesh>): void {
+    for (const mesh of meshes) {
+      const mat = styledMaterialOf(mesh);
+      if (!mat) continue;
+      const ud = mesh.userData as any;
+      const pickInfo = ud.geoRef?.pickInfo;
+      if (!pickInfo || Object.keys(pickInfo).length === 0) continue;
+
+      let maxBatch = 0;
+      for (const p of Object.values(pickInfo)) {
+        const id = pickEntryId(p as any);
+        if (id > maxBatch) maxBatch = id;
+      }
+      const width = Math.max(maxBatch + 1, 1);
+
+      let record = this._meshBatchTextures.get(mesh);
+      if (!record || record.width < width) {
+        const data = new Float32Array(width * 6 * 4);
+        const texture = new THREE.DataTexture(data, width, 6, THREE.RGBAFormat, THREE.FloatType);
+        texture.minFilter = THREE.NearestFilter;
+        texture.magFilter = THREE.NearestFilter;
+        record = { texture, data, width };
+        this._meshBatchTextures.set(mesh, record);
+        mat.userData.uBatchTex.value = texture;
+        mat.userData.uBatchTexWidth.value = width;
+      }
+
+      if (!record.texture2 || !record.data2 || record.data2.length < record.width * 6 * 4) {
+        const data2 = new Float32Array(record.width * 6 * 4);
+        const texture2 = new THREE.DataTexture(data2, record.width, 6, THREE.RGBAFormat, THREE.FloatType);
+        texture2.minFilter = THREE.NearestFilter;
+        texture2.magFilter = THREE.NearestFilter;
+        record.data2 = data2;
+        record.texture2 = texture2;
+      }
+
+      // 确保当前纹理包含当前状态
+      this._bakeStylesIntoBuffer(record.data, record.width, pickInfo, mesh, this.featureStyles);
+      record.texture.needsUpdate = true;
+
+      // 烘焙目标状态到 data2
+      const res2 = this._bakeStylesIntoBuffer(record.data2, record.width, pickInfo, mesh, targetStyles);
+      record.texture2.needsUpdate = true;
+
+      mat.userData.uBatchTex2.value = record.texture2;
+      mat.userData.uBatchTexActive.value = 1;
+      if (res2.hasFade && !mat.transparent) mat.transparent = true;
+    }
+  }
+
+  /**
+   * 提交双纹理交叉淡化：将 targetStyles 回写到主状态，并将 data2 复制到 data
+   */
+  commitCrossFade(targetStyles: Map<number, FeatureStyle>, meshes: Iterable<THREE.Mesh>): void {
+    this.featureStyles.clear();
+    for (const [k, v] of targetStyles) {
+      this.featureStyles.set(k, v);
+    }
+    for (const mesh of meshes) {
+      const mat = styledMaterialOf(mesh);
+      if (!mat) continue;
+      const record = this._meshBatchTextures.get(mesh);
+      if (!record || !record.data2 || !record.texture2) continue;
+
+      record.data.set(record.data2);
+      record.texture.needsUpdate = true;
+      mat.userData.uBatchTex2.value = mat.userData.uBatchTex.value;
+    }
+    this._onStyleChanged();
+    this._triggerRepaint();
+  }
+
+  /**
+   * 取消交叉淡化并恢复单一纹理
+   */
+  cancelCrossFade(meshes: Iterable<THREE.Mesh>): void {
+    for (const mesh of meshes) {
+      const mat = styledMaterialOf(mesh);
+      if (!mat) continue;
+      mat.userData.uBatchTex2.value = mat.userData.uBatchTex.value;
+    }
+    this._triggerRepaint();
+  }
+
   markOverridesDirty(subset?: Iterable<THREE.Mesh>, allMeshes?: Iterable<THREE.Mesh>): void {
     if (subset) {
       for (const m of subset) this._markedMeshes.add(m);
@@ -783,6 +1178,7 @@ export class FeatureStyleManager {
     const record = this._meshBatchTextures.get(mesh);
     if (record) {
       record.texture.dispose();
+      record.texture2?.dispose();
       this._meshBatchTextures.delete(mesh);
     }
   }
@@ -807,4 +1203,68 @@ export class FeatureStyleManager {
     this._markedMeshes.clear();
     this._triggerRepaint();
   }
+
+  /**
+   * 将单体绑定到 GPU 路径动画
+   * @param smid 单体 ID
+   * @param pathId GPUPathManager 中的路径索引
+   * @param options 速度、初始相位、循环模式与自动转向配置
+   * @param meshes 可选指定的网格集合，不传则全量生效
+   */
+  bindGPUPath(
+    smid: number,
+    pathId: number,
+    options: Omit<GPUPathOptions, 'pathId'> = {},
+    meshes?: Iterable<THREE.Mesh>
+  ): void {
+    const cur = this.getFeatureStyle(smid) ?? {};
+    this.setFeatureStyle(
+      smid,
+      {
+        ...cur,
+        gpuPath: {
+          pathId,
+          speed: options.speed ?? 0,
+          phase: options.phase ?? 0,
+          loop: options.loop ?? 'loop',
+          autoHeading: options.autoHeading ?? true,
+        },
+      },
+      meshes
+    );
+  }
+
+  /**
+   * 解绑单体的 GPU 路径动画
+   */
+  unbindGPUPath(smid: number, meshes?: Iterable<THREE.Mesh>): void {
+    const cur = this.getFeatureStyle(smid);
+    if (!cur || !cur.gpuPath) return;
+    const next = { ...cur };
+    delete next.gpuPath;
+    this.setFeatureStyle(smid, next, meshes);
+  }
+
+  /**
+   * 直接设置单体在 GPU 路径上的归一化进度（0.0 ~ 1.0）
+   * @param smid 单体 ID
+   * @param progress 归一化进度 (0~1)
+   * @param meshes 可选指定的网格集合
+   */
+  setGPUPathProgress(smid: number, progress: number, meshes?: Iterable<THREE.Mesh>): void {
+    const cur = this.getFeatureStyle(smid);
+    if (!cur?.gpuPath) return;
+    this.setFeatureStyle(
+      smid,
+      {
+        ...cur,
+        gpuPath: {
+          ...cur.gpuPath,
+          speed: 0,
+          phase: Math.min(1.0, Math.max(0.0, progress)),
+        },
+      },
+      meshes
+    );
+  }
 }