s3m-three 0.4.26 → 0.4.27

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.27",
   "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/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);

package/src/render/GeoAdapter.ts

@@ -6,39 +6,151 @@
  * 这个文件只定义接口与默认实现，不依赖任何宿主：
  *
  *   - `GeoAdapter`       —— 宿主需要提供的两个转换函数
- *   - `mercatorFromLngLat` / `lngLatFromMercator` —— 标准 Web 墨卡托换算
+ *   - `mercatorFromLngLat` / `lngLatFromMercator` —— 标准 Web 墨卡托换算（WGS84 椭球）
  *   - `worldFromLngLat` / `lngLatFromWorld` —— 带兜底的封装：
  *       有 adapter 用 adapter（自动适配 MapLibre v5+ 任意 CRS / 自定义投影），
  *       没有就平滑回退到标准 Web 墨卡托。
+ *   - `enuToLngLat` / `lngLatToEnu` —— WGS84 椭球高精度局部坐标互转
  *
  * MapLibre / Mapbox 的 adapter 实现见 s3m-maplibre 包的 MapLibreGeoAdapter.ts。
  */
 
-export const EARTH_RADIUS = 6378137;
+/** WGS84 椭球长半轴 a（米） */
+export const WGS84_A = 6378137.0;
+/** WGS84 椭球扁率 f */
+export const WGS84_F = 1 / 298.257223563;
+/** WGS84 椭球短半轴 b（米） */
+export const WGS84_B = WGS84_A * (1 - WGS84_F);
+/** WGS84 椭球第一偏心率平方 e² = 2f - f² ≈ 0.0066943799901413165 */
+export const WGS84_E2 = 2 * WGS84_F - WGS84_F * WGS84_F;
+
+/** 保持向下兼容：EARTH_RADIUS 对应 WGS84 长半轴 */
+export const EARTH_RADIUS = WGS84_A;
+
+/**
+ * 卯酉圈曲率半径 N(φ) = a / √(1 - e² sin²φ)（米）
+ */
+export function primeVerticalRadius(latRad: number): number {
+  const sin = Math.sin(latRad);
+  return WGS84_A / Math.sqrt(1 - WGS84_E2 * sin * sin);
+}
+
+/**
+ * 子午圈曲率半径 M(φ) = a(1 - e²) / (1 - e² sin²φ)^(3/2)（米）
+ */
+export function meridianRadius(latRad: number): number {
+  const sin = Math.sin(latRad);
+  const w2 = 1 - WGS84_E2 * sin * sin;
+  return (WGS84_A * (1 - WGS84_E2)) / (w2 * Math.sqrt(w2));
+}
+
+/**
+ * 局部 ENU 米坐标 (east, north) → 经纬度 [lon, lat] (度)
+ * 基于 WGS84 椭球中点曲率半径反解，在 100 km 范围内误差 < 1 cm。
+ */
+export function enuToLngLat(
+  anchorLon: number,
+  anchorLat: number,
+  east: number,
+  north: number
+): [number, number] {
+  const lat0 = (anchorLat * Math.PI) / 180;
+  const M0 = meridianRadius(lat0);
+  // 中点迭代一步：在数百公里尺度即可将纬度子午线积分误差压到亚毫米
+  const dLatApprox = north / M0;
+  const latMid = lat0 + dLatApprox * 0.5;
+  const M_mid = meridianRadius(latMid);
+  const latRad = lat0 + north / M_mid;
+
+  const N_lat = primeVerticalRadius(latRad);
+  const cosLat = Math.cos(latRad);
+  const dLon = Math.abs(cosLat) < 1e-12 ? 0 : east / (N_lat * cosLat);
+
+  return [anchorLon + (dLon * 180) / Math.PI, (latRad * 180) / Math.PI];
+}
+
+/**
+ * 经纬度 (lon, lat) → 局部 ENU 米坐标 [east, north]
+ * enuToLngLat 的逆运算。
+ */
+export function lngLatToEnu(
+  anchorLon: number,
+  anchorLat: number,
+  lon: number,
+  lat: number
+): [number, number] {
+  const lat0 = (anchorLat * Math.PI) / 180;
+  const lat1 = (lat * Math.PI) / 180;
+  const latMid = (lat0 + lat1) * 0.5;
+  const north = (lat1 - lat0) * meridianRadius(latMid);
+
+  const N_lat = primeVerticalRadius(lat1);
+  const cosLat = Math.cos(lat1);
+  const dLon = ((lon - anchorLon) * Math.PI) / 180;
+  const east = dLon * N_lat * cosLat;
+
+  return [east, north];
+}
+
+/** 坐标转换结果类型 */
+export interface WorldCoordinateResult {
+  x: number;
+  y: number;
+  z: number;
+  /** 东向：1 米 = 多少世界单位 (Web Mercator 东西向尺度 1 / (2π N cosφ)) */
+  meterInMercatorEast: number;
+  /** 北向：1 米 = 多少世界单位 (Web Mercator 南北向尺度 1 / (2π M cosφ)) */
+  meterInMercatorNorth: number;
+  /** 竖向（高程）：1 米 = 多少世界单位（当前取东向尺度 meterInMercatorEast，以保持局部长方体水平与竖直比例） */
+  meterInMercatorUp: number;
+  /** 兼容旧代码：等同于 meterInMercatorEast。注意：从原先的正球近似更新为更精准的 WGS84 椭球东向尺度 */
+  meterInMercator: number;
+  altitude: number;
+}
 
 /** 宿主地理坐标系能力：S3M 渲染层用到的就只有这两个方向 */
 export interface GeoAdapter {
-  /** 经纬度 + 高程 → 归一化世界坐标，并给出「1 米 = 多少世界单位」 */
+  /** 经纬度 + 高程 → 归一化世界坐标，并给出「1 米 = 多少世界单位」（含各向异性 East / North） */
   worldFromLngLat(
     lng: number,
     lat: number,
     altitude?: number
-  ): { x: number; y: number; z: number; meterInMercator: number; altitude: number };
+  ): WorldCoordinateResult;
   /** 归一化世界坐标 → 经纬度 [lng, lat] */
   lngLatFromWorld(x: number, y: number): [number, number];
 }
 
-/** 经纬度 → 墨卡托归一化坐标（世界为 1×1）—— 默认墨卡托兜底 */
+/** 经纬度 → 墨卡托归一化坐标（世界为 1×1）—— 默认墨卡托兜底（WGS84 椭球曲率半径与各向异性尺度） */
 export function mercatorFromLngLat(
   lon: number,
   lat: number,
   altitude = 0
-): { x: number; y: number; z: number; meterInMercator: number; altitude: number } {
-  const sinLat = Math.sin((lat * Math.PI) / 180);
+): WorldCoordinateResult {
+  const latRad = (lat * Math.PI) / 180;
+  const sinLat = Math.sin(latRad);
+  const cosLat = Math.cos(latRad);
+  const safeCosLat = Math.max(Math.abs(cosLat), 1e-12);
+
   const x = (180 + lon) / 360;
   const y = 0.5 - (0.25 * Math.log((1 + sinLat) / (1 - sinLat))) / Math.PI;
-  const meterInMercator = 1 / (2 * Math.PI * EARTH_RADIUS) / Math.cos((lat * Math.PI) / 180);
-  return { x, y, z: altitude * meterInMercator, meterInMercator, altitude };
+
+  const N = primeVerticalRadius(latRad);
+  const M = meridianRadius(latRad);
+
+  const meterInMercatorEast = 1 / (2 * Math.PI * N * safeCosLat);
+  const meterInMercatorNorth = 1 / (2 * Math.PI * M * safeCosLat);
+  const meterInMercatorUp = meterInMercatorEast;
+
+  return {
+    x,
+    y,
+    z: altitude * meterInMercatorUp,
+    meterInMercatorEast,
+    meterInMercatorNorth,
+    meterInMercatorUp,
+    meterInMercator: meterInMercatorEast,
+    altitude,
+  };
 }
 
 /** 墨卡托归一化坐标 → 经纬度 —— 默认墨卡托兜底 */
@@ -58,8 +170,24 @@ export function worldFromLngLat(
   lon: number,
   lat: number,
   altitude = 0
-): { x: number; y: number; z: number; meterInMercator: number; altitude: number } {
-  if (adapter) return adapter.worldFromLngLat(lon, lat, altitude);
+): WorldCoordinateResult {
+  if (adapter) {
+    const res = adapter.worldFromLngLat(lon, lat, altitude);
+    const east = res.meterInMercatorEast ?? res.meterInMercator;
+    const north = res.meterInMercatorNorth ?? res.meterInMercator ?? east;
+    const up = res.meterInMercatorUp ?? east;
+    const legacy = res.meterInMercator ?? east;
+    return {
+      x: res.x,
+      y: res.y,
+      z: res.z,
+      meterInMercatorEast: east,
+      meterInMercatorNorth: north,
+      meterInMercatorUp: up,
+      meterInMercator: legacy,
+      altitude: res.altitude,
+    };
+  }
   return mercatorFromLngLat(lon, lat, altitude);
 }
 

package/src/render/GeometryBuilder.ts

@@ -18,6 +18,8 @@ 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 { bakeMercatorOffsets } from '../core/BakeMercator.js';
+import { mercatorFromLngLat } from './GeoAdapter.js';
 import type { TileGeometryData, PrimitiveData } from '../core/TileGeometry.js';
 import { decodeScale, decodeRotation } from '../core/GaussianSplat.js';
 import { createSplatMaterial, createQuadGeometry, splatRaycast } from './SplatMaterial.js';
@@ -378,6 +380,15 @@ export interface BuildTileOptions {
    * 不传 = 各自读模块级默认。同样由图层的渲染 profile 带下来。
    */
   textureOptions?: TextureCreateOptions;
+  /**
+   * 是否烘焙精确 Web 墨卡托偏移属性（消除全球尺度下的视差游动）。
+   * 透传给 assembleTileGeometry 和 createStyledMaterial。
+   */
+  bakeMercator?: boolean;
+  /** 瓦片锚点（经纬度），烘焙墨卡托时使用 */
+  tileAnchor?: { lon: number; lat: number; height?: number };
+  /** 瓦片中心偏移（ENU 米），烘焙墨卡托时使用 */
+  tileCenter?: { x: number; y: number; z?: number };
 }
 
 export interface BuildTileResult {
@@ -475,7 +486,8 @@ export async function buildTileObjects(
     code?: string,
     hasAtlasRect = false,
     hasTexCoordZ = false,
-    vertexAlphaMin = 1
+    vertexAlphaMin = 1,
+    hasMercator = false
   ): StyledMaterial => {
     const entry = materialList.find((e) => materialName(unwrapMaterial(e)) === code);
     const m = unwrapMaterial(entry);
@@ -546,6 +558,19 @@ export async function buildTileObjects(
       ? Math.max((m?.alphaCutoff as number) ?? 0, 0.01)
       : 0;
 
+    let initialInvScale: [number, number, number] | undefined;
+    if (options.tileAnchor) {
+      const tileMerc = mercatorFromLngLat(
+        options.tileAnchor.lon,
+        options.tileAnchor.lat,
+        options.tileAnchor.height
+      );
+      const sEast = tileMerc.meterInMercatorEast ?? tileMerc.meterInMercator;
+      const sNorth = tileMerc.meterInMercatorNorth ?? tileMerc.meterInMercator;
+      const sUp = tileMerc.meterInMercatorUp ?? sEast;
+      initialInvScale = [1.0 / sEast, 1.0 / sNorth, 1.0 / sUp];
+    }
+
     const mat = createStyledMaterial({
       uniforms,
       map,
@@ -562,6 +587,9 @@ export async function buildTileObjects(
       // 图层 / 数据集的档位；undefined 时 createStyledMaterial 自己回落到模块级默认
       materialQuality: options.materialQuality,
       colorPipeline: options.colorPipeline,
+      bakeMercator: hasMercator || options.bakeMercator,
+      tilePivot: options.tileCenter ? new THREE.Vector3(options.tileCenter.x, options.tileCenter.y, options.tileCenter.z) : undefined,
+      invTileScale: initialInvScale ? new THREE.Vector3(...initialInvScale) : undefined,
     });
     // 用户配置的深度偏移（共面摩尔纹 / 重合面归属的人工定序，见 BuildTileOptions 注释）
     if (options.polygonOffset) {
@@ -574,11 +602,32 @@ export async function buildTileObjects(
 
   // 3) 纯数据几何组装：Worker 解析时已顺带产出就直接用，否则主线程现场组装
   //    （core/TileGeometry 的同一份实现，两条路径产物一致）
+  if (options.assembled && options.bakeMercator && options.tileAnchor) {
+    for (const prim of options.assembled.primitives) {
+      if (!prim.attributes.aMercatorOffset && prim.attributes.position) {
+        const offsets = bakeMercatorOffsets(
+          prim.attributes.position.array,
+          prim.vertexCount,
+          options.tileAnchor,
+          options.tileCenter ?? { x: 0, y: 0, z: 0 }
+
+        );
+        prim.attributes.aMercatorOffset = {
+          array: offsets,
+          components: 3,
+          normalized: false,
+        };
+      }
+    }
+  }
   const assembled =
     options.assembled ??
     assembleTileGeometry(tile, {
       batching: options.batching !== false,
       dedupeCoincident: options.dedupeCoincident,
+      bakeMercator: options.bakeMercator,
+      tileAnchor: options.tileAnchor,
+      tileCenter: options.tileCenter,
     });
   stats.vertices = assembled.stats.vertices;
   stats.edgeLines = assembled.stats.edgeLines;
@@ -610,11 +659,13 @@ export async function buildTileObjects(
     const geometry = packPrimitive(prim);
     const geoRef = tile.geoPackage[prim.geoNames[0]] ?? null;
     const vp = geoRef?.vertexPackage;
+    const hasMercator = !!prim.attributes.aMercatorOffset;
     const material = makeMaterial(
       prim.passNames[0],
       !!prim.attributes.aAtlasRect,
       !!prim.attributes.aTexCoordZ,
-      minVertexAlpha(prim.attributes.aColor)
+      minVertexAlpha(prim.attributes.aColor),
+      hasMercator
     );
     const matrix =
       prim.matrix && prim.matrix.length === 16 ? new THREE.Matrix4().fromArray(prim.matrix) : null;