s3m-three 0.4.19 → 0.4.21

package/dist/render/S3MViewer.d.ts

@@ -22,224 +22,31 @@
  */
 import * as THREE from 'three';
 import { S3MTileset } from '../tileset/S3MTileset.js';
-import type { BuildTileFn } from '../tileset/S3MTileset.js';
-import { type AuthenticateFn } from '../core/AuthFetch.js';
-import { type LightingPreset } from './lightingPreset.js';
-import type { OutlineMaterial, StyleMode, S3MStyle, EdgesOption, MaterialQuality } from './StyleMaterial.js';
-import type { UnsupportedPolicy } from '../core/degradations.js';
+import type { LightingPreset } from './lightingPreset.js';
+import type { LightOptions, S3MViewerOptions, PickResult, PickableRef, PathFollowOptions } from './viewer/types.js';
+import type { OutlineMaterial, StyleMode, S3MStyle, EdgeModes, EdgesOption, MaterialQuality } from './StyleMaterial.js';
 import { Picker } from './Picker.js';
+import { GpuEdgePass } from './GpuEdgePass.js';
 import { Animator } from '../anim/Animator.js';
 import type { TransitionOptions } from '../anim/Animator.js';
 import { Path } from '../anim/Path.js';
-import type { EasingFn, EasingName } from '../anim/easing.js';
 import type { LineSharedUniforms, ThickLineMaterial } from './EdgeLines.js';
 import { GPUPathManager } from './GPUPathManager.js';
 import type { GPUPathOptions } from './FeatureStyleManager.js';
+import type { InstanceFeature } from '../core/FeatureInfo.js';
 import { AttributeQuery } from '../core/AttributeQuery.js';
 import type { AttributeQueryOptions } from '../core/AttributeQuery.js';
-import type { FeatureAttributes, Stats, StyleUniforms } from '../core/types.js';
+import type { GeoPackageEntry, SegmentBox, Stats, StyleUniforms } from '../core/types.js';
 import { type GeoAdapter } from './GeoAdapter.js';
 import { DatasetManager, type DatasetAlignment, type S3MDatasetOptions, type S3MDatasetEntry } from './DatasetManager.js';
 import { FeatureStyleManager, type FeatureStyle, type ColorByFieldOptions, type ThematicResult, type BatchAudit, type FieldFilterOptions, type FieldFilterResult, type FieldElevationOptions, type FieldElevationResult, type S3MFilter } from './FeatureStyleManager.js';
-import { GroundManager, type GroundMode, type GroundOptions } from './GroundManager.js';
+import { GroundManager, type GroundMode } from './GroundManager.js';
 export type { DatasetAlignment, S3MDatasetOptions, S3MDatasetEntry, } from './DatasetManager.js';
 export type { FeatureStyle, ColorByFieldOptions, ThematicLegendEntry, ThematicResult, BatchConflict, BatchAudit, FieldFilterOptions, FieldFilterResult, FieldElevationOptions, FieldElevationResult, S3MFilter, } from './FeatureStyleManager.js';
 export type { GroundMode, GroundOptions, } from './GroundManager.js';
 export { GroundManager, DatasetManager, FeatureStyleManager };
-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 type { PickResult, LightOptions, S3MViewerOptions, PickableRef, PathFollowOptions, } from './viewer/types.js';
 /** 单体沿折线运动的参数 */
-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;
-}
 export declare class S3MViewer {
     readonly options: S3MViewerOptions;
     readonly pickable: boolean;
@@ -267,12 +74,8 @@ export declare class S3MViewer {
     readonly edgeMaterial: ThickLineMaterial;
     /** 选中棱线材质（同上，选中棱线的逐网格材质共享它的对象） */
     readonly selectionEdgeMaterial: ThickLineMaterial;
-    /** 全局棱线的外观 uniform：逐网格棱线材质直接复用这些对象 */
-    private readonly _edgeStyleUniforms;
-    /** 选中棱线的外观 uniform */
-    private readonly _selEdgeStyleUniforms;
-    /** 全局外扩轮廓的外观 uniform：逐网格轮廓壳共享这些对象 */
-    private readonly _hullStyleUniforms;
+    /** 棱线装饰（见 viewer/EdgeDecorator.ts） */
+    private readonly _edges;
     /** 3D 物理地表面 / 基坑开挖管理器 */
     readonly groundManager: GroundManager;
     /** 多数据集生命周期与锚点管理器 */
@@ -299,29 +102,15 @@ export declare class S3MViewer {
         meterInMercator: number;
         altitude?: number;
     } | null);
-    private readonly _pickables;
-    private _pickSeq;
-    private readonly _freePickIds;
+    /** 拾取表 / pickId 池 / 射线求交（见 viewer/PickService.ts） */
+    private readonly _picks;
     /** SMID → 包含它的网格。改单个单体样式时只重算这几块，不用全量扫 */
     private readonly _smidMeshes;
     /** 每块网格的世界高度范围，用来增量维护 uHeightMin / uHeightMax */
-    private readonly _meshHeight;
-    private _heightMin;
-    private _heightMax;
-    private readonly _boxScratch;
-    private _selection;
-    private _selectedMeshes;
-    private _outlineMesh;
-    private _outlineMeshes;
-    private _selectionEdges;
-    private _selectionEdgeMeshes;
-    private _edgesEnabled;
-    /** 当前生效的棱线画法（line / offset / hull / gpu），决定要不要建 / 拆哪种装饰 */
-    private _edgeModes;
-    /** GPU 描边后处理（深度 + 法线），只在 edges 含 'gpu' 时按帧执行 */
-    private _gpuEdge;
-    /** 给 GPU 描边传色用的临时 Color，避免每帧 new */
-    private readonly _gpuEdgeColor;
+    /** 世界高度范围增量维护（见 viewer/HeightIndex.ts） */
+    private readonly _heights;
+    /** 选中态与装饰（见 viewer/SelectionDecorator.ts） */
+    private readonly _sel;
     /** 瓦片淡入通道的自增序号（不用 pickId：pickId 会被回收复用） */
     private _tileFadeSeq;
     /** setMode 编排的代次，用来作废被新调用顶掉的旧编排 */
@@ -338,15 +127,10 @@ export declare class S3MViewer {
     private readonly _pathScratch;
     /** 求切线用的第二个采样点（包围盒换算 GPU 路径朝向时用） */
     private readonly _pathScratch2;
-    /** 预制棱线缓存（Crease Cache）：从外部 source-creases 载入的全局统一 LineSegments，性能最高、视觉最干净 */
-    private _creaseLines;
-    /** 数据自带的棱线对象（LineSegments），改棱线颜色时只刷这些，不再全场景 traverse */
-    private readonly _nativeEdgeLines;
     /** 点云对象集合：透明度动画时只刷它们，避免每帧遍历全部 pickables */
     private readonly _pointClouds;
-    /** 泼溅排序状态：相机不动且没有新瓦片时，排序结果可以直接复用 */
-    private readonly _lastSplatSortView;
-    private _splatsSorted;
+    /** 泼溅排序调度（见 viewer/SplatLayer.ts） */
+    private readonly _splats;
     /** 当前材质是否处于 transparent 状态，用来避免逐帧重复切换 program */
     private _opacityTransparent;
     /**
@@ -363,16 +147,10 @@ export declare class S3MViewer {
     private readonly _frameMvp;
     /** 颜色换算用的临时对象，避免每帧 new */
     private readonly _colorScratch;
-    private _needsRepaint;
     private _frame;
     private readonly _fps;
-    private _ambientLight;
-    private _hemiLight;
-    private _keyLight;
-    private _fillLight;
-    /** 环境贴图的 PMREM 渲染目标（setEnvironment 建的，unmount 时释放） */
-    private _envRT;
-    private readonly _lightOptions;
+    /** 光源 / 色调映射 / 环境贴图（见 viewer/LightRig.ts） */
+    private readonly _lights;
     private readonly _datasetQueue;
     /** 宿主重画信号与地图朝向，构造时注入 */
     private _onRequestRepaint;
@@ -411,45 +189,33 @@ export declare class S3MViewer {
     restoreContext(gl: WebGLRenderingContext | WebGL2RenderingContext): void;
     /** 解绑场景并释放全部 GPU 资源。对应 MapLibre 图层的 onRemove()。 */
     unmount(): void;
-    private _createLights;
-    private _addLights;
-    private _applyLightOptions;
     /**
-     * 运行时切换光照预设：覆盖四个强度，颜色/朝向保持不变。
-     * 之后再调 `setLight({...})` 仍然可以逐项微调。
+     * @internal 光源实例的转发 —— `lighting.test.ts` 直接读这几个字段。
+     * 实现全在 viewer/LightRig.ts。
      */
-    /**
-     * supermap 完整版 = 光照强度 + 颜色管线一起切：
-     * direct 管线下纹理不做 sRGB 解码、片元按官方常数 Lambert 直乘（见 lightingPreset.ts）。
-     * 两个都是模块级全局态，只影响之后创建的材质 / 纹理 —— 已加载瓦片要重载才换。
-     */
-    private _applyColorPipeline;
+    get _ambientLight(): THREE.AmbientLight | null;
+    get _hemiLight(): THREE.HemisphereLight | null;
+    get _keyLight(): THREE.DirectionalLight | null;
+    get _fillLight(): THREE.DirectionalLight | null;
+    /** @internal 光照位置按当前 bearing 重算，见 viewer/LightRig.ts */
+    _updateLights(): void;
+    private _addLights;
     setLightingPreset(preset: LightingPreset): void;
-    /**
-     * 动态设置光照配置
-     */
+    /** 动态设置光照配置 */
     setLight(options: Partial<LightOptions>): void;
-    /**
-     * 获取当前光照配置快照
-     */
+    /** 获取当前光照配置快照 */
     getLight(): LightOptions;
-    /**
-     * 动态设置色调映射模式与曝光度
-     */
+    /** 动态设置色调映射模式与曝光度 */
     setToneMapping(toneMapping: THREE.ToneMapping, exposure?: number): void;
-    /**
-     * 获取当前色调映射模式与曝光度
-     */
+    /** 获取当前色调映射模式与曝光度 */
     getToneMapping(): {
         toneMapping: THREE.ToneMapping;
         toneMappingExposure: number;
     };
     /**
-     * 更新光照位置与方向：
-     * - 'headlamp': 随地图方位角 bearing 旋转，主光始终在镜头上方，受光面面向镜头；
-     * - 'fixed': 固定世界方位角（如模拟恒定日光）。
+     * 挂 / 摘环境贴图。见 viewer/LightRig.ts（PMREM 预滤波 + 旧 RT 释放）。
      */
-    private _updateLights;
+    setEnvironment(source: string | THREE.Texture | null, intensity?: number): Promise<void>;
     private _normalizeDatasets;
     /** 追加一个数据集。图层 addLayer 之前调用会抛错。 */
     addDataset(ds: S3MDatasetOptions): Promise<S3MDatasetEntry>;
@@ -663,7 +429,6 @@ export declare class S3MViewer {
     private _isFeatureHidden;
     getAllMeshes(): THREE.Mesh[];
     private _meshesOf;
-    private _markOverridesDirty;
     flushOverrides(): void;
     /** @internal 内部状态纹理烘焙代理，保留供回归单测与钩子使用 */
     _applyOverridesToMesh(mesh: THREE.Mesh): void;
@@ -682,26 +447,14 @@ export declare class S3MViewer {
      * 通道 key 用自增序号而不是 pickId：pickId 会被回收复用，用它会串到新瓦片上。
      */
     private _startTileFade;
-    /**
-     * 把「当前选中」重放到一块新登记的 mesh 上。
-     *
-     * 为什么需要：选中高亮是直接写在各 mesh 材质的 uSelBatch / uSelWhole 上的，
-     * 而 LOD 细化、瓦片重载、淘汰回补都会换掉 mesh —— 不重放的话，用户点中的那栋楼
-     * 一细化就失去高亮（状态还在 _selection.smid 里，只是没人往新 mesh 上刷）。
-     */
-    /**
-     * 判断一块无 SMID 单体化信息的网格（如倾斜摄影或白模整块）是否空间覆盖当前选中命中点
-     */
-    private _isMeshCoveringSelection;
-    private _replaySelectionOnto;
+    /** @internal 把当前选中重放到新登记的 mesh 上，见 viewer/SelectionDecorator.ts */
+    _replaySelectionOnto(mesh: THREE.Mesh): void;
     /** 瓦片被淘汰：从拾取表和场景里摘掉，并深度彻底释放所有几何体与材质显存 */
     private _unregisterTile;
     /**
      * 拾取 ID 只有 2 个字节（RG 两个通道），65535 个网格就到头了，
      * 所以必须回收：瓦片淘汰 / 数据集移除时把 id 还回池子。
      */
-    private _allocPickId;
-    private _releasePickId;
     /** 动态设置图层整体透明度 (0.0 ~ 1.0) */
     setOpacity(opacity: number, transition?: TransitionOptions): void;
     /**
@@ -715,20 +468,6 @@ export declare class S3MViewer {
     getStyle(): S3MStyle & {
         modeLabel: string;
     };
-    /**
-     * 挂 / 摘环境贴图。
-     *
-     * 金属度（`setStyle({ metalness })`）**必须**有环境图才看得出质感：
-     * PBR 的金属几乎没有漫反射，画面全靠 `scene.environment` 里的环境反射，
-     * 没有它时 metalness 一高就整片发黑，只剩两盏平行灯打成的小高光点。
-     *
-     * @param source 等距柱状图（.hdr / .jpg / .png，2:1）地址，或已加载的 `THREE.Texture`；
-     *               `null` = 关掉环境图
-     * @param intensity 环境光强度（`scene.environmentIntensity`，默认 1）
-     *
-     * 传入 URL 时纹理由内部加载并转成 PMREM（预滤波 mipmap）；传 Texture 时不会接管它的生命周期。
-     */
-    setEnvironment(source: string | THREE.Texture | null, intensity?: number): Promise<void>;
     /** 把某个样式键的取值转成动画通道能吃的形状（标量 or 线性 RGB 三元组） */
     private _animTargetOf;
     /** 该样式键的动画维度：3 = 颜色，1 = 标量 */
@@ -792,171 +531,89 @@ export declare class S3MViewer {
      * 加载 n 块瓦片就是 O(n²) 次矩阵乘 + n² 个垃圾对象。现在只在网格进出的记一次，
      * 全局值从缓存里滚：只有被移除的那块正好卡在边界上时，才回退到一次 O(n) 重算。
      */
-    private _addMeshHeight;
-    private _removeMeshHeight;
-    /** 数据集整体位移（换高程偏移 / 重新布局）后，缓存的世界高度全部失效 */
-    private _refreshAllHeights;
-    private _recomputeHeightRange;
-    private _pushHeightRange;
+    /** @internal 见 viewer/HeightIndex.ts（regressions.test.ts 直接调） */
+    _addMeshHeight(mesh: THREE.Mesh): void;
+    /** @internal 见 viewer/HeightIndex.ts */
+    _removeMeshHeight(mesh: THREE.Mesh): void;
     /** 建 SMID → 网格 反查表，逐单体改样式时才知道该重算哪几块 */
     private _indexMeshSmids;
     private _unindexMeshSmids;
-    /**
-     * 全局棱线开关。
-     *
-     * 取值是 `boolean | EdgeStyle | EdgeStyle[]`（见 resolveEdgeModes）：
-     *   - `true` / `'line'`   折边线（旧口径）
-     *   - `'offset'`          折边线 + 沿边法线外推 `edgeOffset` 米
-     *   - `'hull'`            背面外扩轮廓（选中侧 outlineStyle:'hull' 的整场景版）
-     *   - `'gpu'`             纯片元描边：零几何、零额外 pass，线宽约 1 像素
-     *   - 数组                叠加，例如 `['line', 'hull']`
-     *
-     * 数据自带棱线包（primitiveType 13）时直接用，成本为零；`style.forceCpuEdges`
-     * 可以无视它，改由 CPU 现算 —— 那是 CPU 端的活，几十万面一次性建会卡住主线程
-     * （实测 20 个网格 1.9s），所以按 8ms 一帧切片，边建边出。
-     *
-     * 棱线本身用「屏幕空间等宽线」画（见 EdgeLines.ts）：WebGL 的 lineWidth 基本无效，
-     * 只有摊成面向屏幕的四边形，`edgeWidth` 才能真正调粗。
-     *
-     * 带 `transition` 时做「淡入 / 淡出」，**不对几何做插值**（几何没法插值）：
-     * 开：立刻置位 + 开始分片建线，同时 `uEdgeFade` 0→1 —— 建好一块亮一块，视觉上是渐显；
-     * 关：`uEdgeFade` 1→0，淡完才 dispose，避免棱线「啪」一下消失。
-     */
+    /** @internal 测试用：棱线是否开启（实现在 EdgeDecorator） */
+    get _edgesEnabled(): boolean;
+    /** @internal 测试用：当前画法 */
+    get _edgeModes(): EdgeModes;
+    /** @internal 测试用：GPU 描边实例（可替换） */
+    get _gpuEdge(): GpuEdgePass | null;
+    set _gpuEdge(v: GpuEdgePass | null);
+    /** @internal 测试用：给一块网格补折边线 */
+    _ensureEdges(mesh: THREE.Mesh): void;
+    /** @internal 测试用：拆掉一块网格的棱线装饰 */
+    _removeEdges(mesh: THREE.Mesh): void;
+    /** 全局棱线开关，实现在 viewer/EdgeDecorator.ts */
     setEdges(edges: EdgesOption, transition?: TransitionOptions): void;
-    /** 直接写棱线淡入乘子（不走动画通道） */
-    private _setEdgeFade;
-    /** 释放所有现算棱线几何 */
-    private _disposeEdges;
-    /**
-     * 挂载预制棱线缓存（Crease Cache）。
-     *
-     * 直接把 `source-creases.f32` 这类 Float32Array 缓冲载入为一组全局统一的
-     * LineSegments —— 相比逐 Mesh 现算 EdgesGeometry，性能高一个量级，视觉也最干净。
-     * 坐标按「场景本地坐标」（相对场景锚点的米）处理，与瓦片几何同一坐标系。
-     *
-     * @param url  棱线缓存地址（二进制 Float32 序列：x,y,z,x,y,z,… 成对成段）
-     */
+    /** 挂载预制棱线缓存（Crease Cache），见 viewer/EdgeDecorator.ts */
     loadCreases(url: string): Promise<void>;
     /** 移除并释放预制棱线缓存 */
     clearCreases(): void;
-    /**
-     * 让全局棱线材质跟上 style.edgeColor / edgeWidth / edgeOpacity / edgeOffset。
-     *
-     * 全程 O(1)：只有一份共享 edgeMaterial（所有逐 mesh 棱线都用它）+ 一份预制缓存
-     * + 一批共享外观对象的轮廓壳，所以棱线淡入淡出只要改一个 uniform，
-     * 新建瓦片自动继承当前进度。
-     */
-    private _syncEdgeStyle;
-    /** 让数据自带的棱线跟着 style.edgeColor / opacity 走（这些是 LineBasicMaterial，改不了粗细） */
-    private _styleEdgeLine;
-    /**
-     * 刷新所有棱线外观。
-     *
-     * 数据自带的棱线是逐对象的 LineBasicMaterial，改颜色只能一个个写；但原来每次都要
-     * 遍历整个数据集树（几千个节点），颜色动画逐帧跑就是灾难。改成只刷注册时收集好的
-     * 那批 LineSegments，复杂度降到 O(棱线条数)。
-     */
-    private _refreshEdgeLines;
-    /** 地形 / 绿地 / 道路 / 地面铺装等不参与自动描边（数据自带棱线包另说） */
-    private static readonly _EDGE_SKIP_KEYWORDS;
-    /** 数据集级别的棱线开关：enableEdges 优先，否则跟随全局 style.edges */
-    private _datasetEdgesEnabled;
-    /** 该 mesh 是否命中「跳过自动描边」的关键字（skeletonName / 数据集名） */
-    private _shouldSkipAutoEdges;
-    /**
-     * 这块网格还缺哪种棱线装饰（缺就建，齐了就不动）。
-     *
-     * setEdges 的分片建线靠它筛「还没建完的」，注册新瓦片也靠它决定要不要动手。
-     */
-    private _needsEdgeDecoration;
-    /** 按当前画法补齐这块网格的棱线装饰 */
-    private _ensureEdgeDecoration;
-    private _ensureEdges;
-    /**
-     * 给一块网格挂「背面外扩轮廓」（整场景版）。
-     *
-     * 复用选中侧那套 `createOutlineMaterial`：顶点沿法线鼓 `edgeHullWidth` 米、只画背面，
-     * 于是被本体挡住的部分不显示，露出来的那圈就是描边。与折边线的差别在于——
-     * 这里**不建任何新几何**，成本只是把同一块网格多画一遍，折边判定那套 CPU 活全省了。
-     *
-     * 实例化几何拿不到逐实例变换（轮廓壳是 mesh 的子节点，不吃 instanceMatrix），
-     * 直接跳过：宁可这栋没描边，也不要所有实例的壳叠在原点。
-     */
-    private _ensureHull;
-    /**
-     * 给一块网格造专属的棱线材质。
-     *
-     * 棱线材质必须逐网格一份，因为它要绑定**这个网格**的单体状态纹理；但外观
-     * （颜色 / 粗细 / 透明度）必须全局统一——所以外观 uniform 直接复用
-     * `_edgeStyleUniforms` 里的对象，`_syncEdgeStyle()` 改一次全部生效，
-     * program 也因为着色器相同而只编译一次。
-     */
-    private _createEdgeMaterial;
-    /** 选中棱线的逐网格材质，道理同上 */
-    private _createSelectionEdgeMaterial;
-    private _removeEdges;
-    /** 获取指定屏幕像素对应的场景射线（用于高精度求交与穿透拾取） */
+    /** 屏幕像素 → 场景射线，见 viewer/PickService.ts */
     getRayAt(x: number, y: number): THREE.Ray | null;
-    private _intersectMeshAtRay;
-    private _buildPickResult;
-    /**
-     * 泼溅的拾取结果。
-     *
-     * 整块泼溅瓦片当一个单体（没有单体级 smid 可报），命中点由 `splatRaycast` 给出 ——
-     * 它按每个高斯的 3σ 球求交，比拾取那一趟为了命中率摊开的 4px 方块准得多。
-     * 包围盒必须由 `iCenter` 算：geometry 的 position 只是 [-1,1]² 的四边形角点。
-     */
-    private _buildSplatPickResult;
-    /** 按 canvas 左上角的 CSS 像素坐标拾取。 */
+    /** 按 canvas 左上角的 CSS 像素坐标拾取 */
     pick(x: number, y: number): PickResult | null;
-    /**
-     * 拾取指定屏幕像素对应的世界坐标与场景位置。
-     * 优先与命中的建筑网格精确求交；未命中建筑时若视线与地表相交则返回地面交点。
-     */
+    /** 拾取并返回经纬度 + 高程 */
     pickPosition(x: number, y: number): {
         lngLat: [number, number];
         altitude: number;
         point: [number, number, number];
     } | null;
-    /**
-     * 沿视线方向穿透拾取多个单体，按由近至远排序返回。
-     */
+    /** 穿透拾取：沿射线返回前 `limit` 个命中 */
     drillPick(x: number, y: number, limit?: number): PickResult[];
-    /**
-     * 获取指定 SMID 单体的经纬度包围盒 [[minLng, minLat], [maxLng, maxLat]]。
-     * 若模型尚未加载到场景中或无此单体则返回 null。
-     */
+    /** 单体的经纬度包围盒 */
     getFeatureBounds(smid: number): [[number, number], [number, number]] | null;
-    /** 实例序号 → 所属单体（按网格缓存反查表，实例多的数据不用每次重建） */
-    private _instanceFeature;
-    /** 实例化几何的单体包围盒：base mesh 的包围盒套上该实例的矩阵 */
-    private _instanceBox;
-    /** 选中/取消选中单体。`silent` 为 true 时不回调 onPick。 */
-    select(result: PickResult | null, { silent }?: {
+    /** @internal 见 viewer/PickService.ts */
+    _intersectMeshAtRay(mesh: THREE.Mesh, ray: THREE.Ray, instanceIndex?: number): THREE.Vector3 | null;
+    /** @internal 见 viewer/PickService.ts */
+    _buildPickResult(hit: {
+        objectId: number;
+        batchId: number;
+        instanceIndex?: number;
+    }, ref: PickableRef, exactPoint?: THREE.Vector3, ray?: THREE.Ray): PickResult | null;
+    /** @internal 见 viewer/PickService.ts */
+    _buildSplatPickResult(hit: {
+        objectId: number;
+        batchId: number;
+        instanceIndex?: number;
+    }, ref: PickableRef, exactPoint?: THREE.Vector3, ray?: THREE.Ray): PickResult | null;
+    /** @internal 见 viewer/PickService.ts */
+    _instanceFeature(mesh: THREE.Mesh, geoRef: GeoPackageEntry | undefined, instanceIndex: number): InstanceFeature | null;
+    /** @internal 见 viewer/PickService.ts */
+    _instanceBox(mesh: THREE.Mesh, instanceIndex: number): SegmentBox | null;
+    /** @internal 拾取 id 池，见 viewer/PickService.ts */
+    _allocPickId(): number;
+    /** @internal */
+    _releasePickId(id: number): void;
+    /** @internal 拾取表（测试直接读写），见 viewer/PickService.ts */
+    get _pickables(): Map<number, PickableRef>;
+    /**
+     * 选中一个单体（或整块网格），高亮与轮廓装饰见 viewer/SelectionDecorator.ts。
+     * 传 `null` 清空选中；`silent` 为真时不触发 `onPick`。
+     */
+    select(result: PickResult | null, opts?: {
         silent?: boolean;
     }): void;
-    /**
-     * 选中单体的棱线：只挑这个单体自己的三角面算折边，再画成屏幕空间等宽线。
-     * 抽出来的线段数很少（一栋楼通常几百到几千条），所以选中开销可以忽略。
-     */
-    private _addSelectionEdges;
-    /** 实例化几何：把某个实例的矩阵套到一个普通 Mesh/子节点上（子节点不参与父级的 instanceMatrix） */
-    private _applyInstanceTransform;
-    /** 旧的描边画法：背面外扩法，整块几何一起上，靠 uSelBatch 只显示选中那栋 */
-    private _addSelectionHull;
-    /** 只改 uniform：颜色 / 粗细 / 拔高，拖着滑块实时生效，不重建几何 */
-    private _syncSelectionStyle;
-    /** 选中单体的实际拔高 = 全局选中拔高 + 该单体的独立拔高（与着色器口径一致） */
-    private _selectionElevation;
-    private _clearSelectionDecoration;
+    /** @internal 选中外观跟随样式变化，见 viewer/SelectionDecorator.ts */
+    _syncSelectionStyle(): void;
+    /** @internal 测试用：当前选中 */
+    get _selection(): PickResult | null;
+    /** @internal 测试用：被高亮的网格 */
+    get _selectedMeshes(): THREE.Object3D[];
+    /** @internal 测试用：选中棱线的网格列表 */
+    get _selectionEdgeMeshes(): THREE.Mesh[];
     /**
      * 执行一帧 GPU 描边（法线 + 深度后处理）。
      *
      * 参数全部来自 style，不缓存：`edgeWidth` 在这里是「采样偏移」，线宽 ≈ 2×它；
      * `edgeThreshold` 是折边敏感度（夹角小于它不描），和 CPU 折边线同一口径。
      */
-    private _renderGpuEdges;
-    /** 等宽线要按设备像素换算线宽：uResolution 用绘图缓冲尺寸，uDpr 是缓冲 / CSS 的比值 */
     private _updateLineResolution;
     /** 当前 LOD 切换距离缩放系数 */
     get lodRangeScale(): number;
@@ -992,6 +649,14 @@ export declare class S3MViewer {
      * 实际裁剪发生在下一次 `update()` 末尾，不会当场掉内容。
      */
     setMaxTriangles(n: number, datasetId?: string): void;
+    /** 当前每个数据集的驻留显存/内存字节预算。Infinity = 不限制 */
+    get maxMemory(): number;
+    /**
+     * 调整每个数据集驻留显存字节数的软上限（默认 Infinity = 不限制）。
+     * 不传 `datasetId` 时对所有已存在数据集立即生效，并作为之后新增数据集的默认值。
+     * 实际裁剪发生在每帧调度末尾（make-before-break），不会当场开洞。
+     */
+    setMaxMemory(bytes: number, datasetId?: string): void;
     /** 当前各向异性过滤上限。Infinity = 不封顶 */
     get anisotropyCap(): number;
     /**
@@ -1018,7 +683,8 @@ export declare class S3MViewer {
      * 乱序混合就是满屏彩色噪点。相机没动且没有新瓦片时整个跳过；
      * 单个瓦片顺序本来就对时 sortSplatMesh 内部也会跳过重写。
      */
-    private _sortSplats;
+    /** @internal 泼溅按视深重排，见 viewer/SplatLayer.ts */
+    _sortSplats(): void;
     /**
      * 渲染一帧。所有宿主相关量都由调用方喂进来，viewer 不碰任何地图 API：
      *