s3m-three 0.4.25 → 0.4.26

package/src/core/S3MBParser.ts

@@ -12,6 +12,7 @@
 import { BinaryReader } from './BinaryReader.js';
 import { parseDracoGeometry } from './Draco.js';
 import { parseMeshOptGeometry } from './MeshOpt.js';
+import { applyCustomAttributeSemantics } from './CustomAttributes.js';
 import { isS3M1Buffer, parseS3M1 } from './S3M1Parser.js';
 import type { DegradationKind } from './degradations.js';
 import type {
@@ -53,6 +54,8 @@ export interface ParseOptions {
   inflate?: InflateFn;
   /** 逐段追踪偏移，调试解析用 */
   trace?: (section: string, detail?: unknown, offset?: number) => void;
+  /** config.json 声明的顶点属性描述清单（用于语义重映射与维度判定） */
+  vertexAttributeDescript?: unknown;
 }
 
 /** 默认解压：zlib（文件头 78 9C / 78 DA）。浏览器与 Node 18+ 均可用。 */
@@ -73,9 +76,8 @@ function pushAttr(
   offset = 0,
   divisor?: number,
   dtype: AttrDType = 'f32'
-): void {
-  vp.attrLocation[semantic] = vp.vertexAttributes.length;
-  vp.vertexAttributes.push({
+): VertexAttribute {
+  const attr: VertexAttribute = {
     semantic,
     data,
     components,
@@ -83,7 +85,10 @@ function pushAttr(
     offsetInBytes: offset,
     divisor,
     dtype,
-  });
+  };
+  vp.attrLocation[semantic] = vp.vertexAttributes.length;
+  vp.vertexAttributes.push(attr);
+  return attr;
 }
 
 function newVertexPackage(): VertexPackage {
@@ -248,15 +253,19 @@ function parseInstanceInfo(r: BinaryReader, vp: VertexPackage, version: number):
   }
 }
 
-function parseVertexAttrExtension(r: BinaryReader, vp: VertexPackage): void {
+export { applyCustomAttributeSemantics } from './CustomAttributes.js';
+
+function parseVertexAttrExtension(r: BinaryReader, vp: VertexPackage): VertexAttribute[] {
   const n = r.u32();
+  const attrs: VertexAttribute[] = [];
   for (let i = 0; i < n; i++) {
     const count = r.u32();
     const dim = r.u16();
     const type = r.u16();
     const size = AttrTypeSize[type] ?? 4;
-    pushAttr(vp, `custom${i}`, r.bytes(count * dim * size), dim, dim * size);
+    attrs.push(pushAttr(vp, `custom${i}`, r.bytes(count * dim * size), dim, dim * size));
   }
+  return attrs;
 }
 
 function parseTangent(r: BinaryReader): void {
@@ -267,7 +276,7 @@ function parseTangent(r: BinaryReader): void {
   r.skip(n * dim * 4);
 }
 
-function parseStandardSkeleton(r: BinaryReader, vp: VertexPackage, version: number): void {
+function parseStandardSkeleton(r: BinaryReader, vp: VertexPackage, version: number, options?: ParseOptions): void {
   if (version >= 3) r.u32(); // streamSize
 
   parseVertex(r, vp);
@@ -278,9 +287,17 @@ function parseStandardSkeleton(r: BinaryReader, vp: VertexPackage, version: numb
   parseInstanceInfo(r, vp, version);
 
   if (version >= 3) {
-    parseVertexAttrExtension(r, vp);
+    const extAttrs = parseVertexAttrExtension(r, vp);
     const descript = r.string();
-    vp.customVertexAttribute = descript ? JSON.parse(descript) : undefined;
+    try {
+      vp.customVertexAttribute = descript ? JSON.parse(descript) : undefined;
+    } catch {
+      vp.customVertexAttribute = descript;
+    }
+    if (!vp.customVertexAttribute && options?.vertexAttributeDescript) {
+      vp.customVertexAttribute = options.vertexAttributeDescript;
+    }
+    applyCustomAttributeSemantics(vp, extAttrs, options?.vertexAttributeDescript);
     r.align4();
     parseTangent(r);
   }
@@ -386,7 +403,8 @@ function isFiniteBox(box: { center: Vec3; xExtent: Vec3; yExtent: Vec3; zExtent:
 export async function parseSkeletonEntries(
   r: BinaryReader,
   version: number,
-  trace?: ParseOptions['trace']
+  trace?: ParseOptions['trace'],
+  options?: ParseOptions
 ): Promise<Record<string, GeoPackageEntry>> {
   const count = r.u32();
   const geoPackage: Record<string, GeoPackageEntry> = {};
@@ -419,7 +437,7 @@ export async function parseSkeletonEntries(
     let indexPackages: IndexPackage[] = [];
 
     if (tag === VertexTag.STANDARD) {
-      parseStandardSkeleton(r, vp, version);
+      parseStandardSkeleton(r, vp, version, options);
       indexPackages = parseIndexPackages(r, version);
     } else if (tag === VertexTag.COMPRESSED) {
       if (version >= 3) {
@@ -462,10 +480,11 @@ export async function parseSkeletonEntries(
 export async function parseSkeletons(
   r: BinaryReader,
   version: number,
-  trace?: ParseOptions['trace']
+  trace?: ParseOptions['trace'],
+  options?: ParseOptions
 ): Promise<Record<string, GeoPackageEntry>> {
   r.u32(); // streamSize
-  const geoPackage = await parseSkeletonEntries(r, version, trace);
+  const geoPackage = await parseSkeletonEntries(r, version, trace, options);
 
   // v1/v2 在骨架数组之后还有一段附加流。官方写法是
   //   bytesOffset += secColorSize; bytesOffset += 4;
@@ -649,7 +668,7 @@ export async function parseS3MB(arrayBuffer: ArrayBuffer, options: ParseOptions
   trace?.('fileOptions', fileOptions, t.offset);
   const groupNode = parseGroupNode(t, version);
   trace?.('groupNode', groupNode.pageLods.length, t.offset);
-  const geoPackage = await parseSkeletons(t, version, trace);
+  const geoPackage = await parseSkeletons(t, version, trace, options);
   trace?.('skeletons', Object.keys(geoPackage).length, t.offset);
   const textures = parseTextures(t);
   trace?.('textures', Object.keys(textures).length, t.offset);

package/src/core/TileGeometry.ts

@@ -20,6 +20,7 @@ import type {
   ParsedTile,
   VertexAttribute,
 } from './types.js';
+import { applyCustomAttributeSemantics } from './CustomAttributes.js';
 
 /**
  * S3M 规范里 `DrawPrimitiveType` 的两个特殊值（原住 GeometryBuilder，随组装层
@@ -297,6 +298,7 @@ export interface AssembleOptions {
    * `useWorker: false` 或 Worker 崩溃降级时它落在主线程上。
    */
   dedupeCoincident?: boolean;
+  vertexAttributeDescript?: unknown;
 }
 
 /* ------------------------------------------------------------------ 合批合并 */
@@ -556,8 +558,15 @@ interface SkeletonAsm {
 }
 
 /** 每骨架只解一次交错流（同一骨架被多个 pack / geode 引用时共享同一份数据） */
-function assembleSkeleton(name: string, geo: GeoPackageEntry, tile: ParsedTile, skipped: string[]): SkeletonAsm | null {
+function assembleSkeleton(
+  name: string,
+  geo: GeoPackageEntry,
+  tile: ParsedTile,
+  skipped: string[],
+  options?: AssembleOptions
+): SkeletonAsm | null {
   const vp = geo.vertexPackage;
+  applyCustomAttributeSemantics(vp, undefined, (tile as any).vertexAttributeDescript ?? options?.vertexAttributeDescript);
   const positionAttr = vp.vertexAttributes.find((a) => a.semantic === 'position');
   if (!positionAttr) {
     skipped.push(`${name} 无 position`);
@@ -585,11 +594,29 @@ function assembleSkeleton(name: string, geo: GeoPackageEntry, tile: ParsedTile,
     else if (attr.semantic === 'normal') normalData = deinterleave(attr);
     else if (attr.semantic === 'uv') uvData = deinterleave(attr);
     else if (attr.semantic === 'uv2') uv1Data = deinterleave(attr);
-    // custom0 = uv 的第三分量，官方 aTextureCoordMatrix：决定「这张贴图用不用、
-    // 用图集的哪个子区域、按 2 的几次幂缩放」。BIM/OSGB 转出来的数据依赖它，
-    // 丢掉就会把本该纯色的墙面贴上整张材质图。语义见 core/TexCoordZ.ts。
-    else if (attr.semantic === 'custom0' && (attr.components ?? 1) >= 1) {
-      texCoordZData = deinterleave(attr);
+    // uv 第三分量（官方 aTextureCoordMatrix）：决定「这张贴图用不用、
+    // 用图集的哪个子区域、按 2 的几次幂缩放」。语义见 core/TexCoordZ.ts。
+    // 注意：按语义查槽（找 TextureCoordMatrix），不要固定取 custom0；
+    // 绝对不能把 VertexWeight（高度值）等其它语义属性当成贴图矩阵；
+    // 若全为哨兵（-99999）则视为无第三分量，跳过采样/图集选择逻辑。
+    else if (
+      (attr.semantic === 'TextureCoordMatrix' ||
+        attr.semantic === 'aTextureCoordMatrix' ||
+        (attr.semantic === 'custom0' && !vp.vertexAttributes.some((a) => a.semantic === 'TextureCoordMatrix' || a.semantic === 'VertexWeight'))) &&
+      (attr.components ?? 1) >= 1
+    ) {
+      const plain = deinterleave(attr);
+      const arr = plain.array as Float32Array;
+      let hasValid = false;
+      for (let i = 0; i < arr.length; i++) {
+        if (arr[i]! >= -99900) {
+          hasValid = true;
+          break;
+        }
+      }
+      if (hasValid) {
+        texCoordZData = plain;
+      }
     }
   }
 
@@ -752,7 +779,7 @@ export function assembleTileGeometry(tile: ParsedTile, options: AssembleOptions
 
   const skeletons = new Map<string, SkeletonAsm>();
   for (const [name, geo] of Object.entries(tile.geoPackage ?? {})) {
-    const asm = assembleSkeleton(name, geo, tile, skipped);
+    const asm = assembleSkeleton(name, geo, tile, skipped, options);
     if (asm) {
       skeletons.set(name, asm);
       stats.vertices += geo.vertexPackage.verticesCount || 0;

package/src/core/types.ts

@@ -201,6 +201,7 @@ export interface ParsedTile {
   materials: unknown;
   pickInfo: unknown;
   extensions?: unknown;
+  vertexAttributeDescript?: unknown;
   /**
    * 解析成功、但渲染能力不完整的项（机器可读）。
    *

package/src/index.ts

@@ -60,8 +60,8 @@ export {
 export type { GeoAdapter } from './render/GeoAdapter.js';
 
 // —— 瓦片层
-export { S3MTileset } from './tileset/S3MTileset.js';
-export type { TileNode, BuildTileFn, S3MTilesetOptions } from './tileset/S3MTileset.js';
+export { S3MTileset, parseConfigText, classifyDatasetKind } from './tileset/S3MTileset.js';
+export type { TileNode, BuildTileFn, S3MTilesetOptions, DatasetKind } from './tileset/S3MTileset.js';
 
 // —— 渲染层
 export { S3MViewer } from './render/S3MViewer.js';
@@ -138,6 +138,8 @@ export { setMaterialQuality, getMaterialQuality } from './render/StyleMaterial.j
 
 export { Picker } from './render/Picker.js';
 export { GpuEdgePass } from './render/GpuEdgePass.js';
+export { MotionBlurPass, normalizeMotionBlur, autoMotionBlurDamp } from './render/MotionBlurPass.js';
+export type { MotionBlurOptions, MotionBlurConfig, MotionBlurParams } from './render/MotionBlurPass.js';
 
 /* 三维空间分析内核：纯数学，不依赖 WebGL，可单独用于服务端 / Worker */
 export * from './analysis/index.js';

package/src/render/GeometryBuilder.ts

@@ -619,8 +619,8 @@ export async function buildTileObjects(
     const matrix =
       prim.matrix && prim.matrix.length === 16 ? new THREE.Matrix4().fromArray(prim.matrix) : null;
 
-    // 棱线包：线段，不是三角面。默认隐藏，等 setEdges(true) 再显示
-    if (isLinePrimitive(prim.primitiveType)) {
+    // 棱线包（13）：线段，不是三角面。默认隐藏，等 setEdges(true) 再显示
+    if (prim.primitiveType === LINE_PRIMITIVE) {
       const lines = new THREE.LineSegments(geometry, edgeLineMaterial);
       lines.visible = options.edges === true;
       lines.renderOrder = EDGE_LINES_RENDER_ORDER;
@@ -636,6 +636,41 @@ export async function buildTileObjects(
       continue;
     }
 
+    // 实体线段 / 折线几何（2=线段，3=折线，如 3D-pipe 管线）：实体几何，默认可见并取材质色
+    if (prim.primitiveType === 2 || prim.primitiveType === 3) {
+      const entry = materialList.find((e) => materialName(unwrapMaterial(e)) === prim.passNames[0]);
+      const m = unwrapMaterial(entry);
+      const diff = m?.diffuse;
+      const lineColor = diff
+        ? new THREE.Color(diff.r ?? 1, diff.g ?? 1, diff.b ?? 1)
+        : new THREE.Color(0xffffff);
+      const hasVertColor = !!geometry.getAttribute('aColor') || !!geometry.getAttribute('color');
+      if (hasVertColor && !geometry.getAttribute('color')) {
+        geometry.setAttribute('color', geometry.getAttribute('aColor')!);
+      }
+      const lineMaterial = new THREE.LineBasicMaterial({
+        color: lineColor,
+        vertexColors: hasVertColor,
+        transparent: diff?.a !== undefined && diff.a < 1,
+        opacity: diff?.a ?? 1,
+      });
+      const lines = prim.primitiveType === 3
+        ? new THREE.Line(geometry, lineMaterial)
+        : new THREE.LineSegments(geometry, lineMaterial);
+      lines.visible = true;
+      lines.userData.skeletonName = prim.skeletonName;
+      lines.userData.geoRef = geoRef;
+      lines.userData.tileRef = tile;
+      lines.userData.primitiveType = prim.primitiveType;
+      if (matrix && !matrix.equals(IDENTITY)) {
+        matrix.decompose(lines.position, lines.quaternion, lines.scale);
+      }
+      group.add(lines);
+      objects.push(lines);
+      stats.meshes++;
+      continue;
+    }
+
     // 点云包：顶点即点，按 THREE.Points 渲染。索引只是点序号，直接走 drawRange。
     if (isPointPrimitive(prim.primitiveType)) {
       // 高斯泼溅：带 gsScale / gsRotation 的点云包不画点，画各向异性的高斯片。