s3m-three 0.4.17 → 0.4.19

package/src/core/S3MBlockParser.ts

@@ -73,6 +73,8 @@ import { parseGroupNodeEntries, parseSkeletonEntries, parsePickInfoEntries } fro
 import { atlasAlphaMask, shrinkRectToOpaque } from './AtlasAlpha.js';
 import { packAtlases, decodeAtlasImage } from './AtlasPack.js';
 import type { PackedAtlases } from './AtlasPack.js';
+import { transcodeCRN } from './CRNDecode.js';
+import { resolveTextureKind, PixelFormat, TextureCompress } from './TextureFormat.js';
 
 /** 图集子区域，以及它绑定的几何顶点区间 */
 export interface S3MSubTextureBinding {
@@ -487,13 +489,35 @@ export async function parseTexblockSegments(
 ): Promise<S3MBlockAtlasImage[][]> {
   const inflate = options.inflate ?? defaultInflate;
   const bytes = new Uint8Array(arrayBuffer);
-  const dyn = await tryDynPack(bytes, inflate);
-  if (dyn) return dyn;
-  const stat = await tryStaticPack(bytes, inflate);
-  if (stat) return stat;
-  const container = await readContainerEntries(bytes, inflate);
-  if (container) return [container];
-  throw new Error('[s3m] .texblock 无法识别的外层格式（动态 pack / 静态 pack / 容器均不成立）');
+  let segments: S3MBlockAtlasImage[][] | null = await tryDynPack(bytes, inflate);
+  if (!segments) segments = await tryStaticPack(bytes, inflate);
+  if (!segments) {
+    const container = await readContainerEntries(bytes, inflate);
+    if (container) segments = [container];
+  }
+  if (!segments) {
+    throw new Error('[s3m] .texblock 无法识别的外层格式（动态 pack / 静态 pack / 容器均不成立）');
+  }
+  // 3D-CBD-2 的 texblock 图像是 CRN 压缩（ct=26/27，'Hx' 魔数）。leaf 组合管线
+  // （composeLeafAtlas → decodeAtlasImage）只认 DXT / 已解 RGBA，这里统一在解析层
+  // 转码成 DXT：与主纹理解码的 crn->dxt 路径同一份 crunch wasm。
+  // 转码失败的记录原样保留（下游按缺失精灵处理并计数，不静默吞）。
+  for (const seg of segments) {
+    for (const rec of seg) {
+      if (resolveTextureKind(rec.compressType, rec.pixelFormat) !== 'crn') continue;
+      try {
+        const crn = await transcodeCRN(rec.data);
+        rec.data = crn.data;
+        rec.width = crn.width;
+        rec.height = crn.height;
+        rec.compressType = crn.dxtFormat === 1 ? TextureCompress.DXT1_RGBA : 14; // 14 = DXT5（见 TextureFormat 实测注释）
+        rec.pixelFormat = crn.dxtFormat === 1 ? PixelFormat.DXT1 : PixelFormat.DXT5;
+      } catch {
+        // 保留原记录，交给下游缺失统计
+      }
+    }
+  }
+  return segments;
 }
 
 /** 解压后的裸图像记录区：`ct|w|h|pf|size|data` 可多条连排，尾部允许有无关字节 */
@@ -512,6 +536,27 @@ function readImageRecords(raw: Uint8Array, id: string): S3MBlockAtlasImage[] {
   return out;
 }
 
+/**
+ * 条目负载解压。`zip == unzip` 是**存储态**（未压缩，内容直接就是图像记录区）：
+ * 3D-CBD-2 的 Tex_0_000.texblock 实测存在这种条目，无条件 inflate 会把整包
+ * 判成「无法识别的外层格式」。zlib 流必有 ~11 字节头尾开销，zip == unzip
+ * 不可能是有效 zlib，此判定安全。
+ */
+async function inflateEntryPayload(
+  payload: Uint8Array,
+  unzipSize: number,
+  zipSize: number,
+  inflate: InflateFn
+): Promise<Uint8Array | null> {
+  if (zipSize === unzipSize) return payload;
+  try {
+    const raw = await inflate(payload);
+    return raw.length === unzipSize ? raw : null;
+  } catch {
+    return null;
+  }
+}
+
 /** 读 `count | 条目 × count` 容器（尾部允许有无关字节）。结构不成立返回 null。 */
 async function readContainerEntries(bytes: Uint8Array, inflate: InflateFn): Promise<S3MBlockAtlasImage[] | null> {
   if (bytes.byteLength < 8) return null;
@@ -529,8 +574,8 @@ async function readContainerEntries(bytes: Uint8Array, inflate: InflateFn): Prom
       const unzipSize = r.u32();
       const zipSize = r.u32();
       if (zipSize > r.remaining) return null;
-      const raw = await inflate(r.bytesCopy(zipSize));
-      if (raw.length !== unzipSize) return null;
+      const raw = await inflateEntryPayload(r.bytesCopy(zipSize), unzipSize, zipSize, inflate);
+      if (!raw || raw.length !== unzipSize) return null;
       out.push(...readImageRecords(raw, name));
     }
     return out.length ? out : null;
@@ -552,8 +597,8 @@ async function readSingleEntry(bytes: Uint8Array, inflate: InflateFn): Promise<S
     const unzipSize = r.u32();
     const zipSize = r.u32();
     if (zipSize !== r.remaining) return null;
-    const raw = await inflate(r.bytesCopy(zipSize));
-    if (raw.length !== unzipSize) return null;
+    const raw = await inflateEntryPayload(r.bytesCopy(zipSize), unzipSize, zipSize, inflate);
+    if (!raw || raw.length !== unzipSize) return null;
     const recs = readImageRecords(raw, name);
     return recs.length ? recs : null;
   } catch {

package/src/core/SplatLod.ts

@@ -0,0 +1,83 @@
+/**
+ * 泼溅 / 点云瓦片的细化判据
+ *
+ * 判据只有一条：**单个高斯在屏幕上有多大**。3σ 半轴超过 `SPLAT_REFINE_PX` 像素
+ * 就再细化一层 —— 一个高斯铺出十几二十个像素时，它已经把整片屋顶/柱子糊成一坨，
+ * 细节全在「这一片高斯自己」里，再远的层级也换不回来。
+ *
+ * 走过两轮弯路，都不要再回去：
+ *
+ *   1. **包围球投影像素 vs rangeValue**（网格 LOD 的判据）。泼溅每层的 σ 是同一个
+ *      物理量，包围球半径和 rangeValue 跟「画面够不够密」没有因果关系。实测寿宁阁
+ *      的 rangeMode=2、rangeValue≈0.066·半径，按它算在任何距离都远大于阈值，等于
+ *      「永远细化到叶子」。
+ *
+ *   2. **屏幕覆盖率**（`高斯数/包围球投影面积 × 单个高斯面积`）。看起来很有道理，
+ *      但实测下来是个陷阱：根瓦片 σ=0.21 m、1888 个点，覆盖率就已经算到 1.7；
+ *      子瓦片直接跳到 8 —— 于是**在第二层就停了**，最终只画了 35.6 万个高斯，
+ *      占总量 2.3%。而官方是画到叶子层。21 cm 的高斯画不出 30 cm 宽的柱子，
+ *      画面上就是「柱子没了、到处是一坨坨横着的糊斑」。
+ *      覆盖率回答的是「屏幕盖满了没有」，盖满了也完全可能全是粗高斯。
+ *
+ * 所以现在改成屏幕尺寸判据。它天然自带下限：`splatPx` 已经小到着色器会剔除的量级
+ * （见 SplatProjection 的 `SPLAT_CULL_PIXELS`）时不再细化，再下一层只是白下载。
+ */
+import { SPLAT_SIGMA } from './SplatProjection.js';
+
+/**
+ * 3σ 半轴超过这个像素数就继续细化。
+ *
+ * 4 px 意味着单个高斯在屏幕上约 8 px 宽 —— 再细下去肉眼分辨不出，却要多占几倍显存
+ * （每深一层点数约 ×5）。着色器的亚像素剔除线是 2 px 半径，这里留了一倍余量。
+ */
+export const SPLAT_REFINE_PX = 4.0;
+
+/** 垂直视场角写死 45°，与 LOD 其它路径、官方 PageLod 口径一致 */
+const HALF_FOV_TAN = Math.tan(Math.PI / 8);
+
+/** 高斯实际可见面积相对 π(3σ)² 的比例（exp(-4r²) 衰减下的等效半径） */
+const EFFECTIVE_AREA_RATIO = 0.25;
+
+export interface SplatLodInput {
+  /** 该瓦片里的高斯数 */
+  splats: number;
+  /** 包围球半径（米） */
+  radius: number;
+  /** 相机到球心距离（米） */
+  distance: number;
+  /** 该瓦片高斯的代表性半轴（米）；0/缺省 = 未知，退回调用方的通用判据 */
+  sigma: number;
+  /** 绘图缓冲高度（像素） */
+  screenHeight: number;
+  /** 是否还有子瓦片 */
+  hasChild: boolean;
+}
+
+export interface SplatLodResult {
+  /** 3σ 半轴在屏幕上的长度（像素）—— 判据本体 */
+  splatPx: number;
+  /** 每像素高斯数（诊断用） */
+  density: number;
+  /** 屏幕覆盖率（诊断用；**不是**判据，原因见文件头） */
+  coverage: number;
+  needRefine: boolean;
+}
+
+/**
+ * 决定泼溅瓦片要不要再细化一层。
+ * `sigma <= 0` 时返回 `needRefine: false`，调用方应退回原判据。
+ */
+export function splatLodDecision(o: SplatLodInput): SplatLodResult {
+  const dist = Math.max(o.distance, 1e-6);
+  const ppm = o.screenHeight / 2 / HALF_FOV_TAN / dist;
+  const splatPx = SPLAT_SIGMA * Math.max(o.sigma, 0) * ppm;
+  if (!(o.sigma > 0) || !(o.radius > 0)) {
+    return { splatPx, density: 0, coverage: 0, needRefine: false };
+  }
+
+  const areaPx = Math.PI * (ppm * o.radius) ** 2;
+  const density = areaPx > 1e-6 ? o.splats / areaPx : 0;
+  const coverage = density * Math.PI * splatPx * splatPx * EFFECTIVE_AREA_RATIO;
+  const needRefine = o.hasChild && splatPx > SPLAT_REFINE_PX;
+  return { splatPx, density, coverage, needRefine };
+}

package/src/core/SplatProjection.ts

@@ -0,0 +1,231 @@
+/**
+ * 高斯泼溅的屏幕空间 EWA 投影（纯数学，供单测与顶点着色器共用同一套公式）
+ *
+ * 旧做法是把两个主轴投到「垂直于视线」的平面上、丢掉 z 分量。薄片高斯侧对
+ * 相机时被丢的那根轴直接归零，四边形塌成一条线 → 满墙空洞；远处高斯不足
+ * 一个像素时又会被光栅化漏掉。这里换成标准 EWA：
+ *
+ *   Σ′ = J · (W R S Sᵀ Rᵀ Wᵀ) · Jᵀ      （3D 协方差 → 屏幕 2×2）
+ *
+ * J 是 ndc 对视图坐标的雅可比，**直接用投影矩阵的元素**求，不假设它是标准
+ * 针孔透视 —— 本项目的 projectionMatrix 是 ENU→clip 的完整矩阵（w 行不是
+ * 恒等的 (0,0,-1,0)），套用教科书简式会算错。
+ *
+ * 得到的 2×2 做特征分解，两个特征向量 × 3σ 就是四边形在 ndc 里的两根半轴。
+ * 另有两道像素级处理，口径都照抄官方顶点着色器：
+ *   - 低通：协方差对角加 0.3px 的方差（3DGS 论文的抗锯齿口径）；
+ *   - 亚像素剔除：两根半轴都短于 2px 就整片丢弃（官方 covVectors<2 判据）。
+ *     这一条是「彩色马赛克」的对症解：泼溅数据被细化到亚像素时，一个像素上
+ *     压着几十个高斯，逐个画出来就是满屏噪点。
+ *
+ * 半轴**不会被放大**到可见尺寸。早先版本有个 minPixels 把细轴抬到 0.7px，
+ * 那等于把每片薄高斯都变成一个硬点，噪点依旧、覆盖还失真 —— 已删除。
+ *
+ * 着色器（render/SplatMaterial.ts）里是这套公式的逐行 GLSL 版，改公式两边同步。
+ */
+import type * as THREE from 'three';
+
+/** 3σ 覆盖 99.7% 的能量，与 3DGS 论文的裁剪口径一致 */
+export const SPLAT_SIGMA = 3.0;
+/** 抗锯齿低通的标准差（像素），3DGS 论文取 0.3 */
+export const SPLAT_LOW_PASS_PIXELS = 0.3;
+/**
+ * 半轴的最小像素长度（≈ 官方 lambda2 下限 0.1px² 对应的 sqrt(2*0.1)）。
+ * 只防完全退化，绝不是「抬成可见尺寸」—— 后者是彩色噪点的来源。
+ */
+export const SPLAT_MIN_AXIS_PIXELS = 0.45;
+/** 两根轴都短于这个像素数就整片丢弃（官方：dot(cov, cov) < 4.0 两轴同时成立） */
+export const SPLAT_CULL_PIXELS = 2.0;
+/**
+ * 半轴的像素上限。EWA 在中心贴近相机平面时会数值爆炸（实测近距离 max 4.2e6 px）：
+ * 一个 quad 跨满整屏、只跟视锥相交出一个角，看上去就是锐角三角面和放射状拉丝。
+ * 1024px 只砍这些异常投影，正常建筑（放大到贴脸看也就几百 px）碰不到。
+ */
+export const SPLAT_MAX_AXIS_PIXELS = 1024;
+
+export interface SplatScreenAxesOptions {
+  /** 视图空间中心（已乘过 modelViewMatrix） */
+  center: ArrayLike<number>;
+  /** 单位四元数 (x, y, z, w) */
+  quat: ArrayLike<number>;
+  /** 三个主轴半径（米） */
+  scale: ArrayLike<number>;
+  /** 只取旋转/缩放部分，用于把协方差带进视图空间 */
+  modelView: THREE.Matrix4;
+  /** 视图→clip 的完整矩阵（不要求是标准透视） */
+  projection: THREE.Matrix4;
+  viewportWidth: number;
+  viewportHeight: number;
+  /** 两根轴都短于这个像素数就剔除（返回 null）；0 = 不剔除 */
+  cullPixels: number;
+  /** 半轴像素上限，超过则整体等比缩小；0 / 不传 = 不封顶 */
+  maxPixels?: number;
+}
+
+export interface SplatScreenAxes {
+  /** ndc 半轴 A（对应四边形的 x 方向），已含 3σ 与钳制 */
+  ax: number;
+  ay: number;
+  /** ndc 半轴 B */
+  bx: number;
+  by: number;
+}
+
+/**
+ * 返回四边形在 ndc 里的两根半轴；相机后方（w<=0）返回 null。
+ * 调用方用 `clip.xy += (position.x*A + position.y*B) * clip.w` 出顶点。
+ */
+export function splatScreenAxes(o: SplatScreenAxesOptions): SplatScreenAxes | null {
+  const p = o.projection.elements; // 列主序
+  const cx = o.center[0]!, cy = o.center[1]!, cz = o.center[2]!;
+
+  const clipX = p[0]! * cx + p[4]! * cy + p[8]! * cz + p[12]!;
+  const clipY = p[1]! * cx + p[5]! * cy + p[9]! * cz + p[13]!;
+  const w = p[3]! * cx + p[7]! * cy + p[11]! * cz + p[15]!;
+  if (!(w > 1e-6)) return null;
+
+  // M = W · R · diag(s)，行向量取出后 Σ = M Mᵀ 只需要 6 个点积
+  const m = o.modelView.elements;
+  const [qx, qy, qz, qw] = [o.quat[0]!, o.quat[1]!, o.quat[2]!, o.quat[3]!];
+  const xx = qx * qx, yy = qy * qy, zz = qz * qz;
+  const xy = qx * qy, xz = qx * qz, yz = qy * qz;
+  const wx = qw * qx, wy = qw * qy, wz = qw * qz;
+  // R 的列（列主序）：R[col][row]
+  const r00 = 1 - 2 * (yy + zz), r01 = 2 * (xy - wz), r02 = 2 * (xz + wy);
+  const r10 = 2 * (xy + wz), r11 = 1 - 2 * (xx + zz), r12 = 2 * (yz - wx);
+  const r20 = 2 * (xz - wy), r21 = 2 * (yz + wx), r22 = 1 - 2 * (xx + yy);
+  const sx = o.scale[0]!, sy = o.scale[1]!, sz = o.scale[2]!;
+
+  // W · R · diag(s)：W 的第 i 列乘 R 的第 j 列再乘 s_j —— 直接展开成 M 的列
+  // M[col] = W * (R[col] * s_col)
+  const m00 = (m[0]! * r00 + m[4]! * r10 + m[8]! * r20) * sx;
+  const m10 = (m[1]! * r00 + m[5]! * r10 + m[9]! * r20) * sx;
+  const m20 = (m[2]! * r00 + m[6]! * r10 + m[10]! * r20) * sx;
+  const m01 = (m[0]! * r01 + m[4]! * r11 + m[8]! * r21) * sy;
+  const m11 = (m[1]! * r01 + m[5]! * r11 + m[9]! * r21) * sy;
+  const m21 = (m[2]! * r01 + m[6]! * r11 + m[10]! * r21) * sy;
+  const m02 = (m[0]! * r02 + m[4]! * r12 + m[8]! * r22) * sz;
+  const m12 = (m[1]! * r02 + m[5]! * r12 + m[9]! * r22) * sz;
+  const m22 = (m[2]! * r02 + m[6]! * r12 + m[10]! * r22) * sz;
+
+  // Σ 的上三角：行 i · 行 j
+  const v00 = m00 * m00 + m01 * m01 + m02 * m02;
+  const v01 = m00 * m10 + m01 * m11 + m02 * m12;
+  const v02 = m00 * m20 + m01 * m21 + m02 * m22;
+  const v11 = m10 * m10 + m11 * m11 + m12 * m12;
+  const v12 = m10 * m20 + m11 * m21 + m12 * m22;
+  const v22 = m20 * m20 + m21 * m21 + m22 * m22;
+
+  // 雅可比：ndc = clip.xy / w，对视图坐标求偏导
+  const w2 = w * w;
+  const j00 = (p[0]! * w - clipX * p[3]!) / w2;
+  const j01 = (p[4]! * w - clipX * p[7]!) / w2;
+  const j02 = (p[8]! * w - clipX * p[11]!) / w2;
+  const j10 = (p[1]! * w - clipY * p[3]!) / w2;
+  const j11 = (p[5]! * w - clipY * p[7]!) / w2;
+  const j12 = (p[9]! * w - clipY * p[11]!) / w2;
+
+  // C = J Σ Jᵀ（2×2 对称）
+  const c00 =
+    j00 * (v00 * j00 + v01 * j01 + v02 * j02) +
+    j01 * (v01 * j00 + v11 * j01 + v12 * j02) +
+    j02 * (v02 * j00 + v12 * j01 + v22 * j02);
+  const c01 =
+    j00 * (v00 * j10 + v01 * j11 + v02 * j12) +
+    j01 * (v01 * j10 + v11 * j11 + v12 * j12) +
+    j02 * (v02 * j10 + v12 * j11 + v22 * j12);
+  const c11 =
+    j10 * (v00 * j10 + v01 * j11 + v02 * j12) +
+    j11 * (v01 * j10 + v11 * j11 + v12 * j12) +
+    j12 * (v02 * j10 + v12 * j11 + v22 * j12);
+
+  // 抗锯齿低通：对角各加一个亚像素方差
+  const lpx = (2 * SPLAT_LOW_PASS_PIXELS) / o.viewportWidth;
+  const lpy = (2 * SPLAT_LOW_PASS_PIXELS) / o.viewportHeight;
+  const d00 = c00 + lpx * lpx;
+  const d11 = c11 + lpy * lpy;
+
+  // 2×2 特征分解（解析解，无迭代）
+  const mid = 0.5 * (d00 + d11);
+  const half = 0.5 * (d00 - d11);
+  const disc = Math.sqrt(Math.max(half * half + c01 * c01, 0));
+  const l1 = mid + disc;
+  const l2 = Math.max(mid - disc, 0);
+
+  let v1x = c01, v1y = l1 - d00;
+  const vlen = Math.hypot(v1x, v1y);
+  if (vlen > 1e-20) {
+    v1x /= vlen;
+    v1y /= vlen;
+  } else {
+    v1x = 1;
+    v1y = 0;
+  }
+
+  let r1 = SPLAT_SIGMA * Math.sqrt(Math.max(l1, 0));
+  let r2 = SPLAT_SIGMA * Math.sqrt(l2);
+
+  let ax = v1x * r1, ay = v1y * r1;
+  let bx = -v1y * r2, by = v1x * r2;
+
+  // 两道像素级处理，数值口径逐字照抄官方顶点着色器：
+  //
+  // ① 细轴下限。官方 `lambda2 = max(mid - radius, 0.1)`，即方差不低于 0.1px²，
+  //    对应半轴 sqrt(2*0.1) ≈ 0.447px。它只防「完全退化」，**不会**把一根
+  //    本来只有 1mm 的薄轴放大到肉眼可见 —— 放大才是噪点的来源。
+  // ② 亚像素剔除。官方 `if (dot(cov.xy,cov.xy) < 4.0 && dot(cov.zw,cov.zw) < 4.0)
+  //    discard`：两根轴都短于 2px 的高斯直接不画。泼溅数据被过度细化时，
+  //    一个像素上会压着几十个亚像素高斯，逐个抬成 1px 硬点就是满屏彩色马赛克；
+  //    丢掉它们，粗层的大高斯自然接管，画面才干净。
+  const px = o.viewportWidth / 2;
+  const py = o.viewportHeight / 2;
+
+  // ③ 上限封顶（先于下限）。中心贴近相机平面时雅可比爆炸，半轴能到几百万像素。
+  //    等比缩小两根轴，长宽比保持不变 —— 各向异性形状不能被压圆。
+  //    不做这一步的表现是：一个 quad 跨满屏、与视锥只相交出一个角，
+  //    画面上就是散落的锐角三角面和放射状拉丝。
+  if (o.maxPixels && o.maxPixels > 0) {
+    const la0 = Math.hypot(ax * px, ay * py);
+    const lb0 = Math.hypot(bx * px, by * py);
+    const biggest = Math.max(la0, lb0);
+    if (biggest > o.maxPixels) {
+      const k = o.maxPixels / biggest;
+      ax *= k;
+      ay *= k;
+      bx *= k;
+      by *= k;
+    }
+  }
+
+  const floorPx = SPLAT_MIN_AXIS_PIXELS;
+  const la = Math.hypot(ax * px, ay * py);
+  const lb = Math.hypot(bx * px, by * py);
+  if (la < floorPx) {
+    if (la > 1e-20) {
+      const k = floorPx / la;
+      ax *= k;
+      ay *= k;
+    } else {
+      ax = (2 * floorPx) / o.viewportWidth;
+      ay = 0;
+    }
+  }
+  if (lb < floorPx) {
+    if (lb > 1e-20) {
+      const k = floorPx / lb;
+      bx *= k;
+      by *= k;
+    } else {
+      bx = 0;
+      by = (2 * floorPx) / o.viewportHeight;
+    }
+  }
+
+  if (o.cullPixels > 0) {
+    const ca = Math.hypot(ax * px, ay * py);
+    const cb = Math.hypot(bx * px, by * py);
+    if (ca < o.cullPixels && cb < o.cullPixels) return null;
+  }
+
+  return { ax, ay, bx, by };
+}

package/src/core/SplatSort.ts

@@ -0,0 +1,30 @@
+/**
+ * 高斯泼溅的 back-to-front 排序键（纯数学，可单测）
+ *
+ * alpha 混合是顺序相关的：先画近的再画远的，远的颜色会盖到近的上头，
+ * 画面就是一片随视角乱闪的彩色噪点。3DGS 必须按视深从远到近画。
+ *
+ * 排序键是**视图空间 z**（相机前方为负），升序 = 远的先画。
+ * view 矩阵由调用方给（通常是 camera.matrixWorldInverse × mesh.matrixWorld），
+ * 本模块不关心相机朝向约定，只取矩阵第三行做点积。
+ */
+import type * as THREE from 'three';
+
+export function splatDepthOrder(
+  positions: Float32Array,
+  count: number,
+  view: THREE.Matrix4,
+  out?: Uint32Array
+): Uint32Array {
+  const idx = out && out.length >= count ? out : new Uint32Array(count);
+  const keys = new Float32Array(count);
+  const e = view.elements;
+  const r0 = e[2]!, r1 = e[6]!, r2 = e[10]!, r3 = e[14]!;
+  for (let i = 0; i < count; i++) {
+    idx[i] = i;
+    keys[i] = r0 * positions[i * 3]! + r1 * positions[i * 3 + 1]! + r2 * positions[i * 3 + 2]! + r3;
+  }
+  // TypedArray.sort 带比较函数时是数值排序，且 V8/JSC 对相同键稳定
+  idx.sort((a, b) => keys[a]! - keys[b]!);
+  return idx;
+}

package/src/core/TexCoordZ.ts

@@ -0,0 +1,160 @@
+/**
+ * S3M 的 uv 第三分量（顶点属性 `custom0`，官方叫 `aTextureCoordMatrix`）。
+ *
+ * 为什么需要它：官方引擎对普通（非 S3MBLOCK）S3M 瓦片并不是「有纹理就整张平铺」。
+ * 每个顶点在 uv 之外还带一个 z，iClient3D 在**顶点着色器**里拿它解出一个纹理矩阵：
+ *
+ *   `getTextureMatrixFromZValue( floor(z), xTran, yTran, scale )`
+ *     bit[0:7]   → yTran     （图集列号）
+ *     bit[8:15]  → xTran     （图集行号）
+ *     bit[16:19] → level     （scale = 1 / 2^level，即图集是 2^level × 2^level 格）
+ *   三档哨兵（官方 bundle getTextureColor / getUV 实测）：
+ *     z < -99900 → `return vec4(1.0)` 纯白不采样（平涂顶点色面，值 -99999）
+ *     z < -9000  → 「uv 原样平铺整图」：calculateTexCoord 里 `out = inTexCoord.xy`
+ *                   （不 fract 不缩放），普通 texture2D（自动 mip）采样
+ *     其余       → 图集子区域公式
+ *
+ * 片元侧是 `calculateMipLevel` + `calculateTexCoord`：
+ *
+ *   fTile = scale * texWidth                       // 一格在图里的像素宽
+ *   mip   = clamp( 0.5*log2(d), 0, log2(fTile) - 1.62 )
+ *   f     = clamp( fract(uv), 2^mip/fTile, 1 - 2^mip/fTile )   // 越糊越往格子中心收缩
+ *   out   = ( f + T ) * scale
+ *
+ * 实测 SuperMap Online 的 `3D-BIMbuilding-2`（OSGB 转 S3M，全部 7 个根瓦片）：
+ *   z ∈ { -99999, 0, 65536, 65537, 65792, 65793, 262144, 327680 }
+ *   uv 是米制世界坐标（1 单位 ≈ 1 m），每米一个纹理周期。
+ *
+ * 本文件是这段数学的**唯一可执行版本**：着色器里是它的 GLSL 直译
+ * （见 render/StyleMaterial.ts 的 VERT_TEXCOORD_Z / s3mTexCoordZUnit），
+ * 单测 tests/unit/texcoord-z-math.test.ts 钉住两边必须一致。
+ */
+
+/** 官方哨兵：`inTexCoord.z < -9000` 走「uv 原样平铺」分支（getTexColorForS3M / calculateTexCoord） */
+export const TEX_COORD_Z_DISABLED_BELOW = -9000;
+
+/**
+ * 官方白色哨兵：`texCoordZ < -99900` 时 getTextureColor 直接 `return vec4(1.0)`，
+ * **完全不采样纹理**（数据里是 -99999）。最终颜色 = 白 × 材质 diffuse × 顶点色，
+ * 即「平涂顶点色面」—— BIM 场景的地面标线 / 色块就是这类（SMID 3464：灰色地面 +
+ * 黄色标线 + 暗红区域，全靠顶点色）。
+ *
+ * 注意与 -9000 平铺哨兵的区分：-99999 一旦按平铺处理，uv（-85..85 这类米制值）
+ * 会把整张纹理平铺上百次，表现为「uv 整图」——这正是三档语义漏掉白色档的教训。
+ */
+export const TEX_COORD_Z_WHITE_BELOW = -99900;
+
+/** 官方 calculateMipLevel 里那个上限收缩量 */
+export const MIP_LIMIT_BIAS = 1.62;
+
+/** 该顶点是否走「uv 原样平铺」分支。没有这条属性的数据 z 取 0，返回 false，行为不变。 */
+export function isTexCoordDisabled(z: number): boolean {
+  return z < TEX_COORD_Z_DISABLED_BELOW;
+}
+
+/** 该顶点是否走「纯白、不采样」分支（z < -99900，实测值 -99999）。优先级高于平铺。 */
+export function isTexCoordWhite(z: number): boolean {
+  return z < TEX_COORD_Z_WHITE_BELOW;
+}
+
+/** 解码结果。`disabled` 为真时其余字段无意义（着色器里对应 scale = -1；`white` 时 scale = -2） */
+export interface TexMatrix {
+  disabled: boolean;
+  /** z < -99900：纯白不采样（见 TEX_COORD_Z_WHITE_BELOW） */
+  white: boolean;
+  /** 一格占整张纹理的比例，1/2^level */
+  scale: number;
+  /** 图集列号 */
+  xTran: number;
+  /** 图集行号 */
+  yTran: number;
+}
+
+/**
+ * 官方 `getTextureMatrixFromZValue` 的逐行移植。
+ *
+ * 注意 `nZ <= 0` 时官方直接 return，**不改**外部初值 —— 也就是单位变换
+ * `scale=1, T=(0,0)`，等价于整张纹理按 uv 平铺。
+ *
+ * 着色器侧的档位编码：scale = -2 → 白；-1 → 平铺；>0 → 图集公式。
+ */
+export function decodeTexMatrix(z: number): TexMatrix {
+  if (isTexCoordWhite(z)) {
+    return { disabled: true, white: true, scale: -2, xTran: 0, yTran: 0 };
+  }
+  if (isTexCoordDisabled(z)) {
+    return { disabled: true, white: false, scale: -1, xTran: 0, yTran: 0 };
+  }
+  const nz = Math.floor(z);
+  if (nz <= 0) {
+    return { disabled: false, white: false, scale: 1, xTran: 0, yTran: 0 };
+  }
+  const nDel8 = Math.floor(nz / 256);
+  const nDel16 = Math.floor(nDel8 / 256);
+  const nDel20 = Math.floor(nDel16 / 16);
+  return {
+    disabled: false,
+    white: false,
+    xTran: nDel8 - nDel16 * 256,
+    yTran: nz - nDel8 * 256,
+    scale: 1 / Math.pow(2, nDel16 - nDel20 * 16),
+  };
+}
+
+/** 官方 `vTexMatrix.w = log2( uTexture0Width * vTexMatrix.z )` */
+export function texMaxMip(texWidth: number, scale: number): number {
+  return Math.log2(texWidth * scale);
+}
+
+const clamp = (v: number, lo: number, hi: number) => Math.min(Math.max(v, lo), hi);
+
+/**
+ * 官方 `calculateMipLevel` 的逐行移植。
+ *
+ * 四个导数参数是 `dFdx(u) / dvDx / duDy / dFdy(v)`（uv 单位每像素），
+ * 内部乘 `fTile = scale*texWidth` 换成纹素单位 —— 与官方
+ * `dFdx( inTexCoord * vecTile )` 完全一致。
+ *
+ * ★ 必须用**未 fract 的 uv** 求导：先 fract 再求导会在平铺接缝处炸出一个
+ *   巨大导数，硬件会把整块面采成最糊的 mip，表现为每条接缝一条暗带。
+ */
+export function texMipLevel(
+  duDx: number,
+  dvDx: number,
+  duDy: number,
+  dvDy: number,
+  fTile: number,
+  maxMip: number
+): number {
+  const xU = duDx * fTile;
+  const xV = dvDx * fTile;
+  const yU = duDy * fTile;
+  const yV = dvDy * fTile;
+  const dotX = xU * xU + xV * xV;
+  const dotY = yU * yU + yV * yV;
+  const dMax = Math.max(dotX, dotY);
+  const dMin = Math.min(dotX, dotY);
+  const off = clamp((dMax - dMin) / Math.max(dMax + dMin, 1e-8), 0, 1);
+  const d = dMax * (1 - off) + dMin * off;
+  return clamp(0.5 * Math.log2(Math.max(d, 1e-8)), 0, maxMip - MIP_LIMIT_BIAS);
+}
+
+/**
+ * 官方 `calculateTexCoord` 的逐行移植：fract → 按 mip 内缩 → 平移 + 缩放。
+ *
+ * `mip` 必须已经过 `texMipLevel` 的上限裁剪（≤ maxMip - 1.62），
+ * 否则 `2^mip/fTile > 0.5` 时 clamp 的上下界会翻转，官方同样会出问题。
+ */
+export function sampleTexCoord(
+  m: TexMatrix,
+  u: number,
+  v: number,
+  texWidth: number,
+  mip: number
+): { u: number; v: number } {
+  const fTile = Math.max(m.scale * texWidth, 1);
+  const inner = Math.pow(2, mip) / fTile;
+  const fu = clamp(u - Math.floor(u), inner, 1 - inner);
+  const fv = clamp(v - Math.floor(v), inner, 1 - inner);
+  return { u: (fu + m.xTran) * m.scale, v: (fv + m.yTran) * m.scale };
+}