s3m-three 0.4.26 → 0.4.28

package/src/render/tilePlacement.ts

@@ -0,0 +1,121 @@
+/**
+ * 瓦片级放置（issue #12 / #17）。
+ *
+ * ## 问题
+ *
+ * 场景只有一个切平面：`_enuMatrix` 用**场景锚点纬度**的常量 `meterInMercator`
+ * 把整个场景缩放进 Web 墨卡托。但墨卡托的比例 `s(φ) = 1/(2πN·cos φ)` 随纬度变化，
+ * 且 WGS84 椭球下东西向 (N) 与南北向 (M) 曲率半径存在各向异性偏差（赤道 0.67%，中纬度约 0.4%）。
+ * 所以距锚点 `d` 处的真实尺度是 `s(φ₀ + Δφ)`，相对误差随距离累积。
+ *
+ * 数据集**原点**是精确的（`layoutDataset` 用精确墨卡托差除以常量 s，两者互逆），
+ * 错的是数据集**内部**每一个顶点——它们被同一个常量缩放，于是整块模型被整体
+ * 放大/缩小，误差随离锚点的距离线性累积。
+ *
+ * ## 做法
+ *
+ * 每块瓦片用自己的中心经纬度算东西向与南北向尺度，并把它的几何绕自己的中心各向异性缩放：
+ *
+ * ```
+ * A(v) = position + K · (v - pivot)
+ * K = diag(sEast_tile / sEast_scene, sNorth_tile / sNorth_scene, sEast_tile / sEast_scene)
+ * ```
+ *
+ * 其中 `position` 是瓦片中心在**数据集局部 ENU**（即 `entry.root` 坐标系）里的位置，
+ * 用精确墨卡托反解得到；`pivot` 是中心在数据集 ENU 里的坐标（`node.sphere.center`）。
+ *
+ * 渲染时 `_enuMatrix` 依旧作用在整个场景上，于是合成结果是中心精确落位，周边顶点按自己的尺度缩放。
+ */
+import { worldFromLngLat, enuToLngLat, type GeoAdapter } from './GeoAdapter.js';
+
+/** 归一化世界坐标 + 米尺度（`DatasetManager.sceneAnchor` 的形状） */
+export interface SceneAnchorLike {
+  x: number;
+  y: number;
+  z: number;
+  meterInMercatorEast?: number;
+  meterInMercatorNorth?: number;
+  meterInMercatorUp?: number;
+  meterInMercator: number;
+  altitude?: number;
+}
+
+/** 数据集锚点（`Anchor` 的形状：经纬度 + 椭球高） */
+export interface DatasetAnchorLike {
+  lon: number;
+  lat: number;
+  height: number;
+}
+
+export interface TilePlacementInput {
+  /** 瓦片中心在数据集局部 ENU 中的位置（米），即 `node.sphere.center` */
+  center: { x: number; y: number; z: number };
+  /** 数据集锚点 */
+  datasetAnchor: DatasetAnchorLike;
+  /** 场景锚点 */
+  sceneAnchor: SceneAnchorLike;
+  /** 数据集相对场景锚点的偏移（场景 ENU 米），即 `entry.offset` */
+  datasetOffset: readonly [number, number, number];
+  /** 宿主的坐标适配器；`null` = 标准 Web 墨卡托兜底 */
+  geo: GeoAdapter | null;
+}
+
+export interface TilePlacement {
+  /** 变换枢轴，数据集局部 ENU（米） */
+  pivot: readonly [number, number, number];
+  /** 枢轴落到的位置，**数据集局部** ENU（米）——父级 `entry.root` 会再加回 `datasetOffset` */
+  position: readonly [number, number, number];
+  /** 兼容旧代码：等同于 scaleEast */
+  scale: number;
+  /** 东向相对缩放 `sEast_tile / sEast_scene` */
+  scaleEast: number;
+  /** 北向相对缩放 `sNorth_tile / sNorth_scene` */
+  scaleNorth: number;
+  /** 逐瓦片逆尺度 (1 / sTileEast, 1 / sTileNorth, 1 / sTileUp)，供烘焙着色器抵消各向异性缩放 */
+  invTileScale?: readonly [number, number, number];
+}
+
+/**
+ * 算一块瓦片的放置参数。
+ *
+ * 拿不到可用锚点时返回 `null`，调用方应保持瓦片原状（矩阵不动）——这保证
+ * 「数据不完整」时的表现与不开本功能时一致，而不是把瓦片甩到别处去。
+ */
+export function computeTilePlacement(input: TilePlacementInput): TilePlacement | null {
+  const { center, datasetAnchor, sceneAnchor, datasetOffset, geo } = input;
+
+  const sSceneEast = sceneAnchor.meterInMercatorEast ?? sceneAnchor.meterInMercator;
+  const sSceneNorth = sceneAnchor.meterInMercatorNorth ?? sceneAnchor.meterInMercator;
+  if (!Number.isFinite(sSceneEast) || sSceneEast <= 0 || !Number.isFinite(sSceneNorth) || sSceneNorth <= 0) return null;
+  if (!Number.isFinite(center.x) || !Number.isFinite(center.y) || !Number.isFinite(center.z)) return null;
+
+  // 1) 瓦片中心 → 经纬度（高精度 WGS84 椭球反解）
+  const [lng, lat] = enuToLngLat(datasetAnchor.lon, datasetAnchor.lat, center.x, center.y);
+
+  // 2) 中心处的精确墨卡托位置 + 该处的真实尺度
+  const altitude = datasetAnchor.height + center.z;
+  const tMerc = worldFromLngLat(geo, lng, lat, altitude);
+  const sTileEast = tMerc.meterInMercatorEast ?? tMerc.meterInMercator;
+  const sTileNorth = tMerc.meterInMercatorNorth ?? tMerc.meterInMercator;
+  if (!Number.isFinite(sTileEast) || sTileEast <= 0 || !Number.isFinite(sTileNorth) || sTileNorth <= 0) return null;
+
+  // 3) 精确的场景 ENU 位置（与 `_enuMatrix` 互逆），再扣掉父级的偏移
+  const position: [number, number, number] = [
+    (tMerc.x - sceneAnchor.x) / sSceneEast - datasetOffset[0],
+    -(tMerc.y - sceneAnchor.y) / sSceneNorth - datasetOffset[1],
+    (tMerc.z - sceneAnchor.z) / sSceneEast - datasetOffset[2],
+  ];
+
+  const scaleEast = sTileEast / sSceneEast;
+  const scaleNorth = sTileNorth / sSceneNorth;
+  const sTileUp = (tMerc as any).meterInMercatorUp ?? sTileEast;
+
+  return {
+    pivot: [center.x, center.y, center.z],
+    position,
+    scale: scaleEast,
+    scaleEast,
+    scaleNorth,
+    invTileScale: [1.0 / sTileEast, 1.0 / sTileNorth, 1.0 / sTileUp],
+  };
+}

package/src/render/viewer/EdgeDecorator.ts

@@ -98,6 +98,7 @@ export interface EdgeHost {
   renderer: THREE.WebGLRenderer | null;
   camera: THREE.Camera | null;
   readonly authenticate: AuthenticateFn | undefined;
+  resolveDepthMode?(): 'scene' | 'clear';
   requestRepaint(): void;
 }
 
@@ -219,6 +220,8 @@ export class EdgeDecorator {
   /** 一帧的 GPU 描边，必须画在主场景之后（依赖本帧已写好的深度） */
   renderGpuEdges(canvas: HTMLCanvasElement): void {
     if (!this._modes.gpu) return;
+    // clear 深度模式下宿主深度已丢失，GPU 描边会穿透地形，必须跳过
+    if (this.host.resolveDepthMode?.() === 'clear') return;
     const renderer = this.host.renderer;
     const scene = this.host.scene;
     const camera = this.host.camera;

package/src/render/viewer/PickService.ts

@@ -49,11 +49,30 @@ export interface PickHost {
   readonly scene: THREE.Scene | null;
   readonly canvas: HTMLCanvasElement | null;
   readonly style: { floorHeight: number };
-  readonly sceneAnchor: { x: number; y: number; z: number; meterInMercator: number; altitude?: number } | null;
+  readonly sceneAnchor: {
+    x: number;
+    y: number;
+    z: number;
+    meterInMercatorEast?: number;
+    meterInMercatorNorth?: number;
+    meterInMercator: number;
+    altitude?: number;
+  } | null;
   readonly datasets: Map<string, { name: string }>;
   readonly featureStyleManager: FeatureStyleManager;
   readonly smidMeshes: Map<number, Set<THREE.Mesh>>;
   lngLatFromWorld(x: number, y: number): [number, number];
+  /**
+   * 世界坐标 → **规范**场景 ENU（把瓦片级放置的缩放反解掉）。
+   *
+   * `perTilePlacement` 开启时瓦片几何是绕自身中心缩放 `k` 倍后摆到正确位置的，
+   * 命中点的世界坐标因此不再等于「数据本身的 ENU」。拾取要报的是坐标本身，
+   * 不能带渲染相对底图的缩放，否则同一个屋顶在 20 km 外会比 1 km 内偏出几米，
+   * 量算、贴地、外部标注全都跟着错。
+   *
+   * 未开启本功能、或网格不在已放置的瓦片里时**原样返回**（默认路径零副作用）。
+   */
+  toCanonicalScene(p: THREE.Vector3, mesh?: THREE.Object3D | null): THREE.Vector3;
   gpuPathPoseAt(smid: number): { pos: [number, number, number]; yaw: number } | null;
   isFeatureHidden(smid: number | null, batchId: number): boolean;
 }
@@ -219,8 +238,10 @@ export class PickService {
     if (box && this.host.sceneAnchor) {
       const v = new THREE.Vector3((box.minX + box.maxX) / 2, (box.minY + box.maxY) / 2, (box.minZ + box.maxZ) / 2);
       v.applyMatrix4(ref.mesh.matrixWorld);
-      const s = this.host.sceneAnchor.meterInMercator;
-      centerLngLat = this.host.lngLatFromWorld(v.x * s + this.host.sceneAnchor.x, -v.y * s + this.host.sceneAnchor.y);
+      const c = this.host.toCanonicalScene(v, ref.mesh);
+      const sEast = this.host.sceneAnchor.meterInMercatorEast ?? this.host.sceneAnchor.meterInMercator;
+      const sNorth = this.host.sceneAnchor.meterInMercatorNorth ?? this.host.sceneAnchor.meterInMercator;
+      centerLngLat = this.host.lngLatFromWorld(c.x * sEast + this.host.sceneAnchor.x, -c.y * sNorth + this.host.sceneAnchor.y);
     }
 
     // 精确命中点求交计算
@@ -237,7 +258,8 @@ export class PickService {
       const off = smid != null ? this.host.featureStyleManager.getFeatureEffectiveOffset(smid) : {};
       const trans = off.translation;
       const elev = off.elevation;
-      const finalPos = hitPoint.clone();
+      // 先反解瓦片级放置，再叠单体位移 —— 位移是「米」，必须落在规范 ENU 里
+      const finalPos = this.host.toCanonicalScene(hitPoint, ref.mesh).clone();
 
       if (off.rotation) {
         const rotMat = resolveRotationMatrix(off.rotation);
@@ -256,8 +278,9 @@ export class PickService {
       else if (elev) finalPos.z += elev;
 
       point = [finalPos.x, finalPos.y, finalPos.z];
-      const s = this.host.sceneAnchor.meterInMercator;
-      lngLat = this.host.lngLatFromWorld(finalPos.x * s + this.host.sceneAnchor.x, -finalPos.y * s + this.host.sceneAnchor.y);
+      const sEast = this.host.sceneAnchor.meterInMercatorEast ?? this.host.sceneAnchor.meterInMercator;
+      const sNorth = this.host.sceneAnchor.meterInMercatorNorth ?? this.host.sceneAnchor.meterInMercator;
+      lngLat = this.host.lngLatFromWorld(finalPos.x * sEast + this.host.sceneAnchor.x, -finalPos.y * sNorth + this.host.sceneAnchor.y);
       altitude = finalPos.z + (this.host.sceneAnchor.altitude ?? 0);
     } else if (centerLngLat && box && this.host.sceneAnchor) {
       lngLat = centerLngLat;
@@ -321,16 +344,18 @@ export class PickService {
       floorHeight: this.host.style.floorHeight,
     });
 
-    const s = anchor.meterInMercator;
+    const sEast = anchor.meterInMercatorEast ?? anchor.meterInMercator;
+    const sNorth = anchor.meterInMercatorNorth ?? anchor.meterInMercator;
     let point: [number, number, number] | null = null;
     let lngLat: [number, number] | null = null;
     let altitude: number | null = null;
     let centerLngLat: [number, number] | null = null;
 
     if (hitPoint) {
-      point = [hitPoint.x, hitPoint.y, hitPoint.z];
-      lngLat = this.host.lngLatFromWorld(hitPoint.x * s + anchor.x, -hitPoint.y * s + anchor.y);
-      altitude = hitPoint.z + (anchor.altitude ?? 0);
+      const c = this.host.toCanonicalScene(hitPoint, mesh);
+      point = [c.x, c.y, c.z];
+      lngLat = this.host.lngLatFromWorld(c.x * sEast + anchor.x, -c.y * sNorth + anchor.y);
+      altitude = c.z + (anchor.altitude ?? 0);
       // 泼溅命中的就是一个高斯，没有「单体中心」可言，用命中点当中心
       centerLngLat = lngLat;
     } else if (box) {
@@ -339,8 +364,9 @@ export class PickService {
         (box.minY + box.maxY) / 2,
         (box.minZ + box.maxZ) / 2
       ).applyMatrix4(mesh.matrixWorld);
-      centerLngLat = this.host.lngLatFromWorld(v.x * s + anchor.x, -v.y * s + anchor.y);
-      altitude = v.z + (anchor.altitude ?? 0);
+      const c = this.host.toCanonicalScene(v, mesh);
+      centerLngLat = this.host.lngLatFromWorld(c.x * sEast + anchor.x, -c.y * sNorth + anchor.y);
+      altitude = c.z + (anchor.altitude ?? 0);
     }
 
     return {
@@ -395,8 +421,9 @@ export class PickService {
     const target = new THREE.Vector3();
     const intersect = ray.intersectPlane(groundPlane, target);
     if (intersect) {
-      const s = this.host.sceneAnchor.meterInMercator;
-      const lngLat = this.host.lngLatFromWorld(intersect.x * s + this.host.sceneAnchor.x, -intersect.y * s + this.host.sceneAnchor.y);
+      const sEast = this.host.sceneAnchor.meterInMercatorEast ?? this.host.sceneAnchor.meterInMercator;
+      const sNorth = this.host.sceneAnchor.meterInMercatorNorth ?? this.host.sceneAnchor.meterInMercator;
+      const lngLat = this.host.lngLatFromWorld(intersect.x * sEast + this.host.sceneAnchor.x, -intersect.y * sNorth + this.host.sceneAnchor.y);
       const altitude = intersect.z + (this.host.sceneAnchor.altitude ?? 0);
       return {
         lngLat,
@@ -643,8 +670,9 @@ export class PickService {
           if (gpuPose) c.add(new THREE.Vector3(gpuPose.pos[0], gpuPose.pos[1], gpuPose.pos[2]));
 
           c.applyMatrix4(mesh.matrixWorld);
-          const s = this.host.sceneAnchor.meterInMercator;
-          const [lng, lat] = this.host.lngLatFromWorld(c.x * s + this.host.sceneAnchor.x, -c.y * s + this.host.sceneAnchor.y);
+          const sEast = this.host.sceneAnchor.meterInMercatorEast ?? this.host.sceneAnchor.meterInMercator;
+          const sNorth = this.host.sceneAnchor.meterInMercatorNorth ?? this.host.sceneAnchor.meterInMercator;
+          const [lng, lat] = this.host.lngLatFromWorld(c.x * sEast + this.host.sceneAnchor.x, -c.y * sNorth + this.host.sceneAnchor.y);
           if (lng < minLng) minLng = lng;
           if (lng > maxLng) maxLng = lng;
           if (lat < minLat) minLat = lat;

package/src/render/viewer/types.ts

@@ -77,7 +77,23 @@ export interface LightOptions {
   altitude?: number;
 }
 
+/**
+ * 本层绘制前如何处理宿主已有的深度缓冲。
+ * - `'scene'`  保留（默认）。地形能遮挡本层几何，适用于建筑、管线等离散对象。
+ * - `'clear'`  先清深度再画，本层只与自己做深度测试。适用于贴地地面类数据（倾斜摄影、大范围 DEM 化模型等），消除共面 z-fighting。
+ * - `'auto'`   按数据集类型推断：有 ground 覆盖 / OSGB 倾斜摄影 / 地面类网格 → `'clear'`，否则 `'scene'`。
+ */
+export type DepthMode = 'scene' | 'clear' | 'auto';
+
 export interface S3MViewerOptions {
+  /**
+   * 本层绘制前如何处理宿主已有的深度缓冲。
+   * - `'scene'`  保留（默认）。地形能遮挡本层几何，适用于建筑、管线等离散对象。
+   * - `'clear'`  先清深度再画，本层只与自己做深度测试。适用于贴地地面类数据。
+   * - `'auto'`   按数据集类型推断：有 ground 覆盖 / OSGB 倾斜摄影 / 地面类网格 → `'clear'`，否则 `'scene'`。
+   * 默认 `'scene'`，与改动前行为逐字一致。
+   */
+  depthMode?: DepthMode;
   /**
    * 光照预设：
    * - `'default'`（默认）：现有 PBR 打光，亮部线性总量 ≈ 2.55；
@@ -134,6 +150,34 @@ export interface S3MViewerOptions {
    * 所以默认不启用，由接入方按设备档位自行决定。运行时可用 `setLodPixelRatioCap()` 调整。
    */
   lodPixelRatioCap?: number;
+  /**
+   * 瓦片级放置（默认 `true`）。
+   *
+   * 开启后每块瓦片用自己的中心纬度算 `meterInMercator`，几何绕自身中心缩放，
+   * 修正「全场景共用一个切平面」在大范围下的尺度误差。
+   *
+   * 误差量级（北纬 40°，距场景锚点的距离 → 相对尺度的偏差）：
+   * `5 km → 0.065%`、`20 km → 0.26%（约 26 m）`、`200 km → 2.8%（约 2.8 km）`。
+   * 城市级（几公里）随手开无妨；多数据集相距几十公里、或单个数据集跨 20 km 以上时
+   * 必须开，否则远处的模型会整体偏大/偏小。
+   *
+   * 代价与遗留：
+   * - 每块瓦片的 `Object3D` 走 `matrixAutoUpdate = false`，多一次矩阵乘；
+   * - 场景 ENU 仍是**一个平面**，所以只是把误差按瓦片重新分摊（瓦片跨 2 km 时
+   *   剩余约 0.5 m），彻底消除要逐顶点烘焙墨卡托；
+   * - 拾取 / 量算的 `lngLat ↔ 场景 ENU` 换算仍用场景锚点的常量 s，在本模式下
+   *   保持修复前的误差量级（几何与反解不再自洽，但都不比之前差）。
+   *
+   * 见 `render/tilePlacement.ts` 的文件头。
+   */
+  perTilePlacement?: boolean;
+  /**
+   * 是否对瓦片逐顶点烘焙精确 Web 墨卡托偏移（消除全球大尺度下的视差游动/呼吸效应）。
+   * - undefined（默认）：自动判定。当瓦片集根节点包围球半径 > 25 km 时自动启用，<= 25 km 时保持关闭（逐字节保持原有 ENU 顶点缓冲不变）。
+   * - true：强制开启。
+   * - false：强制关闭。
+   */
+  bakeMercator?: boolean;
   /**
    * 每个数据集驻留三角形总数的软上限（默认不限制）。
    * 见 `S3MTilesetOptions.maxTriangles`：瓦片数管不住的场景（精模、大面片）用这条刹车。
@@ -237,6 +281,13 @@ export interface S3MViewerOptions {
    * 编译着色器、卡一帧。预热在首帧之后异步做，期间跳一两帧渲染，肉眼不可见。
    */
   prewarmShading?: boolean;
+  /**
+   * LOD 细化过渡策略：
+   * - 'binary'（默认）：整节点二值切换
+   * - 'incremental'：增量细化（primary / fallback 双列表 + LEQUAL 深度推移）
+   */
+  lodTransition?: 'binary' | 'incremental';
+  fallbackOffset?: { factor?: number; units?: number };
 }
 
 /* ------------------------------------------------------------------ 内部类型 */