iflow-engine-base 4.0.16 → 4.0.19

package/dist/index.d.ts

@@ -1,15 +1,15 @@
-import { Box3 } from 'three';
+import { Box3 as Box3_2 } from 'three';
 import { Camera } from 'three';
 import { Circle } from 'fabric';
-import { ColorRepresentation } from 'three';
 import { default as default_2 } from 'stats.js';
 import * as GaussianSplats3D from '@mkkellogg/gaussian-splats-3d';
+import { GlobeControls } from '3d-tiles-renderer';
 import { Group } from 'fabric';
 import { IText } from 'fabric';
 import { Line } from 'fabric';
-import { Matrix4 } from 'three';
 import { Object3D } from 'three';
 import { Path } from 'fabric';
+import { PerspectiveCamera } from 'three';
 import { Rect } from 'fabric';
 import { RenderPipeline } from 'three/webgpu';
 import { Scene } from 'three';
@@ -990,13 +990,39 @@ declare class AreaMeasure2d extends BaseMeasureTool2d {
     handleDoubleClick(): void;
 }
 
+/** v2 自动曝光模块，使用低分辨率 RGBA8 离屏目标完成 WebGL 测光。 */
+declare class AutoExposureModule {
+    private readonly engine;
+    private readonly renderer;
+    private readonly scene;
+    private options;
+    private probeTarget;
+    private lastMeasurementTime;
+    private lastUpdateTime;
+    private targetExposure;
+    private disposed;
+    constructor(engine: any);
+    get settings(): ResolvedAutoExposureOptions;
+    isEnabled(): boolean;
+    setEnabled(enabled: boolean): void;
+    setOptions(options: AutoExposureOptions): void;
+    /** 在主动画循环中更新曝光；低分辨率测光按配置间隔执行。 */
+    update(time: DOMHighResTimeStamp): void;
+    dispose(): void;
+    private resolveOptions;
+    private ensureProbeTarget;
+    private measureScene;
+    private calculateTrimmedLuminance;
+    private clampExposure;
+}
+
 /**
  * v3 自动曝光模块。
  *
  * 使用低分辨率离屏渲染探针估计相机当前看到的线性亮度，再用指数平滑更新
  * renderer.toneMappingExposure。探针不会修改主渲染目标，也不会参与后期管线。
  */
-declare class AutoExposureModule {
+declare class AutoExposureModule_2 {
     private readonly engine;
     private readonly renderer;
     private readonly scene;
@@ -1106,7 +1132,7 @@ declare interface BoundsLike_2 {
 /**
  * 基础几何类型定义
  */
-declare interface Box3_2 {
+declare interface Box3 {
     min: {
         x: number;
         y: number;
@@ -1425,54 +1451,43 @@ declare type CalibrationVector3Array = [number, number, number];
 
 declare type CalibrationVector3Array_2 = [number, number, number];
 
-declare class CameraModule {
-    private static readonly MIN_VISIBLE_HEIGHT;
-    private static readonly MIN_CAMERA_DISTANCE;
-    private static readonly CAMERA_ANIMATION_IDLE_EXEMPT_REASON;
-    private engine;
-    perspectiveCamera: THREE.PerspectiveCamera;
-    orthographicCamera: THREE.OrthographicCamera;
-    private cameraAnimationFrame;
-    constructor(engine: any);
-    /** 视图跳转前统一退出图钉查看态，避免批注锁定与相机动画冲突。 */
-    private exitDrawingPinView;
-    private getCameraAspect;
-    private getPerspectiveVisibleHeight;
-    getOrthographicVisibleHeight(camera?: THREE.OrthographicCamera): number;
-    setOrthographicVisibleHeight(visibleHeight: number, camera?: THREE.OrthographicCamera, aspect?: number): void;
-    private getViewDirection;
-    private getStableCameraUp;
-    private updateComposerCamera;
-    private applySwitchedCamera;
-    private resolvePoseReferenceUp;
-    private syncControlsAfterPoseRestore;
-    private inferTargetFromRestoredCamera;
-    switchCurrentCamera(): void;
-    setPerspectiveFov(fov: number, options?: {
-        adjustDistance?: boolean;
-    }): void;
-    switchToPerspectiveCamera(): void;
-    switchToOrthographicCamera(): void;
-    getCameraType(): CameraType;
-    getCameraPose(): ICameraPose;
-    restoreCameraPose(pose: ICameraPose): void;
-    setViewFromOriginAndDirection(origin: {
-        x: number;
-        y: number;
-        z: number;
-    }, direction: {
-        x: number;
-        y: number;
-        z: number;
-    }, stableUp?: any, distanceOverride?: number | null, animationDuration?: number, onComplete?: () => void): void;
-    /** 保持相机位置不变，以过渡动画将观察目标旋转到指定点。 */
-    rotateToTarget(target: {
-        x: number;
-        y: number;
-        z: number;
-    }, animationDuration?: number, onComplete?: () => void): void;
-    private applyCameraPose;
-    private animateCameraToTarget;
+/** 管理 GIS 相机的经纬度定位与平滑视图跳转。 */
+export declare class CameraModule {
+    private readonly camera;
+    private readonly tiles;
+    private readonly cameraFrame;
+    private readonly requestRender;
+    private readonly coordinateModule?;
+    private controls;
+    private currentView;
+    private readonly inverseParentMatrix;
+    private flight;
+    private controlsEnabledBeforeFlight;
+    private disposed;
+    constructor(camera: PerspectiveCamera, tiles: TilesRenderer, cameraFrame: number, requestRender: () => void, initialView?: GISView, coordinateModule?: CoordinateModule | undefined);
+    /** 绑定地球控制器，使跳转期间禁用输入并在结束后同步控制状态。 */
+    setControls(controls: GlobeControls): void;
+    /** 立即跳转到指定经纬度。 */
+    setView(view: GISView): void;
+    /** 平滑飞行到指定经纬度，默认动画时长为 1.5 秒。 */
+    flyTo(view: GISView, options?: GISFlyToOptions): Promise<void>;
+    /** 返回当前已经应用到相机的 WGS84 视图。 */
+    getView(): Required<GISView>;
+    /** 取消当前飞行，并恢复跳转前的控制器状态。 */
+    cancelFlight(message?: string, aborted?: boolean): boolean;
+    /** 由 GIS 共享渲染循环调用，推进当前相机飞行动画。 */
+    update(time: DOMHighResTimeStamp): void;
+    /** 释放飞行任务持有的事件和控制器状态。 */
+    dispose(): void;
+    /** 用户通过 GlobeControls 改变相机后，同步真实地理视图供保存和后续飞行使用。 */
+    private readonly handleControlsChange;
+    private syncViewFromCamera;
+    private resolveView;
+    private applyView;
+    private cleanupFlight;
+    private lerp;
+    private lerpAngle;
+    private normalizeAngle;
 }
 
 declare class CameraModule2d {
@@ -1659,6 +1674,56 @@ declare class CameraModule720 {
 }
 
 declare class CameraModule_2 {
+    private static readonly MIN_VISIBLE_HEIGHT;
+    private static readonly MIN_CAMERA_DISTANCE;
+    private static readonly CAMERA_ANIMATION_IDLE_EXEMPT_REASON;
+    private engine;
+    perspectiveCamera: THREE.PerspectiveCamera;
+    orthographicCamera: THREE.OrthographicCamera;
+    private cameraAnimationFrame;
+    constructor(engine: any);
+    /** 视图跳转前统一退出图钉查看态，避免批注锁定与相机动画冲突。 */
+    private exitDrawingPinView;
+    private getCameraAspect;
+    private getPerspectiveVisibleHeight;
+    getOrthographicVisibleHeight(camera?: THREE.OrthographicCamera): number;
+    setOrthographicVisibleHeight(visibleHeight: number, camera?: THREE.OrthographicCamera, aspect?: number): void;
+    private getViewDirection;
+    private getStableCameraUp;
+    private updateComposerCamera;
+    private applySwitchedCamera;
+    private resolvePoseReferenceUp;
+    private syncControlsAfterPoseRestore;
+    private inferTargetFromRestoredCamera;
+    switchCurrentCamera(): void;
+    setPerspectiveFov(fov: number, options?: {
+        adjustDistance?: boolean;
+    }): void;
+    switchToPerspectiveCamera(): void;
+    switchToOrthographicCamera(): void;
+    getCameraType(): CameraType;
+    getCameraPose(): ICameraPose;
+    restoreCameraPose(pose: ICameraPose): void;
+    setViewFromOriginAndDirection(origin: {
+        x: number;
+        y: number;
+        z: number;
+    }, direction: {
+        x: number;
+        y: number;
+        z: number;
+    }, stableUp?: any, distanceOverride?: number | null, animationDuration?: number, onComplete?: () => void): void;
+    /** 保持相机位置不变，以过渡动画将观察目标旋转到指定点。 */
+    rotateToTarget(target: {
+        x: number;
+        y: number;
+        z: number;
+    }, animationDuration?: number, onComplete?: () => void): void;
+    private applyCameraPose;
+    private animateCameraToTarget;
+}
+
+declare class CameraModule_3 {
     private static readonly MIN_VISIBLE_HEIGHT;
     private static readonly MIN_CAMERA_DISTANCE;
     private static readonly CAMERA_ANIMATION_IDLE_EXEMPT_REASON;
@@ -2140,6 +2205,44 @@ declare interface ContextMenuItemConfig {
     dividerBefore?: boolean;
 }
 
+/** 只负责切换入口，具体控制行为由 GIS 或 v3 已有控制器实现。 */
+export declare class ControllerModule {
+    private readonly engine;
+    private readonly gisControls;
+    private readonly requestRender;
+    private readonly layerManager?;
+    private currentMode;
+    private disposed;
+    private removeThirdPersonPlacementResolver;
+    private removeOrbitCenterResolver;
+    constructor(engine: EngineKernelV3, gisControls: GlobeControls, requestRender: () => void, layerManager?: GISLayerManager | undefined);
+    /** 切换控制器模式，并把业务配置原样委托给 v3 控制模块。 */
+    switchController(mode: GISControllerMode, options?: GISControllerSwitchOptions): void;
+    /** 获取当前已请求的控制器模式。 */
+    getMode(): GISControllerMode;
+    /** 切换到 3d-tiles-renderer 原生 GIS 控制器。 */
+    switchToGIS(): void;
+    /** 切换到 v3 默认轨道控制器。 */
+    switchToDefault(options?: Pick<GISControllerSwitchOptions, 'preserveCameraPose'>): void;
+    /** 切换到 v3 第一人称控制器。 */
+    switchToFirstPerson(): void;
+    /** 进入 v3 第三人称控制器已有的落点选择流程。 */
+    switchToThirdPerson(options?: unknown): void;
+    /** 停止当前控制输入，具体控制器资源仍由各自所属模块释放。 */
+    dispose(): void;
+    /** 重入或离开第三人称前，借助 v3 默认入口清理等待落点状态。 */
+    private leavePendingThirdPersonMode;
+    /** 将 GlobeControls 的旋转支点适配为 v3 ViewCube 使用的 OrbitControls target。 */
+    private ensureViewCubeTargetCompatibility;
+    /** 记录 GIS 当前近远裁剪面，避免底层控制器切换改写地图可见范围。 */
+    private captureCameraRange;
+    /** 将切换前的裁剪范围应用到切换后的活动相机。 */
+    private restoreCameraRange;
+    /** 从当前可见 GIS 图层中拾取地图、地形或模型表面。 */
+    private readonly resolveGISPlacement;
+    private isVisibleWithinLayer;
+}
+
 declare class ControlModule {
     private engine;
     orbitControls: any;
@@ -2157,13 +2260,15 @@ declare class ControlModule {
     private handelBehaved;
     private pendingThirdPersonOptions;
     private prevContainerCursor;
+    private thirdPersonPlacementResolver;
+    private orbitCenterResolver;
     private roamLookDirection;
     private isDragging;
     private isDown;
     private containerOffset;
     constructor(engine: any);
     init(): void;
-    active(): void;
+    active(preferredControl?: any): void;
     disActive(): void;
     private setEngineControls;
     setMoveSpeed(value: number): void;
@@ -2187,7 +2292,17 @@ declare class ControlModule {
     private createThirdPersonControl;
     private beginThirdPersonPlacement;
     isWaitingThirdPersonPlacement(): boolean;
-    applyThirdPersonPlacement(point: THREE.Vector3): boolean;
+    /** 注册 BIM 八叉树之外的第三人称落点表面，例如 GIS 地图和地形。 */
+    setThirdPersonPlacementResolver(resolver: ThirdPersonPlacementResolver | null): () => void;
+    /** 合并 BIM 与扩展表面的拾取结果，始终选择距离相机最近的落点。 */
+    resolveThirdPersonPlacement(event: any): ThirdPersonPlacementHit | null;
+    /** 注册轨道控制器可使用的外部旋转中心表面。 */
+    setOrbitCenterResolver(resolver: OrbitCenterResolver | null): () => void;
+    /** 轨道模式按下时合并 BIM 与 GIS 命中点，供首次拖动立即使用。 */
+    resolveOrbitCenter(event: any): ThirdPersonPlacementHit | null;
+    private resolveSurfaceHit;
+    private toThirdPersonPlacementHit;
+    applyThirdPersonPlacement(point: THREE.Vector3, normal?: THREE.Vector3): boolean;
     setThirdPersonAvatar(model: any, options?: any): void;
     setThirdPersonMoveSpeed(value: number): void;
     setThirdPersonApplyCollision(value: boolean): void;
@@ -2390,6 +2505,8 @@ declare class ControlModule_2 {
     private handelBehaved;
     private pendingThirdPersonOptions;
     private prevContainerCursor;
+    private thirdPersonPlacementResolver;
+    private orbitCenterResolver;
     private suspendedControl;
     private roamLookDirection;
     private isDragging;
@@ -2421,6 +2538,16 @@ declare class ControlModule_2 {
     private createThirdPersonControl;
     private beginThirdPersonPlacement;
     isWaitingThirdPersonPlacement(): boolean;
+    /** 注册 BIM 八叉树之外的第三人称落点表面，例如 GIS 地图和地形。 */
+    setThirdPersonPlacementResolver(resolver: ThirdPersonPlacementResolver_2 | null): () => void;
+    /** 合并 BIM 与扩展表面的拾取结果，始终选择距离相机最近的落点。 */
+    resolveThirdPersonPlacement(event: any): ThirdPersonPlacementHit_2 | null;
+    /** 注册轨道控制器可使用的外部旋转中心表面。 */
+    setOrbitCenterResolver(resolver: OrbitCenterResolver_2 | null): () => void;
+    /** 轨道模式按下时合并 BIM 与 GIS 命中点，供首次拖动立即使用。 */
+    resolveOrbitCenter(event: any): ThirdPersonPlacementHit_2 | null;
+    private resolveSurfaceHit;
+    private toThirdPersonPlacementHit;
     applyThirdPersonPlacement(point: THREE.Vector3, normal?: THREE.Vector3): boolean;
     setThirdPersonAvatar(model: any, options?: any): void;
     setThirdPersonMoveSpeed(value: number): void;
@@ -2472,6 +2599,33 @@ declare class ControlModuleGaussian {
     dispose(): void;
 }
 
+/**
+ * 统一管理 WGS84、ECEF 与 GIS 局部世界坐标之间的转换。
+ * 其他 GIS 模块不得自行假设 Y 轴始终等于地理高程方向。
+ */
+export declare class CoordinateModule {
+    private tiles;
+    private cameraFrame;
+    private readonly inverseTilesMatrix;
+    constructor(tiles: TilesRenderer, cameraFrame: number);
+    /** 切换底图后更新坐标参考，但保持依赖此模块的业务管理器不变。 */
+    setTiles(tiles: TilesRenderer, cameraFrame: number): void;
+    /** 将 WGS84 经纬高转换为 Three.js 世界坐标。 */
+    toWorld(coordinate: GISCoordinate, target?: Vector3): Vector3;
+    /** 将 Three.js 世界坐标反算为 WGS84 经纬高。 */
+    toWgs84(coordinate: Vector3 | GISWorldCoordinate): Required<GISCoordinate>;
+    /** 从相机当前真实世界矩阵读取 WGS84 位置和姿态。 */
+    getCameraView(camera: Camera): Required<GISView>;
+    /** 获取指定 WGS84 位置在 Three.js 世界空间中的东、北、上单位轴。 */
+    getEastNorthUpAxes(coordinate: GISCoordinate, east?: Vector3, north?: Vector3, up?: Vector3): {
+        east: Vector3;
+        north: Vector3;
+        up: Vector3;
+    };
+    private normalizeCoordinate;
+    private normalizeAngle;
+}
+
 /**
  * 动态创建 3D 引擎实例；未指定渲染后端时根据 WebGPU 支持情况自动选择 v3 或 v2。
  * 第二个参数可固定渲染后端，并优先于环境探测结果。
@@ -2497,15 +2651,11 @@ export declare function createEngine720(options: any): Promise<EngineKernel720>;
  */
 export declare function createEngineGaussian(options: any): Promise<EngineKernelGaussian>;
 
-/** 缓存键只暴露不可逆摘要，并把不同凭据隔离到独立命名空间。 */
-export declare function createGisCacheKey(input: GisCacheKeyInput): string;
+/** 按指定底座创建 GIS 引擎，并在传入地理配置时完成数据源加载。 */
+export declare function createEngineGIS(options: EngineGISOptions, gisConfig?: EngineGISConfig): Promise<EngineGISInstance>;
 
 declare function createWebGPUFillAdapter(engine: any, state: WebGPUClippingState): WebGPUFillAdapter;
 
-export declare type DeepPartial<T> = T extends (...args: never[]) => unknown ? T : T extends readonly (infer U)[] ? DeepPartial<U>[] : T extends object ? {
-    [K in keyof T]?: DeepPartial<T[K]>;
-} : T;
-
 export declare const DEFAULT_AUTO_EXPOSURE_OPTIONS: ResolvedAutoExposureOptions;
 
 export declare const DEFAULT_LIGHTING_PRESETS: readonly LightingPreset[];
@@ -2957,12 +3107,6 @@ declare interface DWGMetadata {
     layoutsUrl?: string;
 }
 
-/** 将 ECEF 坐标转换为指定 WGS84 原点下的局部 ENU。 */
-export declare function ecefToEnu(position: GisEcefPosition, origin: GisPosition): GisEnuPosition;
-
-/** 将 ECEF 坐标迭代还原为 WGS84，经极点分支避免除以接近零的 cos(latitude)。 */
-export declare function ecefToWgs84(position: GisEcefPosition): Required<GisPosition>;
-
 declare type EffectState = Record<WebGPUPostProcessingEffect, boolean>;
 
 /**
@@ -3029,6 +3173,10 @@ declare interface Engine720Options {
     dampingFactor?: number;
 }
 
+declare type EngineFrameCallback = (time: DOMHighResTimeStamp) => void;
+
+declare type EngineFrameCallback_2 = (time: DOMHighResTimeStamp) => void;
+
 /**
  * Gaussian 高斯点云引擎配置项。
  * 结构参考 core720，由 EngineKernel 统一装配各模块。
@@ -3052,6 +3200,15 @@ declare interface EngineGaussianOptions {
     viewerOptions?: Record<string, any>;
 }
 
+export declare type EngineGISConfig = GISOptions;
+
+export declare type EngineGISInstance = GIS;
+
+export declare type EngineGISOptions = EngineKernelV3Options & Pick<EngineKernelV2Options, 'limit_memory'> & {
+    /** 默认使用 v3；指定 v2 时创建原生 WebGLRenderer 引擎。 */
+    engineVersion?: GISEngineVersion;
+};
+
 /**
  * 引擎信息统计类
  * 用于统计引擎中模型的顶点和三角面数量
@@ -3510,6 +3667,7 @@ declare class EngineKernelV2 {
     private readonly _idleFrameInterval;
     private _lastIdleFrameTime;
     private readonly _idleFrameRateExemptionReasons;
+    private readonly frameCallbacks;
     private readonly _fpsCheckInterval;
     private readonly _fpsSwitchCooldown;
     private readonly _fpsThreshold;
@@ -3522,11 +3680,12 @@ declare class EngineKernelV2 {
     camera: THREE.Camera | null;
     renderer: THREE.WebGLRenderer | null;
     sceneModule: SceneModule;
-    cameraModule: CameraModule;
+    cameraModule: CameraModule_2;
     deviceModule: DeviceModule;
     renderModule: RenderModule;
     controlModule: ControlModule;
     composerModule: ComposerModule;
+    autoExposureModule: AutoExposureModule;
     loaderModule: LoaderModule;
     engineStatus: EngineStatus;
     events: EventModule;
@@ -3592,13 +3751,17 @@ declare class EngineKernelV2 {
     };
     version: string;
     private versionEl;
-    private container;
+    container: HTMLElement;
     constructor(options: EngineKernelV2Options);
     changeHandelBehavedMode(mode: string): void;
     getHandelBehavedMode(): string;
     updateVersionDisplay(): void;
     bindControlEvents(control: any): void;
     requestComposerRender(): void;
+    /** 与 v3 保持一致的统一重绘入口，供 GIS 等共享模块调用。 */
+    requestRender(): void;
+    /** 注册共享渲染循环回调，返回函数用于释放订阅。 */
+    addFrameCallback(callback: EngineFrameCallback): () => void;
     /**
      * 设置自动锁帧状态；开启后引擎空闲时限制为 1 FPS，关闭后持续全帧渲染。
      */
@@ -3680,9 +3843,21 @@ declare class EngineKernelV2 {
 
 /** v2 引擎初始化参数。 */
 export declare interface EngineKernelV2Options {
-    containerId: string;
+    container?: HTMLElement;
+    containerId?: string;
     /** 移动端硬件内存，单位 GB；用于选择纹理上限和后处理 MSAA 档位。 */
     limit_memory?: number;
+    /** v2 自动曝光；传入 false 可关闭，传入参数对象可覆盖默认值。默认开启。 */
+    autoExposure?: boolean | AutoExposureOptions;
+    /** 普通 Mesh 与实例批次的自动距离裁剪；传入 false 可整体关闭。 */
+    ordinaryMeshOptimization?: false | {
+        enabled?: boolean;
+        meshDistanceCullingEnabled?: boolean;
+        instanceDistanceCullingEnabled?: boolean;
+        instanceDistanceCullingUpdateIntervalMs?: number;
+        maxTrianglesPerMesh?: number;
+        minProjectedSizePx?: number;
+    };
     [key: string]: any;
 }
 
@@ -3698,7 +3873,7 @@ export declare class EngineKernelV3 {
     camera: THREE.Camera;
     renderer: WebGPURenderer;
     sceneModule: SceneModule_2;
-    cameraModule: CameraModule_2;
+    cameraModule: CameraModule_3;
     deviceModule: DeviceModule_2;
     renderModule: RenderModule_2;
     controlModule: ControlModule_2;
@@ -3716,7 +3891,7 @@ export declare class EngineKernelV3 {
     worldToScreen: WorldToScreen;
     modelProperties: ModelProperties_2;
     hoverHighLight: HoverHighLight_2;
-    autoExposureModule: AutoExposureModule;
+    autoExposureModule: AutoExposureModule_2;
     rxQuotaListMapper: RxQuotaListMapper_2;
     filterLoaderModel: FilterLoaderModel_2;
     /** v2 管理器完整集合，保留原有公开 API 以兼容现有调用方。 */
@@ -3759,7 +3934,6 @@ export declare class EngineKernelV3 {
     modelEditor: ModelEditor;
     modelQuantityList: ModelQuantityList;
     roomSpace: RoomSpace;
-    gisManager: GisManager;
     materialReplacement: MaterialReplacementManager;
     stats?: default_2;
     models: any[];
@@ -3778,6 +3952,7 @@ export declare class EngineKernelV3 {
     private readonly idleFrameInterval;
     private lastIdleFrameTime;
     private readonly idleFrameRateExemptionReasons;
+    private readonly frameCallbacks;
     private temporalRenderingRequired;
     private controlsEnabledBeforePause;
     private boundControl;
@@ -3806,6 +3981,8 @@ export declare class EngineKernelV3 {
     /** 仅在交互繁忙期间为时间域后处理保持连续帧，空闲时仍遵循 1 FPS 限帧。 */
     setTemporalRenderingRequired(enabled: boolean): void;
     setIdleFrameRateExempt(reason: string, exempt: boolean): void;
+    /** 注册共享渲染循环回调，返回函数用于释放订阅。 */
+    addFrameCallback(callback: EngineFrameCallback_2): () => void;
     private updateTemporalFrameRateExemption;
     pauseRendering(): void;
     resumeRendering(): void;
@@ -3828,6 +4005,7 @@ export declare interface EngineKernelV3Options {
     assetFiles?: File[] | FileList;
     sdkAuth?: SdkAuthOptions;
     version?: string;
+    /** 强制 WebGPURenderer 使用 WebGL2 后端，适用于后端兼容性验证。 */
     forceWebGL?: boolean;
     antialias?: boolean;
     /** 初始渲染像素比，运行时可由 EngineModelModule 修改，范围 0.5 至 2。 */
@@ -3857,7 +4035,7 @@ export declare interface EngineKernelV3Options {
     modelDepthBias?: boolean;
     postProcessing?: WebGPUPostProcessingOptions;
     /** 初始手动渲染等级，范围 1 至 12，默认 8。 */
-    renderQualityLevel?: RenderQualityLevel;
+    renderQualityLevel?: RenderQualityInput;
     /** 是否显示 EngineModelModule 维护的渲染设置面板，默认显示。 */
     renderQualityUI?: boolean;
     /** v3 自动曝光；传入 false 可关闭，传入参数对象可覆盖默认值。默认开启。 */
@@ -3994,10 +4172,12 @@ declare class EngineModelModule_2 {
     constructor(engine: any);
     /** 初始化默认手动等级和设置面板。 */
     init(): void;
-    /** 手动切换 1 至 12 级渲染质量。 */
-    setQualityLevel(level: number): void;
+    /** 手动切换 1 至 12 级渲染质量，同时接受 v2 三档模式名称。 */
+    setQualityLevel(level: RenderQualityInput): void;
     /** 返回当前数字渲染等级。 */
     getQualityLevel(): RenderQualityLevel;
+    /** 兼容 v2 的三档模式 API，并映射到 v3 的 1、5、8 级。 */
+    switchModel(mode: LegacyRenderMode): void;
     /** 返回指定等级的深拷贝，调用方可以安全地编辑草稿。 */
     getQualityPreset(level: number): RenderQualityPreset;
     /** 保存指定等级的完整参数，并按需立即应用。 */
@@ -4166,15 +4346,6 @@ declare class EngineStatus_2 {
  */
 declare type EntityType = 'LINE' | 'POLYLINE' | 'SPLINE' | 'CIRCLE' | 'HATCH' | 'INSERT' | 'MTEXT' | 'DIMENSIONLINEAR';
 
-/** 将局部 ENU 坐标转换回 ECEF。 */
-export declare function enuToEcef(position: GisEnuPosition, origin: GisPosition): GisEcefPosition;
-
-/** 将 ENU 映射到既有 V3 GIS 场景轴：+X 西、+Y 天、+Z 北。 */
-export declare function enuToScene(position: GisEnuPosition): GisScenePosition;
-
-/** 局部 ENU 到 WGS84 的组合转换。 */
-export declare function enuToWgs84(position: GisEnuPosition, origin: GisPosition): Required<GisPosition>;
-
 declare type EnvironmentType = 'none' | 'hdr' | 'sky';
 
 declare type EnvironmentType_2 = 'none' | 'hdr' | 'sky';
@@ -4873,1458 +5044,574 @@ declare interface GaussianSceneOptions {
 
 declare type GaussianVector3 = [number, number, number];
 
-/** 管理 WGS84、ECEF 与 V3 局部 ENU 场景之间的转换和浮动原点事务。 */
-export declare class GeoReferenceManager {
-    private origin;
-    private readonly floatingOrigin;
-    private readonly onOriginChange?;
-    private readonly participants;
-    private readonly ecefToSceneMatrix;
-    private readonly sceneToEcefMatrix;
-    private readonly temporaryVector;
-    private lastAutomaticChangeAt;
-    private disposed;
-    constructor(options: GeoReferenceManagerOptions);
-    /** 返回当前局部 ENU 原点的不可变副本。 */
-    getOrigin(): Readonly<Required<GisPosition>>;
-    /** 将 WGS84 经纬高转换为当前 V3 场景坐标。 */
-    geographicToScene(position: GisPosition, target?: Vector3): Vector3;
-    /** 将当前 V3 场景坐标转换为 WGS84 经纬高。 */
-    sceneToGeographic(position: GisScenePosition): Required<GisPosition>;
-    /** 复制 ECEF 到当前 V3 场景的仿射矩阵，避免调用方修改内部状态。 */
-    getEcefToSceneMatrix(target?: Matrix4): Matrix4;
-    /** 复制当前 V3 场景到 ECEF 的仿射矩阵。 */
-    getSceneToEcefMatrix(target?: Matrix4): Matrix4;
-    /** 注册需要在浮动原点变化时同步迁移的空间对象持有者。 */
-    registerParticipant(participant: GisOriginParticipant): () => void;
-    /** 手动变更局部原点；所有参与者在当前调用栈内完成迁移或整体回滚。 */
-    setOrigin(nextOrigin: GisPosition, reason?: GisOriginChangeReason): boolean;
-    /** 相机越过阈值时自动把原点移动到相机地理位置；返回本帧是否发生重定位。 */
-    updateFloatingOrigin(cameraPosition: GisScenePosition, now?: number): boolean;
-    /** 清理订阅并禁止继续执行坐标事务。 */
-    dispose(): void;
-    private rebuildMatrices;
-    /** 构建 ECEF 到既有 +X 西、+Y 天、+Z 北场景轴的刚体变换。 */
-    private createEcefToSceneMatrix;
-    private assertUsable;
-}
-
-declare interface GeoReferenceManagerOptions {
-    origin: GisPosition;
-    floatingOrigin?: GisFloatingOriginConfig;
-    onOriginChange?: (event: GisOriginTransaction) => void;
-}
-
 /**
  * 获取 SDK 内置 public 资源根路径，默认使用版本固定的 CDN。
  */
 export declare function getSdkAssetBaseUrl(moduleUrl?: string): string;
 
-declare interface GisAmapImageryLayerConfig extends GisImageryLayerBase {
-    provider: 'amap';
-    layer: 'vector' | 'satellite' | 'labels';
-    key?: GisCredentialProvider;
-    subdomains?: readonly string[];
-}
-
-declare interface GisAttributionDisplayItem {
-    sourceIds: readonly string[];
-    html: string;
-    order: number;
-}
-
-export declare interface GisAttributionDisplayModel {
-    items: readonly GisAttributionDisplayItem[];
-    html: string;
-}
-
-export declare interface GisAttributionEntry {
-    sourceId: string;
-    html: string;
-    visible?: boolean;
-    order?: number;
-}
-
-declare interface GisCacheKeyInput {
-    url: string;
-    method?: string;
-    headers?: Readonly<Record<string, string>>;
-    credential?: string;
-}
-
-declare interface GisCacheMetrics {
-    entries: number;
-    hits: number;
-    misses: number;
-    evictions: number;
-}
-
-export declare interface GisCameraConfig {
-    controller?: {
-        type?: GisControllerType;
-        gis?: GisNavigationControlsOptions;
-        orbitV2?: GisOrbitControlsV2Options;
-    };
-    minHeightAboveSurface?: number;
-    nearFarMode?: 'auto' | 'manual';
-}
-
-/** 统一维护 GIS 相机裁剪面；V3 Renderer 已启用反向深度以提高大范围场景精度。 */
-export declare class GisCameraManager {
-    private readonly geoReference;
-    private readonly options;
-    private camera;
-    private readonly snapshots;
-    private readonly nearFarMode;
-    private readonly minHeightAboveSurface;
-    constructor(camera: Camera, geoReference: GeoReferenceManager, options: GisCameraManagerOptions);
-    /** 相机实例发生切换时记录原裁剪面，销毁 GIS 后可准确恢复。 */
-    setCamera(camera: Camera): void;
-    /** 根据相机椭球高和显示模式收紧 near/far，避免近地深度精度被无界 far 消耗。 */
-    updateClippingPlanes(surfaceHeight?: number): boolean;
-    /** 将相机抬升到最小离地高度，供两种控制器共享同一碰撞底线。 */
-    enforceMinimumHeight(surfaceHeight?: number): boolean;
-    /** 恢复所有接管过的相机裁剪面，不改变相机类型或姿态。 */
-    dispose(): void;
-    private calculateGlobeFar;
-    private capture;
-}
-
-declare interface GisCameraManagerOptions {
-    displayMode: GisDisplayMode;
-    nearFarMode?: 'auto' | 'manual';
-    minHeightAboveSurface?: number;
-}
-
-/** GIS 相机视角；姿态角均使用度。 */
-export declare interface GisCameraView extends GisPosition {
-    heading?: number;
-    pitch?: number;
-    roll?: number;
-}
-
-declare interface GisCesiumIonImageryLayerConfig extends GisImageryLayerBase {
-    provider: 'cesium-ion';
-    assetId: string | number;
-    token: GisCredentialProvider;
-}
-
-/** Cesium ion 鉴权描述只保存凭据引用，不在公开数据源中暴露 Token 明文。 */
-export declare interface GisCesiumIonTilesetAuthentication {
-    type: 'cesium-ion';
-    assetId: string;
-    endpointUrl: string;
-    credentialSourceId: string;
-    autoRefreshToken: boolean;
-}
-
-declare interface GisCesiumIonTilesetConfig extends GisTilesetBaseConfig {
-    provider: 'cesium-ion';
-    assetId: string | number;
-    token: GisCredentialProvider;
-    autoRefreshToken?: boolean;
-}
-
-declare interface GisCesiumTerrainConfig extends GisTerrainBaseConfig {
-    provider: 'cesium-ion';
-    assetId: string | number;
-    token: GisCredentialProvider;
-}
-
-declare interface GisContextHost {
-    scene: Scene;
-    camera: Camera;
-    renderer: GisRuntimeRenderer;
-    container: HTMLElement;
-    options: {
-        backgroundColor?: ColorRepresentation | 'transparent' | null;
-    };
-    controls?: GisOrbitControls | null;
-    controlModule?: {
-        orbitControls?: GisOrbitControls | null;
-        active?: (controls?: GisOrbitControls) => void;
-        disActive?: () => void;
-    };
-    skyManager: GisSkyService;
-    models?: Array<{
-        url?: string;
-        boundingBox?: Box3;
-    }>;
-    requestComposerRender?: () => void;
-    requestShadowUpdate?: () => void;
-    setIdleFrameRateExempt?: (reason: string, enabled: boolean) => void;
-    bindControlEvents?: (controls: GisOrbitControls) => void;
-    composerModule?: {
-        markSceneDirty?: () => void;
-    };
-}
-
-declare interface GisControllerChangeEvent {
-    previous: GisControllerType;
-    current: GisControllerType;
-}
-
-declare interface GisControllerConstraints {
-    minDistance: number;
-    maxDistance: number;
-    minHeightAboveSurface: number;
-    enableCollision: boolean;
-    enableHorizonConstraint: boolean;
-}
-
-/** 控制器之间传递的稳定快照；位置使用 WGS84，上方向使用 ECEF 单位向量。 */
-declare interface GisControllerState {
-    camera: Required<GisPosition>;
-    target: Required<GisPosition>;
-    upEcef: GisScenePosition;
-    distance: number;
-    zoom: number;
-    enabled: boolean;
-    constraints: GisControllerConstraints;
-}
-
-declare interface GisControllerSwitchErrorEvent {
-    requested: GisControllerType;
-    error: GisError;
-}
-
-declare interface GisControllerSwitchOptions {
-    /** 即使目标类型与当前类型相同，也重新同步一次状态。 */
-    force?: boolean;
-}
-
-declare interface GisControllerSwitchResult {
-    changed: boolean;
-    previous: GisControllerType;
-    current: GisControllerType;
-    rolledBack: boolean;
-    error?: GisError;
-}
-
-export declare type GisControllerType = 'gis' | 'orbit-v2';
-
-declare type GisCoordinateSystem = 'WGS84' | 'GCJ02';
-
-declare interface GisCredentialEvent {
-    sourceId: string;
-}
-
-/** 统一解析 Token/Key，并合并同一数据源的并发刷新请求。 */
-export declare class GisCredentialManager {
-    private readonly records;
-    private readonly refreshes;
-    private readonly now;
-    private readonly expirationSkewMs;
-    private readonly onExpired?;
-    private disposed;
-    constructor(options?: GisCredentialManagerOptions);
-    /** 注册或替换数据源凭据；凭据本身不会写入日志、事件或持久缓存。 */
-    register(sourceId: string, provider: GisCredentialProvider): void;
-    /** 移除数据源凭据及其刷新引用。 */
-    remove(sourceId: string): void;
-    /** 解析有效凭据；同一 sourceId 的并发调用共享一个 Promise。 */
-    resolve(sourceId: string, forceRefresh?: boolean): Promise<string>;
-    /** 标记服务端判定的凭据过期，并发出不含 Token 的结构化事件。 */
-    markExpired(sourceId: string): void;
-    /** 强制刷新并继续复用并发刷新任务。 */
-    refresh(sourceId: string): Promise<string>;
-    /** 返回缓存隔离所需的不可逆指纹，不暴露真实凭据。 */
-    getFingerprint(sourceId: string): Promise<string>;
-    /** 清除全部凭据引用，并阻止在途刷新结果写回缓存。 */
-    dispose(): void;
-    private resolveProvider;
-    private isExpired;
-    private assertUsable;
-    private createMissingError;
-}
-
-declare interface GisCredentialManagerOptions {
-    now?: () => number;
-    expirationSkewMs?: number;
-    onExpired?: (sourceId: string) => void;
-}
-
-export declare type GisCredentialProvider = string | (() => string | GisCredentialValue | Promise<string | GisCredentialValue>);
-
-export declare interface GisCredentialValue {
-    value: string;
-    /** Unix 毫秒时间戳；到期前会重新调用异步提供器。 */
-    expiresAt?: number;
-}
-
-/** 聚合各图层版权信息，并随显隐、替换和删除实时生成显示模型。 */
-export declare class GisCreditCollection {
-    private readonly entries;
-    private readonly onChange?;
-    constructor(onChange?: (count: number) => void);
-    /** 添加或替换版权来源；内容未变化时不触发更新。 */
-    upsert(entry: GisAttributionEntry): void;
-    /** 同步图层显隐状态，不删除其版权元数据。 */
-    setVisible(sourceId: string, visible: boolean): void;
-    /** 删除已卸载数据源对应的版权信息。 */
-    remove(sourceId: string): void;
-    /** 清空全部版权来源。 */
-    clear(): void;
-    /** 按顺序聚合可见版权，并把相同文案合并为一个显示项。 */
-    getDisplayModel(): GisAttributionDisplayModel;
-    /** 返回已登记来源总数，包括当前隐藏来源。 */
-    getSourceCount(): number;
-    private emitChange;
-}
-
-declare interface GisCreditConfig {
-    visible?: boolean;
-}
-
-declare interface GisDiagnosticError {
-    timestamp: number;
-    code: GisErrorCode;
-    module: string;
-    sourceId?: string;
-    message: string;
-}
-
-/** 汇总请求、缓存、Provider 和错误指标，不持有场景或业务 UI。 */
-export declare class GisDiagnostics {
-    private requests;
-    private cache;
-    private providerCount;
-    private attributionCount;
-    private readonly recentErrors;
-    private readonly sourceResponses;
-    private disposed;
-    /** 同步当前等待队列长度。 */
-    requestQueued(queueSize: number): void;
-    /** 记录请求开始和当前活动请求数。 */
-    requestStarted(active: number): void;
-    /** 累加一次请求重试。 */
-    requestRetried(): void;
-    /** 记录成功响应及其数据源状态。 */
-    requestCompleted(sourceId: string | undefined, status: number | undefined, durationMs: number): void;
-    /** 记录失败、取消或超时，错误文案会在保存前脱敏。 */
-    requestFailed(error: GisError, sourceId: string | undefined, durationMs: number): void;
-    /** 请求结算后同步活动数与排队数。 */
-    requestSettled(active: number, queued: number): void;
-    /** 累加一次缓存命中。 */
-    cacheHit(): void;
-    /** 累加一次缓存未命中。 */
-    cacheMiss(): void;
-    /** 同步缓存占用和累计淘汰数量。 */
-    setCacheState(entries: number, evictions: number): void;
-    /** 同步已注册 Provider 数量。 */
-    setProviderCount(count: number): void;
-    /** 同步已登记版权来源数量。 */
-    setAttributionCount(count: number): void;
-    /** 返回与内部可变状态隔离的结构化快照。 */
-    getSnapshot(): GisDiagnosticsSnapshot;
-    /** 清理诊断历史并阻止异步请求继续写入。 */
-    dispose(): void;
-    private createErrorRecord;
-    private setSourceResponse;
-}
-
-export declare interface GisDiagnosticsSnapshot {
-    requests: Readonly<GisRequestMetrics>;
-    cache: Readonly<GisCacheMetrics>;
-    providers: number;
-    attributions: number;
-    recentErrors: readonly GisDiagnosticError[];
-    sourceResponses: readonly GisSourceResponseState[];
-}
-
-export declare type GisDisplayMode = 'planar' | 'terrain' | 'globe';
-
-/** ECEF 地心地固直角坐标，单位为米。 */
-export declare interface GisEcefPosition {
-    x: number;
-    y: number;
-    z: number;
-}
-
-/** 以局部原点为基准的东、北、天坐标，单位为米。 */
-export declare interface GisEnuPosition {
-    east: number;
-    north: number;
-    up: number;
-}
-
-export declare interface GisEnvironmentConfig {
-    sky?: boolean | GisSkyConfig;
-    fog?: boolean | GisFogConfig;
-}
-
-/** GIS 统一错误对象，保留原始异常但不在 message 中拼接凭据。 */
-export declare class GisError extends Error {
-    readonly code: GisErrorCode;
-    readonly module: GisErrorModule;
-    readonly cause?: unknown;
-    readonly sourceId?: string;
-    readonly layerId?: string;
-    readonly fieldPath?: string;
-    readonly retryable: boolean;
-    readonly suggestedAction?: string;
-    constructor(options: GisErrorOptions);
-}
-
-/** GIS 错误码保持结构化，业务不需要解析错误文案。 */
-export declare type GisErrorCode = 'GIS_CONFIG_INVALID' | 'GIS_INVALID_STATE' | 'GIS_COORDINATE_INVALID' | 'GIS_CREDENTIALS_MISSING' | 'GIS_CREDENTIALS_EXPIRED' | 'GIS_REQUEST_CANCELLED' | 'GIS_NETWORK_ERROR' | 'GIS_NETWORK_TIMEOUT' | 'GIS_FORMAT_UNSUPPORTED' | 'GIS_DECODE_FAILED' | 'GIS_LEVEL_OUT_OF_RANGE' | 'GIS_SURFACE_UNAVAILABLE' | 'GIS_WEBGPU_UNSUPPORTED' | 'GIS_FEATURE_NOT_IMPLEMENTED' | 'GIS_INITIALIZATION_FAILED' | 'GIS_CONTROLLER_UNAVAILABLE' | 'GIS_CONTROLLER_SWITCH_FAILED' | 'GIS_DISPOSED';
-
-declare type GisErrorModule = 'manager' | 'config' | 'state' | 'imagery' | 'terrain' | 'tileset' | 'camera' | 'controller' | 'environment' | 'credentials' | 'provider' | 'diagnostics' | 'network' | 'placement';
-
-declare interface GisErrorOptions {
-    code: GisErrorCode;
-    module: GisErrorModule;
-    message: string;
-    cause?: unknown;
-    sourceId?: string;
-    layerId?: string;
-    fieldPath?: string;
-    retryable?: boolean;
-    suggestedAction?: string;
-}
-
-declare type GisEventListener<K extends GisEventType> = (event: GisEventMap[K]) => void;
-
-/** 所有 GIS 对外事件的载荷映射。 */
-export declare interface GisEventMap {
-    'state-change': GisStateChangeEvent;
-    ready: void;
-    error: GisError;
-    'layer-added': GisLayerEvent;
-    'layer-ready': GisLayerEvent;
-    'layer-error': GisLayerErrorEvent;
-    'layer-removed': GisLayerEvent;
-    'tile-load-progress': GisTileProgressEvent;
-    'tileset-state-change': GisTilesetPhaseEvent;
-    'tileset-metadata-ready': GisLayerEvent;
-    'tileset-first-visible': GisLayerEvent;
-    'tileset-idle': GisLayerEvent;
-    'camera-change': GisCameraView;
-    'controller-change': GisControllerChangeEvent;
-    'controller-switch-error': GisControllerSwitchErrorEvent;
-    'origin-change': GisOriginChangeEvent;
-    'terrain-ready': GisTerrainEvent;
-    'credentials-expired': GisCredentialEvent;
-    'model-placement-change': GisModelPlacementChangeEvent;
-    'model-placement-refined': GisModelPlacementRefinedEvent;
-    'model-placement-error': GisModelPlacementErrorEvent;
-}
-
-declare type GisEventType = keyof GisEventMap;
-
-declare interface GisFlatTerrainConfig extends GisTerrainBaseConfig {
-    provider: 'flat';
-    height?: number;
-}
-
-export declare interface GisFloatingOriginConfig {
-    enabled?: boolean;
-    /** 相机距局部原点达到该距离后重定位，单位为米。 */
-    thresholdMeters?: number;
-    /** 两次自动重定位的最小间隔，单位为毫秒。 */
-    minimumIntervalMs?: number;
-}
-
-/** 地理相机飞行选项；动画由 V3 单一渲染循环驱动。 */
-declare interface GisFlyToOptions {
-    durationMs?: number;
-    easing?: 'linear' | 'ease-in-out';
-    signal?: AbortSignal;
-}
-
-declare interface GisFogConfig {
-    enabled?: boolean;
-    color?: ColorRepresentation;
-    density?: number;
-}
-
-/** @deprecated 新代码使用 GisEnvironmentConfig.fog。 */
-export declare interface GisFogOptions {
-    enabled?: boolean;
-    color?: ColorRepresentation;
-    density?: number;
-}
-
-export declare interface GisGeoReferenceConfig {
-    floatingOrigin?: GisFloatingOriginConfig;
-}
-
-declare interface GisHeightmapTerrainConfig extends GisTerrainBaseConfig {
-    provider: 'heightmap';
-    url: string;
-    encoding?: 'mapbox' | 'terrarium' | 'raw';
-}
-
-/** 高度相对于椭球、地形或地形偏移的语义。 */
-export declare type GisHeightReference = 'ellipsoid' | 'terrain' | 'relative-to-terrain';
-
-/** 高度参考解析结果统一换算为 WGS84 椭球高。 */
-export declare interface GisHeightResolution {
-    heightReference: GisHeightReference;
-    ellipsoidHeight: number;
-    terrainHeight: number | null;
-    usedFallback: boolean;
-}
-
-declare interface GisHeightResolutionOptions {
-    fallbackTerrainHeight?: number;
-    surfaceOffset?: number;
-}
-
-declare interface GisImageryLayerBase {
-    id: string;
-    visible?: boolean;
-    opacity?: number;
-    zIndex?: number;
-    minLevel?: number;
-    maxLevel?: number;
-    tileSize?: number;
-    attribution?: string;
-}
-
-export declare type GisImageryLayerConfig = GisAmapImageryLayerConfig | GisTiandituImageryLayerConfig | GisCesiumIonImageryLayerConfig | GisXyzImageryLayerConfig | GisWmtsImageryLayerConfig | GisWmsImageryLayerConfig;
-
-declare interface GisImageryLayerHandle extends GisLayerHandle {
-    readonly type: 'imagery';
-    readonly provider: string;
-    readonly zIndex: number;
-}
-
-declare interface GisImageryLayerUpdate {
-    visible?: boolean;
-    opacity?: number;
-    zIndex?: number;
-}
-
-/** @deprecated 仅供旧 createEngine({ gis }) 运行时转换；新代码使用 GisManagerConfig。 */
-export declare interface GisImageryOptions {
-    type?: 'xyz';
-    url: string;
-    projection?: 'EPSG:3857' | 'EPSG:4326';
-    coordinateSystem?: 'WGS84' | 'GCJ02';
-    levels?: number;
-    tileDimension?: number;
-    attribution?: string;
-}
-
-declare type GisImageryRequestScheme = 'xyz' | 'wmts';
-
-/** 影像 Provider 交给瓦片运行时的标准描述，不包含第三方插件实例。 */
-declare interface GisImagerySourceDescriptor extends GisSourceDescriptor {
-    kind: 'imagery';
-    url: string;
-    scheme: GisImageryRequestScheme;
-    projection: GisProjection;
-    coordinateSystem: GisCoordinateSystem;
-    minimumLevel: number;
-    maximumLevel: number;
-    tileSize: number;
-    headers?: Readonly<Record<string, string>>;
-    wmts?: {
-        layer: string;
-        style: string;
-        tileMatrixSet: string;
-        format: string;
-        tileMatrixLabels?: readonly string[];
-        dimensions?: Readonly<Record<string, string | number>>;
-    };
-}
-
-/** 旧试验 API 允许只覆盖部分视角字段；新代码优先使用 GisCameraView。 */
-export declare type GisInitialView = Partial<GisCameraView>;
-
-declare interface GisLayerErrorEvent extends GisLayerEvent {
-    error: GisError;
-}
-
-declare interface GisLayerEvent {
-    id: string;
-    type: 'imagery' | 'terrain' | 'tileset';
-}
-
-/** 对外暴露的稳定图层句柄，不泄漏第三方瓦片对象。 */
-export declare interface GisLayerHandle {
-    readonly id: string;
-    readonly type: 'imagery' | 'terrain' | 'tileset';
-    readonly state: GisLayerState;
-    readonly visible: boolean;
-    readonly opacity: number;
-}
-
-/** 图层在统一管理器中的生命周期状态。 */
-declare type GisLayerState = 'loading' | 'ready' | 'error' | 'removed';
-
-/** 旧试验 API 的兼容别名；新代码使用 GisPosition。 */
-export declare type GisLocalOrigin = GisPosition;
-
-/** V3 GIS 唯一公开门面，统一管理配置、状态、事件与内部模块生命周期。 */
-export declare class GisManager {
-    private readonly events;
-    private readonly stateController;
-    private readonly context;
-    private readonly diagnostics;
-    private readonly providerRegistry;
-    private readonly attributions;
-    private config;
-    private network;
-    private geoReference;
-    private cameraManager;
-    private controllerManager;
-    private runtime;
-    private initializePromise;
-    private lifecycleToken;
-    private legacyAutoInitialize;
-    private legacyCallbacks;
-    readonly imagery: ImageryLayerManager;
-    readonly tilesets: TilesetManager;
-    readonly models: GisModelPlacementManager;
-    constructor(host: GisModuleContextHost, legacyOption?: GisOption);
-    /** 当前兼容运行时的 TilesRenderer；新业务应使用后续图层 API。 */
-    get tiles(): TilesRenderer | null;
-    /** 当前兼容运行时使用的 OrbitControlsV2。 */
-    get controls(): GisOrbitControls | null;
-    /** 同步校验并冻结 GIS 配置，不触发网络请求或创建场景资源。 */
-    configure(config: GisManagerConfig): void;
-    /** 初始化 GIS 资源；并发或重复调用复用同一个任务。 */
-    initialize(): Promise<void>;
-    private initializeInternal;
-    /** 从 stopped 状态恢复已有资源，不重复注册监听或重新请求首屏。 */
-    start(): void;
-    /** 暂停 GIS 更新和输入，但保留已加载资源。 */
-    stop(): void;
-    /** 释放 GIS 自有资源并恢复到 idle；Manager 本身仍可重新配置。 */
-    reset(): Promise<void>;
-    /** 永久销毁 GIS Manager；异步回调在生命周期令牌失效后不再回写。 */
-    dispose(): void;
-    /** 返回当前生命周期状态。 */
-    getState(): GisManagerState;
-    /** 返回校验并冻结后的配置；尚未配置时返回 null。 */
-    getConfig(): Readonly<GisManagerConfig> | null;
-    /** 注册自定义 Provider；新增供应商无需修改影像、地形或相机模块。 */
-    registerProvider<TConfig>(provider: GisProvider<TConfig>): () => void;
-    /** 通过注册器创建标准化数据源描述，供后续图层 Manager 消费。 */
-    createProviderSource<TConfig>(kind: GisProviderKind, providerId: string, config: TConfig): Promise<GisSourceDescriptor>;
-    /** 返回不包含 URL Token 和 Header 凭据的运行诊断快照。 */
-    getDiagnostics(): GisDiagnosticsSnapshot;
-    /** 添加或替换数据源版权；图层显隐与移除应同步调用对应方法。 */
-    setAttribution(entry: GisAttributionEntry): void;
-    /** 同步图层显隐对应的版权显示状态。 */
-    setAttributionVisible(sourceId: string, visible: boolean): void;
-    /** 移除已卸载数据源的版权信息。 */
-    removeAttribution(sourceId: string): void;
-    /** 返回已经排序并去重的版权显示模型。 */
-    getAttributions(): GisAttributionDisplayModel;
-    /** 返回当前局部 ENU 原点；尚未配置时返回 null。 */
-    getOrigin(): Readonly<Required<GisPosition>> | null;
-    /** 将公开 WGS84 坐标转换为当前 V3 GIS 场景坐标。 */
-    geographicToScene(position: GisPosition): GisScenePosition;
-    /** 将当前 V3 GIS 场景坐标转换为公开 WGS84 坐标。 */
-    sceneToGeographic(position: GisScenePosition): Required<GisPosition>;
-    /** 手动移动局部原点；运行中的空间对象会在同一事务内同步迁移。 */
-    setOrigin(origin: GisPosition): boolean;
-    /** 深度合并配置并按原运行状态重建 GIS 资源。 */
-    updateConfig(patch: DeepPartial<GisManagerConfig>): Promise<void>;
-    /** 订阅 GIS 类型化事件，并返回退订函数。 */
-    on<K extends GisEventType>(type: K, listener: GisEventListener<K>): () => void;
-    /** 移除 GIS 类型化事件监听。 */
-    off<K extends GisEventType>(type: K, listener: GisEventListener<K>): void;
-    /** 每帧入口由 V3 单一渲染循环驱动。 */
-    update(): void;
-    /** 同步容器尺寸变化，不创建额外 ResizeObserver。 */
-    resize(): void;
-    /** 设置地理相机视角；当前兼容运行时需处于 ready 或 stopped。 */
-    setView(view: GisCameraView): void;
-    /** 在单一渲染循环中飞行到指定 WGS84 视角。 */
-    flyTo(view: GisCameraView, options?: GisFlyToOptions): Promise<void>;
-    /** 返回当前 GIS 相机视角。 */
-    getView(): GisCameraView;
-    /** 事务式切换 GIS 专用控制器与共享 OrbitControlsV2。 */
-    setController(type: GisControllerType, options?: GisControllerSwitchOptions): Promise<GisControllerSwitchResult>;
-    /** 返回当前实际激活或配置待激活的控制器类型。 */
-    getControllerType(): GisControllerType;
-    /** 返回可跨控制器恢复的 WGS84 状态快照。 */
-    getControllerState(): Readonly<GisControllerState>;
-    /** 将普通场景对象放置到 WGS84 位置。 */
-    placeObject(object: Object3D, placement: GisObjectPlacement): void;
-    /** 将现有 loaderModule 模型放置到 WGS84 位置。 */
-    placeModel(modelUrl: string, placement: GisObjectPlacement): boolean;
-    /** 对当前兼容地表执行高程采样。 */
-    sampleSurfaceHeight(latitude: number, longitude: number, options?: GisSurfaceQueryOptions): Promise<number | null>;
-    /** 将普通模型底面放置到当前地表。 */
-    placeModelOnSurface(modelUrl: string, placement: GisObjectPlacement, options?: GisSurfacePlacementOptions): Promise<GisSurfacePlacementResult>;
-    /** 更新当前 GIS 天空；完整环境配置将在 M9 接入。 */
-    setSky(option: boolean | GisSkyOptions): void;
-    /** 更新当前 GIS 雾；完整环境配置将在 M9 接入。 */
-    setFog(option: boolean | GisFogOptions): void;
-    /** @deprecated 兼容旧内部调用，新代码使用 initialize()。 */
-    init(): Promise<void>;
-    /** 返回是否已经配置 GIS，供旧调用方迁移期间判断。 */
-    isEnabled(): boolean;
-    /** 仅由 Engine 启动旧 createEngine({ gis }) 转换后的配置。 */
-    initializeLegacyIfConfigured(): Promise<void>;
-    private configureLegacyEngineOption;
-    private reportRuntimeError;
-    private assertRuntimeReady;
-    private assertControllerReady;
-    /** 按资源依赖逆序释放，确保共享 OrbitControlsV2 最后恢复。 */
-    private disposeInitializedResources;
-    private assertGeoReference;
-}
-
-/** GIS 的全部配置由 GisManager 持有，不属于 EngineKernel 初始化参数。 */
-export declare interface GisManagerConfig {
-    displayMode: GisDisplayMode;
-    origin: GisPosition;
-    initialView?: GisCameraView;
-    imageryLayers?: GisImageryLayerConfig[];
-    terrain?: false | GisTerrainConfig;
-    tilesets?: GisTilesetConfig[];
-    environment?: GisEnvironmentConfig;
-    camera?: GisCameraConfig;
-    georeference?: GisGeoReferenceConfig;
-    performance?: GisPerformanceConfig;
-    credits?: GisCreditConfig;
-    request?: GisRequestConfig;
-}
-
-/** @deprecated 仅供一个次要版本的旧配置转换器使用。 */
-export declare interface GisManagerOptions {
-    enabled?: boolean;
-    mode?: GisMode;
-    imagery?: GisImageryOptions;
-    imageryLayers?: readonly GisRuntimeImageryLayer[];
-    tilesets?: readonly GisRuntimeTilesetLayer[];
-    tilesetUrl?: string;
-    apiToken?: string;
-    assetId?: string;
-    autoRefreshToken?: boolean;
-    initialView?: GisInitialView;
-    localOrigin?: false | GisLocalOrigin;
-    dracoDecoderPath?: string;
-    fade?: boolean;
-    creasedNormals?: boolean;
-    creaseAngle?: number;
-    errorTarget?: number;
-    loadSiblings?: boolean;
-    maximumCachedTiles?: number;
-    nearFarMode?: 'auto' | 'manual';
-    minHeightAboveSurface?: number;
-    showCredits?: boolean;
-    sky?: boolean | GisSkyOptions;
-    fog?: boolean | GisFogOptions;
-    onLoad?: () => void;
-    onError?: (error: Error) => void;
-}
-
-/** GIS Manager 的公开生命周期状态。 */
-export declare type GisManagerState = 'idle' | 'configured' | 'initializing' | 'ready' | 'stopped' | 'error' | 'disposed';
-
-export declare type GisMode = 'photogrammetry' | 'planar';
-
-/** 放置状态事件载荷。 */
-declare interface GisModelPlacementChangeEvent {
-    handle: GisModelPlacementHandle;
-}
-
-/** 放置错误事件载荷。 */
-declare interface GisModelPlacementErrorEvent {
-    modelId: string;
-    error: Error;
-}
-
-/** 对外只读的放置记录，不暴露 Three.js 对象和内部异步任务。 */
-export declare interface GisModelPlacementHandle {
-    id: string;
-    placement: Readonly<GisObjectPlacement>;
-    options: Readonly<GisModelPlacementOptions>;
-    state: GisModelPlacementState;
-    revision: number;
-    result: Readonly<GisModelPlacementResult> | null;
-}
-
-/**
- * 管理普通 V3 模型的地理放置状态，不接管模型下载、拾取、材质或 GPU 资源。
- * loaderModule 只需要在模型完成加载与卸载时发送通知。
- */
-export declare class GisModelPlacementManager {
-    private readonly context;
-    private readonly records;
-    private readonly directObjects;
-    private geoReference;
-    private unregisterOriginParticipant;
+/** 独立承载 3D Tiles、地球控制器及其生命周期，不依赖旧 GIS Manager。 */
+declare class GIS {
+    readonly options: GISOptions;
+    readonly engine: GISEngineKernel;
+    tiles: TilesRenderer | null;
+    loaderModule: LoaderModule_3;
+    resourceLoaderModule: GISResourceLoaderModule | null;
+    readonly layerManager: GISLayerManager;
+    coordinateModule: CoordinateModule | null;
+    controls: GlobeControls | null;
+    cameraModule: CameraModule | null;
+    controllerModule: ControllerModule | null;
+    modelPositionManager: ModelPositionManager | null;
+    modelCalibrationManager: GISModelCalibrationManager | null;
+    label: GISLabelManager | null;
+    viewCube: GISMainViewManager | null;
+    skyManager: GISSkyManager | null;
+    private resizeObserver;
+    private removeFrameCallback;
+    private previousTime;
     private disposed;
-    constructor(context: GisModelPlacementManagerOptions);
-    /** 绑定当前坐标参考系；重新 configure 后会按地理坐标恢复已有放置记录。 */
-    bindGeoReference(geoReference: GeoReferenceManager | null): void;
-    /** 注册或更新普通模型放置；模型尚未加载时保留为 waiting-model 并在加载通知后自动应用。 */
-    place(modelId: string, placement: GisObjectPlacement, options?: GisModelPlacementOptions): Promise<GisModelPlacementResult>;
-    /** 合并更新现有记录，并重新执行锚点、姿态与高度解析。 */
-    update(modelId: string, update: GisModelPlacementUpdate): Promise<GisModelPlacementResult>;
-    /** 返回指定模型的只读状态快照。 */
-    get(modelId: string): GisModelPlacementHandle | null;
-    /** 返回全部普通模型放置状态快照。 */
-    list(): GisModelPlacementHandle[];
-    /** 删除放置记录；默认恢复 loader 创建时的模型根变换，但不卸载模型。 */
-    remove(modelId: string, restoreTransform?: boolean): boolean;
-    /** loaderModule 完成模型加载后调用；已有待处理放置会自动落位。 */
-    notifyModelLoaded(modelId: string): void;
-    /** loaderModule 卸载模型前调用；放置配置保留，以支持同 URL 重新加载。 */
-    notifyModelUnloaded(modelId: string): void;
-    /** 地形数据源或可见瓦片变化后，重新采样所有贴地与相对贴地模型。 */
-    refreshSurfacePlacements(): Promise<GisModelPlacementResult[]>;
-    /** 兼容旧同步 API：把当前 height 直接视作椭球高应用，并同时建立后续可更新记录。 */
-    placeImmediate(modelId: string, placement: GisObjectPlacement): boolean;
-    /** 放置非 loader 模型对象；该对象同样参与浮动原点事务，但不进入普通模型注册表。 */
-    placeObject(object: Object3D, placement: GisObjectPlacement): void;
-    /** 终止后台回补和原点订阅；模型及其 GPU 资源仍归 loaderModule 所有。 */
-    dispose(): void;
-    private applyRecord;
-    private sampleSurface;
-    private attachTarget;
-    private resolveAnchor;
-    private applyResolvedPlacement;
-    private scheduleRefinement;
-    private queueRefinementAttempt;
-    private refineSurface;
-    private applyOriginChange;
-    private transformObject;
-    private reapplyPlacedObjects;
-    private createRecord;
-    private createResult;
-    private toHandle;
-    private emitChange;
-    private reportError;
-    private cancelRefinement;
-    private cancelAllRefinements;
-    private isCurrent;
-    private normalizeDuration;
-    private requireRecord;
-    private requireGeoReference;
-    private assertUsable;
-}
-
-declare interface GisModelPlacementManagerOptions {
-    getTarget(modelId: string): GisModelPlacementTarget | null;
-    sampleSurfaceHeight(latitude: number, longitude: number, options: GisModelPlacementOptions): Promise<number | null>;
-    markSceneChanged(): void;
-    emit<K extends GisEventType>(type: K, value: GisEventMap[K]): void;
-}
-
-/** 普通模型贴地和异步回补策略；所有高度与时间分别使用米和毫秒。 */
-export declare interface GisModelPlacementOptions extends GisSurfacePlacementOptions {
-    /** 地表暂不可用时是否继续后台采样并自动回补。 */
-    refineAfterFallback?: boolean;
-    /** 后台回补的最长持续时间。 */
-    refineTimeoutMs?: number;
-}
-
-/** 后台地表回补成功事件载荷。 */
-declare interface GisModelPlacementRefinedEvent {
-    result: GisModelPlacementResult;
-}
-
-/** 单次放置或回补后的结构化结果。 */
-export declare interface GisModelPlacementResult {
-    modelId: string;
-    placed: boolean;
-    state: GisModelPlacementState;
-    heightReference: GisHeightReference;
-    surfaceHeight: number | null;
-    appliedHeight: number;
-    usedFallback: boolean;
-    pendingSurfaceRefinement: boolean;
-}
-
-/** 普通 V3 模型地理放置的生命周期状态。 */
-export declare type GisModelPlacementState = 'waiting-model' | 'sampling-surface' | 'placed' | 'fallback' | 'error';
-
-declare interface GisModelPlacementTarget {
-    group: Object3D;
-    boundingBox?: Box3;
-}
-
-/** 更新接口允许只覆盖需要变化的经纬度、姿态或贴地策略。 */
-export declare interface GisModelPlacementUpdate {
-    placement?: Partial<GisObjectPlacement>;
-    options?: Partial<GisModelPlacementOptions>;
-}
-
-/** GIS 子模块可访问的最小 V3 能力集合，不暴露完整 Engine。 */
-declare interface GisModuleContext {
-    readonly scene: Scene;
-    readonly camera: Camera;
-    readonly renderer: GisRuntimeRenderer;
-    readonly container: HTMLElement;
-    readonly inputElement: HTMLElement;
-    readonly backgroundColor: ColorRepresentation | 'transparent' | null | undefined;
-    readonly sky: GisSkyService;
-    getOrbitControls(): GisOrbitControls | null;
-    getActiveControls(): GisOrbitControls | null;
-    setActiveControls(controls: GisOrbitControls): void;
-    restoreActiveControls(controls: GisOrbitControls | null, enabled: boolean): void;
-    getModelPlacementTarget(modelUrl: string): GisModelPlacementTarget | null;
-    requestRender(): void;
-    requestShadowUpdate(): void;
-    markSceneDirty(): void;
-    setContinuousRender(reason: string, enabled: boolean): void;
-    emit<K extends GisEventType>(type: K, value: GisEventMap[K]): void;
-}
-
-declare type GisModuleContextHost = GisContextHost;
-
-declare interface GisNavigationControlsOptions {
-    enableCollision?: boolean;
-    enableHorizonConstraint?: boolean;
-    rotateSpeed?: number;
-    zoomSpeed?: number;
-}
-
-/** 将场景对象锚定到地理位置时使用的位置和朝向。 */
-export declare interface GisObjectPlacement extends GisCameraView {
-    /** 模型默认使用底面中心，普通对象固定使用自身原点。 */
-    anchor?: 'origin' | 'bottom-center';
-    heightReference?: GisHeightReference;
-}
-
-/** @deprecated 从 EngineKernelV3Options 移除，仅在运行时兼容层识别。 */
-export declare type GisOption = boolean | GisManagerOptions;
-
-/** GIS 运行时使用到的 OrbitControlsV2 稳定接口。 */
-declare interface GisOrbitControls {
-    enabled: boolean;
-    object?: Camera;
-    target?: Vector3;
-    origin?: Vector3;
-    minDistance?: number;
-    maxDistance?: number;
-    enableDamping?: boolean;
-    syncStateFromCamera?: (camera: Camera, target: Vector3, options?: {
-        origin?: 'target' | Vector3;
-        referenceUp?: Vector3;
-    }) => boolean;
-    update?: (force?: boolean) => boolean;
-}
-
-declare interface GisOrbitControlsV2Options {
-    minDistance?: number;
-    maxDistance?: number;
-    enableDamping?: boolean;
-}
-
-declare interface GisOriginChangeEvent {
-    previous: GisPosition;
-    current: GisPosition;
-}
-
-declare type GisOriginChangeReason = 'manual' | 'floating-origin';
-
-declare interface GisOriginParticipant {
-    /** 实现必须同步完成，且能够接受反向事务以支持失败回滚。 */
-    applyOriginChange(event: GisOriginTransaction): void;
-}
-
-/** 内部原点事务事件；sceneTransform 将旧场景坐标原子映射到新场景坐标。 */
-declare interface GisOriginTransaction {
-    previous: Required<GisPosition>;
-    current: Required<GisPosition>;
-    reason: GisOriginChangeReason;
-    sceneTransform: Readonly<Matrix4>;
-}
-
-declare interface GisPerformanceConfig {
-    errorTarget?: number;
-    loadSiblings?: boolean;
-    requestConcurrency?: number;
-    maximumCachedTiles?: number;
-}
-
-/** 对外地理位置统一使用 WGS84，经纬度为度，高度为米。 */
-export declare interface GisPosition {
-    longitude: number;
-    latitude: number;
-    height?: number;
-}
-
-declare type GisProjection = 'EPSG:3857' | 'EPSG:4326';
-
-/** 所有供应商适配器遵循同一接口，新增 Provider 无需修改业务 Manager。 */
-export declare interface GisProvider<TConfig = unknown> {
-    readonly id: string;
-    readonly kind: GisProviderKind;
-    readonly capabilities: Readonly<GisProviderCapabilities>;
-    createSource(config: TConfig, context: GisProviderContext): GisSourceDescriptor | Promise<GisSourceDescriptor>;
-}
-
-export declare interface GisProviderCapabilities {
-    readonly projections?: readonly GisProjection[];
-    readonly coordinateSystems?: readonly GisCoordinateSystem[];
-    readonly minimumLevel?: number;
-    readonly maximumLevel?: number;
-    readonly supportsAuthentication?: boolean;
-    readonly supportsAttribution?: boolean;
-    readonly supportsMultipleSources?: boolean;
-}
-
-declare interface GisProviderContext {
-    readonly requests: GisRequestScheduler;
-    readonly credentials: GisCredentialManager;
-    readonly diagnostics: GisDiagnostics;
-}
-
-export declare type GisProviderKind = 'imagery' | 'terrain' | 'tileset' | 'ion';
-
-/** 保存可插拔 Provider，并校验其能力声明与标准化输出。 */
-export declare class GisProviderRegistry {
-    private readonly providers;
-    private readonly onChange?;
-    private disposed;
-    constructor(onChange?: (count: number) => void);
-    /** 注册 Provider；返回的退订函数只移除本次注册的实例。 */
-    register<TConfig>(provider: GisProvider<TConfig>): () => void;
-    /** 按类型和 ID 查询 Provider，不泄漏注册表可变集合。 */
-    get<TConfig = unknown>(kind: GisProviderKind, id: string): GisProvider<TConfig> | null;
-    /** 返回全部或指定类型 Provider 的只读快照。 */
-    list(kind?: GisProviderKind): readonly GisProvider[];
-    /** 调用 Provider 并验证描述符没有跨类型或冒充其他 Provider。 */
-    createSource<TConfig>(kind: GisProviderKind, id: string, config: TConfig, context: GisProviderContext): Promise<GisSourceDescriptor>;
-    /** 清空注册项并禁止销毁后继续注册或创建数据源。 */
-    dispose(): void;
-    private assertUsable;
-    private createProviderError;
-}
-
-declare interface GisProviderRequestDescriptor {
-    url: string;
-    method?: string;
-    headers?: Readonly<Record<string, string>>;
-    query?: Readonly<Record<string, string>>;
-    credentialSourceId?: string;
-}
-
-declare interface GisQuantizedMeshTerrainConfig extends GisTerrainBaseConfig {
-    provider: 'quantized-mesh';
-    url: string;
-    headers?: Record<string, string>;
-}
-
-declare interface GisRequestConfig {
-    timeoutMs?: number;
-    retryCount?: number;
-    retryBaseDelayMs?: number;
-}
-
-declare interface GisRequestExecutionContext {
-    signal: AbortSignal;
-    attempt: number;
-}
-
-declare interface GisRequestExecutionResult<T> {
-    data: T;
-    status?: number;
-    headers?: Readonly<Record<string, string>>;
-}
-
-declare interface GisRequestMetadata {
-    requestId: string;
-    sourceId?: string;
-    url: string;
-    method: string;
-    status?: number;
-    startedAt: number;
-    completedAt: number;
-    durationMs: number;
-    attempts: number;
-    fromCache: boolean;
-}
-
-declare interface GisRequestMetrics {
-    queued: number;
-    active: number;
-    started: number;
-    completed: number;
-    failed: number;
-    canceled: number;
-    timedOut: number;
-    retried: number;
-}
-
-export declare interface GisRequestResult<T> {
-    data: T;
-    headers: Readonly<Record<string, string>>;
-    metadata: GisRequestMetadata;
-}
-
-/** 为全部 GIS Provider 提供统一的并发、取消、超时与重试调度。 */
-export declare class GisRequestScheduler {
-    private readonly queue;
-    private readonly active;
-    private readonly concurrency;
-    private readonly timeoutMs;
-    private readonly retryCount;
-    private readonly retryBaseDelayMs;
-    private readonly cache;
-    private readonly diagnostics;
-    private readonly ownsCache;
-    private requestSequence;
-    private disposed;
-    constructor(options?: GisRequestSchedulerOptions, dependencies?: {
-        cache?: GisResponseCache;
-        diagnostics?: GisDiagnostics;
-    });
-    /** 入队请求并返回可独立取消的句柄。 */
-    schedule<T>(task: GisRequestTask<T>): GisScheduledRequest<T>;
-    /** 取消排队或执行中的单个请求。 */
-    cancel(id: string, reason?: string): void;
-    /** 返回当前等待执行的请求数量。 */
-    getQueueSize(): number;
-    /** 返回当前占用并发槽位的请求数量。 */
-    getActiveCount(): number;
-    /** 取消所有任务并阻止迟到的 Promise 结果写入缓存与诊断。 */
-    dispose(): void;
-    private drain;
-    private run;
-    private runAttempt;
-    private waitForRetry;
-    private normalizeError;
-    private createCancelError;
-    private createRejectedHandle;
-    private syncCacheMetrics;
-}
-
-declare interface GisRequestSchedulerOptions {
-    concurrency?: number;
-    timeoutMs?: number;
-    retryCount?: number;
-    retryBaseDelayMs?: number;
-}
-
-export declare interface GisRequestTask<T> {
-    id?: string;
-    sourceId?: string;
-    url: string;
-    method?: string;
-    headers?: Readonly<Record<string, string>>;
-    /** 仅用于生成不可逆缓存指纹，不进入诊断或错误信息。 */
-    credential?: string;
-    signal?: AbortSignal;
-    timeoutMs?: number;
-    retryCount?: number;
-    retryBaseDelayMs?: number;
-    cache?: boolean;
-    cacheKey?: string;
-    cacheTtlMs?: number;
-    execute(context: GisRequestExecutionContext): Promise<GisRequestExecutionResult<T>>;
-    shouldRetry?(error: GisError, attempt: number): boolean;
-}
-
-/** 保存可复用的标准化响应；采用有界 LRU，避免瓦片请求无限占用内存。 */
-export declare class GisResponseCache {
-    private readonly entries;
-    private readonly maxEntries;
-    private readonly defaultTtlMs;
-    private readonly now;
-    private evictionCount;
-    private disposed;
-    constructor(options?: GisResponseCacheOptions);
-    /** 读取缓存并刷新 LRU 顺序；过期项目会立即释放。 */
-    get<T>(key: string): GisRequestResult<T> | null;
-    /** 写入响应并淘汰最久未使用项目；零容量配置等同关闭缓存。 */
-    set<T>(key: string, value: GisRequestResult<T>, ttlMs?: number): void;
-    /** 清空全部缓存项，但保留缓存实例供后续请求复用。 */
-    clear(): void;
-    /** 返回当前未过期或尚未访问清理的缓存项数量。 */
-    getSize(): number;
-    /** 返回因容量上限发生的累计淘汰次数。 */
-    getEvictionCount(): number;
-    /** 清空缓存并禁止后续异步请求重新写入。 */
+    private baseMapSwitchVersion;
+    private activeBaseSource;
+    private readonly runtimeEngine;
+    constructor(engine: GISEngineKernel, options: GISOptions);
+    /** 按 Three.js 官方示例注册插件、定位相机并启动瓦片调度。 */
+    initialize(): Promise<this>;
+    /** 返回 GIS 是否已完成初始化且尚未销毁。 */
+    isInitialized(): boolean;
+    /** 兼容旧版业务入口，加载 3D Tiles 并返回稳定模型句柄。 */
+    load3DTiles(options: GISLoadTilesetOptions & {
+        url: string;
+        flyTo?: boolean;
+    }): Promise<GISLoadedTileset>;
+    /** 统一加载在线 3D Tiles、glTF/GLB、GeoJSON 或 BIM 模型。 */
+    loadModel(url: string, options?: GISModelLoadOptions): Promise<GISLoadedModel>;
+    /** 加载本地 3D Tiles 文件集、glTF/GLB、GeoJSON 或 BIM 文件包。 */
+    loadModelFile(files: File[] | FileList, options?: GISLocalLoadOptions & LoadModelOptions): Promise<GISLoadedModel[]>;
+    /** 解析 ViewToken 并通过统一 GIS 资源加载链路加载。 */
+    loadModelByViewToken(viewToken: string, options?: GISModelLoadOptions): Promise<GISLoadedModel[]>;
+    /** 按统一模型句柄或 id 卸载资源。 */
+    removeModel(idOrModel: string | GISLoadedModel): boolean;
+    /**
+     * 运行时切换 GIS 底图，并保留当前 WGS84 相机视角和业务图层。
+     * 新底图加载失败时不会修改当前场景。
+     */
+    switchBaseMap(source: GISImageId | GISSource): Promise<void>;
+    /** 同时支持 3D Tiles 图层 id 和 BIM 模型 URL 的 ENU 校准。 */
+    applyCalibration(options: GISModelCalibrationOptions): boolean;
+    /** 返回全部 3D Tiles 与 BIM 校准状态。 */
+    getModelCalibrationItems(): GISModelCalibrationItem[];
+    /** 恢复指定 3D Tiles 或 BIM 模型的校准基准矩阵。 */
+    resetModelCalibration(id: string): boolean;
+    /** 释放控制器、瓦片缓存、事件以及 v3 引擎持有的 GPU 资源。 */
     dispose(): void;
-}
+    private configureControls;
+    /** WebGPU 不编译 GlobeControls 内置的 GLSL ShaderMaterial，因此禁用该辅助圆圈。 */
+    private disableIncompatiblePivotMarker;
+    /** WebGPURenderer 可承载 WebGPU 或 WebGL2，兼容逻辑必须按实际后端判断。 */
+    private usesWebGpuBackend;
+    private readonly update;
+    private readonly updateResolution;
+    private readonly requestRender;
+    private readonly handleLoadError;
+    private getBaseLayerSource;
+    private requireResourceLoader;
+}
+
+/** GIS 场景可切换的控制器模式。 */
+export declare const GISControllerMode: {
+    readonly GIS: "gis";
+    readonly Default: "default";
+    readonly FirstPerson: "first-person";
+    readonly ThirdPerson: "third-person";
+};
 
-declare interface GisResponseCacheOptions {
-    maxEntries?: number;
-    defaultTtlMs?: number;
-    now?: () => number;
-}
+export declare type GISControllerMode = typeof GISControllerMode[keyof typeof GISControllerMode];
 
-/** M5 平面瓦片运行时的内部输入，由 Provider 标准描述符生成。 */
-declare interface GisRuntimeImageryLayer {
-    source: GisImagerySourceDescriptor;
-    visible: boolean;
-    opacity: number;
-    zIndex: number;
+export declare interface GISControllerSwitchOptions {
+    /** 切回 v3 默认控制器时是否保持当前相机姿态。 */
+    preserveCameraPose?: boolean;
+    /** 原样透传给 v3 第三人称控制器的配置。 */
+    thirdPersonOptions?: unknown;
 }
 
-declare interface GisRuntimeRenderer {
-    readonly isWebGPURenderer?: boolean;
-    getPixelRatio(): number;
+/** GIS 对外统一使用的 WGS84 地理坐标，角度单位为度，高度单位为米。 */
+export declare interface GISCoordinate {
+    longitude: number;
+    latitude: number;
+    height?: number;
 }
 
-/** 多实例 3D Tiles 渲染器的内部输入，由 Provider 标准描述符生成。 */
-declare interface GisRuntimeTilesetLayer {
-    source: GisTilesetSourceDescriptor;
-    visible: boolean;
-    maximumScreenSpaceError: number;
-    maximumCachedTiles: number;
-    requestConcurrency: number;
-    transform: GisTilesetTransformConfig;
-}
+/** XYZ 影像采用的经纬度坐标基准。 */
+export declare type GISCoordinateSystem = 'wgs84' | 'gcj02';
 
-declare interface GisSceneBounds {
-    center: GisScenePosition;
-    radius: number;
+export declare interface GISCubeSkyBoxOptions {
+    urls: GISSkyBoxUrls;
+    /** 背景亮度与环境光强度，默认值为 1。 */
+    intensity?: number;
+    /** 背景模糊度，取值范围为 0 到 1。 */
+    blurriness?: number;
+    /** 天空盒绕 Y 轴旋转角度，单位为度。 */
+    rotation?: number;
 }
 
-/** V3 GIS 兼容场景坐标，约定 +X 向西、+Y 向天、+Z 向北，单位为米。 */
-export declare interface GisScenePosition {
-    x: number;
-    y: number;
-    z: number;
-}
+export declare type GISEngineKernel = EngineKernelV2 | EngineKernelV3;
 
-export declare interface GisScheduledRequest<T> {
-    readonly id: string;
-    readonly promise: Promise<GisRequestResult<T>>;
-    cancel(reason?: string): void;
+/** GIS 使用的底层引擎版本；WebGPU 使用 v3，WebGL 使用 v2。 */
+export declare type GISEngineVersion = 'v2' | 'v3';
+
+export declare interface GISFlyToOptions {
+    durationMs?: number;
+    signal?: AbortSignal;
 }
 
-declare interface GisSkyConfig {
-    enabled?: boolean;
-    preset?: SkyPresetName_2;
-    intensity?: number;
-    params?: SkyParams_2;
+export declare interface GISFlyToTilesetOptions {
+    /** 包围球之外的留白倍率，默认 1.25。 */
+    padding?: number;
+    /** 等待根瓦片元数据的超时时间，默认 15 秒。 */
+    timeoutMs?: number;
+    /** 相机相对局部地平线的仰角，单位为度，默认 35。 */
+    elevation?: number;
 }
 
-/** @deprecated 新代码使用 GisEnvironmentConfig.sky。 */
-export declare interface GisSkyOptions {
-    enabled?: boolean;
-    preset?: SkyPresetName_2;
+export declare interface GISHdrSkyBoxOptions {
+    /** v3 引擎内置 HDR 标识，默认使用晴朗无云的 4。 */
+    id?: string;
+    /** HDR 环境光强度，默认值为 0.2。 */
     intensity?: number;
-    params?: SkyParams_2;
+    /** HDR 背景亮度，默认值为 1。 */
+    backgroundIntensity?: number;
 }
 
-declare interface GisSkyService {
-    isActive(): boolean;
-    activate(): void;
-    close(force?: boolean): void;
-    setPreset(name: SkyPresetName_2): void;
-    setParams(params: SkyParams_2): void;
-    setIntensity(intensity: number): void;
+/** 引擎内置影像配置标识。 */
+export declare type GISImageId = 'cesium' | 'gd' | 'gd2';
+
+/** 管理 WGS84 GIS 标签，并在可见 GIS/BIM 图层上完成选点。 */
+export declare class GISLabelManager {
+    private readonly engine;
+    private readonly coordinateModule;
+    private readonly layerManager;
+    private readonly manager;
+    private readonly worldToScreen;
+    private readonly raycaster;
+    constructor(engine: EngineKernelV3, coordinateModule: CoordinateModule, layerManager: GISLayerManager);
+    /** 进入一次选点模式，结果同时包含 WGS84 和 Three.js 世界坐标。 */
+    pickPoint(): Promise<LabelCoordinate | null>;
+    /** 兼容旧版回调式选点。 */
+    startPickPoint(callback?: (coordinate: LabelCoordinate | null) => void): Promise<LabelCoordinate | null>;
+    /** 创建 GIS 标签；经纬度按 WGS84 解释。 */
+    createLabel(options: LabelCreateOptions): string;
+    /** 更新指定 GIS 标签。 */
+    updateLabel(id: string, options: LabelUpdateOptions): boolean;
+    /** 删除指定 GIS 标签。 */
+    deleteLabel(id: string): boolean;
+    /** deleteLabel 的兼容别名。 */
+    removeLabel(id: string): boolean;
+    /** 清空全部 GIS 标签。 */
+    clearLabels(): void;
+    /** 查询单个 GIS 标签。 */
+    getLabel(id: string): LabelInstance | undefined;
+    /** 查询全部 GIS 标签。 */
+    getLabels(): LabelInstance[];
+    /** 监听标签点击，并返回取消监听函数。 */
+    onLabelClick(callback: LabelClickCallback): () => void;
+    /** 取消指定标签点击监听。 */
+    offLabelClick(callback: LabelClickCallback): void;
+    /** 由 GIS 共享帧循环更新标签屏幕位置。 */
+    update(): void;
+    /** 释放 DOM、选点监听和标签数据。 */
+    dispose(): void;
+    private projectCoordinate;
+    private resolveWorldCoordinate;
+    private pickCoordinate;
+    private uniqueObjects;
 }
 
-/** Provider 输出的稳定描述，不向上层泄漏第三方插件实例。 */
-export declare interface GisSourceDescriptor {
+export declare interface GISLayerInfo {
     id: string;
-    provider: string;
-    kind: GisProviderKind;
-    projection?: GisProjection;
-    coordinateSystem?: GisCoordinateSystem;
-    attribution?: readonly string[];
-    request?: GisProviderRequestDescriptor;
-    metadata?: Readonly<Record<string, unknown>>;
+    name: string;
+    type: GISLayerType;
+    source?: string;
+    visible: boolean;
+    /** 图层对应的 Three.js 场景对象，供高级业务读取。 */
+    object: Object3D;
 }
 
-declare interface GisSourceResponseState {
-    sourceId: string;
-    status?: number;
-    durationMs: number;
-    timestamp: number;
-    ok: boolean;
+/** 统一登记 GIS 数据图层，并通过场景对象显隐实现无损开关。 */
+export declare class GISLayerManager {
+    private readonly engine;
+    private readonly layers;
+    private layerSequence;
+    constructor(engine: EngineKernelV3);
+    /** 登记图层；不同对象不得复用同一个 id，避免产生无法查询的孤立图层。 */
+    registerLayer(registration: GISLayerRegistration): GISLayerInfo;
+    /** 查询全部 GIS 图层，返回快照以避免外部修改内部登记信息。 */
+    getLayers(): GISLayerInfo[];
+    /** 按 id 查询单个 GIS 图层。 */
+    getLayer(id: string): GISLayerInfo | null;
+    /** 仅合并当前可见的业务模型，避免底图、地形和标注放大回家视角。 */
+    getModelBoundingBox(): Box3_2 | null;
+    /** 设置图层显隐；图层不存在时返回 false。 */
+    setLayerVisible(id: string, visible: boolean): boolean;
+    /** 开启指定图层。 */
+    showLayer(id: string): boolean;
+    /** 关闭指定图层，但保留已加载资源。 */
+    hideLayer(id: string): boolean;
+    /** 切换指定图层，返回切换后的显隐状态；图层不存在时返回 null。 */
+    toggleLayer(id: string): boolean | null;
+    /** 注销图层登记，不移除或销毁场景资源。 */
+    unregisterLayer(id: string): boolean;
+    /** 调用资源所有者的释放回调并移除图层；无释放回调时返回 false。 */
+    removeLayer(id: string): boolean;
+    /** 清空登记信息；实际资源仍由各自加载器负责释放。 */
+    dispose(): void;
+    private toInfo;
 }
 
-declare interface GisStateChangeEvent {
-    previous: GisManagerState;
-    current: GisManagerState;
+export declare interface GISLayerRegistration {
+    /** 未指定时由管理器按图层类型生成。 */
+    id?: string;
+    name: string;
+    type: GISLayerType;
+    source?: string;
+    object: Object3D;
+    /** 由资源所有者提供的释放回调；未提供时图层只允许注销登记。 */
+    remove?: () => boolean | void;
 }
 
-export declare interface GisSurfacePlacementOptions extends GisSurfaceQueryOptions {
-    surfaceOffset?: number;
-    fallbackHeight?: number;
-}
+/** GIS 图层分类；天空和控制器不属于可开关的数据图层。 */
+export declare type GISLayerType = 'imagery' | 'tileset' | 'model' | 'vector' | 'custom';
 
-export declare interface GisSurfacePlacementResult {
-    placed: boolean;
-    surfaceHeight: number | null;
-    appliedHeight: number;
+/** 对外稳定的 GIS 模型句柄，避免业务依赖具体加载器内部结构。 */
+export declare interface GISLoadedModel {
+    id: string;
+    name: string;
+    type: GISModelType;
+    source: string;
+    object: Object3D;
+    raw?: TilesRenderer | Object3D;
 }
 
-export declare interface GisSurfaceQueryOptions {
-    timeoutMs?: number;
-    retryIntervalMs?: number;
+/** 3D Tiles 模型句柄。 */
+export declare interface GISLoadedTileset extends GISLoadedModel {
+    type: '3dtiles';
+    raw: TilesRenderer;
 }
 
-declare interface GisTerrainBaseConfig {
-    id: string;
-    attribution?: string;
+declare interface GISLoaderTilesetLifecycle {
+    onTilesetAdded?(tiles: TilesRenderer, layer: {
+        id: string;
+        name: string;
+        source: string;
+    }, ready: boolean): void;
+    onTilesetReady?(tiles: TilesRenderer): void;
+    onTilesetRemoved?(tiles: TilesRenderer, layerId?: string): void;
 }
 
-export declare type GisTerrainConfig = GisFlatTerrainConfig | GisCesiumTerrainConfig | GisQuantizedMeshTerrainConfig | GisHeightmapTerrainConfig;
-
-declare interface GisTerrainEvent {
-    id: string;
+export declare interface GISLoadTilesetOptions {
+    /** 图层管理器中的稳定标识；未指定时自动生成。 */
+    id?: string;
+    /** 图层列表中的显示名称，默认使用 URL。 */
+    name?: string;
+    /** 高度偏移，单位为米；局部坐标模式下只改变 Y，不改变水平位置。 */
+    heightOffset?: number;
+    /** 自定义请求入口，供本地 tileset 文件集映射使用。 */
+    fetchData?: (url: string, options?: RequestInit) => Promise<Response>;
 }
 
-declare type GisTerrainHeightSampler = (latitude: number, longitude: number) => number | null | Promise<number | null>;
+/** GIS 本地文件加载选项。 */
+export declare interface GISLocalLoadOptions {
+    id?: string;
+    name?: string;
+    /** GeoJSON 未提供高度时采用的默认高度，单位为米。 */
+    height?: number;
+}
 
-declare interface GisTiandituImageryLayerConfig extends GisImageryLayerBase {
-    provider: 'tianditu';
-    layer: 'vec' | 'img' | 'ter' | 'cva' | 'cia' | 'cta';
-    matrixSet?: 'w' | 'c';
-    token: GisCredentialProvider;
-    subdomains?: readonly string[];
+/** GIS 局部原点；用于消除地心大坐标在 GPU 中产生的浮点精度抖动。 */
+declare interface GISLocalOrigin {
+    latitude: number;
+    longitude: number;
+    height?: number;
 }
 
-declare interface GisTileProgressEvent {
-    id: string;
-    type: 'tileset';
-    loaded: number;
-    total: number;
-    failed: number;
-    ratio: number;
+/** 保存和恢复可持久化的 WGS84 GIS 主视角。 */
+export declare class GISMainViewManager {
+    private cameraModule;
+    private readonly initialView;
+    private mainView;
+    constructor(cameraModule: CameraModule, initialView: GISView);
+    /** 切换底图重建相机模块后更新引用，同时保留已经保存的主视角。 */
+    setCameraModule(cameraModule: CameraModule): void;
+    /** 保存用户当前实际相机姿态，而不是上一次 API 写入的缓存。 */
+    saveMainViewPort(): Required<GISView>;
+    /** 设置主视角并立即应用；null 表示清除已保存视角。 */
+    setMainViewPort(view: GISView | null): void;
+    /** 平滑飞行到已保存的主视角；未保存时保持当前视图。 */
+    goToMainPort(options?: GISFlyToOptions): Promise<void>;
+    /** 清除主视角并回到初始化视图。 */
+    resetMainViewPort(): void;
+    /** 查询已保存主视角的独立快照。 */
+    getMainViewPort(): Required<GISView> | null;
 }
 
-declare interface GisTilesetBaseConfig extends GisTilesetTransformConfig {
+/** 3D Tiles 与 BIM 共用的校准状态快照。 */
+export declare interface GISModelCalibrationItem {
     id: string;
-    visible?: boolean;
-    maximumScreenSpaceError?: number;
-    maximumCachedTiles?: number;
-    requestConcurrency?: number;
-    flyTo?: boolean;
-    attribution?: string;
+    name: string;
+    source: string;
+    type: GISModelCalibrationTargetType;
+    offset: GISModelCalibrationOffset;
+    rotation: GISModelCalibrationRotation;
+    baseMatrix: number[];
+    ready: boolean;
 }
 
-/** tileset 在局部场景和 WGS84 中的包围球快照。 */
-declare interface GisTilesetBounds {
-    readonly center: GisScenePosition;
-    readonly geographicCenter: Required<GisPosition>;
-    readonly radius: number;
+/** 使用当地 ENU 坐标统一校准附加 3D Tiles 与普通 BIM 模型。 */
+export declare class GISModelCalibrationManager {
+    private readonly engine;
+    private readonly coordinateModule;
+    private readonly records;
+    constructor(engine: EngineKernelV3, coordinateModule: CoordinateModule);
+    /** 登记附加 3D Tiles；根节点就绪后再冻结加载完成矩阵作为校准基准。 */
+    registerTileset(id: string, name: string, source: string, tiles: TilesRenderer, ready?: boolean): GISModelCalibrationItem;
+    /** 高度偏移和根瓦片变换完成后，记录最终加载矩阵。 */
+    markTilesetReady(tiles: TilesRenderer): boolean;
+    /** 登记普通 BIM 模型；模型 URL 默认同时作为校准 id。 */
+    registerBimModel(url: string, options?: RegisterBimCalibrationOptions): GISModelCalibrationItem;
+    /** 查询全部模型校准状态快照。 */
+    getItems(): GISModelCalibrationItem[];
+    /** 查询单个模型校准状态。 */
+    getItem(id: string): GISModelCalibrationItem | null;
+    /**
+     * 从基准矩阵应用 ENU 偏移与旋转。
+     * 每次都从 baseMatrix 重算，避免滑块连续调整时累计产生水平漂移。
+     */
+    setTransform(options: GISModelCalibrationOptions): boolean;
+    /** 恢复模型登记时的矩阵。 */
+    reset(id: string): boolean;
+    /** 移除模型的校准记录，不改变模型当前矩阵。 */
+    unregister(id: string): boolean;
+    /** 释放内部快照，模型资源仍由各自加载器管理。 */
+    dispose(): void;
+    private createRecord;
+    private captureBaseState;
+    private readAnchorWorld;
+    private buildCalibratedLocalMatrix;
+    private applyMatrix;
+    private resolveOffset;
+    private resolveRotation;
+    private numberOrCurrent;
+    private emitChanged;
+    private cloneItem;
+    private zeroOffset;
+    private zeroRotation;
+}
+
+/** 模型在当地 ENU 坐标系中的平移，单位为米。 */
+export declare interface GISModelCalibrationOffset {
+    east: number;
+    north: number;
+    up: number;
 }
 
-export declare type GisTilesetConfig = GisUrlTilesetConfig | GisCesiumIonTilesetConfig;
-
-declare interface GisTilesetFlyToOptions extends GisFlyToOptions {
-    padding?: number;
-    minimumHeight?: number;
+/** 应用模型校准时允许只修改偏移或旋转中的一部分。 */
+export declare interface GISModelCalibrationOptions {
+    id: string;
+    offset?: Partial<GISModelCalibrationOffset>;
+    rotation?: Partial<GISModelCalibrationRotation>;
 }
 
-declare interface GisTilesetFormatCapability {
-    readonly id: string;
-    readonly support: GisTilesetFormatSupportLevel;
-    readonly note: string;
+/** 模型在当地 ENU 坐标系中的旋转，单位为度。 */
+export declare interface GISModelCalibrationRotation {
+    heading: number;
+    pitch: number;
+    roll: number;
 }
 
-declare type GisTilesetFormatSupportLevel = 'supported' | 'limited';
+export declare type GISModelCalibrationTargetType = '3dtiles' | 'bim';
 
-/** 3D Tiles 图层的公开快照，不暴露第三方 TilesRenderer 实例。 */
-declare interface GisTilesetLayerHandle extends GisLayerHandle {
-    readonly type: 'tileset';
-    readonly provider: string;
-    readonly maximumScreenSpaceError: number;
-    readonly maximumCachedTiles: number;
-    readonly requestConcurrency: number;
-    readonly phase: GisTilesetPhase;
-    readonly progress: Readonly<GisTileProgressEvent>;
-    readonly transform: Readonly<GisTilesetTransformConfig>;
+/** GIS 统一模型加载选项；type 可用于无扩展名 URL 的显式分流。 */
+export declare interface GISModelLoadOptions extends GISLocalLoadOptions, LoadModelOptions {
+    type?: GISModelType;
+    /** 3D Tiles 加载后是否自动跳转，默认 true。 */
+    flyTo?: boolean;
+    /** 3D Tiles 高度偏移，单位为米。 */
+    heightOffset?: number;
 }
 
-/** GIS-701 支持无需重建数据源即可热更新的 tileset 参数。 */
-declare interface GisTilesetLayerUpdate {
-    visible?: boolean;
-    maximumScreenSpaceError?: number;
-    maximumCachedTiles?: number;
-    requestConcurrency?: number;
-    transform?: GisTilesetTransformConfig;
+/** 普通 BIM 模型的 WGS84 定位信息；角度单位为度，高度单位为米。 */
+export declare interface GISModelPosition {
+    longitude: number;
+    latitude: number;
+    height?: number;
+    heading?: number;
+    pitch?: number;
+    roll?: number;
 }
 
-declare type GisTilesetPhase = 'loading-metadata' | 'metadata-ready' | 'first-visible' | 'idle' | 'error' | 'removed';
+/** GIS 统一模型类型。 */
+export declare type GISModelType = '3dtiles' | 'bim' | 'gltf' | 'geojson';
+
+declare interface GISOptions {
+    /** 内置影像配置标识，未指定时使用 Cesium。 */
+    imageId?: GISImageId;
+    /** 物理天空配置；未提供 sky 与 skyBox 时默认使用内置 HDR 天空盒。 */
+    sky?: boolean | GISSkyOptions;
+    /** 六面图天空盒配置；指定后优先于物理天空。 */
+    skyBox?: GISSkyBoxOptions;
+    source?: GISSource;
+    initialView?: GISView;
+    /** 城市级局部原点；默认使用 initialView 经纬度，传 false 可保留地心坐标。 */
+    localOrigin?: false | GISLocalOrigin;
+    /** Draco 解码器目录；默认使用 SDK 随包发布的 draco/ 资源，通常无需配置。 */
+    dracoDecoderPath?: string;
+    /** 屏幕空间误差阈值，越小近地瓦片越精细，默认值为 2。 */
+    errorTarget?: number;
+    loadSiblings?: boolean;
+    /** 是否启用瓦片渐隐；WebGPU GIS 默认关闭以避免父子 LOD 边界漏缝。 */
+    fade?: boolean;
+    /** 是否保留 TRAA；默认关闭，避免流式瓦片切换时产生时域抖动。 */
+    temporalAntialiasing?: boolean;
+    creasedNormals?: boolean;
+    creaseAngle?: number;
+    onError?: (error: Error) => void;
+}
 
-declare interface GisTilesetPhaseEvent extends GisLayerEvent {
-    phase: GisTilesetPhase;
+/**
+ * 统一加载 GIS 数据资源。
+ * 3D Tiles 复用 GIS 瓦片加载器，BIM 复用 v3 模型加载器，避免产生两套模型状态。
+ */
+export declare class GISResourceLoaderModule {
+    private readonly engine;
+    private readonly tilesLoader;
+    private readonly coordinateModule;
+    private readonly layerManager;
+    private readonly calibrationManager;
+    private readonly resources;
+    private sequence;
+    private disposed;
+    constructor(engine: EngineKernelV3, tilesLoader: LoaderModule_3, coordinateModule: CoordinateModule, layerManager: GISLayerManager, calibrationManager: GISModelCalibrationManager);
+    /** 按 URL 加载 3D Tiles、glTF/GLB、GeoJSON 或 v3 BIM 模型。 */
+    loadModel(url: string, options?: GISModelLoadOptions): Promise<GISLoadedModel>;
+    /**
+     * 加载浏览器选择的本地资源文件。
+     * 支持 3D Tiles 文件集、glTF/GLB、GeoJSON 和 v3 BIM 包，不包含 SHP。
+     */
+    loadModelFile(files: File[] | FileList, options?: GISLocalLoadOptions & LoadModelOptions): Promise<GISLoadedModel[]>;
+    /** 通过 SDK ViewToken 解析资源，再进入相同的类型分流和生命周期。 */
+    loadModelByViewToken(viewToken: string, options?: GISModelLoadOptions): Promise<GISLoadedModel[]>;
+    /** 移除统一资源句柄对应的模型和图层。 */
+    removeModel(idOrModel: string | GISLoadedModel): boolean;
+    /** 查询由本模块加载的全部资源句柄。 */
+    getModels(): GISLoadedModel[];
+    /** 释放独立资源；3D Tiles 与 BIM 分别交还各自底层加载器卸载。 */
+    dispose(): void;
+    private loadTileset;
+    private loadGltfUrl;
+    private loadLocalGltf;
+    private parseGltf;
+    private loadGeoJsonUrl;
+    private createGeoJsonModel;
+    private loadBimUrl;
+    private loadLocalBim;
+    private addBimModel;
+    private addStandaloneModel;
+    private track;
+    private loadLocalTileset;
+    private disposeObject;
+    private inferUrlType;
+    private inferResolvedType;
+    private isGeoJson;
+    private resolveId;
+    private normalizeUrl;
+    private filePath;
+    private baseName;
+    private baseNameFromPath;
+    private normalizePath;
+    private assertUsable;
 }
 
-export declare type GisTilesetProvider<TConfig = unknown> = GisProvider<TConfig> & {
-    readonly kind: 'tileset';
-};
+export declare type GISSkyBoxOptions = GISCubeSkyBoxOptions | GISHdrSkyBoxOptions;
 
-/** URL 数据源可通过该适配器接入项目自己的签名、解密或响应转换链。 */
-declare interface GisTilesetRequestAdapter {
-    preprocessUrl?: (url: string) => string;
-    fetch?: (url: string, options: RequestInit) => Promise<Response>;
-}
+/** 六面图顺序固定为：右、左、上、下、前、后。 */
+export declare type GISSkyBoxUrls = readonly [string, string, string, string, string, string];
 
-declare interface GisTilesetScale3D {
-    x: number;
-    y: number;
-    z: number;
+/** 为 GIS 提供内置 HDR、六面图和物理天空三种简单配置。 */
+export declare class GISSkyManager {
+    private readonly engine;
+    private readonly cubeTextureLoader;
+    private skyBoxTexture;
+    private savedSceneState;
+    private skyBoxLoadVersion;
+    private skyBoxType;
+    constructor(engine: EngineKernelV3);
+    /** 应用天空配置；传 false 时关闭并保留资源，便于后续快速恢复。 */
+    setSky(option?: boolean | GISSkyOptions): void;
+    /** 显示天空，并可同时覆盖预设、参数和环境光强度。 */
+    show(options?: GISSkyOptions): void;
+    /** 设置内置 HDR 或六面图天空盒，未传配置时使用内置晴空。 */
+    setSkyBox(options?: GISSkyBoxOptions): Promise<void>;
+    /** 清除天空盒并恢复设置前的场景背景和环境光。 */
+    clearSkyBox(): void;
+    private releaseCubeSkyBox;
+    /** 返回 HDR 或六面图天空盒是否已经应用到场景。 */
+    isSkyBoxActive(): boolean;
+    /** 隐藏当前天空；天空盒纹理会立即释放，物理天空可按需保留资源。 */
+    hide(remove?: boolean): void;
+    /** 切换 v3 引擎内置天空预设。 */
+    setPreset(preset: GISSkyPreset): void;
+    /** 增量修改太阳、云层和大气参数。 */
+    setParams(params: GISSkyParams): void;
+    /** 设置天空生成的环境光强度。 */
+    setIntensity(intensity: number): void;
+    /** 返回当前天空是否可见。 */
+    isActive(): boolean;
+    /** 释放 GIS 天空资源，v3 引擎销毁时仍会执行兜底清理。 */
+    dispose(): void;
+    private captureSceneState;
+    private validateSkyBoxOptions;
+    private refreshScene;
 }
 
-/** 3D Tiles Provider 交给运行时的标准描述，可表达直接 URL 或 ion endpoint。 */
-export declare interface GisTilesetSourceDescriptor extends GisSourceDescriptor {
-    kind: 'tileset';
-    url?: string;
-    headers?: Readonly<Record<string, string>>;
-    requestAdapter?: GisTilesetRequestAdapter;
-    authentication?: GisCesiumIonTilesetAuthentication;
+export declare interface GISSkyOptions {
+    preset?: GISSkyPreset;
+    params?: GISSkyParams;
+    intensity?: number;
 }
 
-/** 3D Tiles 的地理放置与本地校准参数，角度单位统一为度。 */
-declare interface GisTilesetTransformConfig {
-    position?: GisPosition;
-    enuOffset?: Partial<GisEnuPosition>;
+export declare type GISSkyParams = SkyParams_2;
+
+export declare type GISSkyPreset = SkyPresetName_2;
+
+declare type GISSource = {
+    type: 'url';
+    url: string;
+} | {
+    type: 'xyz';
+    url: string;
+    levels?: number;
+    tileDimension?: number;
+    /** 默认 WGS84；高德等中国大陆影像应指定为 GCJ-02。 */
+    coordinateSystem?: GISCoordinateSystem;
+} | {
+    type: 'cesium-ion';
+    assetId?: string | number;
+    autoRefreshToken?: boolean;
+};
+
+declare interface GISView {
+    latitude: number;
+    longitude: number;
+    height?: number;
     heading?: number;
     pitch?: number;
     roll?: number;
-    scale?: number | GisTilesetScale3D;
-    /** Three.js 列主序 4x4 矩阵，在地理 TRS 之后应用。 */
-    matrix?: readonly number[];
-}
-
-declare interface GisUrlTilesetConfig extends GisTilesetBaseConfig {
-    provider: 'url';
-    url: string;
-    headers?: Record<string, string>;
-    requestAdapter?: GisTilesetRequestAdapter;
 }
 
-/** Web Mercator EPSG:3857 平面坐标，单位为米。 */
-export declare interface GisWebMercatorPosition {
+/** GIS 场景中的 Three.js 世界坐标。 */
+export declare interface GISWorldCoordinate {
     x: number;
     y: number;
-    height?: number;
-}
-
-declare interface GisWmsImageryLayerConfig extends GisImageryLayerBase {
-    provider: 'wms';
-    url: string;
-    layers: string[];
-    version?: string;
-    format?: string;
-    transparent?: boolean;
-}
-
-declare interface GisWmtsImageryLayerConfig extends GisImageryLayerBase {
-    provider: 'wmts';
-    url: string;
-    layer: string;
-    style?: string;
-    tileMatrixSet: string;
-    format?: string;
-    requestEncoding?: 'KVP' | 'REST';
-    token?: GisCredentialProvider;
-    tokenParameter?: string;
-    projection?: GisProjection;
-    tileMatrixLabels?: readonly string[];
-    dimensions?: Readonly<Record<string, string | number>>;
-    subdomains?: readonly string[];
-}
-
-declare interface GisXyzImageryLayerConfig extends GisImageryLayerBase {
-    provider: 'xyz';
-    url: string;
-    scheme?: 'xyz' | 'tms';
-    projection?: GisProjection;
-    coordinateSystem?: GisCoordinateSystem;
-    headers?: Record<string, string>;
-    query?: Record<string, string>;
+    z: number;
 }
 
 declare class Grid {
@@ -6723,6 +6010,7 @@ declare class Hdr {
     private currentHdrId;
     private isVisible;
     private currentIntensity;
+    private currentBackgroundIntensity;
     private currentTexture;
     private currentEnvironmentTexture;
     private skybox;
@@ -6742,7 +6030,10 @@ declare class Hdr {
     getCurrentHdrId(): string;
     getVisible(): boolean;
     setIntensity(intensity: number): void;
+    /** 设置 HDR 背景亮度，不改变场景材质使用的环境光强度。 */
+    setBackgroundIntensity(intensity: number): void;
     getIntensity(): number;
+    getBackgroundIntensity(): number;
     addHdrItem(item: HdrItem): void;
     dispose(): void;
     private _loadHdr;
@@ -6864,6 +6155,7 @@ declare class HoverHighLight {
 declare class HoverHighLight_2 {
     private engine;
     private overlayMaterial;
+    private overlayGroup;
     private overlayMeshes;
     private animState;
     private animStartTime;
@@ -6873,6 +6165,8 @@ declare class HoverHighLight_2 {
     constructor(engine: any);
     showModelNameTag(model: any, originPosition: any): void;
     init(): void;
+    /** 同步当前剖切模式使用的平面，保证独立 hover 掩码只包含未被裁掉的几何。 */
+    syncClippingPlanes(planes?: THREE.Plane[]): void;
     /**
      * 高亮一个或多个网格，在原模型同位置生成轮廓掩码（原模型不受修改）
      * @param meshes  目标网格或网格数组，传 null/[] 则触发淡出清除
@@ -7104,90 +6398,6 @@ export declare interface ILoaderModule {
     getModel(modelId: string): IModel | undefined;
 }
 
-/** 影像图层公共控制器，负责 Provider、状态、版权和运行时事务。 */
-declare class ImageryLayerManager {
-    private readonly options;
-    private readonly records;
-    private readonly reportedRuntimeErrors;
-    private disposed;
-    constructor(options: ImageryLayerManagerOptions);
-    /** 仅保存已校验配置；不会创建数据源或发起请求。 */
-    configure(configs: readonly GisImageryLayerConfig[]): void;
-    /** 初始化阶段解析全部 Provider，供平面瓦片运行时一次接入。 */
-    resolveConfiguredLayers(): Promise<readonly GisRuntimeImageryLayer[]>;
-    /** 将瓦片运行时错误归一化并按图层去重，避免同一故障瓦片持续刷屏。 */
-    reportRuntimeError(id: string, error: unknown): GisError;
-    /** 运行时加载完成后统一提交 ready，避免 Provider 就绪被误认为 GPU 图层就绪。 */
-    markConfiguredLayersReady(): void;
-    add(config: GisImageryLayerConfig): Promise<GisImageryLayerHandle>;
-    update(id: string, patch: GisImageryLayerUpdate): Promise<GisImageryLayerHandle>;
-    replace(id: string, config: GisImageryLayerConfig): Promise<GisImageryLayerHandle>;
-    remove(id: string): Promise<boolean>;
-    get(id: string): GisImageryLayerHandle | null;
-    list(): readonly GisImageryLayerHandle[];
-    clear(): Promise<void>;
-    /** reset 时瓦片运行时已释放，此处只清理控制器快照。 */
-    reset(): void;
-    dispose(): void;
-    private createSource;
-    private createRecord;
-    private toRuntimeLayer;
-    private syncAttribution;
-    private sortedRecords;
-    private snapshot;
-    private requireRecord;
-    private requireRuntime;
-    private normalizeLayerError;
-    private layerError;
-    private assertUsable;
-}
-
-declare interface ImageryLayerManagerOptions {
-    providers: GisProviderRegistry;
-    getProviderContext: () => GisProviderContext | null;
-    getRuntime: () => ImageryTileRenderer | null;
-    setAttribution: (entry: GisAttributionEntry) => void;
-    setAttributionVisible: (id: string, visible: boolean) => void;
-    removeAttribution: (id: string) => void;
-    emit: <K extends GisEventType>(type: K, value: GisEventMap[K]) => void;
-}
-
-/** 平面影像瓦片渲染器，封装四叉树、LOD、缓存上限和 GPU 释放。 */
-declare class ImageryTileRenderer {
-    private readonly context;
-    private readonly origin;
-    private readonly errorTarget;
-    private readonly loadSiblings;
-    private readonly maximumCachedTiles;
-    private readonly onLayerError;
-    private readonly onPrimaryChange?;
-    private readonly layers;
-    private disposed;
-    constructor(context: GisModuleContext, origin: {
-        longitude: number;
-        latitude: number;
-        height: number;
-    }, errorTarget: number, loadSiblings: boolean, maximumCachedTiles: number, onLayerError: (id: string, error: Error) => void, onPrimaryChange?: ((tiles: TilesRenderer | null) => void) | undefined);
-    get primary(): TilesRenderer | null;
-    initialize(options: readonly GisRuntimeImageryLayer[]): Promise<void>;
-    add(options: GisRuntimeImageryLayer): Promise<void>;
-    updateLayer(id: string, patch: Partial<Pick<GisRuntimeImageryLayer, 'visible' | 'opacity' | 'zIndex'>>): void;
-    replace(id: string, options: GisRuntimeImageryLayer): Promise<void>;
-    remove(id: string): boolean;
-    update(): void;
-    setCamera(): void;
-    updateResolution(): void;
-    /** 浮动原点切换时同步迁移全部平面图层。 */
-    applyWorldTransform(transform: Matrix4): void;
-    dispose(): void;
-    private updateLayerOrdering;
-    private updateCacheBudgets;
-    private applyModelPresentation;
-    private correctWebGpuUv;
-    private requireLayer;
-    private assertUsable;
-}
-
 /**
  * 运行时模型对象接口
  */
@@ -7197,7 +6407,7 @@ export declare interface IModel {
     name: string;
     visible: boolean;
     /** 获取模型的包围盒 */
-    getBoundingBox(): Box3_2;
+    getBoundingBox(): Box3;
     /** 更新模型矩阵 */
     setMatrix(matrix: number[]): void;
 }
@@ -7236,6 +6446,8 @@ declare class InteractionModule {
     private getNodeGuid;
     handleMouseDoubleClick(event: any): void;
     private clearModelHighlightBeforeCameraFlight;
+    /** 单击选中后用构件世界包围盒建立控制器速度参照，不改变当前相机姿态。 */
+    private setSelectionReference;
     handleMouseClickInstance(raycaster: any): any;
     private ensureSelectionBox;
     private updateSelectionBox;
@@ -7330,6 +6542,8 @@ declare class InteractionModule_2 {
     private getNodeGuid;
     handleMouseDoubleClick(event: any): void;
     private clearModelHighlightBeforeCameraFlight;
+    /** 单击选中后用构件世界包围盒建立控制器速度参照，不改变当前相机姿态。 */
+    private setSelectionReference;
     handleMouseClickInstance(raycaster: any): any;
     private ensureSelectionBox;
     private updateSelectionBox;
@@ -7802,16 +7016,16 @@ declare class Label_2 {
     private pickRawModelIntersection;
 }
 
-declare type LabelClickCallback = (payload: LabelClickPayload) => void;
+export declare type LabelClickCallback = (payload: LabelClickPayload) => void;
 
-declare interface LabelClickPayload {
+export declare interface LabelClickPayload {
     id: string;
     label: LabelInstance;
     coordinate: LabelCoordinate;
     originalEvent: MouseEvent;
 }
 
-declare interface LabelCoordinate {
+export declare interface LabelCoordinate {
     x?: number;
     y?: number;
     z?: number;
@@ -7820,7 +7034,7 @@ declare interface LabelCoordinate {
     height?: number;
 }
 
-declare interface LabelCreateOptions {
+export declare interface LabelCreateOptions {
     id?: string;
     coordinate: LabelCoordinate;
     icon: string;
@@ -7838,7 +7052,7 @@ declare interface LabelIconSizeValue {
     height: number;
 }
 
-declare interface LabelInstance {
+export declare interface LabelInstance {
     id: string;
     coordinate: LabelCoordinate;
     icon: string;
@@ -7849,7 +7063,7 @@ declare interface LabelInstance {
     element: HTMLDivElement;
 }
 
-declare interface LabelUpdateOptions {
+export declare interface LabelUpdateOptions {
     coordinate?: LabelCoordinate;
     icon?: string;
     name?: string;
@@ -7952,6 +7166,9 @@ declare interface LayoutViewport2d {
     boundaryEntity?: any;
 }
 
+/** v2 对外暴露的三档渲染模式名称。 */
+declare type LegacyRenderMode = 'simple' | 'balance' | 'advanced';
+
 declare class Level {
     private engine;
     private isVisible;
@@ -8261,8 +7478,14 @@ declare class LightModule {
  */
 declare class LightModule_2 {
     private engine;
+    private ambientLight;
     private directionalLight;
     private lastBounds;
+    private readonly lightDirection;
+    private readonly boundsCenter;
+    private readonly boundsSize;
+    private readonly lastShadowTarget;
+    private lastShadowHalfSize;
     constructor(engine: any);
     /** 创建参考项目使用的环境光和主定向光。 */
     init(): void;
@@ -8270,15 +7493,54 @@ declare class LightModule_2 {
     updateShadowCameraRange(camera: THREE.Camera | null): void;
     /** 请求主定向光在下一次场景渲染时重建阴影贴图。 */
     requestShadowUpdate(): void;
-    /**
-     * 使用 WEBGPUTEMP 的 fitDirectionalLight 公式更新灯光位置和阴影视锥。
-     * 相机参数只为保持原公共接口，参考实现本身不依赖相机。
-     */
-    updateDirectionalShadow(_camera: THREE.Camera | null): void;
+    /** 捕获基础灯光状态，供 GIS 等临时场景在退出时无损恢复。 */
+    captureState(): LightModuleState | null;
+    /** 增量应用场景灯光，不重新创建光源或阴影贴图对象。 */
+    applyEnvironment(settings: LightModuleEnvironmentSettings): void;
+    /** 恢复先前捕获的基础灯光状态。 */
+    restoreState(state: LightModuleState | null): void;
+    /** 模型范围变化后刷新缓存，并按当前视区重新拟合定向光阴影视锥。 */
+    updateDirectionalShadow(camera: THREE.Camera | null): void;
+    /** 相机变化时仅使用缓存模型范围更新阴影，避免重复遍历大型场景。 */
+    updateDirectionalShadowView(camera: THREE.Camera | null, force?: boolean): void;
+    /** 估算相机目标深度处的可视半边长。 */
+    private getCameraHalfSize;
+    /** 优先跟随交互中心；漫游控制器没有 target 时改为覆盖相机前方。 */
+    private resolveShadowTarget;
+    /** 仅保留模型沿光照方向实际占用的深度段，提高阴影深度精度。 */
+    private getShadowDepthRange;
     /** 获取 v3 当前模型的整体包围盒。 */
     private getModelBounds;
 }
 
+declare interface LightModuleEnvironmentSettings {
+    ambientColor?: THREE.ColorRepresentation;
+    ambientIntensity?: number;
+    directionalColor?: THREE.ColorRepresentation;
+    directionalIntensity?: number;
+    direction?: THREE.Vector3;
+    castShadow?: boolean;
+    shadowMapSize?: number;
+    shadowBias?: number;
+    shadowNormalBias?: number;
+    shadowIntensity?: number;
+}
+
+declare interface LightModuleState {
+    ambientColor: number;
+    ambientIntensity: number;
+    directionalColor: number;
+    directionalIntensity: number;
+    direction: THREE.Vector3;
+    position: THREE.Vector3;
+    targetPosition: THREE.Vector3;
+    castShadow: boolean;
+    shadowMapSize: number;
+    shadowBias: number;
+    shadowNormalBias: number;
+    shadowIntensity: number;
+}
+
 /**
  * 超链接标注配置
  */
@@ -8340,6 +7602,12 @@ declare class LinkView2d3d_2 {
     private applyRotation;
 }
 
+declare interface Loaded3DTiles {
+    tiles: TilesRenderer;
+    Controls: typeof GlobeControls;
+    cameraFrame: number;
+}
+
 /** 已加载的 octree tile，渲染时每个 tile 会对应一个 THREE.Group。 */
 declare interface LoadedCadTile2d {
     id: string;
@@ -8667,6 +7935,51 @@ declare class LoaderModule_2 {
     private static createLocalModelId;
 }
 
+/** 负责 GIS 影像与 3D Tiles 数据的创建和插件配置。 */
+declare class LoaderModule_3 {
+    private readonly engine;
+    private readonly options;
+    private readonly isWebGpuRenderer;
+    private readonly layerManager?;
+    private readonly managedTilesets;
+    private lifecycle;
+    private disposed;
+    private readonly imageConfigs;
+    constructor(engine: EngineKernelV3, options?: GISOptions, isWebGpuRenderer?: boolean, layerManager?: GISLayerManager | undefined);
+    /** 注册附加 Tileset 生命周期回调，业务管理器通过此入口维护校准等状态。 */
+    setTilesetLifecycle(lifecycle: GISLoaderTilesetLifecycle | null): void;
+    /** 加载初始化配置指定的影像，未指定时默认使用 Cesium。 */
+    loadImage(): Promise<Loaded3DTiles>;
+    /** 按内置配置标识加载影像。 */
+    loadImageById(id: GISImageId): Promise<Loaded3DTiles>;
+    /** 按 URL 加载自定义 3D Tiles 影像。 */
+    loadImageCustomize(url: string): Promise<Loaded3DTiles>;
+    /** 当前地形由 3D Tiles 影像一并提供。 */
+    loadTerrain(): Promise<Loaded3DTiles>;
+    /** 在当前 GIS 底图上叠加通用 3D Tiles，并接入统一渲染生命周期。 */
+    loadTileset(url: string, options?: GISLoadTilesetOptions): Promise<TilesRenderer>;
+    /** 移除附加的 3D Tiles，并释放其缓存与 GPU 资源。 */
+    removeTileset(tiles: TilesRenderer): boolean;
+    /** 等待附加 Tileset 就绪，并把相机调整到可完整观察模型的位置。 */
+    flyToTileset(tiles: TilesRenderer, options?: GISFlyToTilesetOptions): Promise<void>;
+    /** 更新全部附加瓦片的 LOD 调度。 */
+    update(): void;
+    /** 同步全部附加瓦片使用的屏幕分辨率。 */
+    updateResolution(): void;
+    /** 释放 LoaderModule 管理的附加瓦片；主底图仍由 GIS 实例释放。 */
+    dispose(): void;
+    /** 创建 TilesRenderer，并注册官方示例使用的扩展插件。 */
+    load3dtiles(source?: GISSource): Promise<Loaded3DTiles>;
+    private resolveLocalOrigin;
+    /** 将高德瓦片的 GCJ-02 投影适配到引擎统一使用的 WGS84 地表。 */
+    private correctGcj02Overlay;
+    private registerHeightOffset;
+    /** 根瓦片加载完成后再冻结校准基准，避免使用尚未建立的包围球锚点。 */
+    private registerTilesetReady;
+    private waitForBoundingSphere;
+    private assertUsable;
+}
+
 /**
  * Gaussian 加载模块。
  * 负责加载、卸载和登记 .ply / .splat / .ksplat / .spz 场景。
@@ -10064,7 +9377,6 @@ declare class ModelEdge_2 {
     private explodeHidden;
     private groupVisibleBeforeExplode;
     private highlightVisibleBeforeExplode;
-    private lastReportedOpacity;
     private getModelEntry;
     /** 判断模型是否允许加载边线；旧模型记录未包含该字段时按允许处理。 */
     private shouldLoadModelEdge;
@@ -11104,6 +10416,34 @@ declare interface ModelPoseOptions_2 {
     forwardAxis?: THREE.Vector3Tuple;
 }
 
+/** 将 v3 普通 BIM 模型根分组定位到地球表面的指定经纬度与朝向。 */
+export declare class ModelPositionManager {
+    private readonly engine;
+    private tiles;
+    private readonly layerManager?;
+    private readonly calibrationManager?;
+    private readonly records;
+    private readonly inverseParentMatrix;
+    constructor(engine: EngineKernelV3, tiles: TilesRenderer, layerManager?: GISLayerManager | undefined, calibrationManager?: GISModelCalibrationManager | undefined);
+    /** 切换底图后更新地理参考，已有 BIM 模型的世界定位保持不变。 */
+    setTiles(tiles: TilesRenderer): void;
+    /** 定位已加载模型；模型本地 +Y 为上方，heading 从正北向东顺时针增加。 */
+    setPosition(url: string, position: GISModelPosition): ResolvedGISModelPosition;
+    /** 模型未加载时先通过 v3 Loader 加载，再应用地理定位。 */
+    loadAndPosition(url: string, position: GISModelPosition, loadOptions?: LoadModelOptions): Promise<ResolvedGISModelPosition>;
+    /** 获取指定模型最近一次由本管理器应用的定位信息。 */
+    getPosition(url: string): ResolvedGISModelPosition | null;
+    /** 恢复模型定位前的根分组矩阵。 */
+    resetPosition(url: string): boolean;
+    /** 释放内部记录；模型资源由引擎统一管理。 */
+    dispose(): void;
+    private requireModelGroup;
+    private resolvePosition;
+    private assertUrl;
+    private normalizeAngle;
+    private getLayerId;
+}
+
 declare class ModelProperties {
     private engine;
     extended‌: Map<string, any>;
@@ -11652,6 +10992,10 @@ declare class OneClickEncoding_2 {
     chat(str: string): Promise<any>;
 }
 
+declare type OrbitCenterResolver = ThirdPersonPlacementResolver;
+
+declare type OrbitCenterResolver_2 = ThirdPersonPlacementResolver_2;
+
 declare class Pan2dControls extends THREE.EventDispatcher {
     object: THREE.OrthographicCamera;
     domElement: HTMLElement;
@@ -12767,6 +12111,11 @@ declare class RangeScale_2 {
     dispose(): void;
 }
 
+export declare interface RegisterBimCalibrationOptions {
+    id?: string;
+    name?: string;
+}
+
 /** 渲染中间态，block 展开后先统一转成这种结构，再按图层和颜色合批。 */
 declare interface RenderItem2d {
     kind: RenderKind2d;
@@ -12793,7 +12142,7 @@ declare type RenderKind2d = 'line' | 'text' | 'hatch' | 'image';
 
 declare type RenderMode = 'simple' | 'balance' | 'advanced';
 
-declare type RenderMode_2 = RenderQualityLevel;
+declare type RenderMode_2 = RenderQualityInput;
 
 declare class RenderModule {
     private engine;
@@ -13039,6 +12388,9 @@ declare class RenderModuleGaussian {
 
 declare type RenderQualityEffectState = Record<QualityEffect, boolean>;
 
+/** v3 原生数字等级与 v2 三档模式共用的输入类型。 */
+declare type RenderQualityInput = RenderQualityLevel | LegacyRenderMode;
+
 export declare type RenderQualityLevel = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12;
 
 declare type RenderQualityParameters = {
@@ -13070,8 +12422,7 @@ export declare interface ResolvedAutoExposureOptions {
     highPercentile: number;
 }
 
-/** 将椭球高、贴地和相对地形高度统一解析为 WGS84 椭球高。 */
-export declare function resolveHeightReference(position: GisPosition, heightReference: GisHeightReference, sampleTerrainHeight: GisTerrainHeightSampler, options?: GisHeightResolutionOptions): Promise<GisHeightResolution>;
+export declare type ResolvedGISModelPosition = Required<GISModelPosition>;
 
 /**
  * 解析 SDK 内置 public 资源 URL。绝对 URL 和 data/blob URL 原样返回。
@@ -13334,9 +12685,6 @@ declare class SceneModuleGaussian {
     dispose(): void;
 }
 
-/** 将 V3 场景坐标还原为 ENU。 */
-export declare function sceneToEnu(position: GisScenePosition): GisEnuPosition;
-
 export declare interface SdkAuthOptions {
     endpoint: string;
     token?: string;
@@ -13881,7 +13229,7 @@ declare class Setting_2 {
     setSettings(data: Partial<EngineSettings_2>): Promise<void>;
     /** 閲嶇疆鎵€鏈夎缃负榛樿鍊?*/
     resetToDefault(): Promise<void>;
-    /** 设置 1 至 12 的手动渲染等级。 */
+    /** 设置 1 至 12 的手动等级，或使用 v2 的 simple、balance、advanced 三档模式。 */
     setRenderMode(mode: RenderMode_2): void;
     /** 璁剧疆瀵规瘮搴︼紙0~100锛?*/
     setContrast(value: number): void;
@@ -14209,146 +13557,21 @@ declare class ThemeManager {
     dispose(): void;
 }
 
-declare interface TilesetDefaults {
-    maximumScreenSpaceError: number;
-    maximumCachedTiles: number;
-    requestConcurrency: number;
-}
-
-declare type TilesetLifecycleUpdate = {
-    kind: 'phase';
-    phase: GisTilesetPhase;
-} | {
-    kind: 'progress';
-    progress: GisTileProgressEvent;
-};
-
-/** 3D Tiles 公共控制器，管理多实例配置、状态、范围、飞行和运行期操作。 */
-declare class TilesetManager {
-    private readonly options;
-    private readonly records;
-    private readonly reportedRuntimeErrors;
-    private defaults;
-    private disposed;
-    constructor(options: TilesetManagerOptions);
-    /** 仅保存已校验配置，不创建渲染器或发起网络请求。 */
-    configure(configs: readonly GisTilesetConfig[], defaults?: Partial<TilesetDefaults>): void;
-    /** 初始化阶段通过统一 Provider 解析 URL 与 ion 数据源。 */
-    resolveConfiguredLayers(): Promise<readonly GisRuntimeTilesetLayer[]>;
-    /** 运行期添加独立 tileset；返回时渲染器已注册，元数据仍可能处于加载中。 */
-    add(config: GisTilesetConfig): Promise<GisTilesetLayerHandle>;
-    /** 热更新显隐、LOD、请求并发和地理校准参数。 */
-    update(id: string, patch: GisTilesetLayerUpdate): Promise<GisTilesetLayerHandle>;
-    /** 返回根元数据就绪后的场景/WGS84 包围球。 */
-    getBounds(id: string): GisTilesetBounds | null;
-    /** 飞行到 tileset 包围球；元数据未就绪时返回明确状态错误。 */
-    flyTo(id: string, options?: GisTilesetFlyToOptions): Promise<void>;
-    /** 返回当前运行时明确验证过的格式与压缩扩展兼容矩阵。 */
-    getFormatCapabilities(): readonly GisTilesetFormatCapability[];
-    /** 接收渲染层生命周期更新，并映射为稳定公开状态与事件。 */
-    reportLifecycle(id: string, update: TilesetLifecycleUpdate): void;
-    /** 移除单个 tileset，并同步清理版权、凭据和错误快照。 */
-    remove(id: string): Promise<boolean>;
-    get(id: string): GisTilesetLayerHandle | null;
-    list(): readonly GisTilesetLayerHandle[];
-    clear(): Promise<void>;
-    /** 将运行期加载错误归一化并按图层去重。 */
-    reportRuntimeError(id: string, error: unknown): GisError;
-    reset(): void;
-    dispose(): void;
-    private createRecord;
-    private beginLoading;
-    private createRuntimeLayer;
-    private createSource;
-    private syncAttribution;
-    private snapshot;
-    private createProgress;
-    private failRecord;
-    private validateRuntimeSettings;
-    private releaseCredential;
-    private requireRecord;
-    private requireRuntime;
-    private normalizeLayerError;
-    private layerError;
-    private assertUsable;
+declare interface ThirdPersonPlacementHit {
+    point: THREE.Vector3;
+    normal?: THREE.Vector3;
+    distance?: number;
 }
 
-declare interface TilesetManagerOptions {
-    providers: GisProviderRegistry;
-    getProviderContext: () => GisProviderContext | null;
-    getRuntime: () => TilesetRenderer | null;
-    sceneToGeographic: (position: {
-        x: number;
-        y: number;
-        z: number;
-    }) => {
-        longitude: number;
-        latitude: number;
-        height: number;
-    };
-    flyToBounds: (bounds: GisTilesetBounds, options?: GisTilesetFlyToOptions) => Promise<void>;
-    setAttribution: (entry: GisAttributionEntry) => void;
-    setAttributionVisible: (id: string, visible: boolean) => void;
-    removeAttribution: (id: string) => void;
-    emit: <K extends GisEventType>(type: K, value: GisEventMap[K]) => void;
+declare interface ThirdPersonPlacementHit_2 {
+    point: THREE.Vector3;
+    normal?: THREE.Vector3;
+    distance?: number;
 }
 
-/** 管理多个 3D Tiles 渲染实例，仅负责场景资源、LOD 和 GPU 生命周期。 */
-declare class TilesetRenderer {
-    private readonly context;
-    private readonly origin;
-    private readonly options;
-    private readonly onLayerError;
-    private readonly onLifecycleUpdate;
-    private readonly onPrimaryChange?;
-    private readonly records;
-    private readonly transformComposer;
-    private readonly transformMatrix;
-    private readonly boundsSphere;
-    private currentCamera;
-    private disposed;
-    constructor(context: GisModuleContext, origin: Required<GisPosition>, options: TilesetRendererOptions, onLayerError: (id: string, error: Error) => void, onLifecycleUpdate: (id: string, update: TilesetLifecycleUpdate) => void, onPrimaryChange?: ((tiles: TilesRenderer | null) => void) | undefined);
-    /** 返回首个已注册 tileset，供兼容相机和表面查询逻辑使用。 */
-    get primary(): TilesRenderer | null;
-    /** 按配置顺序创建全部实例；单实例失败由上层 Manager 隔离。 */
-    initialize(layers: readonly GisRuntimeTilesetLayer[]): Promise<void>;
-    /** 创建独立 TilesRenderer、放置根节点、解码器、缓存和生命周期跟踪器。 */
-    add(layer: GisRuntimeTilesetLayer): Promise<void>;
-    /** 热更新不会重建数据源或丢弃已加载 GPU 资源。 */
-    updateLayer(id: string, patch: Partial<Pick<GisRuntimeTilesetLayer, 'visible' | 'maximumScreenSpaceError' | 'maximumCachedTiles' | 'requestConcurrency' | 'transform'>>): void;
-    /** 返回已加载根 tileset 的世界空间包围球；元数据未就绪时返回 null。 */
-    getBounds(id: string): GisSceneBounds | null;
-    /** 卸载单个实例并立即取消请求、解除监听、释放解码器及 GPU 资源。 */
-    remove(id: string): boolean;
-    /** 仅调度可见实例，隐藏图层不产生持续遍历开销。 */
-    update(): void;
-    /** 相机对象发生替换时，从全部实例解绑旧相机并绑定新相机。 */
-    setCamera(): void;
-    /** 同步所有实例的物理像素分辨率，保证 SSE 在高 DPI 下正确。 */
-    updateResolution(): void;
-    /** 浮动原点切换时在同一事务内迁移全部业务放置根节点。 */
-    applyWorldTransform(transform: Readonly<Matrix4>): void;
-    /** 返回内部实例仅供 GIS 运行时兼容入口使用。 */
-    getRenderer(id: string): TilesRenderer | null;
-    /** 释放所有实例，销毁后禁止再次添加。 */
-    dispose(): void;
-    private registerIonPlugin;
-    private registerReorientationPlugin;
-    private applyPlacement;
-    private requireRecord;
-    private assertUsable;
-}
+declare type ThirdPersonPlacementResolver = (raycaster: THREE.Raycaster) => ThirdPersonPlacementHit | null;
 
-declare interface TilesetRendererOptions {
-    dracoDecoderPath?: string;
-    loadSiblings: boolean;
-    creasedNormals: boolean;
-    creaseAngle: number;
-    fade: boolean;
-    resolveCredential?: (sourceId: string, forceRefresh?: boolean) => Promise<string>;
-    markCredentialExpired?: (sourceId: string) => void;
-    geographicToScene: (position: GisPosition, target: Vector3) => Vector3;
-}
+declare type ThirdPersonPlacementResolver_2 = (raycaster: THREE.Raycaster) => ThirdPersonPlacementHit_2 | null;
 
 /** TRAA 参数。 */
 export declare interface TRAAPostProcessingSettings {
@@ -14385,6 +13608,7 @@ declare interface ViewBounds {
 
 declare class ViewCube {
     private engine;
+    private homeBoundingBoxProvider;
     cubeTool: any;
     mainViewPort: any;
     constructor(engine: any);
@@ -14393,6 +13617,8 @@ declare class ViewCube {
     show(): void;
     CameraGoHome(time: number): void;
     cameraGoHome(time: number): void;
+    setHomeBoundingBoxProvider(provider: (() => THREE.Box3 | null) | null): void;
+    getHomeBoundingBox(): THREE.Box3 | null | undefined;
     zoomToModel(box: any, time?: number): void;
     zoomToModels(m: any): void;
     flyToModels(ms?: any[]): void;
@@ -14420,6 +13646,7 @@ declare class ViewCube2d {
 
 declare class ViewCube_2 {
     private engine;
+    private homeBoundingBoxProvider;
     cubeTool: any;
     mainViewPort: any;
     constructor(engine: any);
@@ -14428,6 +13655,8 @@ declare class ViewCube_2 {
     show(): void;
     CameraGoHome(time: number): void;
     cameraGoHome(time: number): void;
+    setHomeBoundingBoxProvider(provider: (() => THREE.Box3 | null) | null): void;
+    getHomeBoundingBox(): THREE.Box3 | null | undefined;
     zoomToModel(box: any, time?: number): void;
     zoomToModels(m: any): void;
     flyToModels(ms?: any[]): void;
@@ -14641,18 +13870,6 @@ declare class WebGPUSectionFace extends SectionFace {
     dispose(): void;
 }
 
-/** 将 Web Mercator 米制坐标转换为 WGS84。 */
-export declare function webMercatorToWgs84(position: GisWebMercatorPosition): Required<GisPosition>;
-
-/** 将 WGS84 经纬高转换为 ECEF 地心地固坐标。 */
-export declare function wgs84ToEcef(position: GisPosition): GisEcefPosition;
-
-/** WGS84 到局部 ENU 的组合转换。 */
-export declare function wgs84ToEnu(position: GisPosition, origin: GisPosition): GisEnuPosition;
-
-/** 将 WGS84 投影为标准 Web Mercator；极区纬度钳制到 EPSG:3857 有效范围。 */
-export declare function wgs84ToWebMercator(position: GisPosition): GisWebMercatorPosition;
-
 /**
  * 世界坐标与屏幕坐标转换工具类
  * 提供世界坐标（3D空间坐标）与屏幕坐标（2D像素坐标）之间的双向转换功能