zf-twin-3d 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,1346 @@
+import * as three from 'three';
+import { PerspectiveCamera, Object3D, Group, Mesh, Sprite, WebGLRenderer, Scene } from 'three';
+export * from 'three';
+import { OrbitControls } from 'three/examples/jsm/controls/OrbitControls.js';
+
+/**
+ * 场景视角控制
+ */
+declare class Camera {
+    /** 透视相机实例 */
+    readonly pcInstance: PerspectiveCamera;
+    /** 轨道控制器 */
+    orbitControls?: OrbitControls;
+    /** 相机补间分组 */
+    private readonly cameraTweenGroup;
+    /** 补间开始前记录的轨道阻尼开关，用于结束后恢复 */
+    private cameraTweenDampingRestore;
+    constructor(width: number, height: number);
+    init(domElement: HTMLElement): void;
+    /**
+     * 推进相机 Tween，须在渲染循环中调用（早于 OrbitControls.update）
+     * @param time 毫秒时间戳，默认 performance.now()
+     */
+    updateCameraTweens(time?: number): void;
+    /**
+     * 设置视角
+     * @param options 视角参数
+     * @example
+     * ```
+     * this.setCamera({ target: [0, 0, 0], position: [0, 5, 50] });
+     * this.setCamera({ target: [0, 0, 0], yaw: 0, pitch: 90, distance: 50 });
+     * ```
+     */
+    setCamera(options: {
+        /** 观察目标 */
+        target: Position;
+        /** 相机位置 */
+        position: Position;
+        /**
+         * 过渡时长（秒）
+         * @default 2
+         */
+        duration?: number;
+    } | {
+        /** 观察目标 */
+        target: Position;
+        /** 方位角 */
+        yaw: number;
+        /** 俯仰角 */
+        pitch: number;
+        /** 距离 */
+        distance: number;
+        /**
+         * 过渡时长（秒）
+         * @default 2
+         */
+        duration?: number;
+    }): Promise<void>;
+    /**
+     * 聚焦自定义对象
+     * @param object 目标对象
+     * @param options 聚焦参数
+     * @returns 过渡结束后完成
+     */
+    focusObject(object: BaseObject, options?: {
+        /**
+         * 方位角
+         * @default 0
+         */
+        yaw?: number;
+        /**
+         * 俯仰角
+         * @default 35
+         */
+        pitch?: number;
+        /** 距离 */
+        distance?: number;
+        /**
+         * 过渡时长（秒）
+         * @default 2
+         */
+        duration?: number;
+    }): Promise<void>;
+    /**
+     * 获取当前视角参数
+     * @returns 相机位置、观察目标、方位角、俯仰角、与target的距离
+     */
+    getCamera(): {
+        position: Position;
+        target: Position;
+        yaw: number;
+        pitch: number;
+        distance: number;
+    };
+    /**
+     * 沿路径移动相机
+     * @param path 路径
+     * @param duration 走完全程所用秒数
+     */
+    moveCameraAlongPath(path: Position[], duration: number): Promise<void>;
+    /**
+     * 中断 {@link moveCameraAlongPath} 进行中的路径移动
+     */
+    stopCameraPathMovement(): void;
+    /**
+     * 在渲染器画布上创建官方 OrbitControls（旋转、平移、缩放）
+     * @param domElement WebGLRenderer.domElement
+     */
+    private attachOrbitControls;
+    /**
+     * 动画结束后恢复 OrbitControls.enableDamping
+     */
+    private finishCameraTweenDamping;
+    /**
+     * 停止并清空相机动画分组。
+     */
+    private clearCameraPoseTweens;
+    /**
+     * 使用 Tween.js 在指定秒内插值相机位置与观察目标
+     */
+    private runCameraPoseTween;
+    /**
+     * 根据包围盒估算聚焦距离
+     * @param bounds 对象包围盒
+     */
+    private resolveFocusDistanceByBounds;
+}
+
+/** 物体类型 */
+declare enum ObjectType {
+    /** 园区 */
+    CAMPUS = "campus",
+    /** 建筑 */
+    BUILDING = "building",
+    /** 楼层 */
+    FLOOR = "floor",
+    /** 标记 */
+    MARKER = "marker",
+    /** UI 锚点 */
+    UI_ANCHOR = "ui-anchor",
+    /** 普通物体 */
+    ELEMENT = "element",
+    /** 独立模型对象 */
+    THING = "thing",
+    /** 折线 */
+    POLYLINE = "polyline"
+}
+/** 节点名前缀 */
+declare enum ObjectNamePrefix {
+    /** 建筑节点名前缀 */
+    BUILDING = "building_",
+    /** 楼层节点名前缀 */
+    FLOOR = "floor_"
+}
+
+/** 楼层类 */
+declare class Floor extends BaseObject {
+    /** 所属建筑 */
+    readonly building: Building;
+    get parent(): Building;
+    constructor(option: FloorOption, app: App);
+    /** 绑定楼层节点与 Floor 实例的映射 */
+    private bindFloorCustomObject;
+    protected disposeOwnedResources(): void;
+    /**
+     * 建筑整体销毁时 glTF 根已统一 dispose，仅同步本对象状态，避免后续 destroy 重复释放 GPU
+     */
+    releaseAfterBuildingDisposed(): void;
+}
+
+type Nullable<T> = T | null;
+
+declare function isCampus(obj: SceneLevelObject): obj is Campus;
+declare function isBuilding(obj: SceneLevelObject): obj is Building;
+declare function isFloor(obj: SceneLevelObject): obj is Floor;
+/** 是否为 Campus glTF 解析出的子对象 */
+declare function isCampusDerivedObject(type: ObjectType): type is ObjectType.BUILDING | ObjectType.FLOOR | ObjectType.ELEMENT;
+
+/**
+ * 场景层级
+ */
+declare class SceneLevel {
+    private readonly app;
+    /** 当前层级对象 */
+    private level;
+    /** 层级回退记录栈 */
+    private levelHistoryStack;
+    constructor(app: App);
+    /** 获取当前层级对象 */
+    get current(): Nullable<SceneLevelObject>;
+    /**
+     * 按目标类型切换层级
+     * @param target 目标层级对象
+     */
+    changeLevel(target: SceneLevelObject): void;
+    /**
+     * 设置默认层级对象
+     * @param target 层级对象
+     */
+    applyDefault(target: SceneLevelObject): void;
+    /**
+     * 返回上一级视图
+     */
+    goToParentLevel(): void;
+    /**
+     * 判断 child 是否为 parent 在园区-建筑-楼层树上的直接子级（仅 Campus→Building、Building→Floor）
+     * @param parent 父级场景对象
+     * @param child 子级场景对象
+     */
+    private isImmediateChildLevel;
+    /**
+     * 按目标对象重建显示状态，确保任意层级切换后显示一致
+     * @param target 目标层级对象
+     */
+    private syncVisibilityByTarget;
+    /**
+     * 园区视图：显示园区全部建筑、楼层及附属物
+     * @param campus 园区对象
+     */
+    private showCampus;
+    /**
+     * 建筑视图：仅保留目标建筑内部楼层可见，隐藏其他建筑及附属物
+     * @param building 建筑对象
+     */
+    private showBuilding;
+    /**
+     * 楼层视图：先切换为建筑视图，再仅显示目标楼层
+     * @param floor 楼层对象
+     */
+    private showFloor;
+    /**
+     * 记录当前层级对象与视角，用于回退时恢复
+     */
+    private pushCurrentLevelHistory;
+    /**
+     * 当回退后层级对象与记录一致时恢复视角
+     */
+    private restoreCameraIfHistoryMatch;
+}
+
+/** 场景事件类型 */
+declare enum SceneEventType {
+    /** 场景点击事件 */
+    CLICK = "click",
+    /** 双击模型事件 */
+    DOUBLE_CLICK = "double-click",
+    /** 模型移入事件 */
+    MOUSE_ENTER = "mouse-enter",
+    /** 模型移出事件 */
+    MOUSE_LEAVE = "mouse-leave",
+    /** 右键双击 */
+    RIGHT_DOUBLE_CLICK = "right-double-click",
+    /** 场景层级变化 */
+    LEVEL_CHANGE = "level-change",
+    /** 每帧更新（渲染前） */
+    FRAME_UPDATE = "frame-update"
+}
+/** 内置事件键值 */
+declare enum BuiltInEventKey {
+    /** 建筑悬浮高亮 */
+    BUILDING_HOVER_HIGHLIGHT = "building-hover-highlight",
+    /** 场景层级切换 */
+    SCENE_LEVEL_SWITCH = "scene-level-switch"
+}
+/** 事件类型与回调的映射 */
+type SceneEventMap = {
+    [SceneEventType.CLICK]: {
+        /** 位置 */
+        position: Position;
+        /** 屏幕坐标（相对 canvas） */
+        screen: {
+            x: number;
+            y: number;
+        };
+        /** 模型对象 */
+        object?: Object3D;
+        /** 自定义对象实例 */
+        customObject?: BaseObject;
+    };
+    [SceneEventType.DOUBLE_CLICK]: {
+        /** 位置 */
+        position: Position;
+        /** 屏幕坐标（相对 canvas） */
+        screen: {
+            x: number;
+            y: number;
+        };
+        /** 模型对象 */
+        object?: Object3D;
+        /** 自定义对象实例 */
+        customObject?: BaseObject;
+    };
+    [SceneEventType.MOUSE_ENTER]: {
+        /** 模型对象 */
+        object?: Object3D;
+        /** 自定义对象实例 */
+        customObject?: BaseObject;
+    };
+    [SceneEventType.MOUSE_LEAVE]: {
+        /** 模型对象 */
+        object?: Object3D;
+        /** 自定义对象实例 */
+        customObject?: BaseObject;
+    };
+    [SceneEventType.RIGHT_DOUBLE_CLICK]: MouseEvent;
+    [SceneEventType.LEVEL_CHANGE]: {
+        /** 变化前的层级对象 */
+        previous: Nullable<SceneLevelObject>;
+        /** 变化后的当前层级对象 */
+        current: SceneLevelObject;
+    };
+    [SceneEventType.FRAME_UPDATE]: void;
+};
+
+/** 场景事件 */
+declare class SceneEvent {
+    private app;
+    /** 事件回调集合 */
+    private readonly listeners;
+    /** 是否已初始化 */
+    private isInit;
+    /** 内置事件管理器 */
+    private readonly builtInEventManager;
+    /** 当前悬浮的模型对象 */
+    private hoveredObject?;
+    /** 最近一次鼠标移动事件 */
+    private latestMouseMoveEvent?;
+    /** 是否存在待处理的悬浮检测 */
+    private hoverDirty;
+    /** 用于识别「同一物体」双击事件 */
+    private doubleClickPending;
+    /** 延迟派发单击的定时器 */
+    private deferredClickTimer?;
+    /** 最近一次左键在画布上 mousedown 时的屏幕坐标，用于区分点击与拖拽 */
+    private primaryButtonDownPosition;
+    /** 右键双击：仅按时间间隔配对，记录上一次右键 mousedown 时刻 */
+    private rightDoubleClickPending;
+    constructor(app: App);
+    /** 初始化场景事件 */
+    init(): void;
+    /**
+     * 订阅事件
+     * @param event 事件类型
+     * @param handler 回调
+     */
+    on<T extends SceneEventType>(event: T, handler: (payload: SceneEventMap[T]) => any): void;
+    /**
+     * 取消订阅
+     * @param event 事件类型
+     * @param handler 与订阅时相同的回调引用
+     */
+    off(event: SceneEventType, handler: (...args: any[]) => any): void;
+    /**
+     * 订阅一次事件
+     * @param event 事件类型
+     * @param handler 回调
+     */
+    once<T extends SceneEventType>(event: T, handler: (payload: SceneEventMap[T]) => any): void;
+    /** 每帧更新：执行内置逻辑并派发给订阅者 */
+    tickFrame(): void;
+    /** 每帧处理一次鼠标悬浮检测 */
+    private processHover;
+    /**
+     * 暂停指定内置事件
+     * @param eventKey 内置事件键值
+     */
+    pauseBuiltInEvent(eventKey: BuiltInEventKey): void;
+    /**
+     * 恢复指定内置事件
+     * @param eventKey 内置事件键值
+     */
+    resumeBuiltInEvent(eventKey: BuiltInEventKey): void;
+    /** 触发事件 */
+    emit<T extends SceneEventType>(event: T, payload: SceneEventMap[T]): void;
+    /**
+     * 处理画布点击
+     */
+    private handleCanvasClick;
+    /** 清除延迟派发单击的定时器 */
+    private clearDeferredClickTimer;
+    /**
+     * 在双击判定窗口结束时：要么派发延迟的单击，要么仅清除待配对状态（仅订阅双击时）
+     */
+    private scheduleDeferredClickResolution;
+    /**
+     * 处理画布 mousedown：左键记录起点以过滤拖拽后的误触 click；右键处理双击事件
+     */
+    private handleCanvasMouseDown;
+    /**
+     * 处理画布鼠标移动
+     */
+    private handleCanvasMouseMove;
+    /**
+     * 是否存在对应事件监听器
+     * @param event 事件类型
+     */
+    private hasListeners;
+}
+
+/**
+ * 默认场景灯光
+ */
+declare class SceneLights {
+    private app;
+    constructor(app: App);
+    /**
+     * 初始化场景灯光
+     */
+    private init;
+}
+
+/** 独立模型对象 */
+declare class Thing extends BaseObject<Group> {
+    /** 是否已订阅帧更新 */
+    private isFrameUpdateSubscribed;
+    /** 路径移动 Tween 分组 */
+    private pathTweenGroup;
+    /** 进行中的路径移动 Tween */
+    private pathTween;
+    /** 是否存在正在运行且未暂停的模型动画 */
+    isAnimationPlaying: boolean;
+    /** 动画片段 */
+    private animationClips;
+    /** 模型动画混合器 */
+    private animationMixer;
+    /** 按名称缓存的动画动作 */
+    private animationActions;
+    /** 模型动画帧间隔计时 */
+    private animationTimer;
+    constructor(option: ThingOption, app: App);
+    /**
+     * 模型内嵌动画名称列表
+     */
+    get animationNames(): readonly string[];
+    /**
+     * 播放指定模型动画
+     * @param name 动画名称，见 {@link animationNames}
+     * @param loop 是否循环播放，默认 true
+     */
+    playAnimation(name: string, loop?: boolean): void;
+    /**
+     * 暂停指定模型动画
+     * @param name 动画名称
+     */
+    pauseAnimation(name: string): void;
+    /**
+     * 继续播放已暂停的模型动画
+     * @param name 动画名称
+     */
+    resumeAnimation(name: string): void;
+    /**
+     * 停止指定模型动画并重置到起始帧
+     * @param name 动画名称
+     */
+    stopAnimation(name: string): void;
+    /** 设置世界位置；模型底部对齐 Y 轴 */
+    setPosition(position: Position): void;
+    /** 设置相对父对象的位置；模型底部对齐父级局部 Y */
+    setLocalPosition(localPosition: Position): void;
+    /**
+     * 沿路径移动模型
+     * @param path 路径
+     * @param duration 走完全程所用秒数
+     * @param loop 是否循环执行，默认 false；为 true 时 Promise 仅在 {@link stopPathMovement} 后 resolve
+     */
+    moveAlongPath(path: Position[], duration: number, loop?: boolean): Promise<void>;
+    /** 中断 {@link moveAlongPath} 进行中的路径移动 */
+    stopPathMovement(): void;
+    protected disposeOwnedResources(): void;
+    protected afterDisposeResources(): void;
+    /**
+     * 按路径切线设置朝向（仅 Y 轴，避免 lookAt 与 GLTF 模型轴向冲突）
+     * @param position 当前位置
+     * @param lookTarget 朝向前瞻点
+     */
+    private setPathYaw;
+    /**
+     * 加载 GLTF 模型并挂载到场景
+     * @param url 模型资源地址
+     * @param onReady 加载完成回调
+     */
+    private loadModel;
+    /**
+     * 按名称获取或创建动画动作
+     * @param name 动画名称
+     */
+    private getAnimationAction;
+    /** 根据各 AnimationAction 运行状态同步 {@link isAnimationPlaying} */
+    private syncAnimationPlaying;
+    /** 单次非循环动画结束时的混合器回调 */
+    private handleAnimationFinished;
+    /** 按需初始化路径动画资源并订阅帧更新 */
+    private ensurePathAnimation;
+    /** 按需初始化动画资源并订阅帧更新 */
+    private ensureAnimation;
+    /** 按需订阅帧更新 */
+    private ensureFrameUpdate;
+    /** 帧更新回调：推进路径 Tween 与 AnimationMixer */
+    private handleFrameUpdate;
+}
+
+/** 折线 */
+declare class Polyline extends BaseObject<Mesh> {
+    /** 路径数据 */
+    private points;
+    /** 线宽（单位米） */
+    private width;
+    /** 拐角圆角半径（单位米） */
+    private cornerRadius;
+    /** 拐角圆角细分段数 */
+    private cornerSegments;
+    /** 线条颜色 */
+    private color;
+    /** 线条材质 */
+    private meshMaterial;
+    /** 贴图路径 */
+    private imagePath;
+    /** 贴图沿路径滚动速度（米/秒） */
+    private textureScrollSpeed;
+    /** 贴图沿路径方向一个完整图案占用的世界长度（米） */
+    private textureWorldSize;
+    /** 贴图沿路径方向相邻图案之间的空隙长度（米） */
+    private textureGap;
+    /** 是否启用贴图滚动 */
+    private enableTextureScroll;
+    /** 贴图实例 */
+    private texture;
+    /** 贴图滚动累积偏移（米） */
+    private textureScrollOffset;
+    /** 传给材质的图案占周期比例 uniform（图案长度 / 周期长度） */
+    private readonly textureImageFractionUniform;
+    /** 是否已订阅帧更新 */
+    private isFrameUpdateSubscribed;
+    /** 帧间隔计时 */
+    private frameTimer;
+    constructor(option: PolylineOption, app: App);
+    /**
+     * 设置路径数据
+     * @param points 世界坐标路径点
+     */
+    setPoints(points: Position[]): void;
+    /**
+     * 设置线宽
+     * @param width 线宽（单位米）
+     */
+    setWidth(width: number): void;
+    /**
+     * 设置拐角圆角半径
+     * @param cornerRadius 圆角半径（单位米）；0 表示直角
+     */
+    setCornerRadius(cornerRadius: number): void;
+    /**
+     * 设置拐角圆角细分段数
+     * @param cornerSegments 数值越大圆角越平滑
+     */
+    setCornerSegments(cornerSegments: number): void;
+    /**
+     * 设置线条颜色
+     * @param color 支持 #rgb/#rrggbb、rgb()、rgba() 及 CSS 命名色
+     */
+    setColor(color: string): void;
+    /**
+     * 设置贴图路径
+     * @param imagePath 图片地址
+     */
+    setImagePath(imagePath: string): void;
+    /**
+     * 设置贴图沿路径滚动速度
+     * @param speed 速度（米/秒）；正数沿路径正向
+     */
+    setTextureScrollSpeed(speed: number): void;
+    /**
+     * 设置贴图沿路径方向一个完整图案占用的世界长度
+     * @param textureWorldSize 世界长度（米）；值越大图案越稀疏
+     */
+    setTextureWorldSize(textureWorldSize: number): void;
+    /**
+     * 设置贴图沿路径方向相邻图案之间的空隙长度
+     * @param textureGap 空隙长度（米）；值越大图案间距越大，空隙区域透明
+     */
+    setTextureGap(textureGap: number): void;
+    /**
+     * 设置是否启用贴图滚动
+     * @param enable 是否滚动
+     */
+    setEnableTextureScroll(enable: boolean): void;
+    protected disposeOwnedResources(): void;
+    protected afterDisposeResources(): void;
+    /** 创建折线并挂载到场景 */
+    private buildLine;
+    /** 按当前路径重建几何体 */
+    private rebuildGeometry;
+    /** 根据当前状态构建网格几何体 */
+    private createMeshGeometry;
+    /** 加载贴图并应用到材质 */
+    private loadTexture;
+    /** 将贴图应用到当前材质 */
+    private applyTexturedMaterial;
+    /** 根据累积偏移更新贴图 UV 偏移 */
+    private applyTextureOffset;
+    /** 设置贴图包裹模式 */
+    private applyTextureWrap;
+    /** 按需订阅或取消帧更新 */
+    private syncFrameSubscription;
+    /** 订阅全局帧更新 */
+    private ensureFrameUpdate;
+    /** 取消帧更新订阅 */
+    private unsubscribeFrameUpdate;
+    /** 帧更新：推进贴图滚动 */
+    private handleFrameUpdate;
+    /** 是否应生成贴图 UV */
+    private shouldUseTextureUv;
+    /** 同步「图案占周期比例」到材质 uniform */
+    private updateTextureImageFraction;
+    /** 贴图布局参数变更后重建几何并同步偏移 */
+    private refreshTextureLayout;
+    private disposeMaterial;
+}
+
+/** 标记 */
+declare class Marker extends BaseObject<Sprite | Mesh> {
+    /** 图片宽高比 */
+    private textureAspect;
+    /** 图片路径 */
+    private readonly imagePath;
+    /** 是否以 3D 模型展示 */
+    private readonly is3D;
+    /** 是否保持近大远小 */
+    private readonly enablePerspectiveScale;
+    /** 标记尺寸：[宽度, 高度] */
+    private readonly size;
+    constructor(option: MarkerOption, app: App);
+    setScale(scale: Scale): void;
+    setRotation(rotation: Rotation): void;
+    setPosition(position: Position): void;
+    /** 加载贴图并创建标记 */
+    private loadTexture;
+    protected disposeOwnedResources(): void;
+    /**
+     * 根据像素尺寸计算当前帧世界尺度
+     * @param sprite 标记精灵
+     * @param camera 当前相机
+     */
+    private applyPixelScale;
+    /**
+     * 创建 2D 标记
+     * @param texture 贴图资源
+     */
+    private createSpriteMarker;
+    /**
+     * 创建 3D 标记
+     * @param texture 贴图资源
+     */
+    private createMeshMarker;
+}
+
+/**
+ * 轮廓高亮后处理管线（基于 OutlinePass）
+ */
+declare class OutlineHighlighter {
+    private readonly renderer;
+    private readonly scene;
+    private readonly camera;
+    /** 后处理合成器 */
+    private readonly composer;
+    /** 轮廓通道 */
+    private readonly outlinePass;
+    constructor(renderer: WebGLRenderer, scene: Scene, camera: PerspectiveCamera);
+    /**
+     * 同步后处理画布尺寸
+     * @param width 画布宽度（CSS 像素）
+     * @param height 画布高度（CSS 像素）
+     */
+    resize(width: number, height: number): void;
+    /** 使用后处理通道渲染当前帧 */
+    render(): void;
+    /**
+     * 设置轮廓选中的物体
+     * @param object 场景节点
+     */
+    setSelection(object: Object3D): void;
+    /** 清空轮廓选中 */
+    clearSelection(): void;
+    /** 释放合成器及相关 GPU 资源 */
+    dispose(): void;
+}
+
+/** 查询结果过滤函数 */
+type SelectionPredicate<T extends BaseObject> = (item: T, index: number) => boolean;
+/** 查询结果类型守卫过滤函数 */
+type SelectionTypeGuard<T extends BaseObject, S extends T> = (item: T, index: number) => item is S;
+/** 业务对象查询结果集 */
+declare class ObjectSelection<T extends BaseObject = BaseObject> {
+    /** 快照结果集合 */
+    private readonly selectedItems;
+    constructor(items: Iterable<T>);
+    /** 获取结果快照 */
+    items(): T[];
+    /** 获取第一个匹配结果 */
+    get first(): T | undefined;
+    /**
+     * 遍历结果集
+     * @param fn 遍历函数
+     */
+    forEach(fn: (item: T, index: number) => void): this;
+    /**
+     * 过滤结果集
+     * @param predicate 过滤函数。可为普通断言函数或类型守卫函数。
+     * @example
+     * ```
+     * // 传入普通谓词，返回 ObjectSelection<BaseObject>
+     * const visibleSelection = selection.filter((item, index) => {
+     *   return item.visible && index < 10;
+     * });
+     *
+     * // 传入类型守卫谓词，返回 ObjectSelection<Building>
+     * const buildingSelection = selection.filter(
+     *   (item): item is Building => item.type === ObjectType.BUILDING
+     * );
+     * ```
+     */
+    filter<S extends T>(predicate: SelectionTypeGuard<T, S>): ObjectSelection<S>;
+    filter(predicate: SelectionPredicate<T>): ObjectSelection<T>;
+    /**
+     * 批量控制显隐
+     * @param visible 是否可见
+     */
+    setVisible(visible: boolean): this;
+}
+
+/** 业务对象查询器 */
+declare class ObjectQuery {
+    private readonly app;
+    constructor(app: App);
+    queryAll(): ObjectSelection<BaseObject<three.Object3D<three.Object3DEventMap>>>;
+    /**
+     * 根据对象名称查询
+     * @param name 对象名称
+     * @param option 查询参数
+     */
+    queryByName(name: string, option?: {
+        /**
+         * 是否精确匹配
+         * @default true
+         */
+        exact?: boolean;
+        /**
+         * 是否大小写敏感
+         * @default true
+         */
+        caseSensitive?: boolean;
+    }): ObjectSelection<BaseObject<three.Object3D<three.Object3DEventMap>>>;
+    /**
+     * 根据对象唯一标识查询
+     * @param id 对象 id
+     */
+    queryById(id: string): ObjectSelection<BaseObject<three.Object3D<three.Object3DEventMap>>>;
+    /**
+     * 根据对象类型查询
+     * @param type 对象类型
+     */
+    queryByType(type: ObjectType.CAMPUS): ObjectSelection<Campus>;
+    queryByType(type: ObjectType.BUILDING): ObjectSelection<Building>;
+    queryByType(type: ObjectType.FLOOR): ObjectSelection<Floor>;
+    queryByType(type: ObjectType.MARKER): ObjectSelection<Marker>;
+    queryByType(type: ObjectType.UI_ANCHOR): ObjectSelection<UIAnchor>;
+    queryByType(type: ObjectType.ELEMENT): ObjectSelection<Element>;
+    queryByType(type: ObjectType): ObjectSelection<BaseObject>;
+    /**
+     * 归一化对象名称
+     * @param name 对象名称
+     * @param caseSensitive 是否大小写敏感
+     */
+    private normalizeName;
+}
+
+/**
+ * 场景入口\
+ * 负责初始化场景，管理场景中的所有对象
+ */
+declare class App {
+    /** 场景 */
+    readonly scene: Scene;
+    /** 相机 */
+    readonly camera: Camera;
+    /** 渲染器 */
+    readonly renderer: WebGLRenderer;
+    /** 场景灯光 */
+    readonly sceneLights: SceneLights;
+    /** 场景事件 */
+    readonly sceneEvent: SceneEvent;
+    /** 轮廓高亮后处理 */
+    readonly outlineHighlighter: OutlineHighlighter;
+    /** 当前场景层级（园区 / 建筑 / 楼层） */
+    readonly sceneLevel: SceneLevel;
+    /** 业务对象查询器 */
+    readonly objectQuery: ObjectQuery;
+    /** 自定义 3D 对象集合 */
+    readonly customObjects: Set<BaseObject<three.Object3D<three.Object3DEventMap>>>;
+    /** 容器元素 */
+    private containerEl?;
+    /** 窗口尺寸变化观察器 */
+    private resizeObserver?;
+    constructor();
+    /** 根据容器 id 初始化渲染器、相机与空场景 */
+    init(containerId: string): void;
+    /**
+     * 从自定义对象集合中移除
+     * @param customObject 已注册对象
+     */
+    unregisterCustomObject(customObject: BaseObject): void;
+    /** 创建物体 */
+    create(option: CampusOption): Campus;
+    create(option: MarkerOption): Marker;
+    create(option: UIAnchorOption): UIAnchor;
+    create(option: ThingOption): Thing;
+    create(option: PolylineOption): Polyline;
+    /**
+     * 设置天空盒
+     * @param imgUrls 图片地址，顺序为：[px, nx, py, ny, pz, nz]
+     */
+    setSkyBox(imgUrls: string[]): void;
+    /** 根据容器当前大小同步相机与渲染器 */
+    private syncSize;
+    /** 每帧：更新轨道控制、派发帧事件并渲染 */
+    private runFrame;
+    /** 处理窗口尺寸变化 */
+    private handleWindowResize;
+    /**
+     * 根据画面大小同步相机纵横比
+     */
+    private syncAspect;
+    /** 初始化渲染器 */
+    private initRenderer;
+}
+
+type ElementOption = {
+    object3D: Mesh | Group;
+    parent: BaseObject;
+    /** 对象唯一标识；未传时与节点 name 一致 */
+    id?: string;
+};
+/**
+ * 场景元素\
+ * 某类业务场景下，解析完业务对象后，额外的模型对象则视为场景元素
+ */
+declare class Element extends BaseObject<Mesh | Group> {
+    get parent(): BaseObject;
+    constructor(option: ElementOption, app: App);
+    /**
+     * 仅同步本对象状态，避免后续 destroy 重复释放 GPU
+     */
+    releaseAfterCampusDisposed(): void;
+    protected beforeDisposeResources(): void;
+    protected disposeOwnedResources(): void;
+    private bindElementCustomObject;
+}
+
+/** 园区类 */
+declare class Campus extends BaseObject {
+    /** 建筑列表 */
+    readonly buildings: Building[];
+    /** 普通物体列表 */
+    readonly otherElements: Element[];
+    constructor(option: CampusOption, app: App);
+    /**
+     * 从园区建筑列表中摘除建筑
+     * @param building 建筑实例
+     */
+    detachBuilding(building: Building): void;
+    /**
+     * 加载模型并添加到场景
+     * @param url 模型地址
+     */
+    private loadModel;
+    protected disposeOwnedResources(): void;
+    /** 解析建筑 */
+    private parseBuildings;
+    /** 获取 Mesh 的父节点，如果父节点是 Group，则返回父节点，否则返回 Mesh 自身 */
+    private getParentGroup;
+    /**
+     * 判断 glTF 节点名是否为独立建筑根（如 building_YFDL；building_YFDL_xxx 则不是）
+     * @param name 节点名称
+     */
+    private isBuildingName;
+    /**
+     * 判断节点名是否属于建筑体系（包含建筑根节点及其拆分后的子 Mesh）
+     */
+    private isBuildingRelatedName;
+    /**
+     * 判断节点名是否属于楼层体系（包含楼层根节点及其拆分后的子 Mesh）
+     */
+    private isFloorRelatedName;
+}
+
+/** 建筑类 */
+declare class Building extends BaseObject {
+    /** 所属园区 */
+    readonly campus: Campus;
+    get parent(): Campus;
+    /** 楼层列表 */
+    readonly floors: Floor[];
+    constructor(option: BuildingOption, app: App);
+    /** 绑定建筑节点与 Building 实例的映射 */
+    private bindBuildingCustomObject;
+    /** 解析当前建筑下的楼层 */
+    private parseFloors;
+    /**
+     * 从建筑楼层列表中摘除楼层
+     * @param floor 楼层实例
+     */
+    detachFloor(floor: Floor): void;
+    /**
+     * 设置建筑显隐
+     * @param visible 是否可见
+     * @param withFloors 是否同步楼层显隐，默认同步
+     */
+    setVisible(visible: boolean, withFloors?: boolean): void;
+    protected disposeOwnedResources(): void;
+    /**
+     * 园区整体销毁时 glTF 根已统一 dispose，仅同步本对象状态，避免后续 destroy 重复释放 GPU
+     */
+    releaseAfterCampusDisposed(): void;
+}
+
+/** 对象就绪回调 */
+type OnObjectReady<T> = (instance: T) => void;
+/** 标记对象初始化参数 */
+interface MarkerOption {
+    /** 物体类型 */
+    type: ObjectType.MARKER;
+    /** 对象名称 */
+    name?: string;
+    /** 对象唯一标识；未传时与 name 一致 */
+    id?: string;
+    /** 位置 */
+    position: Position;
+    /** 图片路径 */
+    imagePath: string;
+    /**
+     * 是否以 3D 模式展示
+     * @default false
+     */
+    is3D?: boolean;
+    /**
+     * 标记尺寸：[宽度, 高度]
+     * - is3D = false：屏幕像素尺寸
+     * - is3D = true：世界尺寸（单位米）
+     */
+    size: [number, number];
+    /**
+     * 是否保持近大远小
+     * @default false
+     */
+    enablePerspectiveScale?: boolean;
+    /**
+     * 缩放；is3D = true 时生效
+     * @default [1, 1, 1]
+     */
+    scale?: Scale;
+    /**
+     * 欧拉角旋转（单位度），顺序 XYZ；is3D = true 时生效
+     * @default [0, 0, 0]
+     */
+    rotation?: Rotation;
+    /** 层级父对象 */
+    parent?: BaseObject;
+    /** 对象就绪回调 */
+    onReady?: OnObjectReady<Marker>;
+}
+/** UI 锚点初始化参数 */
+interface UIAnchorOption {
+    /** 物体类型 */
+    type: ObjectType.UI_ANCHOR;
+    /** 对象名称 */
+    name?: string;
+    /** 对象唯一标识；未传时与 name 一致 */
+    id?: string;
+    /**
+     * 是否以 3D 模式展示
+     * @default false
+     */
+    is3D?: boolean;
+    /**
+     * 需要挂载的 DOM 元素\
+     * is3D ? HTMLCanvasElement : HTMLElement
+     */
+    element: HTMLElement | HTMLCanvasElement;
+    /** 世界坐标 */
+    position: Position;
+    /**
+     * 屏幕像素偏移 [x, y]
+     * @default [0, -12]
+     */
+    offsetPx?: [number, number];
+    /**
+     * 缩放；is3D = true 时生效
+     * @default [1, 1, 1]
+     */
+    scale?: Scale;
+    /**
+     * 欧拉角旋转（单位度），顺序 XYZ；is3D = true 时生效
+     * @default [0, 0, 0]
+     */
+    rotation?: Rotation;
+    /** 层级父对象 */
+    parent?: BaseObject;
+    /** 对象就绪回调 */
+    onReady?: OnObjectReady<UIAnchor>;
+}
+/** 园区对象初始化参数 */
+interface CampusOption {
+    /** 物体类型 */
+    type: ObjectType.CAMPUS;
+    /** 对象名称 */
+    name?: string;
+    /** 对象唯一标识；未传时与 name 一致 */
+    id?: string;
+    /** glb 模型地址 */
+    url: string;
+    /**
+     * 位置
+     * @default [0, 0, 0]
+     */
+    position?: Position;
+    /**
+     * 缩放
+     * @default [1, 1, 1]
+     */
+    scale?: Scale;
+    /**
+     * 欧拉角旋转（单位度），顺序 XYZ
+     * @default [0, 0, 0]
+     */
+    rotation?: Rotation;
+    /** 对象就绪回调 */
+    onReady?: OnObjectReady<Campus>;
+}
+/** 折线对象初始化参数 */
+interface PolylineOption {
+    /** 物体类型 */
+    type: ObjectType.POLYLINE;
+    /** 对象名称 */
+    name?: string;
+    /** 对象唯一标识；未传时与 name 一致 */
+    id?: string;
+    /** 路径数据 */
+    points: Position[];
+    /** 线宽（单位米） */
+    width: number;
+    /** 线条颜色 */
+    color: string;
+    /**
+     * 拐角圆角半径（单位米）；0 表示直角
+     * @default 0
+     */
+    cornerRadius?: number;
+    /**
+     * 拐角圆角细分段数，数值越大越平滑
+     * @default 10
+     */
+    cornerSegments?: number;
+    /** 贴图路径；不传则仅使用 color 纯色 */
+    imagePath?: string;
+    /**
+     * 贴图沿路径滚动速度（米/秒）；正数沿路径正向
+     * @default 0
+     */
+    textureScrollSpeed?: number;
+    /**
+     * 是否启用贴图滚动
+     * @default false
+     */
+    enableTextureScroll?: boolean;
+    /**
+     * 贴图沿路径方向一个完整图案占用的世界长度（米）
+     * @default 2
+     */
+    textureWorldSize?: number;
+    /**
+     * 贴图沿路径方向相邻图案之间的空隙长度（米），空隙区域透明
+     * @default 0
+     */
+    textureGap?: number;
+    /** 层级父对象 */
+    parent?: BaseObject;
+    /** 对象就绪回调 */
+    onReady?: OnObjectReady<Polyline>;
+}
+/** Thing 对象初始化参数 */
+interface ThingOption {
+    /** 物体类型 */
+    type: ObjectType.THING;
+    /** 对象名称 */
+    name?: string;
+    /** 对象唯一标识；未传时与 name 一致 */
+    id?: string;
+    /** glb 模型地址 */
+    url: string;
+    /**
+     * 位置
+     * @default [0, 0, 0]
+     */
+    position?: Position;
+    /**
+     * 缩放
+     * @default [1, 1, 1]
+     */
+    scale?: Scale;
+    /**
+     * 欧拉角旋转（单位度），顺序 XYZ
+     * @default [0, 0, 0]
+     */
+    rotation?: Rotation;
+    /** 层级父对象 */
+    parent?: BaseObject;
+    /**
+     * 相对父对象的位置
+     * @default [0, 0, 0]
+     */
+    localPosition?: Position;
+    /** 对象就绪回调 */
+    onReady?: OnObjectReady<Thing>;
+}
+/** 建筑对象初始化参数 */
+interface BuildingOption {
+    /** 对象名称 */
+    name?: string;
+    /** 对象唯一标识；未传时与 name 一致 */
+    id?: string;
+    /** 关联的 glTF 节点（建筑根对象） */
+    object3D: Object3D;
+    /** 父级园区 */
+    parent: Campus;
+}
+/** 楼层对象初始化参数 */
+interface FloorOption {
+    /** 对象名称 */
+    name?: string;
+    /** 对象唯一标识；未传时与 name 一致 */
+    id?: string;
+    /** 关联的 glTF 节点（楼层根对象） */
+    object3D: Object3D;
+    /** 父级建筑 */
+    parent: Building;
+}
+/** 创建物体选项 */
+type CreateOption = CampusOption | MarkerOption | UIAnchorOption | ThingOption | PolylineOption;
+/** 场景层级对象 */
+type SceneLevelObject = Campus | Building | Floor;
+
+/** 三维坐标 */
+type Position = [number, number, number];
+/** 缩放 */
+type Scale = [number, number, number];
+/** 欧拉角旋转（单位度），顺序 XYZ */
+type Rotation = [number, number, number];
+/** 视角参数 */
+type GetCameraOptions = ReturnType<Camera['getCamera']>;
+
+/** 基础对象样式 */
+declare class BaseStyle {
+    private readonly app;
+    private readonly customObject;
+    /** 材质颜色快照 */
+    private materialSnapshots;
+    /** 材质是否已隔离 */
+    private materialsIsolated;
+    constructor(app: App, customObject: BaseObject);
+    /** 高亮模型 */
+    highlight(): void;
+    /** 取消高亮模型 */
+    clearHighlight(): void;
+    /**
+     * 设置模型颜色
+     * @param color 支持 #rgb/#rrggbb/#rrggbbaa、rgb()、rgba() 及 CSS 命名色
+     */
+    setColor(color: string): void;
+    /**
+     * 设置模型透明度
+     * @param opacity 不透明度，范围 [0, 1]；0 全透明，1 不透明
+     */
+    setOpacity(opacity: number): void;
+    /** 恢复为首次 setColor / setOpacity 前的默认颜色与透明度 */
+    resetColor(): void;
+    /** 重置样式状态 */
+    reset(): void;
+    private forEachModelMaterial;
+    private ensureMaterialSnapshots;
+    private ensureMaterialIsolation;
+}
+
+/** 基础对象类 */
+declare abstract class BaseObject<T extends Object3D = Object3D> {
+    /** 物体类型 */
+    readonly type: ObjectType;
+    /** 对象名称 */
+    readonly name: string;
+    /** 对象唯一标识 */
+    readonly id: string;
+    /**
+     * 相对父对象的位置
+     * @default [0, 0, 0]
+     */
+    localPosition: Nullable<Position>;
+    /** 位置 */
+    position: Position;
+    /** 缩放 */
+    scale: Scale;
+    /** 欧拉角旋转（单位度），顺序 XYZ */
+    rotation: Rotation;
+    /** 可见状态 */
+    visible: boolean;
+    /** 用户数据 */
+    userData: Record<PropertyKey, unknown>;
+    /** 样式 */
+    readonly style: BaseStyle;
+    /** 父对象 */
+    protected _parent: Nullable<BaseObject>;
+    /** 对象关联的场景节点 */
+    protected _object3D: Nullable<T>;
+    /** 是否已执行销毁（幂等） */
+    protected destroyed: boolean;
+    protected readonly app: App;
+    constructor(init: {
+        app: App;
+        type: ObjectType;
+        name?: string;
+        id?: string;
+        parent?: Nullable<BaseObject>;
+        position?: Position;
+        scale?: Scale;
+        rotation?: Rotation;
+        localPosition?: Position;
+    });
+    get parent(): Nullable<BaseObject>;
+    /** 对象关联的场景节点 */
+    get object3D(): Nullable<T>;
+    protected set object3D(value: Nullable<T>);
+    protected get children(): readonly BaseObject[];
+    /**
+     * 设置模型显隐
+     * @param visible 是否可见
+     */
+    setVisible(visible: boolean): void;
+    /**
+     * 设置位置
+     * @param position 位置
+     */
+    setPosition(position: Position): void;
+    /**
+     * 设置相对父对象的位置
+     * @param localPosition 相对父对象的位置
+     */
+    setLocalPosition(localPosition: Position): void;
+    /**
+     * 设置缩放
+     * @param scale 缩放
+     */
+    setScale(scale: Scale): void;
+    /**
+     * 设置旋转（欧拉角，单位度，顺序 XYZ）
+     * @param rotation 各轴旋转角度
+     */
+    setRotation(rotation: Rotation): void;
+    /**
+     * 销毁对象
+     */
+    destroy(): void;
+    /** 销毁流程模板方法 */
+    protected disposeResources(): void;
+    /** 释放前钩子 */
+    protected beforeDisposeResources(): void;
+    /** 释放对象独占资源 */
+    protected disposeOwnedResources(): void;
+    /** 释放后钩子 */
+    protected afterDisposeResources(): void;
+    /** glTF 节点已有 transform 时，由子类在赋值 object3D 后调用 */
+    protected syncTransformFromObject3D(object3D: Object3D): void;
+    /**
+     * 清理 customObject 映射
+     * @param target 目标节点
+     * @param deep 是否递归清理子树
+     */
+    protected clearCustomObjectBinding(target: Object3D, deep?: boolean): void;
+    /**
+     * 将节点从场景树摘除（无论挂在 scene 根或任意父级）
+     * @param target 目标节点
+     */
+    protected detachObject3D(target: Object3D): void;
+    /**
+     * 释放节点子树下的网格资源
+     * @param target 目标节点
+     */
+    protected disposeObject3DSubtree(target: Object3D): void;
+    /** 仅更新内部 scale，不写入场景节点 */
+    protected setScaleState(scale: Scale): void;
+    /** 仅更新内部 rotation（单位度），不写入场景节点 */
+    protected setRotationState(rotation: Rotation): void;
+    /** 是否使用相对父对象的位置 */
+    protected isUsingLocalPosition(): boolean;
+}
+
+/**
+ * UI 界面锚点\
+ * 将 UI 界面元素固定在场景中某个位置，并跟随相机移动
+ */
+declare class UIAnchor extends BaseObject<Mesh> {
+    /** 覆盖层根元素 ID */
+    static readonly OVERLAY_ROOT_ID = "twin3d-ui-anchor-overlay-root-id";
+    /** 实例锚点容器 */
+    private readonly anchorContainer;
+    /** 屏幕像素偏移 */
+    private readonly offsetPx?;
+    /** UI 锚点元素 */
+    private readonly uiElement;
+    /** 是否以 3D 模式展示 */
+    private readonly is3D;
+    /** 3D 模式尺寸（世界单位） */
+    private readonly meshSize;
+    constructor(option: UIAnchorOption, app: App);
+    /** 设置显隐 */
+    setVisible(visible: boolean): void;
+    setPosition(position: Position): void;
+    setScale(scale: Scale): void;
+    setRotation(rotation: Rotation): void;
+    /** 每帧更新位置 */
+    update(): void;
+    protected beforeDisposeResources(): void;
+    protected disposeOwnedResources(): void;
+    protected afterDisposeResources(): void;
+    /** 创建实例锚点容器 */
+    private createAnchorContainer;
+    /** 订阅全局帧更新 */
+    private subscribeFrameUpdate;
+    /** 帧更新回调 */
+    private handleFrameUpdate;
+    /** 获取覆盖层根元素 */
+    private getOverlayRoot;
+    /** 创建 3D 锚点 */
+    private create3DAnchor;
+    /** 计算 3D 锚点尺寸 */
+    private getMeshSize;
+}
+
+export { App, BaseObject, BaseStyle, Building, type BuildingOption, BuiltInEventKey, Campus, type CampusOption, type CreateOption, Element, Floor, type FloorOption, type GetCameraOptions, Marker, type MarkerOption, type Nullable, ObjectNamePrefix, ObjectType, type OnObjectReady, Polyline, type PolylineOption, type Position, type Rotation, type Scale, type SceneEventMap, SceneEventType, type SceneLevelObject, Thing, type ThingOption, UIAnchor, type UIAnchorOption, isBuilding, isCampus, isCampusDerivedObject, isFloor };