s3m-three 0.4.19 → 0.4.20

package/docs/FORMAT-NOTES.md

@@ -96,25 +96,49 @@ byte[4] 's3m\0' + zlib
 
 ## 五、S3MBLOCK / texblock（纹理分包）
 
-从 `3D-CBD/Xiaopin@CBD` 逐字节标定，并与官方 `@supermapgis/s3m-content-loader` 的 `S3MBlockBufferLoader` 交叉验证。 —— **B 级**
+从 `3D-CBD/Xiaopin@CBD` 与 `3D-OlympicGreen-2`（Road / Building）逐字节标定，并与官方 `@supermapgis/s3m-content-loader` 的 `S3MBlockBufferLoader` 交叉验证。 —— **B 级**
 
-容器：
+### 5.1 容器结构
+
+一个 `.s3mblock` 文件不是“单块瓦片”，而是**一整棵 LOD 子树的打包**（例如 `1_00.s3mblock` 依次包含 `1_00`、`1_0000`、`1_000000` 三层 LOD 组）。
 
 ```
-float32 blockVersion              // 2.1
-uint32 groupCount                 // RO 组数，实测 1
-  每组重复：
-  String  name                    // "0.s3mblock"
-  if blockVersion <= 3.0: uint32 pageLodCount，每组 {float32 rangeValue; uint16 rangeMode; f64 sphere}
-  ...（组内是 zlib 压缩的 v2 瓦片体 + 内嵌纹理图集）
+float32 blockVersion              // 2.1 或 3.0
+uint32  groupCount                // RO 组数（LOD 档位数，实测 1 ~ 5 组）
+  每组重复（按 LOD 从粗到细排列）：
+    String  name                  // 组名，如 "1_00"、"1_0000"、"1_000000"
+    if blockVersion <= 3.0:
+      uint32 pageLodCount         // 外层 pageLOD 条数（注意：叶子瓦片恒为 0，见下文）
+      for 0..pageLodCount:
+        float32 rangeValue        // 切换阈值（RangeMode=1 时为屏幕像素直径）
+        uint16  rangeMode         // 1 = Pixel_Size_OnScreen, 0 = Distance_From_EyePoint
+        float64 sphere.center.xyz // 包围球中心（ENU 米）
+        float64 sphere.radius     // 包围球半径（米）
+        String  childTile         // 下一级瓦片名，如 "1_0000.s3mblock"
+    float32 version               // 内层瓦片数据版本（如 2.1 或 3.0）
+    if version >= 3:
+      uint32 compressedType       // 压缩方式（0 = 默认 zlib）
+    uint32 unzipSize              // 解压后字节数
+    uint32 zipSize                // 压缩块字节数
+    byte   zipData[zipSize]       // zlib 压缩的瓦片体（含段目录：GroupNode / 骨架 / 图集 / 材质 / 单体化）
 ```
 
-关键语义：
-
-- 纹理**不跟瓦片走**，作为「图集」内嵌在块里，材质通过图集 id（如 `-667946976.texblock`）引用，几何顶点的 UV 绑定到图集的子区域 → 解析时要把 UV 重映射进图集空间，多图集走货架式装箱（`AtlasPack`）。
-- **根块（`6.s3mblock`）的图集是内嵌的**（`isSaveData=1`）；但**子瓦（`6_00` / `6_01`）的图集段只有元信息**：`data = null` + `requestNames`，像素在同目录的 `.texblock` 里。不补这一步的后果不是「糊一点」，而是**子瓦整块无贴图**——`tile.textures` 里根本没有这条纹理，建筑变成纯白几何。
-- **只认 `requestNames`。`childTexNames` 是下一级 LOD 的图集指针**，它有自己的 `subTexInfos`：同一个精灵在父级叫 `1460_3`（96×64）、子级叫 `1460_2`（192×128），排布也不一样。拿父级的 rect 去套子级像素必然错位 —— 上一版就是这么把画面搞坏的。官方从不拿它换像素，那个 LOD 的瓦片自己会加载。
-- leaf 多精灵的图集没有整图像素，只有 `subTexInfos` 里每块一个 rect，按 `subName` 把精灵贴回各 rect 组合成整张自上而下 RGBA 画布（`composeLeafAtlas`）。精灵自带「左 2/3 base + 右 1/3 内联 mip 金字塔」，与 `StyleMaterial` 的 `s3mAtlasLod` 2/3 采样公式配套，rect 一个像素都不用改。
+### 5.2 关键语义与常见坑
+
+- **叶子瓦片（Leaf）外层 `pageLodCount` 恒为 0，绝对不能冲掉内层 `groupNode`**：
+  - S3MBLOCK 的外层 pageLOD 仅记录具有下级子代的瓦片调度门限与下级文件名。到了子树末端的叶子瓦片（没有后续子代），外层记录的 `pageLodCount` 恒为 `0`；
+  - 真正包含几何摆放的权威数据在**解压后的内层 GroupNode 段**里：内层始终带有一组完整的 `PageLOD`，其中挂着该瓦片的核心 `geodes`（每个 geode 携带 4×4 的 `matrix` 空间局部变换矩阵，以及包围球与 OBB）；
+  - **历史血泪 Bug**：若用外层 `pageLods.map(...)` 覆盖内层，当叶子瓦片外层为 0 条时，`mergedLods` 会直接变成空数组 `[]`，彻底丢弃内层的 `geodes`。渲染器取不到 geode 矩阵回退为单位矩阵，在存在场景大偏移的数据集（如 `Road@OlympicGreen` 矩阵平移为 `[-130, -1354, -0.15]` 米）中，表现为**瓦片细化瞬间闪烁并瞬移数公里**；且由于网格坐标偏离几公里，被 Three.js 视锥裁剪直接剔除，表现为**道路加载着加载着整片消失**；
+  - **正确处理方式**：当外层 `pageLods.length === 0` 时，直接回退并完整保留内层 `groupNode.pageLods`；若内层层数多于外层，亦将超出的内层条目追加保留；
+  - **官方 loader 对账**：官方 `@supermapgis/s3m-content-loader` 在解压完直接使用内层的 `groupNode = ShellEntitiesLoader.load(...)`，外层 pageLOD 仅用来跳过字节流，官方从不把内层清空。
+- **纹理不跟瓦片走（图集机制）**：
+  - 材质通过图集 id（如 `-667946976.texblock`）引用，几何顶点的 UV 绑定到图集的子区域 → 解析时要把 UV 重映射进图集空间，多图集走货架式装箱（`AtlasPack`）。
+- **根块与子瓦的图集分离**：
+  - 根块（`6.s3mblock`）的图集是内嵌的（`isSaveData=1`）；但子瓦（`6_00` / `6_01`）的图集段只有元信息：`data = null` + `requestNames`，像素在同目录的 `.texblock` 里。必须补齐外部图集，否则子瓦整块无贴图变成纯白。
+- **只认 `requestNames`，禁止用 `childTexNames` 替换像素**：
+  - `childTexNames` 是下一级 LOD 的图集指针，它有自己的 `subTexInfos`。同一个精灵在父级与子级的命名（如 `1460_3` vs `1460_2`）和排布不同，拿父级的 rect 去套子级像素必然错位。官方从不拿它换像素。
+- **Leaf 多精灵组合画布**：
+  - leaf 多精灵的图集没有整图像素，只有 `subTexInfos` 里每块一个 rect，按 `subName` 把精灵贴回各 rect 组合成整张自上而下 RGBA 画布（`composeLeafAtlas`）。精灵自带「左 2/3 base + 右 1/3 内联 mip 金字塔」，与 `StyleMaterial` 的 `s3mAtlasLod` 2/3 采样公式配套，rect 一个像素都不用改。
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "s3m-three",
-  "version": "0.4.19",
+  "version": "0.4.20",
   "description": "SuperMap S3M 三维模型格式的 three.js 渲染内核：浏览器内直接解析 .s3mb 瓦片，无需转 3D Tiles，支持 LOD 调度、白膜/按高度/按单体/动态扫描着色、单体级 GPU 拾取。宿主无关，可单独用于任意 three 场景。",
   "type": "module",
   "repository": {

package/src/core/Draco.ts

@@ -32,7 +32,7 @@
  * `version === 3` 的判定对 3.01 瓦片不成立），实际解析不了这个服务，所以以实测为准。
  */
 import type { BinaryReader } from './BinaryReader.js';
-import type { AttrDType, IndexPackage, VertexAttribute, VertexPackage } from './types.js';
+import type { AttrDType, IndexPackage, VertexPackage } from './types.js';
 import type { DracoModule, DracoPointAttribute, DracoPointCloud } from '../vendor/draco_decoder.module.js';
 
 /* ------------------------------------------------------------ draco 枚举（本地副本） */
@@ -41,7 +41,6 @@ import type { DracoModule, DracoPointAttribute, DracoPointCloud } from '../vendo
 const ATTR_POSITION = 0;
 const ATTR_NORMAL = 1;
 const ATTR_COLOR = 2;
-const ATTR_GENERIC = 4;
 
 /** draco::DataType（DT_INVALID = 0 占位） */
 const DT_UINT8 = 2;

package/src/core/S3MBlockParser.ts

@@ -67,13 +67,12 @@
  * 等价，但不需要官方的采样数组。顶点上取 fract 会让跨平铺边界的三角形反向扫纹理，别那样做。
  */
 import { BinaryReader } from './BinaryReader.js';
-import type { InflateFn, ParseOptions } from './S3MBParser.js';
+import type { InflateFn } from './S3MBParser.js';
 import type { GeoPackageEntry, GroupNode, PageLOD, ParsedTile, S3MAtlasRects, S3MTexture } from './types.js';
-import { parseGroupNodeEntries, parseSkeletonEntries, parsePickInfoEntries } from './S3MBParser.js';
-import { atlasAlphaMask, shrinkRectToOpaque } from './AtlasAlpha.js';
 import { packAtlases, decodeAtlasImage } from './AtlasPack.js';
 import type { PackedAtlases } from './AtlasPack.js';
 import { transcodeCRN } from './CRNDecode.js';
+import { parseGroupNodeEntries, parseSkeletonEntries, parsePickInfoEntries } from './S3MBParser.js';
 import { resolveTextureKind, PixelFormat, TextureCompress } from './TextureFormat.js';
 
 /** 图集子区域，以及它绑定的几何顶点区间 */
@@ -961,19 +960,31 @@ export async function parseS3MBlockGroups(
     const atlasRects = buildAtlasRects(geoPackage, texturePackage, packed);
     const textures = buildTextureTable(texturePackage);
 
-    // pageLOD：容器提供的 LOD/子瓦片信息是权威；geodes 在内层 groupNode 里
-    const innerLods = groupNode.pageLods;
-    const mergedLods: PageLOD[] = pageLods.map((lod, i) => {
-      const inner = innerLods[i];
-      return {
-        rangeValue: lod.rangeValue,
-        rangeMode: lod.rangeMode,
-        boundingSphere: lod.boundingSphere,
-        childTile: lod.childTile,
-        geodes: inner?.geodes ?? [],
-        ...(inner?.obb ? { obb: inner.obb } : {}),
-      };
-    });
+    // pageLOD：容器提供的 LOD/子瓦片信息是权威；geodes 在内层 groupNode 里。
+    // 注意：叶子瓦片（没有子代）在容器外层通常 pageLodCount 为 0，
+    // 此时绝对不能清空 pageLods，必须回退使用内层 groupNode 携带的真实 pageLOD
+    // （含关键的 geode 空间变换矩阵与包围球）。否则叶子瓦片会丢失 geode 矩阵，
+    // 退化为单位矩阵渲染，表现为「闪烁后瞬移/偏移数公里」以及因视锥剔除「渲染着消失」。
+    const innerLods = groupNode.pageLods ?? [];
+    let mergedLods: PageLOD[];
+    if (pageLods.length === 0) {
+      mergedLods = innerLods;
+    } else {
+      mergedLods = pageLods.map((lod, i) => {
+        const inner = innerLods[i];
+        return {
+          rangeValue: lod.rangeValue,
+          rangeMode: lod.rangeMode,
+          boundingSphere: lod.boundingSphere,
+          childTile: lod.childTile,
+          geodes: inner?.geodes ?? [],
+          ...(inner?.obb ? { obb: inner.obb } : {}),
+        };
+      });
+      if (innerLods.length > pageLods.length) {
+        mergedLods.push(...innerLods.slice(pageLods.length));
+      }
+    }
 
     tiles.push({
       version,

package/src/core/SplatSort.ts

@@ -1,5 +1,5 @@
 /**
- * 高斯泼溅的 back-to-front 排序键（纯数学，可单测）
+ * 高斯泼溅的 back-to-front 排序（纯数学，可单测）
  *
  * alpha 混合是顺序相关的：先画近的再画远的，远的颜色会盖到近的上头，
  * 画面就是一片随视角乱闪的彩色噪点。3DGS 必须按视深从远到近画。
@@ -7,9 +7,38 @@
  * 排序键是**视图空间 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,
@@ -17,14 +46,47 @@ export function splatDepthOrder(
   out?: Uint32Array
 ): Uint32Array {
   const idx = out && out.length >= count ? out : new Uint32Array(count);
-  const keys = new Float32Array(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;
-    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]!);
+
+  // 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/TileGeometry.ts

@@ -287,6 +287,16 @@ export interface TileGeometryData {
 export interface AssembleOptions {
   /** 是否对 primitiveType=4 的三角面做瓦片内同材质合批（默认 true） */
   batching?: boolean;
+  /**
+   * 是否剔除「同单体、同位置、同绕向」的共面重复三角形（默认 true）。
+   *
+   * 开：修掉数据自重叠造成的斜向摩尔纹（`3D-BIMbuilding-2` 实测单 geo 有 1/3 重复）。
+   * 关：完全不碰索引，一个循环都不跑 —— 数据本来没问题、又不想付这份 CPU 时用。
+   *
+   * 注意这份开销按三角形数线性增长（10 万三角形约 90 ms），在 Worker 里跑不占主线程；
+   * `useWorker: false` 或 Worker 崩溃降级时它落在主线程上。
+   */
+  dedupeCoincident?: boolean;
 }
 
 /* ------------------------------------------------------------------ 合批合并 */
@@ -851,17 +861,20 @@ export function assembleTileGeometry(tile: ParsedTile, options: AssembleOptions
   // 数据自重叠：同单体、同位置、同绕向的重复三角形会互相压深度，出斜向摩尔纹。
   // 只在**单 geo** 的 primitive 上做：合批产物里多个 geo 的 batchId 各自从 0 起，
   // 混在一起会把「不同单体恰好共面」误判成同一条。
-  for (const p of primitives) {
-    if (p.primitiveType !== 4 || !p.index) continue;
-    if (p.geoNames.length > 1) continue;
-    const positions = p.attributes.position?.array;
-    if (!positions) continue;
-    const batchIds = p.attributes.aBatchId?.array ?? null;
-    const { index, dropped } = dropCoincidentTriangles(p.index, positions, batchIds);
-    if (dropped > 0) {
-      p.index = index;
-      p.indexCount = index.length;
-      stats.deduped = (stats.deduped ?? 0) + dropped;
+  // 默认开；显式关掉时连循环都不进（stats 里也不会出现 deduped）。
+  if (options.dedupeCoincident !== false) {
+    for (const p of primitives) {
+      if (p.primitiveType !== 4 || !p.index) continue;
+      if (p.geoNames.length > 1) continue;
+      const positions = p.attributes.position?.array;
+      if (!positions) continue;
+      const batchIds = p.attributes.aBatchId?.array ?? null;
+      const { index, dropped } = dropCoincidentTriangles(p.index, positions, batchIds);
+      if (dropped > 0) {
+        p.index = index;
+        p.indexCount = index.length;
+        stats.deduped = (stats.deduped ?? 0) + dropped;
+      }
     }
   }
 

package/src/render/FeatureStyleManager.ts

@@ -18,7 +18,7 @@ import {
   buildAttributes,
   pickEntryId,
 } from '../core/FeatureInfo.js';
-import type { AttributeQuery, AttributeQueryOptions, AttributeRow } from '../core/AttributeQuery.js';
+import type { AttributeQuery, AttributeRow } from '../core/AttributeQuery.js';
 import type { StyledMaterial } from './StyleMaterial.js';
 import { restoreBaseBlendState } from './StyleMaterial.js';
 

package/src/render/GeometryBuilder.ts

@@ -127,14 +127,33 @@ function buildSplatGeometry(
   // 真实包围球：拾取要先用它做「射线有没有碰到这一块」的快速排除。
   // createQuadGeometry 里给的是空球（渲染靠 frustumCulled = false，不看它），
   // 留成 Infinity 的话每点一次要把所有瓦片的每个高斯都算一遍。
-  const box = new THREE.Box3();
-  const p = new THREE.Vector3();
-  for (let i = 0; i < count; i++) {
-    box.expandByPoint(p.set(posAttr.array[i * 3]!, posAttr.array[i * 3 + 1]!, posAttr.array[i * 3 + 2]!));
-  }
+  //
+  // 包围盒和最长轴在同一遍里扫完：10 万点的瓦片，多一遍就是几毫秒。
+  const pos = posAttr.array;
+  let minX = Infinity, minY = Infinity, minZ = Infinity;
+  let maxX = -Infinity, maxY = -Infinity, maxZ = -Infinity;
   let maxAxis = 0;
   for (let i = 0; i < count; i++) {
-    maxAxis = Math.max(maxAxis, scales[i * 3]!, scales[i * 3 + 1]!, scales[i * 3 + 2]!);
+    const x = pos[i * 3]!;
+    const y = pos[i * 3 + 1]!;
+    const z = pos[i * 3 + 2]!;
+    if (x < minX) minX = x;
+    if (x > maxX) maxX = x;
+    if (y < minY) minY = y;
+    if (y > maxY) maxY = y;
+    if (z < minZ) minZ = z;
+    if (z > maxZ) maxZ = z;
+    const sx = scales[i * 3]!;
+    const sy = scales[i * 3 + 1]!;
+    const sz = scales[i * 3 + 2]!;
+    if (sx > maxAxis) maxAxis = sx;
+    if (sy > maxAxis) maxAxis = sy;
+    if (sz > maxAxis) maxAxis = sz;
+  }
+  const box = new THREE.Box3();
+  if (count > 0) {
+    box.min.set(minX, minY, minZ);
+    box.max.set(maxX, maxY, maxZ);
   }
   const sphere = new THREE.Sphere(new THREE.Vector3(), 0);
   if (!box.isEmpty()) box.getBoundingSphere(sphere);
@@ -319,6 +338,13 @@ export interface BuildTileOptions {
    * 对倾斜摄影、大网格切片瓦片可减少 90%+ DrawCall，显著提高渲染帧率。
    */
   batching?: boolean;
+  /**
+   * 是否剔除同单体共面重复三角形（默认 true）。
+   *
+   * 见 `AssembleOptions.dedupeCoincident`。只在主线程现场组装时生效——
+   * 走 Worker 的路径在 Worker 里已经按默认值组装完了。
+   */
+  dedupeCoincident?: boolean;
   /**
    * Worker 侧已完成的纯数据几何组装（经典 .s3mb 路径由解析 Worker 顺带产出）。
    * 缺省时在主线程现场组装（core/TileGeometry 的同一份实现），两条路径产物一致。
@@ -526,7 +552,12 @@ export async function buildTileObjects(
 
   // 3) 纯数据几何组装：Worker 解析时已顺带产出就直接用，否则主线程现场组装
   //    （core/TileGeometry 的同一份实现，两条路径产物一致）
-  const assembled = options.assembled ?? assembleTileGeometry(tile, { batching: options.batching !== false });
+  const assembled =
+    options.assembled ??
+    assembleTileGeometry(tile, {
+      batching: options.batching !== false,
+      dedupeCoincident: options.dedupeCoincident,
+    });
   stats.vertices = assembled.stats.vertices;
   stats.edgeLines = assembled.stats.edgeLines;
   stats.instanced = assembled.stats.instanced;