s3m-three 0.4.18 → 0.4.20

package/dist/render/viewer/types.d.ts

@@ -0,0 +1,250 @@
+/**
+ * `S3MViewer` 的公共类型：选项、光照、拾取结果、路径跟随。
+ *
+ * 从 `S3MViewer.ts` 整块搬出来的纯类型定义（零运行时）。搬出去的原因只有一个：
+ * 这些类型占了两百多行，和「类怎么实现」没有关系，留在主类里会把真正的逻辑冲淡。
+ *
+ * `S3MViewer.ts` 仍然 re-export 它们，所以 `import { S3MViewerOptions } from '.../S3MViewer'`
+ * 这类既有写法不受影响。
+ */
+import * as THREE from 'three';
+import type { EasingFn, EasingName } from '../../anim/easing.js';
+import type { FeatureAttributes, GeoPackageEntry, ParsedTile, Stats } from '../../core/types.js';
+import type { UnsupportedPolicy } from '../../core/degradations.js';
+import type { AttributeQueryOptions } from '../../core/AttributeQuery.js';
+import type { AuthenticateFn } from '../../core/AuthFetch.js';
+import type { LightingPreset } from '../lightingPreset.js';
+import type { S3MStyle } from '../StyleMaterial.js';
+import type { BuildTileFn } from '../../tileset/S3MTileset.js';
+import type { S3MDatasetEntry, S3MDatasetOptions } from '../DatasetManager.js';
+import type { GroundOptions } from '../GroundManager.js';
+export interface PickResult extends FeatureAttributes {
+    datasetId: string;
+    datasetName: string;
+    /** 网格编号 */
+    objectId: number;
+    /** 单体控制位（顶点区间型 = batchId，实例化型 = 状态纹理下标），-1 表示没有单体化信息 */
+    batchId: number;
+    /** 实例化几何命中的实例序号；非实例化为 undefined */
+    instanceIndex?: number;
+    skeletonName: string;
+    /** 单体中心经纬度，拿不到时为 null */
+    centerLngLat: [number, number] | null;
+    /** 命中点三维场景坐标 [x, y, z]（米，场景 ENU） */
+    point?: [number, number, number] | null;
+    /** 命中点经纬度 [lng, lat] */
+    lngLat?: [number, number] | null;
+    /** 命中点高程（米） */
+    altitude?: number | null;
+    mesh: THREE.Mesh;
+}
+export interface LightOptions {
+    /** 环境光强度，默认 0.4 */
+    ambientIntensity?: number;
+    /** 环境光颜色，十六进制或 CSS 颜色字符串，默认 0xffffff */
+    ambientColor?: number | string;
+    /** 半球光天空强度，默认 0.8 */
+    hemisphereIntensity?: number;
+    /** 半球光天空颜色，默认 0xffffff */
+    hemisphereColor?: number | string;
+    /** 半球光地面颜色，默认 0xb6c0cb */
+    hemisphereGroundColor?: number | string;
+    /** 主平行光强度，默认 1.0 */
+    keyLightIntensity?: number;
+    /** 主平行光强度别名（兼容写法） */
+    mainIntensity?: number;
+    /** 主平行光颜色，默认 0xffffff */
+    keyLightColor?: number | string;
+    /** 主平行光颜色别名（兼容写法） */
+    mainColor?: number | string;
+    /** 补光强度，默认 0.35 */
+    fillLightIntensity?: number;
+    /** 补光颜色，默认 0xffffff */
+    fillLightColor?: number | string;
+    /**
+     * 光照朝向模式：
+     * - 'headlamp': 默认头灯模式（随相机 bearing 旋转，受光面始终面向镜头）
+     * - 'fixed': 固定世界坐标方位角（如太阳光模拟）
+     */
+    mode?: 'headlamp' | 'fixed';
+    /** 方位角（度，0~360），固定模式下以正北为 0 顺时针，头灯模式下为相机相对偏角，默认 150 */
+    azimuth?: number;
+    /** 太阳/光源仰角（度，0~90），默认 50 */
+    altitude?: number;
+}
+export interface S3MViewerOptions {
+    /**
+     * 光照预设：
+     * - `'default'`（默认）：现有 PBR 打光，亮部线性总量 ≈ 2.55；
+     * - `'supermap'`：对齐 iClient3D 观感（暗部 0.46 / 亮部 2.44），远处不发灰、饱和度更高。
+     *   只改光源，不动材质与色调映射；`light` 里的显式字段仍然优先生效。
+     */
+    lightingPreset?: LightingPreset;
+    /** 光照参数配置（强度、颜色、朝向模式、太阳方位角/仰角等） */
+    light?: LightOptions;
+    /**
+     * 三角面材质深度偏移（共面摩尔纹 / 重合面归属的人工定序）。
+     * 例：factor -1 / units -2 把配置材质的片元深度略微拉近。
+     * 这是 mesh 粒度开关，见 BuildTileOptions.polygonOffset 的说明。
+     */
+    polygonOffset?: {
+        factor: number;
+        units: number;
+    };
+    /**
+     * 色调映射模式（默认 THREE.NoToneMapping，避免 ACESFilmic 压暗中暗部及导致底图与建筑色彩失真；
+     * 可传入 THREE.ACESFilmicToneMapping、THREE.LinearToneMapping、THREE.ReinhardToneMapping 等）
+     */
+    toneMapping?: THREE.ToneMapping;
+    /** 色调映射曝光度，默认 1.0 */
+    toneMappingExposure?: number;
+    /** 全局总驻留瓦片上限（多数据集多图层共享预算），在所有可见数据集之间动态均衡分配，彻底防止爆显存 */
+    totalMaxTiles?: number;
+    /** 单数据集简写 */
+    configUrl?: string;
+    /** 多数据集 */
+    datasets?: S3MDatasetOptions[];
+    style?: Partial<S3MStyle>;
+    /** 3D 物理地表面 / 基坑开挖配置 */
+    ground?: GroundOptions;
+    pickable?: boolean;
+    /** 每个数据集最多驻留瓦片 */
+    maxTiles?: number;
+    /** 每个数据集并发请求数 */
+    maxConcurrent?: number;
+    /**
+     * 图层级默认的降级处置策略（默认 `'warn'`），数据集可用 `unsupported` 单独覆盖。
+     * 见 `S3MTilesetOptions.unsupported`。
+     */
+    unsupported?: UnsupportedPolicy;
+    /** 是否用 Web Worker 解析经典 .s3mb 瓦片（默认开，崩溃自动降级主线程），见 S3MTilesetOptions.useWorker */
+    useWorker?: boolean;
+    /** LOD 切换范围缩放系数（默认 1.0），> 1 更倾向保留粗模，< 1 提前换细模 */
+    lodRangeScale?: number;
+    /**
+     * LOD 判定用屏幕高度时的「设备像素比上限」（默认不限制，行为与旧版一致）。
+     *
+     * LOD 的屏幕空间误差按 `canvasHeight` 物理像素算（与官方 `calcPixFromCam` 同口径），
+     * 于是 3x DPR 的手机上判定高度是 2556 而不是 852，细化层数与瓦片数都会远多于桌面。
+     * 传 2 表示「按 CSS 高度 × 2 截断」，砍掉 3x 屏的超采样余量；传 `Infinity` = 不截断。
+     *
+     * 代价：截断会把每块瓦片的屏幕投影放大同样倍数，几何误差与纹理密度同步变差，
+     * 所以默认不启用，由接入方按设备档位自行决定。运行时可用 `setLodPixelRatioCap()` 调整。
+     */
+    lodPixelRatioCap?: number;
+    /**
+     * 每个数据集驻留三角形总数的软上限（默认不限制）。
+     * 见 `S3MTilesetOptions.maxTriangles`：瓦片数管不住的场景（精模、大面片）用这条刹车。
+     */
+    maxTriangles?: number;
+    /**
+     * 纹理缓存条数上限（默认 128）。一条对应一张已解码的瓦片纹理，
+     * 1024² 的 RGBA 一张约 4MB，128 条就是 512MB 显存 —— 低端设备建议 32~48。
+     * 与 `maxTextureSize` 配合使用：后者降单张尺寸，这条降张数。
+     */
+    maxImageCache?: number;
+    /**
+     * 各向异性过滤上限（默认不封顶，取 GPU 报的最大值，通常 16）。
+     * 移动端封到 4 或 8 肉眼通常无差，采样成本明显下降。只影响**之后创建**的纹理。
+     */
+    anisotropyCap?: number;
+    /**
+     * 纹理长边像素上限（默认不限制）。
+     * 非图集的 RGBA / WebP 纹理会按 2× 盒式滤波逐次减半到上限内；DXT 压缩直传与
+     * 图集（UV 已重映射）不受影响。手机上 1024 与 2048 肉眼几乎无差，显存差 4 倍。
+     */
+    maxTextureSize?: number;
+    /**
+     * 光照模型（默认 `'pbr'`）。
+     *
+     * - `'pbr'`：`MeshStandardMaterial`，GGX + 环境球谐，质感最好也最贵
+     * - `'lambert'`：`MeshLambertMaterial`，只保留漫反射 + 平行光，片元开销约省一半；
+     *   白模 / 纯色 / 按高度着色这类不需要高光的模式肉眼差别很小
+     *
+     * 模块级全局状态：同页多个图层会互相覆盖，后创建的那个决定全局。
+     * 只影响**之后创建**的材质 —— 已加载的瓦片要重新加载才会换。
+     */
+    materialQuality?: 'pbr' | 'lambert';
+    /** 自定义瓦片构建器（测试 / 服务端渲染时注入） */
+    buildTile?: BuildTileFn | null;
+    /**
+     * 可选：业务属性查询配置（iServer 数据服务）。
+     * 配上之后才能用 `colorByField()` 按业务字段着色 —— 属性值不在 S3M 瓦片里，只能去数据服务查。
+     */
+    attributes?: AttributeQueryOptions;
+    /** 宿主请求重画的信号。MapLibre 传 `() => map.triggerRepaint()`；纯 three 宿主传自己的渲染循环 */
+    onRequestRepaint?: () => void;
+    /** 地图朝向（弧度），用于让灯光跟着视角走。不传则灯光方向固定 */
+    getBearing?: () => number;
+    /**
+     * 鉴权适配函数（全局默认，数据集可用自己的 `authenticate` 覆盖）。
+     * 内核主线程发出的全部请求（配置 scp / 瓦片 / 子图集 / 棱线缓存 / 属性查询）
+     * 发出前都过一遍，可改写 URL（加 `?token=`）或附加请求头。
+     * 不传 = 行为与旧版完全一致。见 `AuthenticateFn`。
+     */
+    authenticate?: AuthenticateFn;
+    onStats?: (stats: Stats) => void;
+    onReady?: (entry: S3MDatasetEntry) => void;
+    onPick?: (result: PickResult | null) => void;
+    onError?: (error: unknown) => void;
+    /**
+     * 首次出现瓦片后自动预热另一种 `shading` 变体（默认开）。
+     *
+     * `flat` / `smooth` 是编译期变体，不预热的话第一次 `setStyle({ shading })` 会同步
+     * 编译着色器、卡一帧。预热在首帧之后异步做，期间跳一两帧渲染，肉眼不可见。
+     */
+    prewarmShading?: boolean;
+}
+export interface PickableRef {
+    datasetId: string;
+    mesh: THREE.Mesh;
+    tile: ParsedTile;
+    skeletonName: string;
+}
+export interface MeshUserData {
+    pickId?: number;
+    datasetId?: string;
+    skeletonName?: string;
+    geoRef?: GeoPackageEntry;
+    tileRef?: ParsedTile;
+    primitiveType?: number;
+    /** 点云对象（THREE.Points）：不吃面着色，也没有棱可描 */
+    isPointCloud?: boolean;
+    /** CPU 端现算的棱线对象（等宽线 Mesh） */
+    edges?: THREE.Object3D | null;
+    /** 背面外扩轮廓壳（edges 含 'hull' 时挂上） */
+    edgeHull?: THREE.Mesh | null;
+    /** 数据自带棱线包（此时不再用 EdgesGeometry 现算） */
+    nativeEdges?: boolean;
+    /** 数据本身有没有棱线包（不受 forceCpuEdges 影响，用来运行中切换时重算 nativeEdges） */
+    nativeEdgesRaw?: boolean;
+    /** 数据自带的棱线对象本身 */
+    isEdgeLines?: boolean;
+    /** CPU 现算的等宽棱线（与 isEdgeLines 区分，便于刷新样式） */
+    isThickEdge?: boolean;
+    /** 背面外扩轮廓壳（edges 含 'hull' 时挂上） */
+    isEdgeHull?: boolean;
+    /** 选中单体的棱线对象 */
+    isSelectionEdge?: boolean;
+    /** 该网格正在淡入时占用的动画通道 key，瓦片淘汰时要回收 */
+    tileFadeKey?: string;
+    pickMaterial?: THREE.Material;
+    [key: string]: unknown;
+}
+export interface PathFollowOptions {
+    /** 走完全程的时长（毫秒）。不传则按 speed 或默认 2000ms 推算 */
+    duration?: number;
+    /** 线速度（米/秒）。给了 duration 就以 duration 为准 */
+    speed?: number;
+    /** 是否循环 */
+    loop?: boolean;
+    /** 是否把折线首尾相连 */
+    closed?: boolean;
+    /** 缓动曲线：作用在**已走距离**上，默认 linear（恒速） */
+    easing?: EasingName | EasingFn;
+    /** 路径整体偏移（米），相当于路径原点 */
+    offset?: [number, number, number];
+    /** 单次走完（非循环）时回调 */
+    onComplete?: () => void;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/render/viewer/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/render/viewer/types.ts"],"names":[],"mappings":"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"}

package/dist/render/viewer/types.js

@@ -0,0 +1,3 @@
+export {};
+/* ------------------------------------------------------------------ 图层 */
+//# sourceMappingURL=types.js.map

package/dist/render/viewer/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/render/viewer/types.ts"],"names":[],"mappings":";AAgQA,2EAA2E"}

package/dist/tileset/S3MTileset.d.ts

@@ -1,3 +1,4 @@
+import type { UnsupportedPolicy } from '../core/degradations.js';
 import { type AuthenticateFn } from '../core/AuthFetch.js';
 import type { S3MBlockAtlasImage } from '../core/S3MBlockParser.js';
 import type { Anchor, ParsedTile, Stats, StyleUniforms } from '../core/types.js';
@@ -65,6 +66,14 @@ export interface TileNode {
     parentUrl?: string;
     /** 当前帧是否满足细化条件 */
     needRefine?: boolean;
+    /**
+     * 该瓦片高斯的最长轴中位长度（米）。非泼溅瓦片为 undefined。
+     * 有值时细化判据改走 core/SplatLod.ts —— 点云的各层 σ 恒定，
+     * 包围球像素误差那套判据对它无效（见该文件头部）。
+     */
+    splatSigma?: number;
+    /** 该瓦片的高斯实例数（泼溅瓦片才有） */
+    splatCount?: number;
     /** 该瓦片引用的纹理 key 清单，用于引用计数与显存释放 */
     textureKeys?: string[];
     /** 瓦片构建产生的统计信息，用于淘汰时准确扣减 stats */
@@ -80,6 +89,11 @@ export type BuildTileFn = (tile: ParsedTile, options: {
     uniforms: StyleUniforms | null;
     /** Worker 侧已完成的纯数据几何组装（经典 .s3mb 路径），构建器直接包装成 three 对象 */
     assembled?: TileGeometryData;
+    /** 深度偏移配置（透传给 buildTileObjects），见 BuildTileOptions.polygonOffset */
+    polygonOffset?: {
+        factor: number;
+        units: number;
+    };
 }) => Promise<{
     group: Group;
     stats: Partial<Stats>;
@@ -91,6 +105,11 @@ export interface S3MTilesetOptions {
     /** 原始图像/子图集缓存上限（LRU），默认 128 */
     maxImageCache?: number;
     buildTile?: BuildTileFn | null;
+    /** 三角面材质深度偏移（共面摩尔纹 / 重合面归属），透传给 buildTileObjects */
+    polygonOffset?: {
+        factor: number;
+        units: number;
+    };
     /**
      * 是否用 Web Worker 解析经典 `.s3mb` 瓦片（默认开）。
      *
@@ -135,6 +154,17 @@ export interface S3MTilesetOptions {
      * 子图集）发出前过一遍，可改写 URL（加 `?token=`）或附加请求头。见 `AuthenticateFn`。
      */
     authenticate?: AuthenticateFn;
+    /**
+     * 遇到「解析得了但画不出该有的样子」的数据时怎么办。**默认 `'warn'`**。
+     *
+     * 目前只有一类：3DGS 数据按点渲染（`gsScale` / `gsRotation` 的量化格式未标定）。
+     *   'warn'   —— 首次遇到告警一次，照常出图。旧版没有这个开关，但也不告警，
+     *               所以这里的差异只有多一条日志，不传参时的渲染路径逐字未变。
+     *   'throw'  —— 直接拒绝这类瓦片（标 `permanent`，不重试）。给「宁可不显示，
+     *               也不要显示一个看不出是错的画面」的场景。
+     *   'silent' —— 只记录到 `stats.degradations`，由 UI 自己决定怎么提示。
+     */
+    unsupported?: UnsupportedPolicy;
 }
 export declare class S3MTileset {
     configUrl: string;
@@ -194,13 +224,14 @@ export declare class S3MTileset {
     private readonly _maxRetries;
     /** 鉴权适配函数；undefined = 不做任何改写（行为与旧版一致） */
     readonly authenticate: AuthenticateFn | undefined;
+    /** 能力降级的处置策略，默认 'warn'，见 `S3MTilesetOptions.unsupported` */
+    private readonly _unsupported;
     /** 失败重试计数与下次可用时间，退避期间 _enqueue 会直接跳过 */
     private readonly _retryCount;
     private readonly _retryAt;
     /** 子瓦片 URL → 父瓦片 URL，用于淘汰后补洞 */
     private readonly _parentOf;
     private _frame;
-    private _lodDbgOnce;
     /** 格式类永久错误只向上报一次，避免整棵瓦片树刷同样的日志 */
     private _permanentReported;
     /** 请求量的硬上限（软上限 maxTiles 的超额余量），见构造函数注释 */
@@ -208,6 +239,7 @@ export declare class S3MTileset {
     /** 本数据集是 S3M 1.x（SuperMapCache，.s3m）：子瓦地址规则与 3.x 不同 */
     private isS3MV1;
     private _buildTile;
+    private readonly _polygonOffset;
     private readonly _uniforms;
     /** 经典 .s3mb 的 Worker 解析客户端；undefined = 尚未尝试创建，null = 不可用/已降级 */
     private _workerClient;
@@ -345,6 +377,15 @@ export declare class S3MTileset {
      * 现在换图统一走 `_fillExternalAtlases` + `evaluateAtlasUpgrade` 的验证流程。
      */
     private _upgradeAtlasLod;
+    /**
+     * 处置一块瓦片的降级项。
+     *
+     * 位置很讲究：必须在 `build` 之前。`'throw'` 策略下要在浪费一次几何组装
+     * （几十万面的解交错 + 合批）之前就拒绝，否则「拒绝」本身也成了开销。
+     *
+     * 抛出的错带 `permanent`，由 `_load` 的 catch 识别 → 不重试、直接进 failed。
+     */
+    private _noteDegradations;
     private _load;
     /**
      * @param camEnu 相机在该数据集局部 ENU 坐标系中的位置（米）

package/dist/tileset/S3MTileset.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"S3MTileset.d.ts","sourceRoot":"","sources":["../../src/tileset/S3MTileset.ts"],"names":[],"mappings":"AASA,OAAO,EAAa,KAAK,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAatE,OAAO,KAAK,EAEV,kBAAkB,EAInB,MAAM,2BAA2B,CAAC;AACnC,OAAO,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACjF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAChE,OAAO,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC;AAgC5C;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CASnD;AAMD,kBAAkB;AAClB,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;CACb;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,OAAO,GAAG,SAAS,GAAG,IAAI,CAS5D;AAED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAiB7F;AAED,wEAAwE;AACxE,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CA2DrE;AAED,MAAM,WAAW,QAAQ;IACvB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,UAAU,CAAC;IACjB,KAAK,EAAE,KAAK,CAAC;IACb,MAAM,EAAE;QAAE,MAAM,EAAE;YAAE,CAAC,EAAE,MAAM,CAAC;YAAC,CAAC,EAAE,MAAM,CAAC;YAAC,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IAC/E,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,sCAAsC;IACtC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,8BAA8B;IAC9B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,sCAAsC;IACtC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,kBAAkB;IAClB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,kCAAkC;IAClC,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,kCAAkC;IAClC,KAAK,CAAC,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;CACjE;AAED,yCAAyC;AACzC,MAAM,MAAM,WAAW,GAAG,CACxB,IAAI,EAAE,UAAU,EAChB,OAAO,EAAE;IACP,YAAY,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,QAAQ,EAAE,aAAa,GAAG,IAAI,CAAC;IAC/B,yDAAyD;IACzD,SAAS,CAAC,EAAE,gBAAgB,CAAC;CAC9B,KACE,OAAO,CAAC;IAAE,KAAK,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,OAAO,CAAC,KAAK,CAAC,CAAA;CAAE,CAAC,CAAC;AAEtD,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,+BAA+B;IAC/B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,SAAS,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;IAC/B;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,QAAQ,CAAC,EAAE,aAAa,GAAG,IAAI,CAAC;IAChC,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,QAAQ,KAAK,IAAI,CAAC;IAClC,6CAA6C;IAC7C,aAAa,CAAC,EAAE,CAAC,IAAI,EAAE,QAAQ,KAAK,IAAI,CAAC;IACzC,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IACpC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;IACnC,0CAA0C;IAC1C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,iDAAiD;IACjD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;;;;;OAQG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;;;;;OAQG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;OAGG;IACH,YAAY,CAAC,EAAE,cAAc,CAAC;CAC/B;AAED,qBAAa,UAAU;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAQ;IAC9C;;;;OAIG;IACH,OAAO,CAAC,eAAe,CAA4B;IACnD,MAAM,EAAE,MAAM,CAAiC;IAE/C,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,CAAM;IACjC,QAAQ,CAAC,KAAK,wBAA+B;IAC7C,QAAQ,CAAC,MAAM,cAAqB;IACpC,QAAQ,CAAC,YAAY,uBAA8B;IACnD,aAAa,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,QAAQ,CAAC,YAAY,CAA6B;IAC1D,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAA+B;IAChE,QAAQ,CAAC,OAAO,cAAqB;IACrC,4DAA4D;IAC5D,QAAQ,EAAE,OAAO,CAAC;IAClB,mDAAmD;IACnD,QAAQ,CAAC,aAAa,yCAAgD;IACtE,uDAAuD;IACvD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAuC;IACnE,oDAAoD;IACpD,QAAQ,CAAC,kBAAkB,yCAAgD;IAC3E;;;OAGG;IACH,QAAQ,CAAC,gBAAgB,2CAAkD;IAC3E,gDAAgD;IAChD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAoC;IACjE,4BAA4B;IAC5B,QAAQ,CAAC,aAAa,cAAqB;IAC3C,uCAAuC;IACvC,QAAQ,CAAC,mBAAmB,sBAA6B;IAGzD,QAAQ,CAAC,KAAK,EAAE,KAAK,CAYnB;IAEF,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IAEtB,qCAAqC;IACrC,IAAI,WAAW,IAAI;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAMrD;IAED,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA2B;IACnD,OAAO,CAAC,QAAQ,CAAC,cAAc,CAA2B;IAC1D,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA2B;IACpD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAyB;IACrD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,yCAAyC;IACzC,QAAQ,CAAC,YAAY,EAAE,cAAc,GAAG,SAAS,CAAC;IAClD,wCAAwC;IACxC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA6B;IACzD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA6B;IACtD,gCAAgC;IAChC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA6B;IACvD,OAAO,CAAC,MAAM,CAAK;IACnB,OAAO,CAAC,WAAW,CAAS;IAC5B,kCAAkC;IAClC,OAAO,CAAC,kBAAkB,CAAS;IACnC,0CAA0C;IAC1C,OAAO,SAAM;IACb,uDAAuD;IACvD,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,UAAU,CAAqB;IACvC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAuB;IACjD,gEAAgE;IAChE,OAAO,CAAC,aAAa,CAAqC;IAAE,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAU;IACjG,OAAO,CAAC,MAAM,CAAgB;IAC9B,OAAO,CAAC,OAAO,CAAK;gBAER,OAAO,EAAE,iBAAiB;IA4BhC,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IA0C3B,OAAO,CAAC,QAAQ;IAiBhB;;;;;;;;;;;OAWG;IACH,6BAA6B;IAC7B,oBAAoB,CAAC,GAAG,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,GAAG,IAAI;IAW9D,sBAAsB;IACtB,cAAc,CAAC,MAAM,EAAE,QAAQ,GAAG,IAAI;IAiCtC,yBAAyB;IACzB,gBAAgB,CAAC,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,kBAAkB,GAAG,IAAI,GAAG,IAAI;IAQlE,aAAa;IACb,gBAAgB,CAAC,EAAE,EAAE,MAAM,GAAG,kBAAkB,GAAG,IAAI,GAAG,SAAS;IAInE,8BAA8B;IAC9B,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,kBAAkB,EAAE,GAAG,IAAI,GAAG,IAAI;IAQrE,kBAAkB;IAClB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,kBAAkB,EAAE,GAAG,IAAI,GAAG,SAAS;IAIrE,OAAO,CAAC,SAAS;IA4CjB,yCAAyC;IACzC,OAAO,CAAC,kBAAkB;IAM1B;;;OAGG;IACH,eAAe,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI;IAIhC;;;;;;;;OAQG;IACH,OAAO,CAAC,WAAW;IAgBnB;;;;;;;OAOG;IACH,OAAO,CAAC,WAAW;IAyBnB,mCAAmC;IACnC,WAAW,IAAI,MAAM;IAQrB,OAAO,CAAC,KAAK;IAWb;;;;;;;OAOG;IACH,OAAO,CAAC,cAAc;IAqCtB,OAAO,CAAC,QAAQ;YAOF,QAAQ;IAQtB;;;;OAIG;YACW,iBAAiB;IAoB/B;;;;;OAKG;IACH,OAAO,CAAC,eAAe;IAUvB;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;YACW,oBAAoB;IAuJlC,mDAAmD;IACnD,OAAO,CAAC,gBAAgB;IASxB;;;;;;OAMG;YACW,cAAc;IAiB5B,gDAAgD;YAClC,cAAc;IAc5B;;;;;;OAMG;YACW,gBAAgB;YAIhB,KAAK;IAmJnB;;;;;OAKG;IACH,MAAM,CAAC,MAAM,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO;IAwIvF,OAAO,CAAC,qBAAqB;IAuD7B,OAAO,IAAI,IAAI;CAiBhB"}
+{"version":3,"file":"S3MTileset.d.ts","sourceRoot":"","sources":["../../src/tileset/S3MTileset.ts"],"names":[],"mappings":"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"}

package/dist/tileset/S3MTileset.js

@@ -7,6 +7,8 @@
  *   命中阈值就请求 childTile，实现渐进式细化。
  */
 import { parseS3MB } from '../core/S3MBParser.js';
+import { planDegradations } from '../core/degradations.js';
+import { splatLodDecision } from '../core/SplatLod.js';
 import { authFetch } from '../core/AuthFetch.js';
 import { getSharedS3MWorker, WorkerDeadError } from '../worker/S3MWorkerClient.js';
 import { composeLeafAtlas, expandTexblockRequestNames, parseS3MBlockGroups, parseTexblockSegments, rebuildBlockTextureState, unpackBlockTextures, } from '../core/S3MBlockParser.js';
@@ -221,6 +223,7 @@ export class S3MTileset {
         programs: 0,
         textures: 0,
         geometries: 0,
+        degradations: [],
     };
     maxConcurrent;
     maxTiles;
@@ -245,13 +248,14 @@ export class S3MTileset {
     _maxRetries;
     /** 鉴权适配函数；undefined = 不做任何改写（行为与旧版一致） */
     authenticate;
+    /** 能力降级的处置策略，默认 'warn'，见 `S3MTilesetOptions.unsupported` */
+    _unsupported;
     /** 失败重试计数与下次可用时间，退避期间 _enqueue 会直接跳过 */
     _retryCount = new Map();
     _retryAt = new Map();
     /** 子瓦片 URL → 父瓦片 URL，用于淘汰后补洞 */
     _parentOf = new Map();
     _frame = 0;
-    _lodDbgOnce = false;
     /** 格式类永久错误只向上报一次，避免整棵瓦片树刷同样的日志 */
     _permanentReported = false;
     /** 请求量的硬上限（软上限 maxTiles 的超额余量），见构造函数注释 */
@@ -259,6 +263,7 @@ export class S3MTileset {
     /** 本数据集是 S3M 1.x（SuperMapCache，.s3m）：子瓦地址规则与 3.x 不同 */
     isS3MV1 = false;
     _buildTile;
+    _polygonOffset;
     _uniforms;
     /** 经典 .s3mb 的 Worker 解析客户端；undefined = 尚未尝试创建，null = 不可用/已降级 */
     _workerClient;
@@ -274,8 +279,10 @@ export class S3MTileset {
         this._onProgress = options.onProgress ?? (() => { });
         this._maxRetries = Math.max(0, options.maxRetries ?? 2);
         this.authenticate = options.authenticate;
+        this._unsupported = options.unsupported ?? 'warn';
         // 渲染层可注入：Node 环境下不需要 three，也能跑 URL / 解析链路
         this._buildTile = options.buildTile ?? null;
+        this._polygonOffset = options.polygonOffset;
         // 着色器共享 uniform，由 S3MLayer 持有并传进来
         this._uniforms = options.uniforms ?? null;
         this._useWorker = options.useWorker !== false;
@@ -908,6 +915,25 @@ export class S3MTileset {
     async _upgradeAtlasLod(_tile, _url) {
         return;
     }
+    /**
+     * 处置一块瓦片的降级项。
+     *
+     * 位置很讲究：必须在 `build` 之前。`'throw'` 策略下要在浪费一次几何组装
+     * （几十万面的解交错 + 合批）之前就拒绝，否则「拒绝」本身也成了开销。
+     *
+     * 抛出的错带 `permanent`，由 `_load` 的 catch 识别 → 不重试、直接进 failed。
+     */
+    _noteDegradations(tile) {
+        const incoming = tile.degradations;
+        if (!incoming?.length)
+            return;
+        const plan = planDegradations(incoming, this.stats.degradations, this._unsupported);
+        this.stats.degradations = plan.known;
+        for (const msg of plan.messages)
+            console.warn(msg);
+        if (plan.error)
+            throw plan.error;
+    }
     async _load(url) {
         if (this.nodes.has(url) || this.pending.has(url) || this.failed.has(url))
             return;
@@ -957,11 +983,14 @@ export class S3MTileset {
                 await this._fillExternalAtlases(tile, baseUrl);
                 await this._upgradeAtlasLod(tile, baseUrl);
             }
+            // 解析成功但能力不完整的（目前只有 3DGS），在花力气建几何之前先决定处置
+            this._noteDegradations(tile);
             const build = await this._builder();
             const buildRes = await build(tile, {
                 textureCache: this.textureCache,
                 uniforms: this._uniforms,
                 assembled,
+                polygonOffset: this._polygonOffset,
             });
             const { group, stats } = buildRes;
             const texKeys = buildRes.textureKeys ?? group.userData?.textureKeys ?? Object.keys(tile.textures ?? {});
@@ -997,6 +1026,8 @@ export class S3MTileset {
                 childUrls,
                 parentUrl: this._parentOf.get(url),
                 state: 'ready',
+                ...(stats.splatSigma ? { splatSigma: stats.splatSigma } : {}),
+                ...(stats.splatCount ? { splatCount: stats.splatCount } : {}),
                 stats: {
                     meshes: stats.meshes ?? 0,
                     vertices: stats.vertices ?? 0,
@@ -1107,7 +1138,26 @@ export class S3MTileset {
             const childUrls = node.childUrls ?? (node.childUrl ? [node.childUrl] : []);
             // 加入 8% 迟滞区间（Hysteresis Band），防止相机在 LOD 临界距离处发生父子瓦片逐帧来回横跳闪烁
             const hFactor = node.needRefine ? (byDistance ? 1.08 : 0.92) : 1.0;
-            const needRefine = childUrls.length > 0 && (byDistance ? metric < threshold * hFactor : metric > threshold * hFactor);
+            // 泼溅 / 点云瓦片走另一套判据：每层 σ 是同一个物理量、只有点数在涨，包围球
+            // 像素误差对它没有含义 —— 按上面那套算，metric 在任何距离都远大于阈值，等于
+            // 「永远细化到叶子」。
+            // 判据换成**屏幕上的高斯尺寸**（3σ 超过 SPLAT_REFINE_PX 就细化），见 core/SplatLod.ts。
+            // 别用覆盖率：主体那块根瓦片 32 万高斯、σ=13.5cm，覆盖率一上来就是 51，
+            // 当场停止细化，最后只画了总量 2.3% 的高斯 —— 柱子就是这么被糊掉的。
+            const splat = node.splatSigma && node.sphere
+                ? splatLodDecision({
+                    splats: node.splatCount ?? node.stats?.vertices ?? 0,
+                    radius: node.sphere.radius,
+                    distance: dist,
+                    sigma: node.splatSigma,
+                    screenHeight,
+                    hasChild: childUrls.length > 0,
+                })
+                : null;
+            const needRefine = splat
+                ? splat.needRefine
+                : childUrls.length > 0 &&
+                    (byDistance ? metric < threshold * hFactor : metric > threshold * hFactor);
             node.needRefine = needRefine;
             const dbgSeen = (globalThis.__S3M_LOD_SEEN ??= new Set());
             if (globalThis.__S3M_LOD_DEBUG && !dbgSeen.has(node.url) && dbgSeen.size < 260) {