s3m-three 0.4.25 → 0.4.27

package/src/core/S3M1Parser.ts

@@ -225,14 +225,45 @@ interface MeshRecord {
   position: Float32Array;
   uv: Float32Array;
   indexCount: number;
-  indices: Uint16Array;
+  indices: Uint16Array | Uint32Array;
+  primitiveType: number;
   materialId: string;
   /** 实例矩阵（每实例 16 float：3×4 行主序 + RGBA），没有实例化时为 undefined */
   instances?: Float32Array;
 }
 
-/** 索引头的第 3 个 dword，全版本固定 */
-const INDEX_HEADER_MARK = 0x00040100;
+/**
+ * 校验 p 偏移处是否为合法的 S3M 1.x 索引头：
+ *   dword[0] = 1 (idxKind)
+ *   dword[1] = indexCount
+ *   dword[2] = mark，按字节小端存储：
+ *     byte 0: indexType (0=u16, 1/3=u32)
+ *     byte 1: useIndex (恒 1)
+ *     byte 2: primitiveType (1=POINTS, 2=LINES, 3=LINE_STRIP, 4=TRIANGLES, 5/6=STRIP/FAN, 13=EDGES)
+ *     byte 3: reserved (恒 0)
+ * 校验紧随其后的索引数据（4 字节对齐）之后，记录尾标记恒为 1。
+ */
+function isValidIndexHeader(view: DataView, p: number): boolean {
+  if (view.getUint32(p, true) !== 1) return false;
+  const count = view.getUint32(p + 4, true);
+  if (count === 0 || count > 10_000_000) return false;
+  const mark = view.getUint32(p + 8, true);
+  const indexType = mark & 0xff;
+  const useIndex = (mark >> 8) & 0xff;
+  const primitiveType = (mark >> 16) & 0xff;
+  const reserved = (mark >> 24) & 0xff;
+  if (useIndex !== 1 || reserved !== 0) return false;
+  if (indexType !== 0 && indexType !== 1 && indexType !== 3) return false;
+  if (![1, 2, 3, 4, 5, 6, 13].includes(primitiveType)) return false;
+  if (primitiveType === 4 && count % 3 !== 0) return false;
+  if (primitiveType === 2 && count % 2 !== 0) return false;
+
+  const wide = indexType === 1 || indexType === 3;
+  const indexBytes = count * (wide ? 4 : 2);
+  const tailOffset = (p + 12 + indexBytes + 3) & ~3;
+  if (tailOffset + 8 > view.byteLength) return false;
+  return view.getUint32(tailOffset, true) === 1;
+}
 
 /**
  * v1 里每个实例记录固定 20 个 float（80 字节）：
@@ -321,11 +352,7 @@ function readInstances(
 function findIndexHeader(view: DataView, from: number): number {
   const limit = view.byteLength - 12;
   for (let p = from; p <= limit; p += 4) {
-    if (view.getUint32(p, true) !== 1) continue;
-    const count = view.getUint32(p + 4, true);
-    if (count === 0 || count % 3 !== 0) continue;
-    if (view.getUint32(p + 8, true) !== INDEX_HEADER_MARK) continue;
-    return p;
+    if (isValidIndexHeader(view, p)) return p;
   }
   return -1;
 }
@@ -389,6 +416,39 @@ function applyQuantBox(position: Float32Array, box: Float32Array): boolean {
   return true;
 }
 
+/**
+ * 从版本 1 属性块中尝试提取 UV 坐标：
+ * 倾斜摄影（OSGB）等数据中，UV 块通常紧贴在索引头前：
+ *   头: [count: u32, dim: u32 = 2]
+ *   数据: V * 8 字节 float32 (u, v)
+ */
+function findV1UV(view: DataView, from: number, to: number, V: number): Float32Array | null {
+  const head = to - V * 8 - 8;
+  if (head >= from && view.getUint32(head, true) === V && view.getUint32(head + 4, true) === 2) {
+    let uv = new Float32Array(V * 2);
+    for (let i = 0; i < V * 2; i++) {
+      uv[i] = view.getFloat32(head + 8 + i * 4, true);
+    }
+    return uv;
+  }
+  for (let p = to - V * 8 - 8; p >= from; p -= 4) {
+    if (view.getUint32(p, true) === V && view.getUint32(p + 4, true) === 2) {
+      let uv = new Float32Array(V * 2);
+      let ok = true;
+      for (let i = 0; i < V * 2; i++) {
+        const val = view.getFloat32(p + 8 + i * 4, true);
+        if (!Number.isFinite(val) || Math.abs(val) > 1e4) {
+          ok = false;
+          break;
+        }
+        uv[i] = val;
+      }
+      if (ok) return uv;
+    }
+  }
+  return null;
+}
+
 function readGeometry(
   br: BinaryReader,
   geoSize: number
@@ -433,7 +493,7 @@ function readGeometry(
       position[i * 3 + 2] = z;
     }
 
-    const uv = new Float32Array(V * 2);
+    let uv = new Float32Array(V * 2);
     let instances: Float32Array | undefined;
     if (v0UvAt16) {
       // 版本 0：UV 数组头 [0,0,0,kind=1,count=V,flag=2]
@@ -456,7 +516,12 @@ function readGeometry(
         throw new Error(`[s3m] S3M 1.x 属性段无法定位索引头：网格 ${geoName}（偏移 ${br.offset}/${geoSize}）`);
       }
       if (at !== br.offset) {
-        skippedAttrs++;
+        const foundUv = findV1UV(br.view, br.offset, at, V);
+        if (foundUv) {
+          uv = foundUv;
+        } else {
+          skippedAttrs++;
+        }
         // 优先认实例化：柱状图是真·实例化的（一份模板 + N 个变换矩阵），
         // 顶点本来就该保持单位盒，靠矩阵摆位/缩放/上色。
         const inst = readInstances(br.view, br.offset, at);
@@ -471,15 +536,29 @@ function readGeometry(
       }
     }
 
-    // 索引头 [1, indexCount, 0x00040100]
+    // 索引头 [1, indexCount, mark]
     const idxKind = br.u32();
     const indexCount = br.u32();
-    br.u32(); // 常量标记
-    if (idxKind !== 1 || indexCount === 0 || indexCount % 3 !== 0) {
-      throw new Error(`[s3m] S3M 1.x 索引头不符：网格 ${geoName} kind=${idxKind} count=${indexCount}`);
+    const mark = br.u32();
+    const indexType = mark & 0xff;
+    const useIndex = (mark >> 8) & 0xff;
+    const primitiveType = (mark >> 16) & 0xff;
+    if (idxKind !== 1 || indexCount === 0 || useIndex !== 1) {
+      throw new Error(`[s3m] S3M 1.x 索引头不符：网格 ${geoName} kind=${idxKind} count=${indexCount} mark=0x${mark.toString(16)}`);
+    }
+    if (primitiveType === 4 && indexCount % 3 !== 0) {
+      throw new Error(`[s3m] S3M 1.x 索引头不符：网格 ${geoName} 三角形索引数 ${indexCount} 非 3 的倍数`);
+    }
+    if (primitiveType === 2 && indexCount % 2 !== 0) {
+      throw new Error(`[s3m] S3M 1.x 索引头不符：网格 ${geoName} 线段索引数 ${indexCount} 非 2 的倍数`);
+    }
+    const wide = indexType === 1 || indexType === 3;
+    const indices = wide ? new Uint32Array(indexCount) : new Uint16Array(indexCount);
+    if (wide) {
+      for (let i = 0; i < indexCount; i++) indices[i] = br.u32();
+    } else {
+      for (let i = 0; i < indexCount; i++) indices[i] = br.u16();
     }
-    const indices = new Uint16Array(indexCount);
-    for (let i = 0; i < indexCount; i++) indices[i] = br.u16();
     if (br.offset > geoSize) throw new Error(`[s3m] S3M 1.x 索引越界：网格 ${geoName}`);
     br.align4();
 
@@ -495,6 +574,7 @@ function readGeometry(
       uv,
       indexCount,
       indices,
+      primitiveType,
       materialId,
       ...(instances ? { instances } : {}),
     });
@@ -511,10 +591,10 @@ function readGeometry(
  */
 export function pixelFormatOfBpp(bpp: number, rawFormat: number): number {
   if (!Number.isFinite(bpp) || bpp <= 0) return rawFormat;
-  if (Math.abs(bpp - 0.5) < 0.02) return 17; // DXT1
-  if (Math.abs(bpp - 1) < 0.02) return 21; // DXT5
-  if (Math.abs(bpp - 4) < 0.02) return 14; // BGRA
-  if (Math.abs(bpp - 3) < 0.02) return 10; // RGB
+  if (Math.abs(bpp - 0.5) < 0.05 || (bpp >= 0.6 && bpp <= 0.75)) return 17; // DXT1（含全 mip 链 ~0.667 B/px）
+  if (Math.abs(bpp - 1) < 0.05 || (bpp >= 1.25 && bpp <= 1.5)) return 21; // DXT5（含全 mip 链 ~1.333~1.44 B/px）
+  if (Math.abs(bpp - 4) < 0.05) return 14; // BGRA
+  if (Math.abs(bpp - 3) < 0.05) return 10; // RGB
   console.warn(`[s3m] S3M 1.x 纹理密度 ${bpp.toFixed(3)} B/px 不在已知档位，按原 format=${rawFormat} 交给上层判定`);
   return rawFormat;
 }
@@ -668,9 +748,9 @@ export async function parseS3M1(arrayBuffer: ArrayBuffer, options: ParseS3M1Opti
     }
     const pack: IndexPackage = {
       indexCount: mesh.indexCount,
-      indexType: 0, // 0 = UNSIGNED_SHORT
+      indexType: mesh.indices instanceof Uint32Array ? 1 : 0,
       useIndex: 1,
-      primitiveType: 4, // TRIANGLES
+      primitiveType: mesh.primitiveType ?? 4,
       indices: new Uint8Array(mesh.indices.buffer, mesh.indices.byteOffset, mesh.indices.byteLength),
       passNames: [mesh.materialId],
     };

package/src/core/S3MBParser.ts

@@ -12,6 +12,7 @@
 import { BinaryReader } from './BinaryReader.js';
 import { parseDracoGeometry } from './Draco.js';
 import { parseMeshOptGeometry } from './MeshOpt.js';
+import { applyCustomAttributeSemantics } from './CustomAttributes.js';
 import { isS3M1Buffer, parseS3M1 } from './S3M1Parser.js';
 import type { DegradationKind } from './degradations.js';
 import type {
@@ -53,6 +54,8 @@ export interface ParseOptions {
   inflate?: InflateFn;
   /** 逐段追踪偏移，调试解析用 */
   trace?: (section: string, detail?: unknown, offset?: number) => void;
+  /** config.json 声明的顶点属性描述清单（用于语义重映射与维度判定） */
+  vertexAttributeDescript?: unknown;
 }
 
 /** 默认解压：zlib（文件头 78 9C / 78 DA）。浏览器与 Node 18+ 均可用。 */
@@ -73,9 +76,8 @@ function pushAttr(
   offset = 0,
   divisor?: number,
   dtype: AttrDType = 'f32'
-): void {
-  vp.attrLocation[semantic] = vp.vertexAttributes.length;
-  vp.vertexAttributes.push({
+): VertexAttribute {
+  const attr: VertexAttribute = {
     semantic,
     data,
     components,
@@ -83,7 +85,10 @@ function pushAttr(
     offsetInBytes: offset,
     divisor,
     dtype,
-  });
+  };
+  vp.attrLocation[semantic] = vp.vertexAttributes.length;
+  vp.vertexAttributes.push(attr);
+  return attr;
 }
 
 function newVertexPackage(): VertexPackage {
@@ -248,15 +253,19 @@ function parseInstanceInfo(r: BinaryReader, vp: VertexPackage, version: number):
   }
 }
 
-function parseVertexAttrExtension(r: BinaryReader, vp: VertexPackage): void {
+export { applyCustomAttributeSemantics } from './CustomAttributes.js';
+
+function parseVertexAttrExtension(r: BinaryReader, vp: VertexPackage): VertexAttribute[] {
   const n = r.u32();
+  const attrs: VertexAttribute[] = [];
   for (let i = 0; i < n; i++) {
     const count = r.u32();
     const dim = r.u16();
     const type = r.u16();
     const size = AttrTypeSize[type] ?? 4;
-    pushAttr(vp, `custom${i}`, r.bytes(count * dim * size), dim, dim * size);
+    attrs.push(pushAttr(vp, `custom${i}`, r.bytes(count * dim * size), dim, dim * size));
   }
+  return attrs;
 }
 
 function parseTangent(r: BinaryReader): void {
@@ -267,7 +276,7 @@ function parseTangent(r: BinaryReader): void {
   r.skip(n * dim * 4);
 }
 
-function parseStandardSkeleton(r: BinaryReader, vp: VertexPackage, version: number): void {
+function parseStandardSkeleton(r: BinaryReader, vp: VertexPackage, version: number, options?: ParseOptions): void {
   if (version >= 3) r.u32(); // streamSize
 
   parseVertex(r, vp);
@@ -278,9 +287,17 @@ function parseStandardSkeleton(r: BinaryReader, vp: VertexPackage, version: numb
   parseInstanceInfo(r, vp, version);
 
   if (version >= 3) {
-    parseVertexAttrExtension(r, vp);
+    const extAttrs = parseVertexAttrExtension(r, vp);
     const descript = r.string();
-    vp.customVertexAttribute = descript ? JSON.parse(descript) : undefined;
+    try {
+      vp.customVertexAttribute = descript ? JSON.parse(descript) : undefined;
+    } catch {
+      vp.customVertexAttribute = descript;
+    }
+    if (!vp.customVertexAttribute && options?.vertexAttributeDescript) {
+      vp.customVertexAttribute = options.vertexAttributeDescript;
+    }
+    applyCustomAttributeSemantics(vp, extAttrs, options?.vertexAttributeDescript);
     r.align4();
     parseTangent(r);
   }
@@ -386,7 +403,8 @@ function isFiniteBox(box: { center: Vec3; xExtent: Vec3; yExtent: Vec3; zExtent:
 export async function parseSkeletonEntries(
   r: BinaryReader,
   version: number,
-  trace?: ParseOptions['trace']
+  trace?: ParseOptions['trace'],
+  options?: ParseOptions
 ): Promise<Record<string, GeoPackageEntry>> {
   const count = r.u32();
   const geoPackage: Record<string, GeoPackageEntry> = {};
@@ -419,7 +437,7 @@ export async function parseSkeletonEntries(
     let indexPackages: IndexPackage[] = [];
 
     if (tag === VertexTag.STANDARD) {
-      parseStandardSkeleton(r, vp, version);
+      parseStandardSkeleton(r, vp, version, options);
       indexPackages = parseIndexPackages(r, version);
     } else if (tag === VertexTag.COMPRESSED) {
       if (version >= 3) {
@@ -462,10 +480,11 @@ export async function parseSkeletonEntries(
 export async function parseSkeletons(
   r: BinaryReader,
   version: number,
-  trace?: ParseOptions['trace']
+  trace?: ParseOptions['trace'],
+  options?: ParseOptions
 ): Promise<Record<string, GeoPackageEntry>> {
   r.u32(); // streamSize
-  const geoPackage = await parseSkeletonEntries(r, version, trace);
+  const geoPackage = await parseSkeletonEntries(r, version, trace, options);
 
   // v1/v2 在骨架数组之后还有一段附加流。官方写法是
   //   bytesOffset += secColorSize; bytesOffset += 4;
@@ -649,7 +668,7 @@ export async function parseS3MB(arrayBuffer: ArrayBuffer, options: ParseOptions
   trace?.('fileOptions', fileOptions, t.offset);
   const groupNode = parseGroupNode(t, version);
   trace?.('groupNode', groupNode.pageLods.length, t.offset);
-  const geoPackage = await parseSkeletons(t, version, trace);
+  const geoPackage = await parseSkeletons(t, version, trace, options);
   trace?.('skeletons', Object.keys(geoPackage).length, t.offset);
   const textures = parseTextures(t);
   trace?.('textures', Object.keys(textures).length, t.offset);

package/src/core/TileGeometry.ts

@@ -20,6 +20,8 @@ import type {
   ParsedTile,
   VertexAttribute,
 } from './types.js';
+import { applyCustomAttributeSemantics } from './CustomAttributes.js';
+import { bakeMercatorOffsets, type TileAnchorLike, type TileCenterLike } from './BakeMercator.js';
 
 /**
  * S3M 规范里 `DrawPrimitiveType` 的两个特殊值（原住 GeometryBuilder，随组装层
@@ -248,6 +250,8 @@ export interface PrimitiveAttributes {
    * 只有存在该流时才产生；解码语义见 core/TexCoordZ.ts。
    */
   aTexCoordZ?: PlainAttribute;
+  /** 逐顶点精确 Web 墨卡托偏移（Issue #15） */
+  aMercatorOffset?: PlainAttribute;
 }
 
 export interface PrimitiveData {
@@ -297,6 +301,11 @@ export interface AssembleOptions {
    * `useWorker: false` 或 Worker 崩溃降级时它落在主线程上。
    */
   dedupeCoincident?: boolean;
+  /** 是否烘焙精确 Web 墨卡托偏移（Issue #15） */
+  bakeMercator?: boolean;
+  tileAnchor?: TileAnchorLike;
+  tileCenter?: TileCenterLike;
+  vertexAttributeDescript?: unknown;
 }
 
 /* ------------------------------------------------------------------ 合批合并 */
@@ -556,8 +565,15 @@ interface SkeletonAsm {
 }
 
 /** 每骨架只解一次交错流（同一骨架被多个 pack / geode 引用时共享同一份数据） */
-function assembleSkeleton(name: string, geo: GeoPackageEntry, tile: ParsedTile, skipped: string[]): SkeletonAsm | null {
+function assembleSkeleton(
+  name: string,
+  geo: GeoPackageEntry,
+  tile: ParsedTile,
+  skipped: string[],
+  options?: AssembleOptions
+): SkeletonAsm | null {
   const vp = geo.vertexPackage;
+  applyCustomAttributeSemantics(vp, undefined, (tile as any).vertexAttributeDescript ?? options?.vertexAttributeDescript);
   const positionAttr = vp.vertexAttributes.find((a) => a.semantic === 'position');
   if (!positionAttr) {
     skipped.push(`${name} 无 position`);
@@ -585,11 +601,29 @@ function assembleSkeleton(name: string, geo: GeoPackageEntry, tile: ParsedTile,
     else if (attr.semantic === 'normal') normalData = deinterleave(attr);
     else if (attr.semantic === 'uv') uvData = deinterleave(attr);
     else if (attr.semantic === 'uv2') uv1Data = deinterleave(attr);
-    // custom0 = uv 的第三分量，官方 aTextureCoordMatrix：决定「这张贴图用不用、
-    // 用图集的哪个子区域、按 2 的几次幂缩放」。BIM/OSGB 转出来的数据依赖它，
-    // 丢掉就会把本该纯色的墙面贴上整张材质图。语义见 core/TexCoordZ.ts。
-    else if (attr.semantic === 'custom0' && (attr.components ?? 1) >= 1) {
-      texCoordZData = deinterleave(attr);
+    // uv 第三分量（官方 aTextureCoordMatrix）：决定「这张贴图用不用、
+    // 用图集的哪个子区域、按 2 的几次幂缩放」。语义见 core/TexCoordZ.ts。
+    // 注意：按语义查槽（找 TextureCoordMatrix），不要固定取 custom0；
+    // 绝对不能把 VertexWeight（高度值）等其它语义属性当成贴图矩阵；
+    // 若全为哨兵（-99999）则视为无第三分量，跳过采样/图集选择逻辑。
+    else if (
+      (attr.semantic === 'TextureCoordMatrix' ||
+        attr.semantic === 'aTextureCoordMatrix' ||
+        (attr.semantic === 'custom0' && !vp.vertexAttributes.some((a) => a.semantic === 'TextureCoordMatrix' || a.semantic === 'VertexWeight'))) &&
+      (attr.components ?? 1) >= 1
+    ) {
+      const plain = deinterleave(attr);
+      const arr = plain.array as Float32Array;
+      let hasValid = false;
+      for (let i = 0; i < arr.length; i++) {
+        if (arr[i]! >= -99900) {
+          hasValid = true;
+          break;
+        }
+      }
+      if (hasValid) {
+        texCoordZData = plain;
+      }
     }
   }
 
@@ -752,7 +786,7 @@ export function assembleTileGeometry(tile: ParsedTile, options: AssembleOptions
 
   const skeletons = new Map<string, SkeletonAsm>();
   for (const [name, geo] of Object.entries(tile.geoPackage ?? {})) {
-    const asm = assembleSkeleton(name, geo, tile, skipped);
+    const asm = assembleSkeleton(name, geo, tile, skipped, options);
     if (asm) {
       skeletons.set(name, asm);
       stats.vertices += geo.vertexPackage.verticesCount || 0;
@@ -878,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/core/types.ts

@@ -201,6 +201,7 @@ export interface ParsedTile {
   materials: unknown;
   pickInfo: unknown;
   extensions?: unknown;
+  vertexAttributeDescript?: unknown;
   /**
    * 解析成功、但渲染能力不完整的项（机器可读）。
    *

package/src/index.ts

@@ -51,17 +51,25 @@ 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 } from './tileset/S3MTileset.js';
-export type { TileNode, BuildTileFn, S3MTilesetOptions } from './tileset/S3MTileset.js';
+export { S3MTileset, parseConfigText, classifyDatasetKind } from './tileset/S3MTileset.js';
+export type { TileNode, BuildTileFn, S3MTilesetOptions, DatasetKind } from './tileset/S3MTileset.js';
 
 // —— 渲染层
 export { S3MViewer } from './render/S3MViewer.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';
 
@@ -138,6 +148,8 @@ export { setMaterialQuality, getMaterialQuality } from './render/StyleMaterial.j
 
 export { Picker } from './render/Picker.js';
 export { GpuEdgePass } from './render/GpuEdgePass.js';
+export { MotionBlurPass, normalizeMotionBlur, autoMotionBlurDamp } from './render/MotionBlurPass.js';
+export type { MotionBlurOptions, MotionBlurConfig, MotionBlurParams } from './render/MotionBlurPass.js';
 
 /* 三维空间分析内核：纯数学，不依赖 WebGL，可单独用于服务端 / Worker */
 export * from './analysis/index.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);