s3m-three 0.4.26 → 0.4.28

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;