s3m-three 0.4.18 → 0.4.19

package/src/core/TileGeometry.ts

@@ -106,8 +106,16 @@ export function deinterleave(attr: VertexAttribute): PlainAttribute {
 }
 
 /** 把 u8 顶点色转成 float vec3，供着色器直接相乘（原 toColorAttribute） */
+/**
+ * 顶点色解成 RGBA。
+ *
+ * **必须带 alpha**：BIM 数据里"材质不透明、靠顶点色 alpha 表达半透明"是常见做法。
+ * 实测 `3D-BIMbuilding-2` 的 SMID 4421（`WhiteMaterial_1`，无纹理、`diffuse.a=1`）
+ * 顶点色是 u8 `(0,128,192,63)`，alpha = 0.247 —— 之前只取 RGB，这一片就变成实心青色。
+ * 官方片元里 `baseColorWithAlpha = vColor` 是 vec4，走的就是这条路。
+ */
 function colorData(attr: VertexAttribute | null, vertexCount: number): Float32Array {
-  const out = new Float32Array(vertexCount * 3);
+  const out = new Float32Array(vertexCount * 4);
   if (!attr) {
     out.fill(1);
     return out;
@@ -115,11 +123,14 @@ function colorData(attr: VertexAttribute | null, vertexCount: number): Float32Ar
   const src = attr.data;
   const comp = attr.components ?? 4;
   const scale = attr.dtype === 'u8' ? 1 / 255 : 1;
+  // 只有 RGB 的旧数据补 alpha = 1，避免留下 0（那会整片全透明）
+  const hasAlpha = comp >= 4;
   for (let i = 0; i < vertexCount; i++) {
     const o = i * comp;
-    out[i * 3] = (src[o] ?? 255) * scale;
-    out[i * 3 + 1] = (src[o + 1] ?? 255) * scale;
-    out[i * 3 + 2] = (src[o + 2] ?? 255) * scale;
+    out[i * 4] = (src[o] ?? 255) * scale;
+    out[i * 4 + 1] = (src[o + 1] ?? 255) * scale;
+    out[i * 4 + 2] = (src[o + 2] ?? 255) * scale;
+    out[i * 4 + 3] = hasAlpha ? (src[o + 3] ?? 255) * scale : 1;
   }
   return out;
 }
@@ -232,6 +243,11 @@ export interface PrimitiveAttributes {
   aAtlasRect?: PlainAttribute;
   aAtlasRect1?: PlainAttribute;
   aSecUv?: PlainAttribute;
+  /**
+   * uv 第三分量（文件里的 `custom0`，官方 `aTextureCoordMatrix`）。
+   * 只有存在该流时才产生；解码语义见 core/TexCoordZ.ts。
+   */
+  aTexCoordZ?: PlainAttribute;
 }
 
 export interface PrimitiveData {
@@ -258,6 +274,8 @@ export interface TileGeometryStats {
   edgeLines: number;
   /** 合批前独立网格数（batching 生效时 > meshes） */
   originalMeshes?: number;
+  /** 被剔除的「同单体共面重复」三角形数（数据自重叠，见 dropCoincidentTriangles） */
+  deduped?: number;
   skipped: string[];
 }
 
@@ -355,6 +373,7 @@ function mergeCandidates(candidates: Candidate[]): PrimitiveData {
   let hasUv = false;
   let hasUv1 = false;
   let hasAtlas = false;
+  let hasTexZ = false;
 
   for (const c of candidates) {
     totalVertices += c.vertexCount;
@@ -363,17 +382,19 @@ function mergeCandidates(candidates: Candidate[]): PrimitiveData {
     if (c.attrs.uv) hasUv = true;
     if (c.attrs.uv1) hasUv1 = true;
     if (c.attrs.aAtlasRect) hasAtlas = true;
+    if (c.attrs.aTexCoordZ) hasTexZ = true;
   }
 
   const mergedPos: PlainAttribute = { array: new Float32Array(totalVertices * 3), components: 3, normalized: false };
   const mergedNorm = hasNormal ? { array: new Float32Array(totalVertices * 3), components: 3, normalized: false } : null;
   const mergedUv = hasUv ? { array: new Float32Array(totalVertices * 2), components: 2, normalized: false } : null;
   const mergedUv1 = hasUv1 ? { array: new Float32Array(totalVertices * 2), components: 2, normalized: false } : null;
-  const mergedColor: PlainAttribute = { array: new Float32Array(totalVertices * 3), components: 3, normalized: false };
+  const mergedColor: PlainAttribute = { array: new Float32Array(totalVertices * 4), components: 4, normalized: false };
   const mergedBatchId: PlainAttribute = { array: new Float32Array(totalVertices), components: 1, normalized: false };
   const mergedRect0 = hasAtlas ? { array: new Float32Array(totalVertices * 4), components: 4, normalized: false } : null;
   const mergedRect1 = hasAtlas ? { array: new Float32Array(totalVertices * 4), components: 4, normalized: false } : null;
   const mergedSecUv = hasAtlas ? { array: new Float32Array(totalVertices * 2), components: 2, normalized: false } : null;
+  const mergedTexZ = hasTexZ ? { array: new Float32Array(totalVertices), components: 1, normalized: false } : null;
   const mergedIndices = (totalVertices > 65535 ? new Uint32Array(totalIndices) : new Uint16Array(totalIndices)) as Uint16Array | Uint32Array;
 
   const tmp = [0, 0, 0];
@@ -389,6 +410,8 @@ function mergeCandidates(candidates: Candidate[]): PrimitiveData {
     const normArr = attrs.normal?.array;
     const uvArr = attrs.uv?.array;
     const uv1Arr = attrs.uv1?.array;
+    const tzArr = attrs.aTexCoordZ?.array;
+    const tzOut = mergedTexZ?.array as Float32Array | undefined;
     const colArr = attrs.aColor.array;
     const bArr = attrs.aBatchId.array;
     const posOut = mergedPos.array as Float32Array;
@@ -433,15 +456,19 @@ function mergeCandidates(candidates: Candidate[]): PrimitiveData {
         uv1Out[dst * 2] = uv1Arr[i * 2];
         uv1Out[dst * 2 + 1] = uv1Arr[i * 2 + 1];
       }
-      // aColor
+      // aTexCoordZ（uv 第三分量）：缺这条流的候选补 0 = 单位变换
+      if (tzOut) tzOut[dst] = tzArr ? tzArr[i]! : 0;
+      // aColor（RGBA：alpha 是 4421 这类「材质不透明、顶点半透明」的唯一来源）
       if (colArr) {
-        colOut[dst * 3] = colArr[i * 3];
-        colOut[dst * 3 + 1] = colArr[i * 3 + 1];
-        colOut[dst * 3 + 2] = colArr[i * 3 + 2];
+        colOut[dst * 4] = colArr[i * 4];
+        colOut[dst * 4 + 1] = colArr[i * 4 + 1];
+        colOut[dst * 4 + 2] = colArr[i * 4 + 2];
+        colOut[dst * 4 + 3] = colArr[i * 4 + 3] ?? 1;
       } else {
-        colOut[dst * 3] = 1;
-        colOut[dst * 3 + 1] = 1;
-        colOut[dst * 3 + 2] = 1;
+        colOut[dst * 4] = 1;
+        colOut[dst * 4 + 1] = 1;
+        colOut[dst * 4 + 2] = 1;
+        colOut[dst * 4 + 3] = 1;
       }
       // aBatchId
       bOut[dst] = bArr ? bArr[i] : -1;
@@ -501,6 +528,7 @@ function mergeCandidates(candidates: Candidate[]): PrimitiveData {
       aAtlasRect: mergedRect0 ?? undefined,
       aAtlasRect1: mergedRect1 ?? undefined,
       aSecUv: mergedSecUv ?? undefined,
+      aTexCoordZ: mergedTexZ ?? undefined,
     },
     index: mergedIndices,
     bounds,
@@ -529,7 +557,7 @@ function assembleSkeleton(name: string, geo: GeoPackageEntry, tile: ParsedTile,
   const vertexCount = vp.verticesCount || 0;
   const attrs: PrimitiveAttributes = {
     position: deinterleave(positionAttr),
-    aColor: { array: new Float32Array(0), components: 3, normalized: false },
+    aColor: { array: new Float32Array(0), components: 4, normalized: false },
     aBatchId: { array: new Float32Array(0), components: 1, normalized: false },
   };
   let colorAttr: VertexAttribute | null = null;
@@ -537,6 +565,7 @@ function assembleSkeleton(name: string, geo: GeoPackageEntry, tile: ParsedTile,
   let normalData: PlainAttribute | null = null;
   let uvData: PlainAttribute | null = null;
   let uv1Data: PlainAttribute | null = null;
+  let texCoordZData: PlainAttribute | null = null;
 
   for (const attr of vp.vertexAttributes) {
     if (attr.divisor !== undefined) continue; // 实例属性不进顶点流
@@ -546,15 +575,22 @@ 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);
+    }
   }
 
-  attrs.aColor = { array: colorData(colorAttr, vertexCount), components: 3, normalized: false };
+  attrs.aColor = { array: colorData(colorAttr, vertexCount), components: 4, normalized: false };
   attrs.aBatchId = batchAttr
     ? { array: deinterleave(batchAttr).array, components: 1, normalized: false }
     : { array: new Float32Array(vertexCount).fill(-1), components: 1, normalized: false };
   if (normalData) attrs.normal = normalData;
   if (uvData) attrs.uv = uvData;
   if (uv1Data) attrs.uv1 = uv1Data;
+  if (texCoordZData) attrs.aTexCoordZ = texCoordZData;
 
   // S3MBLOCK 图集：逐顶点带子区域矩形；烘焙图用第二套 UV（aSecUv）
   const rects = tile.atlasRects?.[name];
@@ -624,6 +660,77 @@ function primitiveOf(
   };
 }
 
+/**
+ * 丢弃「同单体、同位置、同绕向」的重复三角形。
+ *
+ * 为什么需要：OSGB 转出来的 S3M 里确实存在**模型自重叠**。实测
+ * `3D-BIMbuilding-2` 的 `Tile_-85071_248749_0000` 中 geo E2F8F0 有 7156 个三角形，
+ * 其中 2276 个与前面某个三角形的三个顶点坐标完全相同（4 位小数，0.1 mm 内），
+ * `Tile_-85071_248750_0000` 的 geo 386340 是 58/156 —— 文件级统计，不是我们合批造出来的。
+ *
+ * 两个共面三角形各自光栅化时深度值只差最后几位，深度缓冲分不出谁在前，
+ * 屏幕上就是一片斜向摩尔纹（用户说的「模型重叠的斜线」）；若两份材质不同，
+ * 还会随绘制顺序闪成另一种颜色。
+ *
+ * 只丢**同 batchId** 的重复：跨单体的重叠是数据本身两个单体压在一起，
+ * 丢掉任何一个都会让那个 SMID 变得不可见 / 不可拾取，只能留给业务层处理。
+ *
+ * @param quantum 顶点坐标量化步长（米）。1 mm 足以合并「同一条边」的重复，
+ *                又不会误伤真正相邻的两个面。
+ */
+export function dropCoincidentTriangles(
+  index: Uint16Array | Uint32Array,
+  positions: ArrayLike<number>,
+  batchIds: ArrayLike<number> | null,
+  quantum = 1e-3
+): { index: Uint16Array | Uint32Array; dropped: number } {
+  const triCount = Math.floor(index.length / 3);
+  if (triCount === 0) return { index, dropped: 0 };
+
+  const inv = 1 / quantum;
+  const keyOf = (v: number): string =>
+    `${Math.round(positions[v * 3] * inv)},${Math.round(positions[v * 3 + 1] * inv)},${Math.round(positions[v * 3 + 2] * inv)}`;
+
+  const seen = new Set<string>();
+  const out = new (index instanceof Uint32Array ? Uint32Array : Uint16Array)(index.length);
+  let w = 0;
+  let dropped = 0;
+  for (let t = 0; t < triCount; t++) {
+    const a = index[t * 3];
+    const b = index[t * 3 + 1];
+    const c = index[t * 3 + 2];
+    const ka = keyOf(a);
+    const kb = keyOf(b);
+    const kc = keyOf(c);
+    // 把字典序最小的顶点转到首位，**保持绕向**：
+    // 绕向相同的两份才是「同一个面画了两遍」；正反两份是有意做的双面片，
+    // 它们共面且绕向相反，深度相等时后者覆盖前者、着色一致，不会出摩尔纹。
+    let k1 = ka;
+    let k2 = kb;
+    let k3 = kc;
+    if (kb <= ka && kb <= kc) {
+      k1 = kb;
+      k2 = kc;
+      k3 = ka;
+    } else if (kc <= ka && kc <= kb) {
+      k1 = kc;
+      k2 = ka;
+      k3 = kb;
+    }
+    const key = k1 + k2 + k3 + (batchIds ? `#${batchIds[a]}` : '');
+    if (seen.has(key)) {
+      dropped++;
+      continue;
+    }
+    seen.add(key);
+    out[w++] = a;
+    out[w++] = b;
+    out[w++] = c;
+  }
+  if (dropped === 0) return { index, dropped: 0 };
+  return { index: out.slice(0, w) as Uint16Array | Uint32Array, dropped };
+}
+
 /**
  * 瓦片几何组装入口。与 GeometryBuilder 的摆放/分组逻辑逐位对齐，
  * 但只产出纯数据 —— three 包装在渲染层。
@@ -741,5 +848,22 @@ export function assembleTileGeometry(tile: ParsedTile, options: AssembleOptions
     }
   }
 
+  // 数据自重叠：同单体、同位置、同绕向的重复三角形会互相压深度，出斜向摩尔纹。
+  // 只在**单 geo** 的 primitive 上做：合批产物里多个 geo 的 batchId 各自从 0 起，
+  // 混在一起会把「不同单体恰好共面」误判成同一条。
+  for (const p of primitives) {
+    if (p.primitiveType !== 4 || !p.index) continue;
+    if (p.geoNames.length > 1) continue;
+    const positions = p.attributes.position?.array;
+    if (!positions) continue;
+    const batchIds = p.attributes.aBatchId?.array ?? null;
+    const { index, dropped } = dropCoincidentTriangles(p.index, positions, batchIds);
+    if (dropped > 0) {
+      p.index = index;
+      p.indexCount = index.length;
+      stats.deduped = (stats.deduped ?? 0) + dropped;
+    }
+  }
+
   return { primitives, stats };
 }

package/src/core/degradations.ts

@@ -0,0 +1,74 @@
+/**
+ * 降级上报：解析成功、但能力不完整的数据要让调用方看得见
+ *
+ * 分界：**「解析不了」应该抛错，「解析得了但画不出该有的样子」必须显式说明。**
+ * 前者是 fail loudly，后者最容易被写成静默降级 —— 用户看到一个能跑但不对的画面，
+ * 会去怀疑数据、怀疑网络、怀疑显卡，很难怀疑到「这个分支还没做完」。
+ *
+ * 目前唯一一类降级是 3DGS：数据里的 `gsScale` / `gsRotation` 已经保留成顶点属性，
+ * 但那 4 字节的量化格式没有标定，所以只能按 Points 渲染，画不出 EWA splatting。
+ * 详见 `docs/FORMAT-NOTES.md` 第九节。
+ *
+ * 策略：
+ *   'warn'（默认） —— 首次遇到告警一次，画照画。不传参时与旧版行为一致（旧版不抛）。
+ *   'throw'        —— 直接拒绝这块瓦片，标 `permanent` 让调度器不要重试。
+ *                     给「宁可不出图，也不要出一张错的图」的场景用。
+ *   'silent'       —— 只记录到 `stats.degradations`，不告警。给已经自己接管提示的 UI 用。
+ */
+export type DegradationKind = 'gaussian-splatting-points';
+
+export type UnsupportedPolicy = 'warn' | 'throw' | 'silent';
+
+/** 告警文案要自己解释清楚「看到了什么」和「为什么不对」，不要只说一句 "unsupported" */
+const MESSAGES: Record<DegradationKind, string> = {
+  'gaussian-splatting-points':
+    '[s3m] 数据声明是 3DGS（高斯泼溅），但骨架里没有 gsScale / gsRotation 这两条流，' +
+    '只能按点云渲染。这不是数据损坏，但也不是预期的泼溅效果 —— ' +
+    '若确认是导出配置问题，可以 unsupported: "throw" 让它直接报错。',
+};
+
+export interface DegradationPlan {
+  /** 本次新出现的降级项（调用方据此告警） */
+  fresh: DegradationKind[];
+  /** 合并后的已知清单，写回 `stats.degradations` */
+  known: DegradationKind[];
+  /** 需要输出的告警文案（`silent` 时为空） */
+  messages: string[];
+  /** `throw` 策略下要抛的错（已标 `permanent`，调度器不要重试） */
+  error?: Error;
+}
+
+/**
+ * 纯函数：给定「本次遇到的降级项」和「已经报过的」，算出要做什么。
+ *
+ * 去重是必须的：一个 3DGS 服务一上来几十块瓦片都是同一个原因，
+ * 不去重就是几十条一模一样的告警，把真正有用的日志冲掉。
+ */
+export function planDegradations(
+  incoming: readonly DegradationKind[],
+  known: readonly DegradationKind[],
+  policy: UnsupportedPolicy
+): DegradationPlan {
+  const knownSet = new Set(known);
+  const fresh: DegradationKind[] = [];
+  for (const kind of incoming) {
+    if (!knownSet.has(kind)) {
+      knownSet.add(kind);
+      fresh.push(kind);
+    }
+  }
+
+  const messages = policy === 'warn' ? fresh.map((k) => MESSAGES[k] ?? `[s3m] 降级：${k}`) : [];
+
+  if (policy === 'throw' && fresh.length > 0) {
+    const err = new Error(
+      `[s3m] 数据包含当前实现不完整的特性，已按 unsupported: "throw" 拒绝：${fresh.join(', ')}。` +
+        `详见 docs/FORMAT-NOTES.md`
+    ) as Error & { permanent?: boolean };
+    // 格式层面的能力缺失，重试一万次也不会变好
+    err.permanent = true;
+    return { fresh, known: [...knownSet], messages, error: err };
+  }
+
+  return { fresh, known: [...knownSet], messages };
+}

package/src/core/types.ts

@@ -4,6 +4,7 @@
  * 这里只放「跨模块共享」的结构定义。模块内部的私有类型各自就近声明。
  */
 import type { Color } from 'three';
+import type { DegradationKind } from './degradations.js';
 
 /* ------------------------------------------------------------------ 数学 */
 
@@ -200,6 +201,14 @@ export interface ParsedTile {
   materials: unknown;
   pickInfo: unknown;
   extensions?: unknown;
+  /**
+   * 解析成功、但渲染能力不完整的项（机器可读）。
+   *
+   * 空 / 不传 = 这份数据的每一项能力都实现了。目前只会由 3DGS 数据填上
+   * `'gaussian-splatting-points'` —— 那种数据能加载、能看出轮廓，但画不出泼溅。
+   * 处置策略见 `core/degradations.ts` 与 `S3MTilesetOptions.unsupported`。
+   */
+  degradations?: DegradationKind[];
   /** 实际消费的字节数，应与 bytesTotal 相等 */
   bytesRead: number;
   bytesTotal: number;
@@ -230,6 +239,20 @@ export interface Stats {
   textures: number;
   /** 显存里驻留的几何数（renderer.info.memory.geometries） */
   geometries: number;
+  /**
+   * 泼溅瓦片里高斯最长轴的中位长度（米），用来估「屏幕上一个高斯多大」。
+   * 非泼溅数据为 undefined；顶点统计接口也会带上这个可选字段。
+   */
+  splatSigma?: number;
+  /** 泼溅瓦片里的高斯实例数；非泼溅数据为 undefined */
+  splatCount?: number;
+  /**
+   * 当前场景里出现过的降级项（去重）。空数组 = 所有数据的能力都完整实现了。
+   *
+   * 这是给 UI 用的：状态栏 / 诊断面板可以直接读它，不必去翻 console。
+   * 语义与 `ParsedTile.degradations` 一致，只是从「单块瓦片」聚到「整个场景」。
+   */
+  degradations: DegradationKind[];
 }
 
 /* ------------------------------------------------------------------ 单体属性 */
@@ -291,6 +314,15 @@ export interface StyleUniforms {
   uTexMix?: { value: number };
   /** 基础漫反射底色增益 / 直通自发光微调（0~1，默认 0.0） */
   uAmbientGain?: { value: number };
+  /**
+   * 金属度覆盖（0~1，**负数 = 不覆盖**，保持材质自身的值）。
+   *
+   * PBR 材质才有意义：注入在 `metalnessmap_fragment` 之后直接改写 metalnessFactor，
+   * 不重建材质也就不会重编译 program。lambert 光照模型没有这个 chunk，会被忽略。
+   */
+  uMetalness?: { value: number };
+  /** 粗糙度覆盖（0~1，负数 = 不覆盖）。同上，只有 pbr 生效。 */
+  uRoughness?: { value: number };
   /** 双纹理交叉淡化插值因子（0~1，0 = 状态 A，1 = 状态 B） */
   uBatchMix?: { value: number };
   /** 图层整体透明度（共享 uniform，透明度动画靠它做到 O(1)） */

package/src/index.ts

@@ -14,6 +14,8 @@ export { parseS3MB, S3MFormatError, S3M_VERSION, VertexTag, VertexTagV3 } from '
 export { parseS3M1, isS3M1Buffer } from './core/S3M1Parser.js';
 export type { ParseOptions, InflateFn } from './core/S3MBParser.js';
 export { BinaryReader } from './core/BinaryReader.js';
+export { planDegradations } from './core/degradations.js';
+export type { DegradationKind, UnsupportedPolicy, DegradationPlan } from './core/degradations.js';
 export { resolveFeature, measureSegments, buildAttributes, DEFAULT_FLOOR_HEIGHT } from './core/FeatureInfo.js';
 export { AttributeQuery } from './core/AttributeQuery.js';
 export type {
@@ -110,10 +112,15 @@ export type {
   PathFollowOptions,
 } 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';
+
 export { buildTileObjects } from './render/GeometryBuilder.js';
 export type { BuildTileOptions, BuildTileResult, TileBuildStats } from './render/GeometryBuilder.js';
 
-export { createTexture, PixelFormat, setMaxAnisotropy, setMaxTextureSize } from './render/TextureFactory.js';
+export { createTexture, PixelFormat, setMaxAnisotropy, setMaxTextureSize, setSrgbTextureDecode } from './render/TextureFactory.js';
+export { setColorPipeline, getColorPipeline } from './render/StyleMaterial.js';
+export type { ColorPipeline } from './render/StyleMaterial.js';
 export type { DecodedTexture } from './render/TextureFactory.js';
 
 export { resolveTextureKind, dxtPixelFormatOf, TextureCompress } from './core/TextureFormat.js';

package/src/render/DatasetManager.ts

@@ -11,6 +11,7 @@ import * as THREE from 'three';
 import { S3MTileset, usableGeoBounds } from '../tileset/S3MTileset.js';
 import type { AuthenticateFn } from '../core/AuthFetch.js';
 import type { Anchor } from '../core/types.js';
+import type { UnsupportedPolicy } from '../core/degradations.js';
 import { worldFromLngLat, type GeoAdapter } from './GeoAdapter.js';
 
 export type DatasetAlignment = 'origin' | 'bottom' | 'top' | 'center';
@@ -38,6 +39,8 @@ export interface S3MDatasetOptions {
   heightOffset?: number;
   /** 是否用 Web Worker 解析经典 .s3mb 瓦片（默认开，崩溃自动降级主线程），见 S3MTilesetOptions.useWorker */
   useWorker?: boolean;
+  /** 三角面材质深度偏移（共面摩尔纹 / 重合面归属），见 BuildTileOptions.polygonOffset */
+  polygonOffset?: { factor: number; units: number };
   /**
    * 是否对该数据集生成几何棱线（CPU 端 EdgesGeometry）。
    * - 不填：跟随全局 `style.edges`
@@ -49,6 +52,11 @@ export interface S3MDatasetOptions {
    * 适合多数据集走不同网关 / 不同 token 的场景。见 `AuthenticateFn`。
    */
   authenticate?: AuthenticateFn;
+  /**
+   * 本数据集遇到「解析得了但画不出该有的样子」时怎么办（默认 `'warn'`）。
+   * 目前只有 3DGS：按点渲染，做不出泼溅。见 `S3MTilesetOptions.unsupported`。
+   */
+  unsupported?: UnsupportedPolicy;
 }
 
 export interface S3MDatasetEntry {
@@ -211,8 +219,10 @@ export class DatasetManager {
       maxImageCache: ds.maxImageCache ?? maxImageCache,
       lodRangeScale: ds.lodRangeScale ?? defaultLodRangeScale,
       buildTile: buildTile ?? null,
+      polygonOffset: ds.polygonOffset,
       useWorker: ds.useWorker,
       authenticate: ds.authenticate ?? authenticate,
+      unsupported: ds.unsupported,
       uniforms: uniforms,
       onTile: (node) => {
         callbacks.onTile(node, entry);

package/src/render/FeatureStyleManager.ts

@@ -20,6 +20,7 @@ import {
 } from '../core/FeatureInfo.js';
 import type { AttributeQuery, AttributeQueryOptions, AttributeRow } from '../core/AttributeQuery.js';
 import type { StyledMaterial } from './StyleMaterial.js';
+import { restoreBaseBlendState } from './StyleMaterial.js';
 
 export interface GPUPathOptions {
   /** 绑定的路径索引 ID（0, 1, 2...） */
@@ -1011,8 +1012,9 @@ export class FeatureStyleManager {
       if (mat.userData.uBatchTexActive) {
         mat.userData.uBatchTexActive.value = 0;
       }
-      // 单体淡化清除后，把材质 transparent 还原成全局透明度语义
-      if (mat.transparent && !this._isLayerTransparent()) mat.transparent = false;
+      // 单体淡化清除后，把材质 transparent 还原成「自身语义 || 全局透明度」
+      // （只看全局透明度会把 alphaMode blend / 顶点 alpha 材质误关成不透明）
+      if (mat.transparent && !this._isLayerTransparent()) restoreBaseBlendState(mat, false);
       return;
     }
 
@@ -1020,7 +1022,7 @@ export class FeatureStyleManager {
       if (mat.userData.uBatchTexActive) {
         mat.userData.uBatchTexActive.value = 0;
       }
-      if (mat.transparent && !this._isLayerTransparent()) mat.transparent = false;
+      if (mat.transparent && !this._isLayerTransparent()) restoreBaseBlendState(mat, false);
       return;
     }
 
@@ -1052,9 +1054,9 @@ export class FeatureStyleManager {
       this.featureStyles
     );
 
-    // 有淡化单体时整块材质要开混合才有透明效果；清除后还原为全局透明度语义
+    // 有淡化单体时整块材质要开混合才有透明效果；清除后还原为「自身语义 || 全局透明度」
     if (hasFade && !mat.transparent) mat.transparent = true;
-    else if (!hasFade && mat.transparent && !this._isLayerTransparent()) mat.transparent = false;
+    else if (!hasFade && mat.transparent && !this._isLayerTransparent()) restoreBaseBlendState(mat, false);
 
     if (conflicts > 0 && !this._batchConflictWarned) {
       this._batchConflictWarned = true;