s3m-three 0.3.7 → 0.3.9

package/src/anim/easing.ts

@@ -0,0 +1,195 @@
+/**
+ * 缓动曲线库
+ *
+ * 纯函数，不依赖 three / DOM，可以单独在 Worker 或 Node 里跑。
+ *
+ * 三类：
+ *   1. 命名曲线 —— CSS 那套 easeIn/Out/InOut × Quad…Bounce，覆盖 90% 场景
+ *   2. cubicBezier(x1,y1,x2,y2) —— 与 CSS `cubic-bezier()` 数值对齐，用来做产品级调校
+ *   3. steps(n, position) —— 离散跳变，做逐帧动画或「咔哒」感
+ *
+ * spring 不在这里：它没有「时长」概念，靠物理收敛，所以实现为 Animator 里的一种
+ * Track 类型，而不是 (t) => number 的曲线。
+ */
+
+export type EasingFn = (t: number) => number;
+
+/* ------------------------------------------------------------------ 基础 */
+
+const c1 = 1.70158;
+const c2 = c1 * 1.525;
+const c3 = c1 + 1;
+const c4 = (2 * Math.PI) / 3;
+const c5 = (2 * Math.PI) / 4.5;
+const n1 = 7.5625;
+const d1 = 2.75;
+
+function outBounce(t: number): number {
+  if (t < 1 / d1) return n1 * t * t;
+  if (t < 2 / d1) {
+    const x = t - 1.5 / d1;
+    return n1 * x * x + 0.75;
+  }
+  if (t < 2.5 / d1) {
+    const x = t - 2.25 / d1;
+    return n1 * x * x + 0.9375;
+  }
+  const x = t - 2.625 / d1;
+  return n1 * x * x + 0.984375;
+}
+
+function inBounce(t: number): number {
+  return 1 - outBounce(1 - t);
+}
+
+/* ------------------------------------------------------------------ 曲线表 */
+
+const CURVES = {
+  linear: (t) => t,
+
+  easeInQuad: (t) => t * t,
+  easeOutQuad: (t) => 1 - (1 - t) * (1 - t),
+  easeInOutQuad: (t) => (t < 0.5 ? 2 * t * t : 1 - Math.pow(-2 * t + 2, 2) / 2),
+
+  easeInCubic: (t) => t * t * t,
+  easeOutCubic: (t) => 1 - Math.pow(1 - t, 3),
+  easeInOutCubic: (t) => (t < 0.5 ? 4 * t * t * t : 1 - Math.pow(-2 * t + 2, 3) / 2),
+
+  easeInQuart: (t) => t * t * t * t,
+  easeOutQuart: (t) => 1 - Math.pow(1 - t, 4),
+  easeInOutQuart: (t) => (t < 0.5 ? 8 * t * t * t * t : 1 - Math.pow(-2 * t + 2, 4) / 2),
+
+  easeInQuint: (t) => t * t * t * t * t,
+  easeOutQuint: (t) => 1 - Math.pow(1 - t, 5),
+  easeInOutQuint: (t) => (t < 0.5 ? 16 * t * t * t * t * t : 1 - Math.pow(-2 * t + 2, 5) / 2),
+
+  easeInSine: (t) => 1 - Math.cos((t * Math.PI) / 2),
+  easeOutSine: (t) => Math.sin((t * Math.PI) / 2),
+  easeInOutSine: (t) => -(Math.cos(Math.PI * t) - 1) / 2,
+
+  easeInExpo: (t) => (t === 0 ? 0 : Math.pow(2, 10 * t - 10)),
+  easeOutExpo: (t) => (t === 1 ? 1 : 1 - Math.pow(2, -10 * t)),
+  easeInOutExpo: (t) =>
+    t === 0 ? 0 : t === 1 ? 1 : t < 0.5 ? Math.pow(2, 20 * t - 10) / 2 : (2 - Math.pow(2, -20 * t + 10)) / 2,
+
+  easeInCirc: (t) => 1 - Math.sqrt(1 - t * t),
+  easeOutCirc: (t) => Math.sqrt(1 - Math.pow(t - 1, 2)),
+  easeInOutCirc: (t) =>
+    t < 0.5
+      ? (1 - Math.sqrt(1 - Math.pow(2 * t, 2))) / 2
+      : (Math.sqrt(1 - Math.pow(-2 * t + 2, 2)) + 1) / 2,
+
+  easeInBack: (t) => c3 * t * t * t - c1 * t * t,
+  easeOutBack: (t) => 1 + c3 * Math.pow(t - 1, 3) + c1 * Math.pow(t - 1, 2),
+  easeInOutBack: (t) =>
+    t < 0.5
+      ? (Math.pow(2 * t, 2) * ((c2 + 1) * 2 * t - c2)) / 2
+      : (Math.pow(2 * t - 2, 2) * ((c2 + 1) * (t * 2 - 2) + c2) + 2) / 2,
+
+  easeInElastic: (t) =>
+    t === 0 ? 0 : t === 1 ? 1 : -Math.pow(2, 10 * t - 10) * Math.sin((t * 10 - 10.75) * c4),
+  easeOutElastic: (t) =>
+    t === 0 ? 0 : t === 1 ? 1 : Math.pow(2, -10 * t) * Math.sin((t * 10 - 0.75) * c4) + 1,
+  easeInOutElastic: (t) =>
+    t === 0
+      ? 0
+      : t === 1
+        ? 1
+        : t < 0.5
+          ? -(Math.pow(2, 20 * t - 10) * Math.sin((20 * t - 11.125) * c5)) / 2
+          : (Math.pow(2, -20 * t + 10) * Math.sin((20 * t - 11.125) * c5)) / 2 + 1,
+
+  easeInBounce: inBounce,
+  easeOutBounce: outBounce,
+  easeInOutBounce: (t) => (t < 0.5 ? (1 - inBounce(1 - 2 * t)) / 2 : (1 + inBounce(2 * t - 1)) / 2),
+} satisfies Record<string, EasingFn>;
+
+/** 全部内置曲线名（顺序稳定，方便做下拉框 / 遍历自检） */
+export const EASING_NAMES = Object.keys(CURVES) as EasingName[];
+
+export type EasingName = keyof typeof CURVES;
+
+/** 按名字取曲线；名字不存在直接抛错，不做静默降级（拼错会变成「没动画」，很难查） */
+export function easing(name: EasingName | EasingFn): EasingFn {
+  if (typeof name === 'function') return name;
+  const fn = (CURVES as Record<string, EasingFn>)[name];
+  if (!fn) throw new Error(`[s3m] 未知的缓动曲线: ${String(name)}`);
+  return fn;
+}
+
+/* ------------------------------------------------------------------ 贝塞尔 */
+
+const NEWTON_ITERATIONS = 8;
+const NEWTON_MIN_SLOPE = 0.001;
+const SUBDIVISION_PRECISION = 1e-7;
+const SUBDIVISION_MAX_ITERATIONS = 12;
+
+const bezA = (a1: number, a2: number): number => 1 - 3 * a2 + 3 * a1;
+const bezB = (a1: number, a2: number): number => 3 * a2 - 6 * a1;
+const bezC = (a1: number): number => 3 * a1;
+
+/** 三次贝塞尔在参数 t 处的值（x 或 y 用同一组公式，只是控制点不同） */
+function bezierAt(t: number, a1: number, a2: number): number {
+  return ((bezA(a1, a2) * t + bezB(a1, a2)) * t + bezC(a1)) * t;
+}
+
+function bezierSlope(t: number, a1: number, a2: number): number {
+  return 3 * bezA(a1, a2) * t * t + 2 * bezB(a1, a2) * t + bezC(a1);
+}
+
+/**
+ * CSS `cubic-bezier(x1, y1, x2, y2)` 的等价实现。
+ *
+ * 与浏览器一致：先解 `x(t) = 输入进度` 得到参数 t，再取 `y(t)`。
+ * 用牛顿迭代，斜率过小时退化为二分——退化控制点（比如 (0,0,1,1)）也稳定。
+ */
+export function cubicBezier(x1: number, y1: number, x2: number, y2: number): EasingFn {
+  // 线性特例：控制点落在对角线上时不必迭代
+  if (x1 === y1 && x2 === y2) return (t) => t;
+
+  const solveT = (x: number): number => {
+    let t = x;
+    for (let i = 0; i < NEWTON_ITERATIONS; i++) {
+      const slope = bezierSlope(t, x1, x2);
+      if (Math.abs(slope) < NEWTON_MIN_SLOPE) break;
+      const err = bezierAt(t, x1, x2) - x;
+      if (Math.abs(err) < SUBDIVISION_PRECISION) return t;
+      t -= err / slope;
+    }
+    // 牛顿不收敛：二分兜底
+    let lo = 0;
+    let hi = 1;
+    t = x;
+    for (let i = 0; i < SUBDIVISION_MAX_ITERATIONS; i++) {
+      const v = bezierAt(t, x1, x2);
+      if (Math.abs(v - x) < SUBDIVISION_PRECISION) return t;
+      if (v < x) lo = t;
+      else hi = t;
+      t = (lo + hi) / 2;
+    }
+    return t;
+  };
+
+  return (t: number): number => {
+    if (t <= 0) return 0;
+    if (t >= 1) return 1;
+    return bezierAt(solveT(t), y1, y2);
+  };
+}
+
+/* ------------------------------------------------------------------ 离散 */
+
+/**
+ * 阶梯曲线。
+ *
+ * @param count    档数
+ * @param position 'end' 表示「走完一档才跳」，'start' 表示「一进档就跳」
+ */
+export function steps(count: number, position: 'start' | 'end' = 'end'): EasingFn {
+  const n = Math.max(1, Math.floor(count));
+  return (t: number): number => {
+    const clamped = Math.min(1, Math.max(0, t));
+    if (position === 'start') return Math.min(1, (Math.floor(clamped * n) + 1) / n);
+    return Math.min(1, Math.floor(clamped * n) / n);
+  };
+}

package/src/anim/index.ts

@@ -0,0 +1,10 @@
+export { Animator } from './Animator.js';
+export type { Channel, SpringSpec, TransitionOptions } from './Animator.js';
+export { Path } from './Path.js';
+export {
+  easing,
+  cubicBezier,
+  steps,
+  EASING_NAMES,
+} from './easing.js';
+export type { EasingFn, EasingName } from './easing.js';

package/src/core/types.ts

@@ -281,5 +281,15 @@ export interface StyleUniforms {
   uFilterHeightActive?: { value: number };
   uRoofThreshold?: { value: number };
   uTexMix?: { value: number };
+  /** 基础漫反射底色增益 / 直通自发光微调（0~1，默认 0.0） */
+  uAmbientGain?: { value: number };
+  /** 双纹理交叉淡化插值因子（0~1，0 = 状态 A，1 = 状态 B） */
+  uBatchMix?: { value: number };
+  /** 图层整体透明度（共享 uniform，透明度动画靠它做到 O(1)） */
+  uOpacity?: { value: number };
+  /** 棱线淡入淡出乘子（setEdges 过渡期间 0→1） */
+  uEdgeFade?: { value: number };
+  /** 整体压暗乘子（mode 切换的 fade-through） */
+  uFade?: { value: number };
   [key: string]: { value: unknown } | undefined;
 }

package/src/index.ts

@@ -78,6 +78,11 @@ export {
   DatasetManager,
   FeatureStyleManager,
 } from './render/S3MViewer.js';
+export {
+  resolveRotationMatrix,
+  extractEulerAngles,
+} from './render/FeatureStyleManager.js';
+export type { RotationMatrix9 } from './render/FeatureStyleManager.js';
 export type {
   DatasetAlignment,
   S3MDatasetOptions,
@@ -96,6 +101,7 @@ export type {
   GroundMode,
   GroundOptions,
   LightOptions,
+  PathFollowOptions,
 } from './render/S3MViewer.js';
 
 export { buildTileObjects } from './render/GeometryBuilder.js';
@@ -117,8 +123,18 @@ export type { StyleMode, SelectMode, StyledMaterial, StyledMaterialOptions, Outl
 export { Picker } from './render/Picker.js';
 export type { PickHit } from './render/Picker.js';
 
+export { Animator, Path, easing, cubicBezier, steps, EASING_NAMES } from './anim/index.js';
+export type {
+  Channel,
+  SpringSpec,
+  TransitionOptions,
+  EasingFn,
+  EasingName,
+} from './anim/index.js';
+
 export {
   buildOrthoMVP,
+  buildBlendedMVP,
   extractProjectionMatrix,
   extractNearFar,
   extractFovRadians,

package/src/render/EdgeLines.ts

@@ -13,6 +13,7 @@
  * B 端算出来的法线正好和 A 端相反，反号一次才能拼成同一个四边形。
  */
 import * as THREE from 'three';
+import { DUMMY_BATCH_TEX } from './StyleMaterial.js';
 
 /** 所有等宽线材质共享的分辨率 uniform（每帧更新一次即可） */
 export interface LineSharedUniforms {
@@ -20,14 +21,36 @@ export interface LineSharedUniforms {
   uDpr: { value: number };
 }
 
+/**
+ * 等宽线的「外观」uniform（颜色 / 粗细 / 透明度 / 拔高）。
+ *
+ * 棱线材质是**逐网格一份**的（见 createThickLineMaterial 的 batchUniforms 参数），
+ * 但外观必须全局统一——所以这些 `{ value }` 对象由调用方持有并共享给每一份材质，
+ * 改一次全场景生效，棱线淡入淡出才能保持 O(1)。
+ */
+export interface ThickLineStyleUniforms {
+  uColor: { value: THREE.Color };
+  uWidth: { value: number };
+  uOpacity: { value: number };
+  uElevation?: { value: number };
+}
+
+/** 等宽线的「单体状态」uniform：直接复用主材质 userData 里那几个对象，自动跟随 */
+export interface ThickLineBatchUniforms {
+  uBatchTex: { value: THREE.Texture };
+  uBatchTex2?: { value: THREE.Texture };
+  uBatchMix?: { value: number };
+  uBatchTexWidth: { value: number };
+  uBatchTexActive: { value: number };
+}
+
 export interface ThickLineMaterial extends THREE.ShaderMaterial {
-  uniforms: LineSharedUniforms & {
-    uColor: { value: THREE.Color };
-    uOpacity: { value: number };
-    uWidth: { value: number };
-    uElevation: { value: number };
-    [uniform: string]: THREE.IUniform;
-  };
+  uniforms: LineSharedUniforms &
+    ThickLineStyleUniforms &
+    Required<ThickLineBatchUniforms> & {
+      uTranslation: { value: THREE.Vector3 };
+      [uniform: string]: THREE.IUniform;
+    };
 }
 
 export function createLineSharedUniforms(): LineSharedUniforms {
@@ -40,18 +63,66 @@ export function createLineSharedUniforms(): LineSharedUniforms {
 const VERT = /* glsl */ `
   attribute vec3 aOther;
   attribute float aSide;
+  attribute float aBatchId;
 
   uniform vec2 uResolution;
   uniform float uDpr;
   uniform float uWidth;
   uniform float uElevation;
   uniform vec3 uTranslation;
+  uniform sampler2D uBatchTex;
+  uniform sampler2D uBatchTex2;
+  uniform float uBatchMix;
+  uniform float uBatchTexWidth;
+  uniform int uBatchTexActive;
+
+  vec4 s3mSampleBatch( sampler2D texA, sampler2D texB, vec2 uv, float mixVal ) {
+    vec4 vA = texture2D( texA, uv );
+    if ( mixVal <= 0.0001 ) return vA;
+    vec4 vB = texture2D( texB, uv );
+    return mix( vA, vB, mixVal );
+  }
 
   void main() {
+    // 单体平移 / 旋转 / 拔高 / 隐藏：与主着色器同一份 5 行状态纹理、同一套变换口径。
+    // 不采样的话，单体一动或一转棱线就留在原地——这正是「棱线跟随」要解决的。
+    vec3 s3mA = position;
+    vec3 s3mB = aOther;
+    vec3 s3mCustomOffset = vec3( 0.0 );
+    mat3 s3mRot = mat3( 1.0 );
+    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 );
+      if ( bState.a < -0.5 ) {
+        // 该单体被隐藏：顶点着色器不能 discard，扔到裁剪空间外
+        gl_Position = vec4( 2.0, 2.0, 2.0, 1.0 );
+        return;
+      }
+      vec4 bOffset = s3mSampleBatch( uBatchTex, uBatchTex2, vec2( s3mU, 0.3 ), 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 );
+      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 );
+    }
+
+    s3mA = s3mRot * ( s3mA - s3mPivot ) + s3mPivot + s3mCustomOffset;
+    s3mB = s3mRot * ( s3mB - s3mPivot ) + s3mPivot + s3mCustomOffset;
+
     // 选中单体平移/拔高：与着色器里 transformed += uTranslation 保持同一口径（物体空间）
     vec3 offset = uTranslation + vec3( 0.0, 0.0, uElevation );
-    vec4 clipA = projectionMatrix * modelViewMatrix * vec4( position + offset, 1.0 );
-    vec4 clipB = projectionMatrix * modelViewMatrix * vec4( aOther + offset, 1.0 );
+    vec4 clipA = projectionMatrix * modelViewMatrix * vec4( s3mA + offset, 1.0 );
+    vec4 clipB = projectionMatrix * modelViewMatrix * vec4( s3mB + offset, 1.0 );
 
     if ( clipA.w <= 0.0 || clipB.w <= 0.0 ) {
       // 端点跑到相机后面，整段丢弃（裁到近平面的线段会有轻微截断，可接受）
@@ -87,19 +158,54 @@ const FRAG = /* glsl */ `
   }
 `;
 
+/**
+ * 创建一份等宽线材质。
+ *
+ * @param styleUniforms  外观 uniform（颜色 / 粗细 / 透明度 / 拔高）。传入时**直接
+ *   复用这些 `{ value }` 对象**而不是新建——棱线材质逐网格一份，但外观必须全局统一，
+ *   共享对象才能让 `_syncEdgeStyle()` 的一次赋值作用到所有棱线上。
+ * @param batchUniforms  单体状态纹理 uniform。传入时同样直接复用主材质 userData 里
+ *   的那几个对象，主材质换纹理 / 开关 active 时棱线自动跟着走，零同步成本。
+ *   不传（或几何没有 aBatchId）时棱线不参与单体状态。
+ */
 export function createThickLineMaterial(
   shared: LineSharedUniforms,
-  opts: { color?: THREE.ColorRepresentation; opacity?: number; width?: number; elevation?: number } = {}
+  opts: { color?: THREE.ColorRepresentation; opacity?: number; width?: number; elevation?: number } = {},
+  styleUniforms?: ThickLineStyleUniforms,
+  batchUniforms?: ThickLineBatchUniforms
 ): ThickLineMaterial {
+  const style: ThickLineStyleUniforms = styleUniforms ?? {
+    uColor: { value: new THREE.Color(opts.color ?? '#ffffff') },
+    uOpacity: { value: opts.opacity ?? 1 },
+    uWidth: { value: opts.width ?? 1.5 },
+    uElevation: { value: opts.elevation ?? 0 },
+  };
+  if (opts.color !== undefined && styleUniforms) style.uColor.value.set(opts.color);
+  if (opts.opacity !== undefined && styleUniforms) style.uOpacity.value = opts.opacity;
+  if (opts.width !== undefined && styleUniforms) style.uWidth.value = opts.width;
+
+  const batch: Required<ThickLineBatchUniforms> = {
+    uBatchTex: batchUniforms?.uBatchTex ?? { value: DUMMY_BATCH_TEX },
+    uBatchTex2: batchUniforms?.uBatchTex2 ?? { value: DUMMY_BATCH_TEX },
+    uBatchMix: batchUniforms?.uBatchMix ?? { value: 0 },
+    uBatchTexWidth: batchUniforms?.uBatchTexWidth ?? { value: 1 },
+    uBatchTexActive: batchUniforms?.uBatchTexActive ?? { value: 0 },
+  };
+
   const mat = new THREE.ShaderMaterial({
     uniforms: {
       uResolution: shared.uResolution,
       uDpr: shared.uDpr,
-      uColor: { value: new THREE.Color(opts.color ?? '#ffffff') },
-      uOpacity: { value: opts.opacity ?? 1 },
-      uWidth: { value: opts.width ?? 1.5 },
-      uElevation: { value: opts.elevation ?? 0 },
+      uColor: style.uColor,
+      uOpacity: style.uOpacity,
+      uWidth: style.uWidth,
+      uElevation: style.uElevation ?? { value: opts.elevation ?? 0 },
       uTranslation: { value: new THREE.Vector3(0, 0, 0) },
+      uBatchTex: batch.uBatchTex,
+      uBatchTex2: batch.uBatchTex2,
+      uBatchMix: batch.uBatchMix,
+      uBatchTexWidth: batch.uBatchTexWidth,
+      uBatchTexActive: batch.uBatchTexActive,
     },
     vertexShader: VERT,
     fragmentShader: FRAG,
@@ -117,14 +223,22 @@ export function createThickLineMaterial(
 
 /**
  * 线段对（每 6 个 float：x1 y1 z1 x2 y2 z2）→ 可绘制等宽线的几何体。
+ *
+ * @param batchIds 每段所属的单体 batchId（长度 = 段数）。给了它，顶点着色器才能
+ *   按单体从状态纹理取平移/拔高——棱线跟随移动靠的就是这个。不传全部填 -1，
+ *   着色器会跳过采样（等于不参与单体状态）。
  */
-export function buildThickLineGeometry(segments: ArrayLike<number>): THREE.BufferGeometry {
+export function buildThickLineGeometry(
+  segments: ArrayLike<number>,
+  batchIds?: ArrayLike<number>
+): THREE.BufferGeometry {
   const count = Math.floor(segments.length / 6);
   const vertexCount = count * 4;
 
   const position = new Float32Array(vertexCount * 3);
   const other = new Float32Array(vertexCount * 3);
   const side = new Float32Array(vertexCount);
+  const batch = new Float32Array(vertexCount);
   const index = vertexCount > 65535 ? new Uint32Array(count * 6) : new Uint16Array(count * 6);
 
   for (let i = 0; i < count; i++) {
@@ -135,6 +249,7 @@ export function buildThickLineGeometry(segments: ArrayLike<number>): THREE.Buffe
     const bx = segments[s + 3];
     const by = segments[s + 4];
     const bz = segments[s + 5];
+    const b = batchIds ? Number(batchIds[i] ?? -1) : -1;
 
     const v = i * 4;
     // A 端两枚
@@ -143,6 +258,7 @@ export function buildThickLineGeometry(segments: ArrayLike<number>): THREE.Buffe
     // B 端两枚（side 反号）
     setVertex(v + 2, bx, by, bz, ax, ay, az, 1);
     setVertex(v + 3, bx, by, bz, ax, ay, az, -1);
+    for (let k = 0; k < 4; k++) batch[v + k] = b;
 
     const o = i * 6;
     index[o] = v;
@@ -177,11 +293,41 @@ export function buildThickLineGeometry(segments: ArrayLike<number>): THREE.Buffe
   geometry.setAttribute('position', new THREE.BufferAttribute(position, 3));
   geometry.setAttribute('aOther', new THREE.BufferAttribute(other, 3));
   geometry.setAttribute('aSide', new THREE.BufferAttribute(side, 1));
+  geometry.setAttribute('aBatchId', new THREE.BufferAttribute(batch, 1));
   geometry.setIndex(new THREE.BufferAttribute(index, 1));
   geometry.computeBoundingSphere();
   return geometry;
 }
 
+/**
+ * 从带 `aBatchId` 的几何里建「量化位置 → batchId」的查找表。
+ *
+ * `EdgesGeometry` 输出的线段只有坐标、没有顶点号，要知道每段棱线属于哪个单体，
+ * 只能拿端点坐标回来查。key 的量化方式必须和 `mergeVerticesByPosition` 完全一致，
+ * 否则焊过的顶点会对不上。返回 null 表示这个几何没有单体化信息。
+ */
+export function buildPositionBatchMap(
+  geometry: THREE.BufferGeometry,
+  tolerance: number
+): Map<string, number> | null {
+  const pos = geometry.getAttribute('position') as THREE.BufferAttribute | undefined;
+  const bid = geometry.getAttribute('aBatchId') as THREE.BufferAttribute | undefined;
+  if (!pos || !bid || pos.count === 0 || pos.count !== bid.count) return null;
+
+  const inv = 1 / Math.max(tolerance, 1e-9);
+  const map = new Map<string, number>();
+  for (let i = 0; i < pos.count; i++) {
+    const key = positionQuantKey(pos.getX(i), pos.getY(i), pos.getZ(i), inv);
+    if (!map.has(key)) map.set(key, bid.getX(i));
+  }
+  return map.size > 0 ? map : null;
+}
+
+/** 位置量化 key：与 mergeVerticesByPosition 同一套网格，保证焊过的顶点对得上 */
+export function positionQuantKey(x: number, y: number, z: number, inv: number): string {
+  return `${Math.round(x * inv)},${Math.round(y * inv)},${Math.round(z * inv)}`;
+}
+
 /* ------------------------------------------------------------------ 单体棱线提取 */
 
 export interface EdgeVertexRange {