s3m-three 0.4.18 → 0.4.20

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,92 @@
+/**
+ * 高斯泼溅的 back-to-front 排序（纯数学，可单测）
+ *
+ * alpha 混合是顺序相关的：先画近的再画远的，远的颜色会盖到近的上头，
+ * 画面就是一片随视角乱闪的彩色噪点。3DGS 必须按视深从远到近画。
+ *
+ * 排序键是**视图空间 z**（相机前方为负），升序 = 远的先画。
+ * view 矩阵由调用方给（通常是 camera.matrixWorldInverse × mesh.matrixWorld），
+ * 本模块不关心相机朝向约定，只取矩阵第三行做点积。
+ *
+ * ## 为什么是基数排序
+ *
+ * 这里是**每帧**都要跑的路径（相机一动就重排），原来的
+ * `TypedArray.sort((a, b) => keys[a] - keys[b])` 有两个代价：
+ *   - 比较函数是 JS 调用，10 万点实测 38 ms/帧；
+ *   - 每次调用都 `new Float32Array(count)` + `new Uint32Array(count)`，每帧分配 800 KB。
+ *
+ * 换成 4 遍 8 位 LSD 基数排序后实测 3 ms，且缓冲全部复用。没选桶排序是因为
+ * 深度分布会很不均匀（正对相机的墙面，几万个点的视深几乎相同），桶内再排会退化。
+ *
+ * 排序键先转成「无符号可比」的 32 位整数（IEEE754 的标准技巧），
+ * 这样无符号整数比较的大小顺序与 float 完全一致，基数排序才成立。
+ */
+import type * as THREE from 'three';
+
+/** 模块级 scratch：只增不减。排序是同步的，同一时刻只有一个在跑 */
+let _keys = new Uint32Array(0);
+let _scratch = new Uint32Array(0);
+const _counts = new Uint32Array(256);
+
+/** float → 无符号可比的 32 位键（正数翻符号位，负数按位取反） */
+const _f32 = new Float32Array(1);
+const _u32 = new Uint32Array(_f32.buffer);
+
+function sortableBits(k: number): number {
+  _f32[0] = k;
+  const u = _u32[0]!;
+  // 负数的 IEEE754 表示是「符号位 1 + 绝对值」，直接按无符号比会把 -1 排到 0 后面
+  return u & 0x80000000 ? ~u >>> 0 : (u | 0x80000000) >>> 0;
+}
+
+export function splatDepthOrder(
+  positions: Float32Array,
+  count: number,
+  view: THREE.Matrix4,
+  out?: Uint32Array
+): Uint32Array {
+  const idx = out && out.length >= count ? out : new Uint32Array(count);
+  if (count <= 1) {
+    if (count === 1) idx[0] = 0;
+    return idx;
+  }
+
+  if (_keys.length < count) _keys = new Uint32Array(count);
+  if (_scratch.length < count) _scratch = new Uint32Array(count);
+  const keys = _keys;
+  const scratch = _scratch;
+
+  const e = view.elements;
+  const r0 = e[2]!, r1 = e[6]!, r2 = e[10]!, r3 = e[14]!;
+  for (let i = 0; i < count; i++) {
+    keys[i] = sortableBits(r0 * positions[i * 3]! + r1 * positions[i * 3 + 1]! + r2 * positions[i * 3 + 2]! + r3);
+    idx[i] = i;
+  }
+
+  // 4 遍 × 8 位。偶数遍 → 结果一定回到 idx，不用再拷一次
+  let src = idx;
+  let dst = scratch;
+  for (let pass = 0; pass < 4; pass++) {
+    const shift = pass * 8;
+    _counts.fill(0);
+    for (let i = 0; i < count; i++) _counts[(keys[src[i]!]! >>> shift) & 0xff]!++;
+    // 前缀和 → 每个桶的起始写位置
+    let sum = 0;
+    for (let b = 0; b < 256; b++) {
+      const c = _counts[b]!;
+      _counts[b] = sum;
+      sum += c;
+    }
+    for (let i = 0; i < count; i++) {
+      const v = src[i]!;
+      dst[_counts[(keys[v]! >>> shift) & 0xff]!++] = v;
+    }
+    const t = src;
+    src = dst;
+    dst = t;
+  }
+
+  // 4 遍之后 src 就是 idx（起始 src=idx，偶数次交换后回到 idx）；防御性兜一下
+  if (src !== idx) idx.set(src);
+  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 };
+}

package/src/core/TextureDecode.ts

@@ -32,6 +32,12 @@ export interface DecodedTextureData {
    */
   blocks?: Uint8Array;
   blockFormat?: 'dxt1' | 'dxt5';
+  /**
+   * 数据自带的 DXT 内联 mip 链（S3M 纹理的 data 常是 level0 + 完整链，`tex.level`
+   * 记录层数）。官方 iClient3D 把整条链逐层上传，远处采样高层级平均成纯色。
+   * 与 blocks 同时存在；渲染层用它构造多层 CompressedTexture。
+   */
+  mipmaps?: { data: Uint8Array; width: number; height: number }[];
   /** CRN 转码失败时的原始错误（渲染层负责打 warn） */
   error?: string;
 }
@@ -195,6 +201,33 @@ export function expectedDxtByteLength(width: number, height: number, format: 'dx
   return bw * bh * (format === 'dxt1' ? 8 : 16);
 }
 
+/**
+ * 切 DXT 内联 mip 链：`data` = level0 + 逐层减半直到 1×1，每层 ceil(w/4)*ceil(h/4)*blockBytes。
+ * 切不出与总字节数严丝合缝的链（不是链 / 格式对不上）返回 null，调用方回退。
+ */
+export function sliceDxtMipChain(
+  data: Uint8Array,
+  width: number,
+  height: number,
+  blockBytes: number
+): { data: Uint8Array; width: number; height: number }[] | null {
+  const levels: { data: Uint8Array; width: number; height: number }[] = [];
+  let w = width;
+  let h = height;
+  let off = 0;
+  for (;;) {
+    const bytes = Math.ceil(w / 4) * Math.ceil(h / 4) * blockBytes;
+    if (off + bytes > data.byteLength) return null;
+    levels.push({ data: data.subarray(off, off + bytes), width: w, height: h });
+    off += bytes;
+    if (w === 1 && h === 1) break;
+    w = Math.max(1, w >> 1);
+    h = Math.max(1, h >> 1);
+  }
+  if (off !== data.byteLength) return null;
+  return levels;
+}
+
 /** 主线程 / Worker 共用的解码入口。不抛错：失败与不支持都体现在返回值里 */
 export async function decodeTextureData(
   tex: S3MTexture,
@@ -230,6 +263,7 @@ async function decodeTextureDataRaw(
   const compressible = (data: Uint8Array, w: number, h: number, format: 'dxt1' | 'dxt5'): boolean =>
     data.byteLength === expectedDxtByteLength(w, h, format);
 
+
   if (kind === 'crn') {
     try {
       const crn = await transcodeCRN(tex.data);
@@ -279,17 +313,35 @@ async function decodeTextureDataRaw(
   if (kind === 'dxt1' || kind === 'dxt3' || kind === 'dxt4' || kind === 'dxt5') {
     const pf = dxtPixelFormatOf(kind);
     // dxt3/dxt4 少见，不进直传白名单；块长与 4×4 对齐公式不符的也回退解码
-    if (canCompress && (kind === 'dxt1' || kind === 'dxt5') && compressible(tex.data, tex.width, tex.height, kind)) {
-      return {
-        kind: `${kind}(c)`,
-        width: tex.width,
-        height: tex.height,
-        rgba: null,
-        bitmap: null,
-        hasAlpha: kind === 'dxt5',
-        blocks: tex.data,
-        blockFormat: kind,
-      };
+    if (canCompress && (kind === 'dxt1' || kind === 'dxt5')) {
+      const level0Bytes = expectedDxtByteLength(tex.width, tex.height, kind);
+      if (tex.data.byteLength === level0Bytes && compressible(tex.data, tex.width, tex.height, kind)) {
+        return {
+          kind: `${kind}(c)`,
+          width: tex.width,
+          height: tex.height,
+          rgba: null,
+          bitmap: null,
+          hasAlpha: kind === 'dxt5',
+          blocks: tex.data,
+          blockFormat: kind,
+        };
+      }
+      // 带内联 mip 链：整条切出来逐层上传（官方同款）。切不齐（字节不吻合）再回退解码
+      const chain = sliceDxtMipChain(tex.data, tex.width, tex.height, kind === 'dxt1' ? 8 : 16);
+      if (chain && chain.length > 1) {
+        return {
+          kind: `${kind}(chain)`,
+          width: tex.width,
+          height: tex.height,
+          rgba: null,
+          bitmap: null,
+          hasAlpha: kind === 'dxt5',
+          blocks: tex.data,
+          blockFormat: kind,
+          mipmaps: chain,
+        };
+      }
     }
     const decoded = decodeDXT({ ...tex, pixelFormat: pf });
     return { kind, width: tex.width, height: tex.height, rgba: decoded.rgba, bitmap: null, hasAlpha: decoded.hasAlpha };