s3m-three 0.4.18 → 0.4.20

package/src/render/GeometryBuilder.ts

@@ -14,13 +14,18 @@
 import * as THREE from 'three';
 import { createTexture } from './TextureFactory.js';
 import { createSharedUniforms, createStyledMaterial } from './StyleMaterial.js';
+import { isTransparentMaterial, minVertexAlpha } from './materialAlpha.js';
 import type { StyledMaterial } from './StyleMaterial.js';
 import { assembleTileGeometry, LINE_PRIMITIVE, POINT_PRIMITIVE } from '../core/TileGeometry.js';
 import type { TileGeometryData, PrimitiveData } from '../core/TileGeometry.js';
+import { decodeScale, decodeRotation } from '../core/GaussianSplat.js';
+import { createSplatMaterial, createQuadGeometry, splatRaycast } from './SplatMaterial.js';
+import { SPLAT_SIGMA } from '../core/SplatProjection.js';
 import type {
   GeoPackageEntry,
   ParsedTile,
   StyleUniforms,
+  VertexPackage,
 } from '../core/types.js';
 
 // 组装层下沉 core 后的对外 API 兼容：常量原住本文件
@@ -35,6 +40,146 @@ function isPointPrimitive(primitiveType: number): boolean {
   return primitiveType === POINT_PRIMITIVE;
 }
 
+/* ------------------------------------------------------------ 高斯泼溅 */
+
+let splatMaterial: THREE.ShaderMaterial | null = null;
+
+/** 泼溅材质全瓦片共享：同一套 program / uniform，不为每块瓦片单独编译 */
+function getSplatMaterial(): THREE.ShaderMaterial {
+  splatMaterial ??= createSplatMaterial();
+  return splatMaterial;
+}
+
+/**
+ * 每帧同步绘图缓冲尺寸：顶点着色器的最小像素半径 / 抗锯齿低通都要拿它
+ * 把 ndc 换算成像素。还没建过泼溅材质时什么都不做（不为了设置而创建）。
+ */
+export function setSplatViewport(width: number, height: number): void {
+  if (splatMaterial) (splatMaterial.uniforms.uViewport!.value as THREE.Vector2).set(width, height);
+}
+
+/**
+ * 点云包 → 实例化四边形（每个高斯一片）。
+ *
+ * 返回 `null` 表示这不是泼溅数据（缺 gsScale / gsRotation），调用方退回 `THREE.Points`。
+ * 这样「有泼溅参数就画泼溅、没有就当点云」的分流只由数据决定，不靠外部开关。
+ */
+function buildSplatGeometry(
+  prim: PrimitiveData,
+  vp: VertexPackage
+): { geo: THREE.InstancedBufferGeometry; sigma: number } | null {
+  const scaleAttr = vp.vertexAttributes.find((a) => a.semantic === 'gsScale');
+  const rotAttr = vp.vertexAttributes.find((a) => a.semantic === 'gsRotation');
+  const posAttr = prim.attributes.position;
+  if (!scaleAttr || !rotAttr || !posAttr) return null;
+
+  // 泼溅参数是逐骨架的，合批不会发生在点云包上；取两者较小值兜住异常数据，
+  // 宁可少画几个高斯，也不要读到越界内存
+  const count = Math.min(
+    vp.verticesCount,
+    Math.floor(posAttr.array.length / posAttr.components)
+  );
+  if (count <= 0) return null;
+
+  const scales = decodeScale(scaleAttr.data, scaleAttr.stride, scaleAttr.offsetInBytes, count);
+  const quats = decodeRotation(rotAttr.data, rotAttr.stride, rotAttr.offsetInBytes, count);
+
+  // 代表性半轴：抽样的最长轴中位数（米）。LOD 判据要拿它估「屏幕上高斯有多大」，
+  // 见 core/SplatLod.ts。抽样上限 512，解码已经付过代价，这里不再逐点扫。
+  const sigma = medianLongAxis(scales, count);
+
+  const geo = createQuadGeometry();
+  geo.instanceCount = count;
+  geo.setAttribute(
+    'iCenter',
+    new THREE.InstancedBufferAttribute(posAttr.array as Float32Array, 3)
+  );
+  geo.setAttribute('iScale', new THREE.InstancedBufferAttribute(scales, 3));
+  geo.setAttribute('iQuat', new THREE.InstancedBufferAttribute(quats, 4));
+
+  // 颜色优先取 vp 的原始 color 流（u8×4，含 alpha）。
+  // prim.attributes.aColor 现在也是 RGBA，但点云这条路径本来就要原始字节
+  // （避免多一轮 float 转换），保持原样即可。
+  const rgba = new Float32Array(count * 4);
+  rgba.fill(1);
+  const colorAttr = vp.vertexAttributes.find((a) => a.semantic === 'color');
+  if (colorAttr && colorAttr.dtype === 'u8') {
+    const comp = colorAttr.components ?? 4;
+    // 异常包里 color 流可能比顶点数短：读不到的点保持默认白，不越界
+    const n = Math.min(count, Math.floor(colorAttr.data.length / colorAttr.stride));
+    for (let i = 0; i < n; i++) {
+      const o = i * colorAttr.stride + colorAttr.offsetInBytes;
+      rgba[i * 4] = colorAttr.data[o]! / 255;
+      rgba[i * 4 + 1] = colorAttr.data[o + 1]! / 255;
+      rgba[i * 4 + 2] = colorAttr.data[o + 2]! / 255;
+      if (comp >= 4) rgba[i * 4 + 3] = colorAttr.data[o + 3]! / 255;
+    }
+  } else if (prim.attributes.aColor) {
+    // 兜底：只有组装后的 RGB（0~1 float），alpha 补 1
+    const src = prim.attributes.aColor;
+    const comp = src.components ?? 4;
+    for (let i = 0; i < count; i++) {
+      for (let k = 0; k < Math.min(comp, 4); k++) rgba[i * 4 + k] = src.array[i * comp + k]!;
+    }
+  }
+  geo.setAttribute('iColor', new THREE.InstancedBufferAttribute(rgba, 4));
+
+  // 真实包围球：拾取要先用它做「射线有没有碰到这一块」的快速排除。
+  // createQuadGeometry 里给的是空球（渲染靠 frustumCulled = false，不看它），
+  // 留成 Infinity 的话每点一次要把所有瓦片的每个高斯都算一遍。
+  //
+  // 包围盒和最长轴在同一遍里扫完：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++) {
+    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);
+  sphere.radius += SPLAT_SIGMA * maxAxis;
+  geo.boundingSphere = sphere;
+
+  return { geo, sigma };
+}
+
+/**
+ * 最长轴的中位长度（米）。抽样上限 512 个，够稳且不拖慢瓦片构建。
+ * 全部非正 / 非有限值时返回 0，调用方据此退回通用 LOD 判据。
+ */
+function medianLongAxis(scales: Float32Array, count: number): number {
+  const step = Math.max(1, Math.floor(count / 512));
+  const xs: number[] = [];
+  for (let i = 0; i < count; i += step) {
+    const m = Math.max(scales[i * 3]!, scales[i * 3 + 1]!, scales[i * 3 + 2]!);
+    if (Number.isFinite(m) && m > 0) xs.push(m);
+  }
+  if (!xs.length) return 0;
+  xs.sort((a, b) => a - b);
+  return xs[xs.length >> 1]!;
+}
+
+
 /* ------------------------------------------------------------------ 图集 UV */
 
 /**
@@ -79,6 +224,18 @@ function getPointCloudMaterial(): THREE.PointsMaterial {
 /** SuperMap 内置水面（`103.water`）的基色：偏深的青蓝，配合低粗糙度出一点天光反射 */
 const WATER_COLOR = new THREE.Color(0x1d4e63);
 
+/**
+ * 棱线 / 高斯点云的绘制顺序基准。
+ *
+ * 三角面网格的 renderOrder 被钉成「文件里的材质序号」（见 materialIndexOf），
+ * 是个从 0 开始的小整数；这两个覆盖层必须排在所有材质之后，
+ * 否则会被某块瓦片的材质序号插到前面去。
+ */
+const EDGE_LINES_RENDER_ORDER = 1000;
+const POINT_SPLAT_RENDER_ORDER = 1001;
+/** 材质序号的上限，留出覆盖层的空间 */
+const MAX_MATERIAL_RENDER_ORDER = 999;
+
 /* ------------------------------------------------------------------ 材质描述 */
 
 interface RawMaterialUnit {
@@ -158,6 +315,13 @@ export interface TileBuildStats {
   edgeLines: number;
   /** 合批前原有独立网格数 */
   originalMeshes?: number;
+  /**
+   * 该瓦片高斯的最长轴中位长度（米）。只有泼溅瓦片才有值，LOD 判据用它估
+   * 「屏幕上一个高斯多大」，见 core/SplatLod.ts。
+   */
+  splatSigma?: number;
+  /** 该瓦片的高斯实例数。泼溅瓦片才有值，LOD 判据用它算屏幕覆盖率 */
+  splatCount?: number;
   /** 被跳过的东西，加载完可以直接在控制台看 */
   skipped: string[];
 }
@@ -174,11 +338,27 @@ export interface BuildTileOptions {
    * 对倾斜摄影、大网格切片瓦片可减少 90%+ DrawCall，显著提高渲染帧率。
    */
   batching?: boolean;
+  /**
+   * 是否剔除同单体共面重复三角形（默认 true）。
+   *
+   * 见 `AssembleOptions.dedupeCoincident`。只在主线程现场组装时生效——
+   * 走 Worker 的路径在 Worker 里已经按默认值组装完了。
+   */
+  dedupeCoincident?: boolean;
   /**
    * Worker 侧已完成的纯数据几何组装（经典 .s3mb 路径由解析 Worker 顺带产出）。
    * 缺省时在主线程现场组装（core/TileGeometry 的同一份实现），两条路径产物一致。
    */
   assembled?: TileGeometryData;
+  /**
+   * 给三角面材质加 polygonOffset（深度偏移）。
+   *
+   * 用途：跨单体完全共面的重复面（如 `3D-BIMbuilding-2` 的 5136）深度值落在
+   * 深度缓冲分辨率边缘时出斜向摩尔纹；给其中一方一个小偏移（负值 = 拉向相机）
+   * 让每个像素稳定选边。这是**整个 mesh 粒度**的开关——该材质所有面都会偏移，
+   * 偏移量随斜率/距离缩放，量级在微米级，正常相邻面不受影响。
+   */
+  polygonOffset?: { factor: number; units: number };
 }
 
 export interface BuildTileResult {
@@ -256,7 +436,28 @@ export async function buildTileObjects(
   // 材质对象本身很轻（program 由 customProgramCacheKey 复用），一栋一个不心疼。
   const materialList = resolveMaterialList(tile.materials);
 
-  const makeMaterial = (code?: string, hasAtlasRect = false): StyledMaterial => {
+  /**
+   * 材质在文件里的序号。
+   *
+   * 用途：完全重合的两份面（实测 `3D-BIMbuilding-2` 里跨单体共面 48 组，顶点偏移中位数
+   * 1 微米、最大 0.44 mm）深度相等，官方 `depthTest = LESS_OR_EQUAL`，
+   * 结果是**后画的那份赢**。官方的提交顺序就是文件里的材质顺序
+   * （每个 index package 一条 DrawCommand），所以这里把 renderOrder 钉成材质序号，
+   * 让"谁在上"与官方一致，而且不随材质重建而变。
+   *
+   * 不能指望 three 自己的排序：不透明队列按 `program.id → material.id → z` 排，
+   * 而 material.id 是创建顺序，`_rebuildStyledMaterials()` 换质感档位时会重新分配，
+   * 顺序可能整体翻转 —— 同一场景换个画质，重合面的颜色就换了一个。
+   */
+  const materialIndexOf = (code?: string): number =>
+    materialList.findIndex((e) => materialName(unwrapMaterial(e)) === code);
+
+  const makeMaterial = (
+    code?: string,
+    hasAtlasRect = false,
+    hasTexCoordZ = false,
+    vertexAlphaMin = 1
+  ): StyledMaterial => {
     const entry = materialList.find((e) => materialName(unwrapMaterial(e)) === code);
     const m = unwrapMaterial(entry);
     const units = materialUnits(m);
@@ -300,13 +501,19 @@ export async function buildTileObjects(
     }
 
     const diffuse = m?.diffuse ?? { r: 1, g: 1, b: 1, a: 1 };
-    const alphaMode = m?.alphaMode;
     // SuperMap 的内置水面：纹理单元 id 是 `103.water`，块里**根本没有像素**
     // （实测 Waters 的 s3mb 只有 1081 字节，textures = 0，材质 diffuse 还是纯白）。
     // 以前当白色漫反射渲染，整片湖就是一块白板。这里按内置水面材质上色。
     const isWater = [unit0, unit1].some((u) => /\.water$/i.test(String(materialName(u) ?? u?.id ?? '')));
-    const transparent =
-      alphaMode === 'AM_BLEND' || (diffuse.a ?? 1) < 0.999 || m?.transparentsorting === true || (isWater && !map);
+    // 官方 isTransparent = (alphaMode === MASK || BLEND)，MASK 我们交给 alphaTest；
+    // 另外顶点色 alpha < 1 也必须走混合（SMID 4421 就是这种）。见 render/materialAlpha.ts
+    const transparent = isTransparentMaterial({
+      alphaMode: m?.alphaMode,
+      diffuseAlpha: diffuse.a ?? 1,
+      transparentSorting: m?.transparentsorting === true,
+      vertexAlphaMin,
+      isWaterWithoutMap: isWater && !map,
+    });
 
     // S3M 的 shininess 是旧式 0~128 高光指数，粗略映射到粗糙度
     const roughness =
@@ -330,14 +537,27 @@ export async function buildTileObjects(
       roughness: isWater && !map ? 0.12 : roughness,
       alphaTest,
       atlas: hasAtlasRect && !!map,
+      // uv 第三分量（custom0）：几何带了这条流，材质才走官方的「按 z 决定采样」分支
+      texCoordZ: hasTexCoordZ && !!map,
       secMap,
     });
+    // 用户配置的深度偏移（共面摩尔纹 / 重合面归属的人工定序，见 BuildTileOptions 注释）
+    if (options.polygonOffset) {
+      mat.polygonOffset = true;
+      mat.polygonOffsetFactor = options.polygonOffset.factor;
+      mat.polygonOffsetUnits = options.polygonOffset.units;
+    }
     return mat;
   };
 
   // 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;
@@ -368,7 +588,12 @@ export async function buildTileObjects(
     const geometry = packPrimitive(prim);
     const geoRef = tile.geoPackage[prim.geoNames[0]] ?? null;
     const vp = geoRef?.vertexPackage;
-    const material = makeMaterial(prim.passNames[0], !!prim.attributes.aAtlasRect);
+    const material = makeMaterial(
+      prim.passNames[0],
+      !!prim.attributes.aAtlasRect,
+      !!prim.attributes.aTexCoordZ,
+      minVertexAlpha(prim.attributes.aColor)
+    );
     const matrix =
       prim.matrix && prim.matrix.length === 16 ? new THREE.Matrix4().fromArray(prim.matrix) : null;
 
@@ -376,7 +601,7 @@ export async function buildTileObjects(
     if (isLinePrimitive(prim.primitiveType)) {
       const lines = new THREE.LineSegments(geometry, edgeLineMaterial);
       lines.visible = options.edges === true;
-      lines.renderOrder = 2;
+      lines.renderOrder = EDGE_LINES_RENDER_ORDER;
       lines.raycast = () => {};
       lines.userData.isEdgeLines = true;
       lines.userData.skeletonName = prim.skeletonName;
@@ -391,6 +616,37 @@ export async function buildTileObjects(
 
     // 点云包：顶点即点，按 THREE.Points 渲染。索引只是点序号，直接走 drawRange。
     if (isPointPrimitive(prim.primitiveType)) {
+      // 高斯泼溅：带 gsScale / gsRotation 的点云包不画点，画各向异性的高斯片。
+      // 这两条流的量化格式见 core/GaussianSplat.ts 的头部（从官方 worker 读出来的）。
+      const splat = vp ? buildSplatGeometry(prim, vp) : null;
+      if (splat) {
+        // 用 InstancedMesh 而不是裸 Mesh：它会正确设置 instanceCount 与
+        // `_maxInstanceCount`，后者缺失时 three 会算出 NaN 个实例、一个像素都不画。
+        // instanceMatrix 我们不用（位置全在 iCenter 里），但**不能**把 raycast 关掉：
+        // 拾取结果的精确命中点要靠它，关掉就只能退回原点那个 2×2 方块的包围盒。
+        const mesh = new THREE.InstancedMesh(splat.geo, getSplatMaterial(), splat.geo.instanceCount);
+        mesh.raycast = splatRaycast;
+        mesh.frustumCulled = false;
+        mesh.renderOrder = POINT_SPLAT_RENDER_ORDER;
+        // LOD 判据要用「这块瓦片的高斯有多大」，见 core/SplatLod.ts。
+        // 多骨架取最大值：宁可判得更细，也别停在稀的粗层。
+        if (splat.sigma > 0) stats.splatSigma = Math.max(stats.splatSigma ?? 0, splat.sigma);
+        stats.splatCount = (stats.splatCount ?? 0) + splat.geo.instanceCount;
+        // 与点云同样打标记：卸载 / 拾取 / 样式链路靠它放行
+        mesh.userData.isPointCloud = true;
+        mesh.userData.isGaussianSplat = true;
+        mesh.userData.skeletonName = prim.skeletonName;
+        mesh.userData.geoRef = geoRef;
+        mesh.userData.tileRef = tile;
+        mesh.userData.primitiveType = prim.primitiveType;
+        if (matrix && !matrix.equals(IDENTITY)) {
+          matrix.decompose(mesh.position, mesh.quaternion, mesh.scale);
+        }
+        group.add(mesh);
+        objects.push(mesh);
+        stats.meshes++;
+        continue;
+      }
       // PointsMaterial 的顶点色读内置 'color' 槽位，与 aColor 共享同一份 buffer
       if (!geometry.getAttribute('color')) {
         geometry.setAttribute('color', geometry.getAttribute('aColor')!);
@@ -480,6 +736,14 @@ export async function buildTileObjects(
     object.userData.geoRef = geoRef;
     object.userData.tileRef = tile;
     object.userData.primitiveType = prim.primitiveType;
+    // 绘制顺序 = 文件材质顺序（见 materialIndexOf 的说明）。只在拿到了序号时钉，
+    // 拿不到就保持 three 的默认 0，不影响其他数据。
+    // 透明材质例外：共面定序解决的是「不透明面深度相等谁赢」，而透明物体的正确
+    // 顺序是「远 → 近」，钉成材质序号反而会把近处玻璃画在远处之前。
+    const matIdx = materialIndexOf(prim.passNames[0]);
+    if (matIdx >= 0 && !material.transparent) {
+      object.renderOrder = Math.min(matIdx, MAX_MATERIAL_RENDER_ORDER);
+    }
     if (prim.batchedFrom != null && prim.batchedFrom > 1) {
       object.userData.isBatched = true;
       object.userData.batchedCount = prim.batchedFrom;

package/src/render/Picker.ts

@@ -15,6 +15,7 @@
  * 的代价（移动端尤其明显）就没了。
  */
 import * as THREE from 'three';
+import { createSplatPickMaterial } from './SplatMaterial.js';
 
 const PICK_VERT = /* glsl */ `
   attribute float aBatchId;
@@ -175,6 +176,8 @@ export interface PickHit {
 interface PickUserData {
   pickId?: number;
   pickMaterial?: THREE.Material;
+  /** 高斯泼溅实例网格：拾取要走专用材质，见 SplatMaterial.createSplatPickMaterial */
+  isGaussianSplat?: boolean;
   [key: string]: unknown;
 }
 
@@ -299,13 +302,26 @@ export class Picker {
       if (!mesh.isMesh && !isPointsObject(mesh)) return;
       const ud = mesh.userData as PickUserData;
       if (ud.pickId === undefined) return;
-      if (!ud.pickMaterial) ud.pickMaterial = createPickMaterial(ud.pickId);
-      if ((mesh as THREE.InstancedMesh).isInstancedMesh) instancedPickIds.add(ud.pickId);
-
-      // 把当前的「单体状态纹理」抄给拾取材质：抬高 / 平移 / 姿态 / GPU 路径都是逐单体
-      // 写在里面的，抄的是同一个纹理与同一批 uniform 对象，主材质那边更新后这里自动跟着变。
+      // 泼溅走自己的拾取材质：通用拾取着色器只读 position，不知道 iCenter，
+      // 交给它每个高斯都会塌在原点，点哪儿都没反应。见 SplatMaterial 里那段注释。
+      const isSplat = ud.isGaussianSplat === true;
+      if (!ud.pickMaterial) {
+        ud.pickMaterial = isSplat ? createSplatPickMaterial(ud.pickId) : createPickMaterial(ud.pickId);
+      }
+      // 泼溅**不登记为实例化单体**：它的实例号在 geoRef.pickInfo 里查不到（没有
+      // instanceMatrix 那套单体表），报成 instanceIndex 只会让上层 `_instanceFeature`
+      // 返回 null 把结果丢掉。泼溅整块瓦片当一个单体，命中点交给 splatRaycast。
+      if (!isSplat && (mesh as THREE.InstancedMesh).isInstancedMesh) instancedPickIds.add(ud.pickId);
       const prev = mesh.material;
       const pm = ud.pickMaterial as THREE.ShaderMaterial;
+      // 泼溅没有单体状态纹理 / GPU 路径那一套 uniform，直接跳过抄写
+      if (isSplat) {
+        swapped.push([mesh, prev]);
+        mesh.material = pm;
+        return;
+      }
+      // 把当前的「单体状态纹理」抄给拾取材质：抬高 / 平移 / 姿态 / GPU 路径都是逐单体
+      // 写在里面的，抄的是同一个纹理与同一批 uniform 对象，主材质那边更新后这里自动跟着变。
       const src = (Array.isArray(prev) ? prev[0] : prev) as THREE.Material & {
         userData?: Record<string, THREE.IUniform>;
         uniforms?: Record<string, THREE.IUniform>;