s3m-three 0.4.19 → 0.4.21

package/src/render/viewer/SelectionDecorator.ts

@@ -0,0 +1,377 @@
+/**
+ * 选中态：高亮写入、轮廓 / 棱线装饰、跨瓦片重放。
+ *
+ * 从 `S3MViewer` 搬出来的第三块。它持有 `selection` 与 `selectedMeshes` 两份状态，
+ * 其余（uniform、样式、轮廓材质、逐网格棱线材质）都从宿主取。
+ *
+ * ## 为什么需要「重放」
+ *
+ * 选中高亮是直接写在各 mesh 材质的 `uSelBatch` / `uSelWhole` 上的，而 LOD 细化、
+ * 瓦片重载、淘汰回补都会换掉 mesh —— 不重放的话，用户点中的那栋楼一细化就失去高亮
+ * （状态还在 `selection.smid` 里，只是没人往新 mesh 上刷）。
+ *
+ * ## 没有单体化信息时的退路
+ *
+ * 倾斜摄影 / 白模整块没有 smid，`uSelBatch` 给 -1 会让「点中了但什么都没亮」。
+ * 这时改置 `uSelWhole = 1` 整块高亮，至少让用户看见自己点到了什么。
+ */
+import * as THREE from 'three';
+import type { OutlineMaterial, S3MStyle, StyledMaterial } from '../StyleMaterial.js';
+import type { ThickLineMaterial } from '../EdgeLines.js';
+import type { FeatureStyleManager } from '../FeatureStyleManager.js';
+import type { GeoPackageEntry, StyleUniforms, PickSegment } from '../../core/types.js';
+import { pickEntryId, resolveFeature } from '../../core/FeatureInfo.js';
+import { buildFeatureEdgeSegments, buildThickLineGeometry } from '../EdgeLines.js';
+import type { PickResult } from '../S3MViewer.js';
+
+/** 取网格上的 styled 材质（与 S3MViewer 里那份逐字一致） */
+function styledMaterialOf(mesh: THREE.Mesh): StyledMaterial | null {
+  const m = Array.isArray(mesh.material) ? mesh.material[0] : mesh.material;
+  return (m as StyledMaterial | undefined)?.userData?.isStyled ? (m as StyledMaterial) : null;
+}
+
+function clampOpacity(v: number | null | undefined): number {
+  const n = v ?? 1;
+  return n < 0 ? 0 : n > 1 ? 1 : n;
+}
+
+function isPointCloud(o: THREE.Object3D): boolean {
+  return (o as THREE.Points).isPoints === true;
+}
+
+interface MeshUserData {
+  datasetId?: string;
+  skeletonName?: string;
+  geoRef?: GeoPackageEntry;
+  [key: string]: unknown;
+}
+
+export interface SelectionHost {
+  readonly uniforms: StyleUniforms;
+  readonly style: S3MStyle;
+  readonly outlineMaterial: OutlineMaterial;
+  /** 选中棱线的全局材质（外观 uniform 的持有者） */
+  readonly selectionEdgeMaterial: ThickLineMaterial;
+  /** 单体样式 / 过滤状态（判断被隐藏的单体不该被高亮） */
+  readonly featureStyleManager: FeatureStyleManager;
+  /** SMID → 包含它的网格 */
+  readonly smidMeshes: Map<number, Set<THREE.Mesh>>;
+  readonly pointClouds: Set<THREE.Points>;
+  applyPointCloudStyle(pc: THREE.Points, selected?: boolean): void;
+  onPick(result: PickResult | null): void;
+  requestRepaint(): void;
+  /** 选中棱线的逐网格材质（由 EdgeDecorator 提供） */
+  createSelectionEdgeMaterial(mesh: THREE.Mesh): ThickLineMaterial;
+}
+
+export class SelectionDecorator {
+  /** 当前选中（null = 没选中） */
+  selection: PickResult | null = null;
+  /** 被高亮的网格（点云也在这份列表里） */
+  selectedMeshes: THREE.Object3D[] = [];
+
+  private _outlineMeshes: THREE.Mesh[] = [];
+  private _selectionEdgeMeshes: THREE.Mesh[] = [];
+
+  constructor(private readonly host: SelectionHost) {}
+
+  /** @internal 测试用：选中棱线的网格列表 */
+  get selectionEdgeMeshes(): THREE.Mesh[] {
+    return this._selectionEdgeMeshes;
+  }
+
+  /** 场景清空 / 卸载时调用：丢掉所有装饰引用，不做逐对象清理 */
+  reset(): void {
+    this.selection = null;
+    this.selectedMeshes = [];
+    this._outlineMeshes = [];
+    this._selectionEdgeMeshes = [];
+  }
+
+  select(result: PickResult | null, { silent = false }: { silent?: boolean } = {}): void {
+    // 清掉上一次
+    if (this.selection) {
+      for (const obj of this.selectedMeshes) {
+        // 点云：恢复成当前着色模式（去掉选中混色）
+        if (isPointCloud(obj)) {
+          this.host.applyPointCloudStyle(obj as unknown as THREE.Points, false);
+          continue;
+        }
+        const mat = styledMaterialOf(obj as THREE.Mesh);
+        if (mat) {
+          mat.userData.uSelBatch.value = -1;
+          mat.userData.uSelWhole.value = 0;
+        }
+      }
+      this.selectedMeshes = [];
+      this.clearDecoration();
+      this.selection = null;
+    }
+
+    if (!result) {
+      this.host.uniforms.uSelMix.value = 0;
+      this.host.uniforms.uDim.value = 0;
+      this.host.outlineMaterial.uniforms.uSelBatch.value = -1;
+      this.host.outlineMaterial.uniforms.uSelWhole.value = 0;
+      this.host.outlineMaterial.uniforms.uElevation.value = 0;
+      this.host.requestRepaint();
+      if (!silent) this.host.onPick(null);
+      return;
+    }
+
+    this.selection = result;
+    const targetMeshes = new Set<THREE.Mesh>();
+    if (result.smid != null) {
+      const smidSet = this.host.smidMeshes.get(result.smid);
+      if (smidSet) {
+        for (const m of smidSet) targetMeshes.add(m);
+      }
+    }
+    targetMeshes.add(result.mesh);
+
+    for (const mesh of targetMeshes) {
+      const mat = styledMaterialOf(mesh);
+      if (!mat) continue;
+      let batchId = result.batchId;
+      if (result.instanceIndex != null && mesh === result.mesh) {
+        batchId = result.batchId;
+      } else if (result.smid != null) {
+        const ud = mesh.userData as MeshUserData;
+        const pickInfo = ud.geoRef?.pickInfo;
+        const entry = (pickInfo as Record<string | number, unknown> | undefined)?.[result.smid] ??
+          (pickInfo as Record<string | number, unknown> | undefined)?.[String(result.smid)];
+        const bId = entry ? pickEntryId(entry as any) : -1;
+        batchId = bId >= 0 ? bId : (mesh === result.mesh ? result.batchId : -1);
+      }
+      mat.userData.uSelBatch.value = batchId;
+      // 没有单体化信息时整块高亮，否则会出现「点中了但什么都没亮、其他全暗了」
+      mat.userData.uSelWhole.value = batchId < 0 ? 1 : 0;
+      this.selectedMeshes.push(mesh);
+    }
+    // 点云没有单体粒度：整块混成 selectColor，让选中至少看得见
+    for (const mesh of this.selectedMeshes) {
+      if (isPointCloud(mesh)) this.host.applyPointCloudStyle(mesh as unknown as THREE.Points, true);
+    }
+    this.host.uniforms.uSelMix.value = 1;
+    this.host.uniforms.uDim.value = this.host.style.dimOthers ? 1 : 0;
+
+    if (this.host.style.outline) {
+      // 棱线 / 外扩轮廓都是按「面」设计的，点云画不出来也不该画
+      const decoMeshes = [...targetMeshes].filter((m) => !isPointCloud(m));
+      if (decoMeshes.length) {
+        if ((this.host.style.outlineStyle ?? 'edges') === 'edges') {
+          this.addSelectionEdges(result, decoMeshes);
+        } else {
+          this.addSelectionHull(result, decoMeshes);
+        }
+      }
+    }
+    this.host.requestRepaint();
+  }
+
+  /**
+   * 选中单体的棱线：只挑这个单体自己的三角面算折边，再画成屏幕空间等宽线。
+   * 抽出来的线段数很少（一栋楼通常几百到几千条），所以选中开销可以忽略。
+   */
+  addSelectionEdges(result: PickResult, meshes: Iterable<THREE.Mesh>): void {
+    this.syncStyle();
+    for (const mesh of meshes) {
+      const ud = mesh.userData as MeshUserData;
+      const geoRef = ud.geoRef;
+      let segments: PickSegment[] = [];
+      // 这块网格上的棱线全部属于选中的那个单体，整批填同一个 batchId，
+      // 顶点着色器才能从状态纹理里取到平移 / 拔高——选中跟随移动靠它。
+      let batchId = -1;
+      if (mesh === result.mesh && result.instanceIndex != null) {
+        // 实例化几何没有逐单体的顶点区间，整个 base mesh 就是这一栋的外形
+        segments = [{ vertexOffset: 0, vertexCount: mesh.geometry.getAttribute('position')?.count ?? 0 }];
+        const pickInfo = geoRef?.pickInfo;
+        const entry = (pickInfo as Record<string | number, unknown> | undefined)?.[result.smid ?? ''] ??
+          (pickInfo as Record<string | number, unknown> | undefined)?.[String(result.smid)];
+        batchId = entry ? pickEntryId(entry as any) : -1;
+      } else if (result.smid != null) {
+        const pickInfo = geoRef?.pickInfo;
+        const entry = (pickInfo as Record<string | number, unknown> | undefined)?.[result.smid] ??
+          (pickInfo as Record<string | number, unknown> | undefined)?.[String(result.smid)];
+        const bId = entry ? pickEntryId(entry as any) : -1;
+        batchId = bId;
+        segments = (entry as any)?.segments ?? (bId >= 0 ? resolveFeature(geoRef, bId).segments : []);
+      } else if (mesh === result.mesh) {
+        const localGeo = (ud.geoByBatchId as Map<number, GeoPackageEntry> | undefined)?.get(result.batchId) ?? geoRef;
+        segments = resolveFeature(localGeo, result.batchId).segments;
+        batchId = result.batchId;
+      }
+
+      const pairs = buildFeatureEdgeSegments(mesh.geometry, segments);
+      if (pairs && pairs.length > 0) {
+        const batchIds = batchId >= 0 ? new Float32Array(pairs.length / 6).fill(batchId) : undefined;
+        const lines = new THREE.Mesh(
+          buildThickLineGeometry(pairs, batchIds),
+          this.host.createSelectionEdgeMaterial(mesh)
+        );
+        lines.renderOrder = 4;
+        // 屏幕空间外扩后可能超出原包围球，关掉剔除更稳
+        lines.frustumCulled = false;
+        lines.raycast = () => {};
+        (lines.userData as MeshUserData).isSelectionEdge = true;
+        if (mesh === result.mesh && result.instanceIndex != null) {
+          this.applyInstanceTransform(lines, result);
+        }
+        mesh.add(lines); // 作为子节点，直接继承世界变换
+        this._selectionEdgeMeshes.push(lines);
+      }
+    }
+
+    if (this._selectionEdgeMeshes.length === 0) {
+      // 抽不出折边（退化几何 / 没有任何夹角）时退回外扩轮廓，至少保证选中可见
+      this.addSelectionHull(result, meshes);
+      return;
+    }
+  }
+
+  /** 实例化几何：把某个实例的矩阵套到一个普通 Mesh/子节点上（子节点不参与父级的 instanceMatrix） */
+  applyInstanceTransform(obj: THREE.Object3D, result: PickResult): void {
+    const im = result.mesh as THREE.InstancedMesh;
+    if (result.instanceIndex == null || !im.isInstancedMesh) return;
+    const m = new THREE.Matrix4();
+    im.getMatrixAt(result.instanceIndex, m);
+    m.decompose(obj.position, obj.quaternion, obj.scale);
+  }
+
+  /** 旧的描边画法：背面外扩法，整块几何一起上，靠 uSelBatch 只显示选中那栋 */
+  addSelectionHull(result: PickResult, meshes: Iterable<THREE.Mesh>): void {
+    const instanced = result.instanceIndex != null;
+    // 实例化：轮廓是这个实例的单独一份副本（普通 Mesh），所以整份都画；
+    // 顶点区间型：整块几何一起画，靠 uSelBatch 只显示选中那栋。
+    this.host.outlineMaterial.uniforms.uSelBatch.value = instanced ? -1 : result.batchId;
+    this.host.outlineMaterial.uniforms.uSelWhole.value = instanced || result.batchId < 0 ? 1 : 0;
+    this.host.outlineMaterial.uniforms.uElevation.value = instanced
+      ? this.selectionElevation(result)
+      : this.host.style.selectElevation ?? 0;
+
+    for (const mesh of meshes) {
+      const mat = styledMaterialOf(mesh);
+      if (mat?.userData?.uBatchTex) {
+        this.host.outlineMaterial.uniforms.uBatchTex.value = mat.userData.uBatchTex.value as THREE.Texture;
+        this.host.outlineMaterial.uniforms.uBatchTexWidth.value = mat.userData.uBatchTexWidth.value as number;
+        this.host.outlineMaterial.uniforms.uBatchTexActive.value = mat.userData.uBatchTexActive.value as number;
+      }
+      const outline = new THREE.Mesh(mesh.geometry, this.host.outlineMaterial);
+      outline.renderOrder = 3;
+      outline.frustumCulled = false;
+      outline.raycast = () => {};
+      if (mesh === result.mesh && result.instanceIndex != null) {
+        this.applyInstanceTransform(outline, result);
+      }
+      mesh.add(outline); // 作为子节点，直接继承世界变换
+      this._outlineMeshes.push(outline);
+    }
+  }
+
+  /** 只改 uniform：颜色 / 粗细 / 拔高，拖着滑块实时生效，不重建几何 */
+  syncStyle(): void {
+    const s = this.host.style;
+    const u = this.host.selectionEdgeMaterial.uniforms;
+    u.uColor.value.set(s.outlineColor ?? s.selectColor);
+    u.uWidth.value = Math.max(0.1, s.outlineWidthPx ?? 3);
+    u.uOpacity.value = clampOpacity(s.opacity);
+    // 只加全局 selectElevation：单体自己的拔高已经写在状态纹理第 2 行 z 里，
+    // 顶点着色器采样时带出来了，这里再加一次就会双重拔高
+    if (u.uElevation) u.uElevation.value = s.selectElevation ?? 0;
+
+    // 外扩描边是另一个材质实例，单体状态纹理的开关是建的时候抄过去的。
+    // 先选中、再抬高（或反过来）时模板会停留在旧值，这里补一次同步。
+    for (const outline of this._outlineMeshes) {
+      const parent = outline.parent as THREE.Mesh | null;
+      const ud = parent ? styledMaterialOf(parent)?.userData : null;
+      if (ud?.uBatchTex) {
+        this.host.outlineMaterial.uniforms.uBatchTex.value = ud.uBatchTex.value;
+        this.host.outlineMaterial.uniforms.uBatchTexWidth.value = ud.uBatchTexWidth.value;
+        this.host.outlineMaterial.uniforms.uBatchTexActive.value = ud.uBatchTexActive.value;
+      }
+    }
+  }
+
+  /** 选中单体的实际拔高 = 全局选中拔高 + 该单体的独立拔高（与着色器口径一致） */
+  selectionElevation(result: PickResult): number {
+    let elev = this.host.style.selectElevation ?? 0;
+    if (result.smid != null) {
+      const off = this.host.featureStyleManager.getFeatureEffectiveOffset(result.smid);
+      if (off.elevation) elev += off.elevation;
+    }
+    return elev;
+  }
+
+  clearDecoration(): void {
+    for (const outline of this._outlineMeshes) {
+      outline.parent?.remove(outline);
+    }
+    this._outlineMeshes = [];
+
+    for (const edges of this._selectionEdgeMeshes) {
+      edges.parent?.remove(edges);
+      edges.geometry.dispose();
+    }
+    this._selectionEdgeMeshes = [];
+  }
+
+  /**
+   * 把「当前选中」重放到一块新登记的 mesh 上。
+   *
+   * 为什么需要：选中高亮是直接写在各 mesh 材质的 uSelBatch / uSelWhole 上的，
+   * 而 LOD 细化、瓦片重载、淘汰回补都会换掉 mesh —— 不重放的话，用户点中的那栋楼
+   * 一细化就失去高亮（状态还在 selection.smid 里，只是没人往新 mesh 上刷）。
+   */
+  /**
+   * 判断一块无 SMID 单体化信息的网格（如倾斜摄影或白模整块）是否空间覆盖当前选中命中点
+   */
+  isMeshCoveringSelection(mesh: THREE.Mesh, sel: PickResult): boolean {
+    if (!sel.point) return false;
+    const geom = mesh.geometry;
+    if (!geom) return false;
+    if (!geom.boundingBox) geom.computeBoundingBox();
+    if (!geom.boundingBox) return false;
+
+    // 将选中的三维场景点转入网格局部坐标系进行包围盒检测
+    const pt = new THREE.Vector3(sel.point[0], sel.point[1], sel.point[2]);
+    mesh.updateWorldMatrix(true, false);
+    const inv = mesh.matrixWorld.clone().invert();
+    const localPt = pt.applyMatrix4(inv);
+
+    // 留出 0.5 米容差，避免刚好处于三角网格边缘缝隙时漏判
+    const box = geom.boundingBox.clone().expandByScalar(0.5);
+    return box.containsPoint(localPt);
+  }
+
+  replayOnto(mesh: THREE.Mesh): void {
+    const sel = this.selection;
+    if (!sel) return;
+    const mat = styledMaterialOf(mesh);
+    if (!mat) return;
+
+    const ud = mesh.userData as MeshUserData;
+    let batchId = -1;
+    if (sel.smid != null) {
+      const pickInfo = ud.geoRef?.pickInfo as Record<string | number, unknown> | undefined;
+      const entry = pickInfo?.[sel.smid] ?? pickInfo?.[String(sel.smid)];
+      batchId = entry ? pickEntryId(entry as any) : -1;
+    }
+    // 拾取命中的那块 mesh 用原始 batchId；同一 smid 散在别的几何里时按各自的区间算
+    if (mesh === sel.mesh) batchId = sel.batchId;
+    // 这块几何里根本没有这个单体 → 不动它（否则会把无关瓦片一起点亮）
+    if (batchId < 0 && mesh !== sel.mesh) {
+      if (sel.smid == null && ud.datasetId === sel.datasetId && this.isMeshCoveringSelection(mesh, sel)) {
+        batchId = -1;
+      } else {
+        return;
+      }
+    }
+
+    mat.userData.uSelBatch.value = batchId;
+    mat.userData.uSelWhole.value = batchId < 0 ? 1 : 0;
+    if (!this.selectedMeshes.includes(mesh)) this.selectedMeshes.push(mesh);
+    if (isPointCloud(mesh)) this.host.applyPointCloudStyle(mesh as unknown as THREE.Points, true);
+    this.host.uniforms.uSelMix.value = 1;
+    this.host.uniforms.uDim.value = this.host.style.dimOthers ? 1 : 0;
+  }
+}

package/src/render/viewer/SplatLayer.ts

@@ -0,0 +1,44 @@
+/**
+ * 泼溅排序的调度：什么时候重排、什么时候整帧跳过。
+ *
+ * 排序算法本身在 `core/SplatSort.ts`，单瓦片的重写在 `render/SplatSorter.ts`。
+ * 这里只管一件事：**相机没动且没有新瓦片时，一帧都不要排**。
+ *
+ * 跳过条件用的是「视图矩阵完全相等」。地图交互时相机每帧都在变，所以这个条件
+ * 实际上只在静止时命中 —— 这是刻意的：移动中必须每帧重排，否则 alpha 混合顺序
+ * 会错，画面是彩色噪点。真正把代价压下去的是排序算法本身（基数排序，见 SplatSort）。
+ */
+import * as THREE from 'three';
+import { sortSplatMesh } from '../SplatSorter.js';
+
+export class SplatLayer {
+  private readonly _lastView = new THREE.Matrix4();
+  private _sorted = false;
+
+  /** 有新瓦片进来 / 瓦片被淘汰：下一帧必须重排 */
+  markDirty(): void {
+    this._sorted = false;
+  }
+
+  /**
+   * 按当前视角重排所有泼溅瓦片。
+   *
+   * @param pointClouds 场景里的点云集合（含非泼溅的，按 `userData.isGaussianSplat` 过滤）
+   */
+  sort(camera: THREE.Camera | null, pointClouds: Iterable<THREE.Points>): void {
+    if (!camera) return;
+    if (this._sorted && this._lastView.equals(camera.matrixWorldInverse)) return;
+    for (const pc of pointClouds) {
+      if (!(pc.userData as { isGaussianSplat?: boolean }).isGaussianSplat) continue;
+      sortSplatMesh(pc as unknown as THREE.Mesh, camera.matrixWorldInverse);
+    }
+    this._lastView.copy(camera.matrixWorldInverse);
+    this._sorted = true;
+  }
+
+  /** 场景清空 / 换相机后重置，避免拿旧矩阵误判「已排过」 */
+  reset(): void {
+    this._sorted = false;
+    this._lastView.identity();
+  }
+}

package/src/render/viewer/types.ts

@@ -0,0 +1,264 @@
+/**
+ * `S3MViewer` 的公共类型：选项、光照、拾取结果、路径跟随。
+ *
+ * 从 `S3MViewer.ts` 整块搬出来的纯类型定义（零运行时）。搬出去的原因只有一个：
+ * 这些类型占了两百多行，和「类怎么实现」没有关系，留在主类里会把真正的逻辑冲淡。
+ *
+ * `S3MViewer.ts` 仍然 re-export 它们，所以 `import { S3MViewerOptions } from '.../S3MViewer'`
+ * 这类既有写法不受影响。
+ */
+import * as THREE from 'three';
+import type { Path } from '../../anim/Path.js';
+import type { EasingFn, EasingName } from '../../anim/easing.js';
+import type { FeatureAttributes, GeoPackageEntry, ParsedTile, Stats } from '../../core/types.js';
+import type { UnsupportedPolicy } from '../../core/degradations.js';
+import type { AttributeQueryOptions } from '../../core/AttributeQuery.js';
+import type { AuthenticateFn } from '../../core/AuthFetch.js';
+import type { LightingPreset } from '../lightingPreset.js';
+import type { S3MStyle } from '../StyleMaterial.js';
+import type { BuildTileFn } from '../../tileset/S3MTileset.js';
+import type { S3MDatasetEntry, S3MDatasetOptions } from '../DatasetManager.js';
+import type { GroundOptions } from '../GroundManager.js';
+
+export interface PickResult extends FeatureAttributes {
+  datasetId: string;
+  datasetName: string;
+  /** 网格编号 */
+  objectId: number;
+  /** 单体控制位（顶点区间型 = batchId，实例化型 = 状态纹理下标），-1 表示没有单体化信息 */
+  batchId: number;
+  /** 实例化几何命中的实例序号；非实例化为 undefined */
+  instanceIndex?: number;
+  skeletonName: string;
+  /** 单体中心经纬度，拿不到时为 null */
+  centerLngLat: [number, number] | null;
+  /** 命中点三维场景坐标 [x, y, z]（米，场景 ENU） */
+  point?: [number, number, number] | null;
+  /** 命中点经纬度 [lng, lat] */
+  lngLat?: [number, number] | null;
+  /** 命中点高程（米） */
+  altitude?: number | null;
+  mesh: THREE.Mesh;
+}
+
+export interface LightOptions {
+  /** 环境光强度，默认 0.4 */
+  ambientIntensity?: number;
+  /** 环境光颜色，十六进制或 CSS 颜色字符串，默认 0xffffff */
+  ambientColor?: number | string;
+  /** 半球光天空强度，默认 0.8 */
+  hemisphereIntensity?: number;
+  /** 半球光天空颜色，默认 0xffffff */
+  hemisphereColor?: number | string;
+  /** 半球光地面颜色，默认 0xb6c0cb */
+  hemisphereGroundColor?: number | string;
+  /** 主平行光强度，默认 1.0 */
+  keyLightIntensity?: number;
+  /** 主平行光强度别名（兼容写法） */
+  mainIntensity?: number;
+  /** 主平行光颜色，默认 0xffffff */
+  keyLightColor?: number | string;
+  /** 主平行光颜色别名（兼容写法） */
+  mainColor?: number | string;
+  /** 补光强度，默认 0.35 */
+  fillLightIntensity?: number;
+  /** 补光颜色，默认 0xffffff */
+  fillLightColor?: number | string;
+  /**
+   * 光照朝向模式：
+   * - 'headlamp': 默认头灯模式（随相机 bearing 旋转，受光面始终面向镜头）
+   * - 'fixed': 固定世界坐标方位角（如太阳光模拟）
+   */
+  mode?: 'headlamp' | 'fixed';
+  /** 方位角（度，0~360），固定模式下以正北为 0 顺时针，头灯模式下为相机相对偏角，默认 150 */
+  azimuth?: number;
+  /** 太阳/光源仰角（度，0~90），默认 50 */
+  altitude?: number;
+}
+
+export interface S3MViewerOptions {
+  /**
+   * 光照预设：
+   * - `'default'`（默认）：现有 PBR 打光，亮部线性总量 ≈ 2.55；
+   * - `'supermap'`：对齐 iClient3D 观感（暗部 0.46 / 亮部 2.44），远处不发灰、饱和度更高。
+   *   只改光源，不动材质与色调映射；`light` 里的显式字段仍然优先生效。
+   */
+  lightingPreset?: LightingPreset;
+  /** 光照参数配置（强度、颜色、朝向模式、太阳方位角/仰角等） */
+  light?: LightOptions;
+  /**
+   * 三角面材质深度偏移（共面摩尔纹 / 重合面归属的人工定序）。
+   * 例：factor -1 / units -2 把配置材质的片元深度略微拉近。
+   * 这是 mesh 粒度开关，见 BuildTileOptions.polygonOffset 的说明。
+   */
+  polygonOffset?: { factor: number; units: number };
+  /**
+   * 色调映射模式（默认 THREE.NoToneMapping，避免 ACESFilmic 压暗中暗部及导致底图与建筑色彩失真；
+   * 可传入 THREE.ACESFilmicToneMapping、THREE.LinearToneMapping、THREE.ReinhardToneMapping 等）
+   */
+  toneMapping?: THREE.ToneMapping;
+  /** 色调映射曝光度，默认 1.0 */
+  toneMappingExposure?: number;
+  /** 全局总驻留瓦片上限（多数据集多图层共享预算），在所有可见数据集之间动态均衡分配，彻底防止爆显存 */
+  totalMaxTiles?: number;
+  /** 单数据集简写 */
+  configUrl?: string;
+  /** 多数据集 */
+  datasets?: S3MDatasetOptions[];
+  style?: Partial<S3MStyle>;
+  /** 3D 物理地表面 / 基坑开挖配置 */
+  ground?: GroundOptions;
+  pickable?: boolean;
+  /** 每个数据集最多驻留瓦片 */
+  maxTiles?: number;
+  /** 每个数据集并发请求数 */
+  maxConcurrent?: number;
+  /**
+   * 图层级默认的降级处置策略（默认 `'warn'`），数据集可用 `unsupported` 单独覆盖。
+   * 见 `S3MTilesetOptions.unsupported`。
+   */
+  unsupported?: UnsupportedPolicy;
+  /** 是否用 Web Worker 解析经典 .s3mb 瓦片（默认开，崩溃自动降级主线程），见 S3MTilesetOptions.useWorker */
+  useWorker?: boolean;
+  /** LOD 切换范围缩放系数（默认 1.0），> 1 更倾向保留粗模，< 1 提前换细模 */
+  lodRangeScale?: number;
+  /**
+   * LOD 判定用屏幕高度时的「设备像素比上限」（默认不限制，行为与旧版一致）。
+   *
+   * LOD 的屏幕空间误差按 `canvasHeight` 物理像素算（与官方 `calcPixFromCam` 同口径），
+   * 于是 3x DPR 的手机上判定高度是 2556 而不是 852，细化层数与瓦片数都会远多于桌面。
+   * 传 2 表示「按 CSS 高度 × 2 截断」，砍掉 3x 屏的超采样余量；传 `Infinity` = 不截断。
+   *
+   * 代价：截断会把每块瓦片的屏幕投影放大同样倍数，几何误差与纹理密度同步变差，
+   * 所以默认不启用，由接入方按设备档位自行决定。运行时可用 `setLodPixelRatioCap()` 调整。
+   */
+  lodPixelRatioCap?: number;
+  /**
+   * 每个数据集驻留三角形总数的软上限（默认不限制）。
+   * 见 `S3MTilesetOptions.maxTriangles`：瓦片数管不住的场景（精模、大面片）用这条刹车。
+   */
+  maxTriangles?: number;
+  /**
+   * 每个数据集驻留显存/内存字节总数的软上限（默认 Infinity = 不限制）。
+   * 包含几何顶点缓冲（精确字节）与纹理显存估计。
+   * 超限时在每帧末尾（make-before-break）主动回收非显示的瓦片及其独占纹理。
+   */
+  maxMemory?: number;
+  /**
+   * 纹理缓存条数上限（默认 128）。一条对应一张已解码的瓦片纹理，
+   * 1024² 的 RGBA 一张约 4MB，128 条就是 512MB 显存 —— 低端设备建议 32~48。
+   * 与 `maxTextureSize` 配合使用：后者降单张尺寸，这条降张数。
+   */
+  maxImageCache?: number;
+  /**
+   * 各向异性过滤上限（默认不封顶，取 GPU 报的最大值，通常 16）。
+   * 移动端封到 4 或 8 肉眼通常无差，采样成本明显下降。只影响**之后创建**的纹理。
+   */
+  anisotropyCap?: number;
+  /**
+   * 纹理长边像素上限（默认不限制）。
+   * 非图集的 RGBA / WebP 纹理会按 2× 盒式滤波逐次减半到上限内；DXT 压缩直传与
+   * 图集（UV 已重映射）不受影响。手机上 1024 与 2048 肉眼几乎无差，显存差 4 倍。
+   */
+  maxTextureSize?: number;
+  /**
+   * 光照模型（默认 `'pbr'`）。
+   *
+   * - `'pbr'`：`MeshStandardMaterial`，GGX + 环境球谐，质感最好也最贵
+   * - `'lambert'`：`MeshLambertMaterial`，只保留漫反射 + 平行光，片元开销约省一半；
+   *   白模 / 纯色 / 按高度着色这类不需要高光的模式肉眼差别很小
+   *
+   * 模块级全局状态：同页多个图层会互相覆盖，后创建的那个决定全局。
+   * 只影响**之后创建**的材质 —— 已加载的瓦片要重新加载才会换。
+   */
+  materialQuality?: 'pbr' | 'lambert';
+  /** 自定义瓦片构建器（测试 / 服务端渲染时注入） */
+  buildTile?: BuildTileFn | null;
+  /**
+   * 可选：业务属性查询配置（iServer 数据服务）。
+   * 配上之后才能用 `colorByField()` 按业务字段着色 —— 属性值不在 S3M 瓦片里，只能去数据服务查。
+   */
+  attributes?: AttributeQueryOptions;
+  /** 宿主请求重画的信号。MapLibre 传 `() => map.triggerRepaint()`；纯 three 宿主传自己的渲染循环 */
+  onRequestRepaint?: () => void;
+  /** 地图朝向（弧度），用于让灯光跟着视角走。不传则灯光方向固定 */
+  getBearing?: () => number;
+  /**
+   * 鉴权适配函数（全局默认，数据集可用自己的 `authenticate` 覆盖）。
+   * 内核主线程发出的全部请求（配置 scp / 瓦片 / 子图集 / 棱线缓存 / 属性查询）
+   * 发出前都过一遍，可改写 URL（加 `?token=`）或附加请求头。
+   * 不传 = 行为与旧版完全一致。见 `AuthenticateFn`。
+   */
+  authenticate?: AuthenticateFn;
+  onStats?: (stats: Stats) => void;
+  onReady?: (entry: S3MDatasetEntry) => void;
+  onPick?: (result: PickResult | null) => void;
+  onError?: (error: unknown) => void;
+  /**
+   * 首次出现瓦片后自动预热另一种 `shading` 变体（默认开）。
+   *
+   * `flat` / `smooth` 是编译期变体，不预热的话第一次 `setStyle({ shading })` 会同步
+   * 编译着色器、卡一帧。预热在首帧之后异步做，期间跳一两帧渲染，肉眼不可见。
+   */
+  prewarmShading?: boolean;
+}
+
+/* ------------------------------------------------------------------ 内部类型 */
+
+export interface PickableRef {
+  datasetId: string;
+  mesh: THREE.Mesh;
+  tile: ParsedTile;
+  skeletonName: string;
+}
+
+export interface MeshUserData {
+  pickId?: number;
+  datasetId?: string;
+  skeletonName?: string;
+  geoRef?: GeoPackageEntry;
+  tileRef?: ParsedTile;
+  primitiveType?: number;
+  /** 点云对象（THREE.Points）：不吃面着色，也没有棱可描 */
+  isPointCloud?: boolean;
+  /** CPU 端现算的棱线对象（等宽线 Mesh） */
+  edges?: THREE.Object3D | null;
+  /** 背面外扩轮廓壳（edges 含 'hull' 时挂上） */
+  edgeHull?: THREE.Mesh | null;
+  /** 数据自带棱线包（此时不再用 EdgesGeometry 现算） */
+  nativeEdges?: boolean;
+  /** 数据本身有没有棱线包（不受 forceCpuEdges 影响，用来运行中切换时重算 nativeEdges） */
+  nativeEdgesRaw?: boolean;
+  /** 数据自带的棱线对象本身 */
+  isEdgeLines?: boolean;
+  /** CPU 现算的等宽棱线（与 isEdgeLines 区分，便于刷新样式） */
+  isThickEdge?: boolean;
+  /** 背面外扩轮廓壳（edges 含 'hull' 时挂上） */
+  isEdgeHull?: boolean;
+  /** 选中单体的棱线对象 */
+  isSelectionEdge?: boolean;
+  /** 该网格正在淡入时占用的动画通道 key，瓦片淘汰时要回收 */
+  tileFadeKey?: string;
+  pickMaterial?: THREE.Material;
+  [key: string]: unknown;
+}
+
+export interface PathFollowOptions {
+  /** 走完全程的时长（毫秒）。不传则按 speed 或默认 2000ms 推算 */
+  duration?: number;
+  /** 线速度（米/秒）。给了 duration 就以 duration 为准 */
+  speed?: number;
+  /** 是否循环 */
+  loop?: boolean;
+  /** 是否把折线首尾相连 */
+  closed?: boolean;
+  /** 缓动曲线：作用在**已走距离**上，默认 linear（恒速） */
+  easing?: EasingName | EasingFn;
+  /** 路径整体偏移（米），相当于路径原点 */
+  offset?: [number, number, number];
+  /** 单次走完（非循环）时回调 */
+  onComplete?: () => void;
+}
+
+/* ------------------------------------------------------------------ 图层 */
+