s3m-three 0.4.26 → 0.4.28

package/docs/API.md

@@ -170,7 +170,11 @@ new S3MViewer(options?: S3MViewerOptions)
 | （随 `useWorker`）纹理解码 | `boolean` | `true` | DXT / CRN / WEBP 纹理解码与 `.s3mb` 解析共用同一个 Worker（`core/TextureDecode.ts` 三方共用同一份实现，WEBP 走可 transfer 的 ImageBitmap）；失败自动回主线程，产物逐字节一致 |
 | （随 `useWorker`）几何组装 | `boolean` | `true` | 顶点解交错 / 法线计算 / 同材质合批合并（`core/TileGeometry.ts`）随解析在 Worker 完成，主线程只做 three 对象包装；Worker 不可用时主线程跑同一份实现，产物一致 |
 | （随 `useWorker`）DXT 压缩直传 | 自动 | 自动 | 宿主 GL 同时支持 `WEBGL_compressed_texture_s3tc`(+srgb) 时，dxt1/dxt5（含 CRN 转码产物）不解码直接 `CompressedTexture` 上传，显存与上传带宽降为 1/4~1/8；块长与 4×4 对齐公式不符、flipY 图集、移动端无扩展时自动回退 RGBA 解码 |
+| `perTilePlacement` | `boolean` | `true` | 瓦片级切平面放置与拾取反解（**默认开启**）。每块瓦片用自身中心纬度计算墨卡托比例与反解拾取，消除「全场景共用一个常量切平面」在大范围（距场景锚点 20 km 处 0.26% 误差，约 26 m；200 km 处 2.8 km）下的累积尺度误差与拾取偏移。逆矩阵自动缓存在瓦片 group 上避免拾取性能损耗。可显式传 `false` 回退旧版单一全场景切平面（下游若缓存了旧坐标或与旧数据对齐时使用） |
+| `bakeMercator` | `boolean` | `undefined`（自动） | 全球大尺度下逐顶点烘焙精确 Web 墨卡托偏移（Issue #15）。消除大范围单瓦片内因墨卡托纬度非线性缩放导致的视差游动与呼吸效应。默认 `undefined`：当瓦片集根节点包围球半径 > 25 km 时自动启用；<= 25 km 时保持关闭（顶点 buffer 逐字节与旧版相同）。传 `true` / `false` 强制开关 |
 | `lodRangeScale` | `number` | `1.0` | LOD 切换距离缩放系数，> 1 更倾向保留粗模，< 1 提前细化 |
+| `lodTransition` | `'binary' \| 'incremental'` | `'binary'` | LOD 细化过渡策略。`'binary'`（默认）：整节点二值切换，所有子瓦片全部就绪或失败后整块替换；`'incremental'`：增量细化（primary / fallback 双列表 + LEQUAL 深度推移），子瓦片就绪一个显示一个，未就绪区域由最近父瓦片（fallback）垫底填充，消除整块跳变与慢 child 阻塞，极端角度接缝无缝衔接且不出洞 |
+| `fallbackOffset` | `{ factor?: number; units?: number }` | `{ factor: 1, units: 2 }` | 增量细化模式下 fallback 兜底瓦片的材质深度偏移系数，向远处推移深度配合 gl.LEQUAL 消除共面 z-fighting |
 | `lodPixelRatioCap` | `number` | `Infinity` | LOD 判定屏幕高度的 **DPR 上限**（不截断）。默认按 `canvasHeight` 物理像素算，与官方 `calcPixFromCam` 同口径；3x DPR 手机上由此会多细化、多拉瓦片，传 `2` 即按「CSS 高度 × 2」截断 |
 | `anisotropyCap` | `number` | `Infinity` | 各向异性过滤上限（不封顶 = 取 GPU 最大值，通常 16）。移动端封到 4 / 8 肉眼通常无差，采样成本明显下降。**图层级**：运行时 `setAnisotropyCap()` 会立刻应用到已上传纹理（改采样参数 + 重传，不重解码、不重载瓦片），图集纹理恒为 1 |
 | `maxTextureSize` | `number` | `Infinity` | 纹理长边像素上限（不限制）。非图集的 RGBA / WebP 产物按 2× 盒式滤波减半到上限内；DXT 压缩直传与图集不受影响。**图层级**，但只影响之后解码的纹理（已解码的不重解） |
@@ -178,6 +182,7 @@ new S3MViewer(options?: S3MViewerOptions)
 | `materialQuality` | `'pbr' \| 'lambert'` | `'pbr'` | 光照模型。`lambert` 用 `MeshLambertMaterial` 替换 PBR，去掉 GGX 与环境球谐，片元约省一半；白模 / 纯色 / 按高度着色几乎无差。**图层级**：同页多个图层各用各的，互不覆盖；不传则跟随模块级默认（`setMaterialQuality`）。只影响之后创建的材质 |
 | `colorPipeline` | `'linear' \| 'direct'` | `'linear'` | 颜色管线。`direct` = 官方 iClient3D 的 sRGB 直乘（同时关掉纹理解码），`lightingPreset: 'supermap'` 会选它。**图层级**：同页多图层各用各的；已加载瓦片可运行时 `setColorPipeline(q, { duration })` 走 fade-through 平滑切过去（重建材质 + 重传纹理，不重下瓦片） |
 | `motionBlur` | `{ mode?: 'afterimage' \| 'velocity'; damp?: number \| 'auto'; maxOffset?: number }` | 不传 = 关闭 | 可选的运动模糊后处理（**默认关闭**，不传时渲染路径与旧版逐字一致）。低端 / 移动设备低帧率下，用帧间残影在感知层面填补卡顿与边缘闪烁。`afterimage`（缺省）= 当前帧 + 上一帧全屏混合，几乎零边际 GPU 成本；`velocity` = 按上一帧 ↔ 当前帧相机矩阵逐像素反推屏幕速度、沿速度方向 8 tap 采样（方向感知，只覆盖相机运动）。`damp` 为拖尾长度（仅 afterimage），`'auto'`（缺省）按实时 FPS 收敛（`0.55^(fps/60)` 封顶 0.92），数值钳 [0, 0.98]；`maxOffset` 为拖影上限（仅 velocity），速度向量的最大屏幕偏移按绘图缓冲宽度的百分比计，缺省 `0.05`，数值钳 [0, 1]。运行时 `setMotionBlur(null)` 关闭并释放 RT。仅 WebGL2（WebGL1 静默回退直渲）；已知限制：拖影只在当前帧几何覆盖范围内（合成 quad 依赖本帧深度保住遮挡正确性）；RT 用 HalfFloatType 存线性值（高光不被 clamp，代价是三张全屏纹理显存 ×2） |
+| `depthMode` | `'scene' \| 'clear' \| 'auto'` | `'scene'` | 本层绘制前深度缓冲处理策略。`'scene'`（默认）：保留宿主深度，建筑/管线等离散对象受地形正常遮挡；`'clear'`：先清深度再画，贴地倾斜摄影/开挖地表/大范围 DEM 化模型消除共面 z-fighting；`'auto'`：按 ground 覆盖或数据集类型自动推断 |
 | `buildTile` | `BuildTileFn \| null` | — | 自定义瓦片构建器（测试 / 服务端渲染时注入） |
 | `attributes` | `AttributeQueryOptions` | — | 可选的 iServer 数据服务配置，配了才能用 `colorByField()` 等便利方法；不配就自己取数 + `setFeaturesStyle()`，见[业务字段](#业务字段锚点在库内对应关系在外部) |
 | `onRequestRepaint` | `() => void` | — | 宿主请求重画的信号：纯 three 宿主接自己的渲染循环 |
@@ -208,6 +213,15 @@ prewarmShading(): Promise<void>        // 手动预热另一种 shading 变体
 
 `geo` 是可写的 `GeoAdapter | null`：`null` 用内置的墨卡托兜底（`worldFromLngLat` / `lngLatFromWorld`），地图宿主注入适配器以支持任意 CRS / 自定义投影。
 
+内置兜底使用高精度 **WGS84 椭球模型**（$a=6378137, f=1/298.257223563$）：
+- `worldFromLngLat` 返回带有各向异性尺度的对象：`{ x, y, z, meterInMercatorEast, meterInMercatorNorth, meterInMercatorUp, meterInMercator, altitude }`
+  - 东西向尺度对应卯酉圈半径 $N(\varphi) = a / \sqrt{1 - e^2 \sin^2\varphi}$：$1 / (2\pi N \cos\varphi)$
+  - 南北向尺度对应子午圈半径 $M(\varphi) = a(1 - e^2) / (1 - e^2 \sin^2\varphi)^{3/2}$：$1 / (2\pi M \cos\varphi)$
+  - 竖直向高程尺度 `meterInMercatorUp` 取东向尺度（局部正圆保角）
+  - `meterInMercator` 保留作为向前兼容属性，取值从旧版球面近似 $1/(2\pi R\cos\varphi)$ 升级为真实的 WGS84 椭球东向尺度（属于精度修正，默认生效且更精准）
+  - 彻底消除传统单标量模型在南北/东西方向上 0.4%~0.67% 的各向异性拉伸与米级系统残差。
+- 包导出了高精度大地测量工具：`primeVerticalRadius`, `meridianRadius`, `enuToLngLat`, `lngLatToEnu` 及 `WGS84_A`, `WGS84_E2` 常量。
+
 ### 数据集管理
 
 ```ts
@@ -516,6 +530,8 @@ type ClipOptions =
 ```ts
 setLodRangeScale(scale: number, datasetId?: string): void
 readonly lodRangeScale: number
+readonly lodTransition: 'binary' | 'incremental'
+setLodTransition(mode: 'binary' | 'incremental'): void
 setLodPixelRatioCap(cap: number): void        // Infinity = 不截断（默认）
 readonly lodPixelRatioCap: number
 setMaxTriangles(n: number, datasetId?: string): void   // Infinity = 不限制（默认）
@@ -527,6 +543,8 @@ readonly anisotropyCap: number
 setMaxTextureSize(n: number): void            // Infinity = 不限制（默认）
 readonly maxTextureSize: number
 readonly maxImageCache: number
+setDepthMode(mode: DepthMode): void            // 运行时调整深度处理策略（'scene' | 'clear' | 'auto'）
+readonly depthMode: DepthMode                  // 当前深度策略
 setMotionBlur(cfg: MotionBlurOptions | null): void  // 运行时开关运动模糊；null = 关闭并释放 RT 显存
 readonly motionBlur: MotionBlurOptions | null       // 当前配置（归一化后的副本）
 readonly stats: Stats

package/package.json

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

package/src/core/BakeMercator.ts

@@ -0,0 +1,96 @@
+/**
+ * 全球大尺度精确 Web 墨卡托烘焙（issue #15）。
+ *
+ * ## 背景与原理
+ *
+ * S3M 场景通常只有一个切平面：`_enuMatrix` 用场景锚点纬度的常量 `meterInMercator`
+ * 把整个场景缩放进 Web 墨卡托。但在跨度超过几十公里的全球或大区域场景中，
+ * 墨卡托投影比例随纬度变化（k = 1 / cos(φ)）。
+ * 即使有 `perTilePlacement`（issue #12）按瓦片重置了原点与缩放，瓦片内部仍然存在
+ * 线性切平面与真实墨卡托投影之间的微小残差。
+ *
+ * 烘焙方案：
+ * 1. 预先或在组装瓦片几何时，逐顶点计算其精确的 Web 墨卡托坐标；
+ * 2. 减去瓦片中心的精确墨卡托坐标，得到相对于瓦片中心的相对偏移量 `aMercatorOffset`（float32）；
+ * 3. 为什么是相对偏移：
+ *    Web 墨卡托全局坐标在 0..1 之间，若直接用 float32（24 位尾数）存储绝对坐标，
+ *    分辨率约为 40000000 / 2^24 ≈ 2.38 米；
+ *    若改为相对瓦片中心（瓦片半径通常 <= 100 km），float32 尾数精度可达：
+ *    100000 / 2^24 ≈ 0.0059 米（小于 6 毫米），常规 2 km 瓦片下更是达到 0.1 毫米以内。
+ * 4. 着色器重构：
+ *    顶点着色器在局部对象空间中还原出抵消瓦片尺度与中心平移后的坐标：
+ *    `transformed = uTilePivot + vec3(aMercatorOffset.x, -aMercatorOffset.y, aMercatorOffset.z) * uInvTileScale;`
+ *    其中 `uInvTileScale = 1 / (sScene * k) = 1 / sTile`。
+ *    经过瓦片矩阵变换与 `_enuMatrix` 缩放平移后，刚好恒等于真实的世界墨卡托坐标，误差 < 1 cm。
+ */
+
+import {
+  EARTH_RADIUS,
+  enuToLngLat as geoEnuToLngLat,
+  mercatorFromLngLat,
+} from '../render/GeoAdapter.js';
+
+/** 超过此半径（米）的瓦片在未指定参数时自动开启墨卡托烘焙（25 km） */
+export const AUTO_BAKE_RADIUS_THRESHOLD = 25000;
+
+export interface TileAnchorLike {
+  lon: number;
+  lat: number;
+  height?: number;
+}
+
+export interface TileCenterLike {
+  x: number;
+  y: number;
+  z?: number;
+}
+
+/**
+ * 局部 ENU 偏移（东, 北 米）→ 经纬度（对接 GeoAdapter 的 WGS84 高精度模型）。
+ */
+export function enuToLngLat(anchor: TileAnchorLike, east: number, north: number): [number, number] {
+  return geoEnuToLngLat(anchor.lon, anchor.lat, east, north);
+}
+
+/**
+ * 逐顶点计算 Web 墨卡托相对于瓦片中心的偏移量。
+ *
+ * @param positions 顶点位置数组（x, y, z...）
+ * @param vertexCount 顶点数
+ * @param tileAnchor 数据集/瓦片地理锚点
+ * @param tileCenter 瓦片中心在数据集局部 ENU 中的位置（米）
+ * @param stride 每个顶点的分量数（默认为 3）
+ * @param target 可选的复用 Float32Array
+ * @returns 长度为 vertexCount * 3 的 Float32Array，存 [dx, dy, dz, ...]
+ */
+export function bakeMercatorOffsets(
+  positions: ArrayLike<number>,
+  vertexCount: number,
+  tileAnchor: TileAnchorLike,
+  tileCenter: TileCenterLike,
+  stride = 3,
+  target?: Float32Array
+): Float32Array {
+  const out = target && target.length >= vertexCount * 3 ? target : new Float32Array(vertexCount * 3);
+
+  const centerAlt = (tileAnchor.height ?? 0) + (tileCenter.z ?? 0);
+  const [centerLon, centerLat] = enuToLngLat(tileAnchor, tileCenter.x, tileCenter.y);
+  const cMerc = mercatorFromLngLat(centerLon, centerLat, centerAlt);
+
+  for (let i = 0; i < vertexCount; i++) {
+    const idx = i * stride;
+    const vx = positions[idx];
+    const vy = positions[idx + 1];
+    const vz = positions[idx + 2] ?? 0;
+
+    const vAlt = (tileAnchor.height ?? 0) + vz;
+    const [vLon, vLat] = enuToLngLat(tileAnchor, vx, vy);
+    const vMerc = mercatorFromLngLat(vLon, vLat, vAlt);
+
+    out[i * 3 + 0] = vMerc.x - cMerc.x;
+    out[i * 3 + 1] = vMerc.y - cMerc.y;
+    out[i * 3 + 2] = vMerc.z - cMerc.z;
+  }
+
+  return out;
+}

package/src/core/S3M1Parser.ts

@@ -62,6 +62,7 @@
  */
 import { BinaryReader } from './BinaryReader.js';
 import type {
+  Geode,
   GeoPackageEntry,
   GroupNode,
   IndexPackage,
@@ -124,7 +125,13 @@ interface XmlMaterial {
   addressMode?: { u: number; v: number };
 }
 
-interface XmlLod {
+export interface XmlGeode {
+  geoName: string;
+  matrix: number[];
+}
+
+export interface XmlLod {
+  geodes?: XmlGeode[];
   geoNames: string[];
   matrix: number[];
   childTile: string;
@@ -158,7 +165,7 @@ function rangeModeOf(text: string | null): number {
   return 1;
 }
 
-function parseXmlLods(xml: string): XmlLod[] {
+export function parseXmlLods(xml: string): XmlLod[] {
   const blocks = [...xml.matchAll(/<(?:[A-Za-z0-9_-]+:)?PagedLOD[^>]*>([\s\S]*?)<\/(?:[A-Za-z0-9_-]+:)?PagedLOD>/gi)];
   const out: XmlLod[] = [];
   for (const b of blocks) {
@@ -180,6 +187,39 @@ function parseXmlLods(xml: string): XmlLod[] {
       radius: num(tag(sphere, 'radius')),
     });
   }
+  // 兜底：S3M 1.x 叶子瓦片没有 <PagedLOD>，<PageLods> 内部直接是 <Geode>
+  if (out.length === 0) {
+    const pageLodsBlock = /<(?:[A-Za-z0-9_-]+:)?PageLods[^>]*>([\s\S]*?)<\/(?:[A-Za-z0-9_-]+:)?PageLods>/i.exec(xml);
+    const scope = pageLodsBlock ? pageLodsBlock[1] : xml;
+    const geodeBlocks = [...scope.matchAll(/<(?:[A-Za-z0-9_-]+:)?Geode[^>]*>([\s\S]*?)<\/(?:[A-Za-z0-9_-]+:)?Geode>/gi)];
+    if (geodeBlocks.length > 0) {
+      const geodes: XmlGeode[] = [];
+      for (const gb of geodeBlocks) {
+        const gs = gb[1];
+        const gName = tag(gs, "GeoName") ?? "";
+        const matStr = tag(gs, "GeoDeModMatrix");
+        const mat = (matStr ?? "1,0,0,0,0,1,0,0,0,0,1,0,0,0,0,1")
+          .split(",")
+          .map((x) => parseFloat(x.trim()))
+          .filter((x) => Number.isFinite(x));
+        geodes.push({
+          geoName: gName,
+          matrix: mat.length === 16 ? mat : [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1],
+        });
+      }
+      out.push({
+        geoNames: geodes.map((g) => g.geoName).filter(Boolean),
+        matrix: geodes[0]?.matrix ?? [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1],
+        geodes,
+        childTile: "",
+        rangeMode: rangeModeOf(null), // 1 = 屏幕像素
+        rangeValue: 0,
+        center: { x: 0, y: 0, z: 0 },
+        radius: 0,
+      });
+    }
+  }
+
   return out;
 }
 
@@ -645,6 +685,108 @@ function readTextures(br: BinaryReader, texSize: number): Record<string, S3MText
 let warnedV1Attrs = false;
 let warnedQuantBox = false;
 
+function computeLodBoundingSphere(
+  geodes: { matrix: number[]; skeletonNames: string[] }[],
+  meshes: MeshRecord[]
+): { center: { x: number; y: number; z: number }; radius: number } | null {
+  const meshMap = new Map(meshes.map((m) => [`SuperMapCache#${m.geoName}`, m]));
+  let minX = Infinity, maxX = -Infinity;
+  let minY = Infinity, maxY = -Infinity;
+  let minZ = Infinity, maxZ = -Infinity;
+  let totalPoints = 0;
+
+  for (const geode of geodes) {
+    const mat = geode.matrix;
+    const isIdentity =
+      !mat ||
+      (mat[0] === 1 && mat[1] === 0 && mat[2] === 0 && mat[3] === 0 &&
+       mat[4] === 0 && mat[5] === 1 && mat[6] === 0 && mat[7] === 0 &&
+       mat[8] === 0 && mat[9] === 0 && mat[10] === 1 && mat[11] === 0 &&
+       mat[12] === 0 && mat[13] === 0 && mat[14] === 0 && mat[15] === 1);
+
+    for (const name of geode.skeletonNames) {
+      const mesh = meshMap.get(name);
+      if (!mesh || !mesh.position) continue;
+      const pos = mesh.position;
+      totalPoints += pos.length / 3;
+
+      if (isIdentity) {
+        for (let i = 0; i < pos.length; i += 3) {
+          const x = pos[i]!, y = pos[i + 1]!, z = pos[i + 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;
+        }
+      } else {
+        const m0 = mat[0]!, m1 = mat[1]!, m2 = mat[2]!;
+        const m4 = mat[4]!, m5 = mat[5]!, m6 = mat[6]!;
+        const m8 = mat[8]!, m9 = mat[9]!, m10 = mat[10]!;
+        const m12 = mat[12]!, m13 = mat[13]!, m14 = mat[14]!;
+        for (let i = 0; i < pos.length; i += 3) {
+          const x = pos[i]!, y = pos[i + 1]!, z = pos[i + 2]!;
+          const tx = m0 * x + m4 * y + m8 * z + m12;
+          const ty = m1 * x + m5 * y + m9 * z + m13;
+          const tz = m2 * x + m6 * y + m10 * z + m14;
+          if (tx < minX) minX = tx; if (tx > maxX) maxX = tx;
+          if (ty < minY) minY = ty; if (ty > maxY) maxY = ty;
+          if (tz < minZ) minZ = tz; if (tz > maxZ) maxZ = tz;
+        }
+      }
+    }
+  }
+
+  if (totalPoints === 0 || !Number.isFinite(minX)) return null;
+
+  const cx = (minX + maxX) * 0.5;
+  const cy = (minY + maxY) * 0.5;
+  const cz = (minZ + maxZ) * 0.5;
+
+  let maxR2 = 0;
+  for (const geode of geodes) {
+    const mat = geode.matrix;
+    const isIdentity =
+      !mat ||
+      (mat[0] === 1 && mat[1] === 0 && mat[2] === 0 && mat[3] === 0 &&
+       mat[4] === 0 && mat[5] === 1 && mat[6] === 0 && mat[7] === 0 &&
+       mat[8] === 0 && mat[9] === 0 && mat[10] === 1 && mat[11] === 0 &&
+       mat[12] === 0 && mat[13] === 0 && mat[14] === 0 && mat[15] === 1);
+
+    for (const name of geode.skeletonNames) {
+      const mesh = meshMap.get(name);
+      if (!mesh || !mesh.position) continue;
+      const pos = mesh.position;
+
+      if (isIdentity) {
+        for (let i = 0; i < pos.length; i += 3) {
+          const dx = pos[i]! - cx, dy = pos[i + 1]! - cy, dz = pos[i + 2]! - cz;
+          const r2 = dx * dx + dy * dy + dz * dz;
+          if (r2 > maxR2) maxR2 = r2;
+        }
+      } else {
+        const m0 = mat[0]!, m1 = mat[1]!, m2 = mat[2]!;
+        const m4 = mat[4]!, m5 = mat[5]!, m6 = mat[6]!;
+        const m8 = mat[8]!, m9 = mat[9]!, m10 = mat[10]!;
+        const m12 = mat[12]!, m13 = mat[13]!, m14 = mat[14]!;
+        for (let i = 0; i < pos.length; i += 3) {
+          const x = pos[i]!, y = pos[i + 1]!, z = pos[i + 2]!;
+          const tx = m0 * x + m4 * y + m8 * z + m12;
+          const ty = m1 * x + m5 * y + m9 * z + m13;
+          const tz = m2 * x + m6 * y + m10 * z + m14;
+          const dx = tx - cx, dy = ty - cy, dz = tz - cz;
+          const r2 = dx * dx + dy * dy + dz * dz;
+          if (r2 > maxR2) maxR2 = r2;
+        }
+      }
+    }
+  }
+
+  const radius = Math.sqrt(maxR2);
+  return {
+    center: { x: cx, y: cy, z: cz },
+    radius: radius > 0 ? radius : 0.001,
+  };
+}
+
 export async function parseS3M1(arrayBuffer: ArrayBuffer, options: ParseS3M1Options = {}): Promise<ParsedTile> {
   const inflate = options.inflate ?? defaultInflate;
   const r = new BinaryReader(arrayBuffer);
@@ -770,17 +912,45 @@ export async function parseS3M1(arrayBuffer: ArrayBuffer, options: ParseS3M1Opti
   const xmlLods = parseXmlLods(xml);
   const pageLods: PageLOD[] = [];
   xmlLods.forEach((lod, i) => {
-    const named = lod.geoNames.map((n) => keyOf.get(n)).filter((k): k is string => !!k);
-    // 名字对不上时退回位置匹配，并让上层有机会发现（宁可少一个 LOD 也不要挂错球）
-    const fallback = meshes[i] ? [`SuperMapCache#${meshes[i].geoName}`] : [];
-    const skeletonNames = named.length ? [...new Set(named)] : fallback;
-    if (!skeletonNames.length) return;
+    let geodes: Geode[];
+    if (lod.geodes && lod.geodes.length > 0) {
+      geodes = lod.geodes
+        .map((g, gi) => {
+          const key = keyOf.get(g.geoName);
+          const fallback = meshes[gi] ? [`SuperMapCache#${meshes[gi].geoName}`] : [];
+          const skeletonNames = key ? [key] : fallback;
+          return {
+            matrix: g.matrix,
+            skeletonNames,
+          };
+        })
+        .filter((g) => g.skeletonNames.length > 0);
+    } else {
+      const named = lod.geoNames.map((n) => keyOf.get(n)).filter((k): k is string => !!k);
+      // 名字对不上时退回位置匹配，并让上层有机会发现（宁可少一个 LOD 也不要挂错球）
+      const fallback = meshes[i] ? [`SuperMapCache#${meshes[i].geoName}`] : [];
+      const skeletonNames = named.length ? [...new Set(named)] : fallback;
+      geodes = skeletonNames.length ? [{ matrix: lod.matrix, skeletonNames }] : [];
+    }
+    if (!geodes.length) return;
+
+    let center = { ...lod.center };
+    let radius = lod.radius;
+    // 缺包围球（如叶子瓦片）时，从网格顶点实时计算真实几何包围球
+    if (radius <= 0) {
+      const computed = computeLodBoundingSphere(geodes, meshes);
+      if (computed) {
+        center = computed.center;
+        radius = computed.radius;
+      }
+    }
+
     pageLods.push({
       rangeValue: lod.rangeValue,
       rangeMode: lod.rangeMode,
-      boundingSphere: { center: { ...lod.center }, radius: lod.radius },
+      boundingSphere: { center, radius },
       childTile: lod.childTile,
-      geodes: [{ matrix: lod.matrix, skeletonNames }],
+      geodes,
     });
   });
   const groupNode: GroupNode = { pageLods };

package/src/core/TileGeometry.ts

@@ -21,6 +21,7 @@ import type {
   VertexAttribute,
 } from './types.js';
 import { applyCustomAttributeSemantics } from './CustomAttributes.js';
+import { bakeMercatorOffsets, type TileAnchorLike, type TileCenterLike } from './BakeMercator.js';
 
 /**
  * S3M 规范里 `DrawPrimitiveType` 的两个特殊值（原住 GeometryBuilder，随组装层
@@ -249,6 +250,8 @@ export interface PrimitiveAttributes {
    * 只有存在该流时才产生；解码语义见 core/TexCoordZ.ts。
    */
   aTexCoordZ?: PlainAttribute;
+  /** 逐顶点精确 Web 墨卡托偏移（Issue #15） */
+  aMercatorOffset?: PlainAttribute;
 }
 
 export interface PrimitiveData {
@@ -298,6 +301,10 @@ export interface AssembleOptions {
    * `useWorker: false` 或 Worker 崩溃降级时它落在主线程上。
    */
   dedupeCoincident?: boolean;
+  /** 是否烘焙精确 Web 墨卡托偏移（Issue #15） */
+  bakeMercator?: boolean;
+  tileAnchor?: TileAnchorLike;
+  tileCenter?: TileCenterLike;
   vertexAttributeDescript?: unknown;
 }
 
@@ -905,5 +912,24 @@ export function assembleTileGeometry(tile: ParsedTile, options: AssembleOptions
     }
   }
 
+  // 逐顶点烘焙精确 Web 墨卡托（Issue #15）
+  if (options.bakeMercator && options.tileAnchor) {
+    for (const p of primitives) {
+      const positions = p.attributes.position?.array;
+      if (!positions || p.vertexCount === 0) continue;
+      const center = options.tileCenter ?? {
+        x: p.bounds.sphereCenter[0],
+        y: p.bounds.sphereCenter[1],
+        z: p.bounds.sphereCenter[2],
+      };
+      const offsets = bakeMercatorOffsets(positions, p.vertexCount, options.tileAnchor, center);
+      p.attributes.aMercatorOffset = {
+        array: offsets,
+        components: 3,
+        normalized: false,
+      };
+    }
+  }
+
   return { primitives, stats };
 }

package/src/index.ts

@@ -51,13 +51,21 @@ export type {
 
 // —— 地理坐标适配（宿主无关接口 + 墨卡托兜底）
 export {
+  WGS84_A,
+  WGS84_B,
+  WGS84_F,
+  WGS84_E2,
   EARTH_RADIUS,
+  primeVerticalRadius,
+  meridianRadius,
+  enuToLngLat,
+  lngLatToEnu,
   mercatorFromLngLat,
   lngLatFromMercator,
   worldFromLngLat,
   lngLatFromWorld,
 } from './render/GeoAdapter.js';
-export type { GeoAdapter } from './render/GeoAdapter.js';
+export type { GeoAdapter, WorldCoordinateResult } from './render/GeoAdapter.js';
 
 // —— 瓦片层
 export { S3MTileset, parseConfigText, classifyDatasetKind } from './tileset/S3MTileset.js';
@@ -110,8 +118,10 @@ export type {
   GroundOptions,
   LightOptions,
   PathFollowOptions,
+  DepthMode,
 } from './render/S3MViewer.js';
 
+export { normalizeDepthMode } from './render/S3MViewer.js';
 export { LIGHT_PRESETS, DEFAULT_LIGHT_PRESET, SUPERMAP_LIGHT_PRESET, resolveLightingPreset } from './render/lightingPreset.js';
 export type { LightingPreset, PresetLightIntensities } from './render/lightingPreset.js';
 

package/src/render/DatasetManager.ts

@@ -14,6 +14,7 @@ import type { Anchor } from '../core/types.js';
 import type { UnsupportedPolicy } from '../core/degradations.js';
 import { worldFromLngLat, type GeoAdapter } from './GeoAdapter.js';
 import type { TextureCreateOptions } from './TextureFactory.js';
+import type { DepthMode } from './viewer/types.js';
 
 export type DatasetAlignment = 'origin' | 'bottom' | 'top' | 'center';
 
@@ -42,6 +43,11 @@ export interface S3MDatasetOptions {
   heightOffset?: number;
   /** 是否用 Web Worker 解析经典 .s3mb 瓦片（默认开，崩溃自动降级主线程），见 S3MTilesetOptions.useWorker */
   useWorker?: boolean;
+  /**
+   * 本数据集推荐的深度模式（'scene' | 'clear' | 'auto'）。
+   * 当图层/Viewer 的 depthMode 为 'auto' 时，若任一可见数据集标注为 'clear'，则整层以 'clear' 绘制。
+   */
+  depthMode?: DepthMode;
   /** 三角面材质深度偏移（共面摩尔纹 / 重合面归属），见 BuildTileOptions.polygonOffset */
   polygonOffset?: { factor: number; units: number };
   /**
@@ -49,6 +55,7 @@ export interface S3MDatasetOptions {
    * 只影响该数据集**之后创建**的材质。
    */
   materialQuality?: 'pbr' | 'lambert';
+  bakeMercator?: boolean;
   /**
    * 是否对该数据集生成几何棱线（CPU 端 EdgesGeometry）。
    * - 不填：跟随全局 `style.edges`
@@ -65,6 +72,13 @@ export interface S3MDatasetOptions {
    * 目前只有 3DGS：按点渲染，做不出泼溅。见 `S3MTilesetOptions.unsupported`。
    */
   unsupported?: UnsupportedPolicy;
+  /**
+   * LOD 细化过渡策略：
+   * - 'binary'（默认）：整节点二值切换
+   * - 'incremental'：增量细化（primary / fallback 双列表 + LEQUAL 深度推移）
+   */
+  lodTransition?: 'binary' | 'incremental';
+  fallbackOffset?: { factor?: number; units?: number };
 }
 
 export interface S3MDatasetEntry {
@@ -97,13 +111,32 @@ export interface DatasetManagerCallbacks {
 
 export class DatasetManager {
   readonly datasets = new Map<string, S3MDatasetEntry>();
-  sceneAnchor: { x: number; y: number; z: number; meterInMercator: number; altitude?: number } | null = null;
+  sceneAnchor: {
+    x: number;
+    y: number;
+    z: number;
+    meterInMercatorEast?: number;
+    meterInMercatorNorth?: number;
+    meterInMercatorUp?: number;
+    meterInMercator: number;
+    altitude?: number;
+  } | null = null;
   totalMaxTiles: number = 0;
   /**
    * 图层级默认光照模型档位（`undefined` = 跟随模块级默认）。
    * 数据集自己指定了 `materialQuality` 就用自己的。
    */
   defaultMaterialQuality: 'pbr' | 'lambert' | undefined = undefined;
+  defaultLodTransition: 'binary' | 'incremental' = 'binary';
+  defaultFallbackOffset?: { factor?: number; units?: number };
+
+  setDefaultLodTransition(mode: 'binary' | 'incremental'): void {
+    this.defaultLodTransition = mode;
+    for (const entry of this.datasets.values()) {
+      entry.tileset?.setLodTransition(mode);
+    }
+  }
+  defaultBakeMercator: boolean | undefined = undefined;
 
   /**
    * 图层档位变更：同步给已存在的数据集（它们之后加载的瓦片才用新档位；
@@ -264,6 +297,8 @@ export class DatasetManager {
       maxMemory: ds.maxMemory ?? maxMemory,
       maxImageCache: ds.maxImageCache ?? maxImageCache,
       lodRangeScale: ds.lodRangeScale ?? defaultLodRangeScale,
+      lodTransition: ds.lodTransition ?? this.defaultLodTransition,
+      fallbackOffset: ds.fallbackOffset ?? this.defaultFallbackOffset,
       buildTile: buildTile ?? null,
       polygonOffset: ds.polygonOffset,
       // 数据集 > 图层 > 模块级默认（undefined 一路传下去，由 createStyledMaterial 回落）
@@ -272,6 +307,7 @@ export class DatasetManager {
       colorPipeline: this.defaultColorPipeline,
       textureOptions: this.defaultTextureOptions,
       useWorker: ds.useWorker,
+      bakeMercator: ds.bakeMercator ?? this.defaultBakeMercator,
       authenticate: ds.authenticate ?? authenticate,
       unsupported: ds.unsupported,
       uniforms: uniforms,
@@ -359,12 +395,14 @@ export class DatasetManager {
     if (!this.sceneAnchor) {
       this.sceneAnchor = worldFromLngLat(geo, entry.anchor.lon, entry.anchor.lat, entry.anchor.height ?? 0);
     }
-    const s = this.sceneAnchor.meterInMercator;
+    const sEast = this.sceneAnchor.meterInMercatorEast ?? this.sceneAnchor.meterInMercator;
+    const sNorth = this.sceneAnchor.meterInMercatorNorth ?? this.sceneAnchor.meterInMercator;
+    const sUp = sEast;
     const a = worldFromLngLat(geo, entry.anchor.lon, entry.anchor.lat, entry.anchor.height ?? 0);
     entry.offset = [
-      (a.x - this.sceneAnchor.x) / s,
-      -(a.y - this.sceneAnchor.y) / s,
-      (a.z - this.sceneAnchor.z) / s + (entry.heightOffset ?? 0),
+      (a.x - this.sceneAnchor.x) / sEast,
+      -(a.y - this.sceneAnchor.y) / sNorth,
+      (a.z - this.sceneAnchor.z) / sUp + (entry.heightOffset ?? 0),
     ];
     entry.root.position.set(entry.offset[0], entry.offset[1], entry.offset[2]);
     entry.root.updateMatrixWorld(true);