@realsee/five 6.8.0-alpha.8 → 6.8.0

package/llms.txt

@@ -4,10 +4,17 @@
 
 ** Documentation for @realsee/five is located in the `ai_guides/` directory. Do NOT use docs/ **
 
+> **Quick Lookup:** For API signatures, go directly to **[ai_guides/api.md](ai_guides/api.md)**. For terminology, see **[ai_guides/glossary.md](ai_guides/glossary.md)**.
+
+> **Keyword Search Tip:** Each doc in `ai_guides/features/` has a `tags` yaml block at the bottom with Chinese and English keywords. Use these for keyword matching when the scenario table below doesn't cover your need.
+
+> **Full Documentation Map:** For a categorized index with development strategies and architecture guidance, see **[ai_guides/README.md](ai_guides/README.md)**.
+
 ## Context & Guidelines
 
-*   **[AI Documentation Guidelines](ai_guides/ai-doc-guidelines.md)**: RULES for writing and updating documentation. READ THIS FIRST before making changes.
+*   **[AI Documentation Guidelines](ai_guides/ai-doc-guidelines.md)**: RULES for writing and updating documentation. **Only read this when maintaining or writing docs, NOT when developing applications.**
 *   **[Intro](ai_guides/intro.md)**: High-level overview of Five SDK capabilities.
+*   **[Glossary](ai_guides/glossary.md)**: Terminology definitions — READ THIS to understand core concepts (Observer, Pose, Mode, Work, PanoIndex, etc.) before writing code.
 
 ## Development Strategies
 
@@ -40,11 +47,12 @@
 
 ### Rendering & Visuals
 *   **[Pano Tile](ai_guides/features/pano-tile.md)**: Panorama tiling mechanism.
+*   **[Pano Filter](ai_guides/features/pano-filter.md)**: Color/Tone adjustments for panoramas.
 *   **[Model](ai_guides/features/model.md)**: Built-in model rendering.
 *   **[Material](ai_guides/features/material.md)**: Material parameters (Opacity, PointScale, VertexMarks).
 *   **[Postprocessing](ai_guides/features/postprocessing.md)**: Visual effects.
-*   **[Flowing Light 2D Pass](ai_guides/features/flowing-light-2d-pass.md)**: Flowing light screen-space effect.
-*   **[Flowing Light 3D Pass](ai_guides/features/flowing-light-3d-pass.md)**: Flowing light effect using depth/normal G-Buffer.
+*   **[Flowing Light 2D Pass](ai_guides/features/flowing-light-2d-pass.md)**: Flowing light screen-space effect with InstancedMesh rendering.
+*   **[Flowing Light 3D Pass](ai_guides/features/flowing-light-3d-pass.md)**: Flowing light effect with 3D world-space projection and InstancedMesh rendering.
 *   **[Gaussian Blur Pass](ai_guides/features/gaussian-blur-pass.md)**: Gaussian blur post-processing effect.
 *   **[Clipper](ai_guides/features/clipper.md)**: Model clipping.
 *   **[3D Tile](ai_guides/features/3dtile.md)**: Large scene 3D tiles.
@@ -58,7 +66,36 @@
 *   **[ViewLayer](ai_guides/features/view-layer.md)**: ViewLayer documentation.
 *   **[Support](ai_guides/support.md)**: Browser compatibility.
 
+## Common Scenarios (场景 → 文档速查)
+
+> Use the `tags` column for keyword matching when your requirement doesn't exactly match the scenario description.
+
+| Scenario | Docs | Tags |
+| :--- | :--- | :--- |
+| 点击拾取物体 / Object picking | [Raycast](ai_guides/features/raycast.md) | click, hit-test, floor-detection, 碰撞检测, 物体选择 |
+| 3D 标签 / HTML overlay on 3D point | [Screen Project](ai_guides/features/screen-project.md) | label, HUD, tooltip, 坐标转换, 3D转2D |
+| 全景滤镜 / 色温调节 / Color correction | [Pano Filter](ai_guides/features/pano-filter.md) | warm, cool, brightness, contrast, saturation, 暖色, 冷色, 饱和度 |
+| 加载外部 GLTF/OBJ/FBX 模型 | [Load External Model](ai_guides/features/load-external-model.md) | gltf, glb, ply, splat, fbx, draco, point-cloud, dispose |
+| 相机巡航 / 自动导览 / Camera fly-through | [Camera Animation](ai_guides/features/camera-animation.md) | rotate, zoom, auto-tour, 运镜, 旋转, 缩放 |
+| 截图 / 放大镜 / Screen capture | [Get Screen Pixels](ai_guides/features/get-screen-pixels.md) | magnifier, screenshot, color-picker, 取色器 |
+| 模型裁切 / 房屋剖面 | [Clipper](ai_guides/features/clipper.md) | clipping-box, section-view, discard, 开盖, 剖面 |
+| 流光特效 / Flowing light effect | [Flowing Light 2D](ai_guides/features/flowing-light-2d-pass.md), [Flowing Light 3D](ai_guides/features/flowing-light-3d-pass.md) | 光带, 导航路径, 动态路径, instanced |
+| 模糊特效 / Blur effect | [Gaussian Blur Pass](ai_guides/features/gaussian-blur-pass.md) | 毛玻璃, 背景虚化, gaussian |
+| 保存/恢复场景状态 | [State](ai_guides/features/state.md) | snapshot, save, restore, 快照, 场景还原 |
+| 多场景切换 / 沙盘 | [Multi-Work](ai_guides/features/multi-work.md) | sandbox, 多户型, 拼接, workCode |
+| 请求鉴权 / CDN 替换 | [Request Proxy](ai_guides/features/request-proxy.md) | authentication, token, url-rewrite, cors, 私有化 |
+| 插件开发 | [Plugin](ai_guides/features/plugin.md) | lifecycle, extension, baseplugin, 状态管理 |
+| 事件监听 / 拦截默认行为 | [Event](ai_guides/features/event.md) | preventDefault, waitUntil, on, off, gesture, 回调 |
+| 手势交互 / 自定义拖拽 | [Gesture](ai_guides/features/gesture.md) | tap, pan, pinch, press, 触摸, 鼠标 |
+| 后处理特效 / 自定义 Shader | [Postprocessing](ai_guides/features/postprocessing.md) | effect-composer, addPass, edl, 描边, 景深 |
+| 材质 / 透明度 / 点云样式 | [Material](ai_guides/features/material.md) | opacity, pointcloud, roof, ceiling, 天花板, 顶点标记 |
+| 模式切换 / 全景↔模型↔户型图 | [Mode](ai_guides/features/mode.md) | panorama, floorplan, mapview, topview, VR |
+| 全景高清瓦片 / 分片加载 | [Pano Tile](ai_guides/features/pano-tile.md) | LOD, tile, 按需加载, 高清全景 |
+| 图片 CDN / 私有化部署 | [Image Options](ai_guides/features/image-options.md) | avif, webp, cdn, private-deployment |
+| 加载进度 / 首屏优化 | [Load Progress](ai_guides/features/load-progress.md) | refined, loaded, loading-bar, 首屏 |
+
 ## Release Notes
 *   [6.8](ai_guides/release_notes/6.8.md)
 *   [6.7](ai_guides/release_notes/6.7.md)
 *   [6.6](ai_guides/release_notes/6.6.md)
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@realsee/five",
-  "version": "6.8.0-alpha.8",
+  "version": "6.8.0",
   "description": "Realsee Renderer SDK",
   "author": "BEIKE REALSEE TECHNOLOGY (HK) LIMITED",
   "license": "SEE LICENSE IN TERMS.txt",
@@ -21,7 +21,7 @@
     }
   },
   "dependencies": {
-    "protobufjs": "^7.5.4",
+    "protobufjs": "^8.0.1",
     "sharp": "^0.34.3",
     "tslib": "^2.8.1"
   },
@@ -81,8 +81,8 @@
   },
   "ai": {
     "documentation": {
-      "entry": "./ai_guides/README.md",
-      "root": "./ai_guides"
+      "llms.txt": "./llms.txt",
+      "guides": "./ai_guides"
     },
     "ignore": [
       "./docs"

package/plugins/CSS3DPlugin/Controller.d.ts

@@ -0,0 +1,64 @@
+import type { Five } from '@realsee/five';
+import { BasePlugin } from '../BasePlugin';
+import * as THREE from 'three';
+import { CSS3DRenderer, CSS3DObject } from '../thirdParty/CSS3DRenderer.js';
+import type * as PluginType from './typing';
+export declare class Controller extends BasePlugin.Controller<PluginType.State, PluginType.EventMap, PluginType.ServerData, PluginType.PluginData> {
+    /** 当前使用的数据 */
+    data?: PluginType.PluginData;
+    /** 插件当前状态 */
+    state: PluginType.State;
+    /** CSS3D 渲染器实例 */
+    renderer: CSS3DRenderer;
+    scene: THREE.Scene;
+    styleSheet: CSSStyleSheet;
+    camera: THREE.PerspectiveCamera;
+    cacheMap: WeakMap<object, any>;
+    private resizeObserver?;
+    private updateState;
+    constructor(five: Five, params?: PluginType.Params);
+    load(data: PluginType.ServerData): Promise<void>;
+    createCSS3DObject: ({ id, name, innerHTML, sprite, normal, position, scalar, visible, timeout, }: PluginType.CreateCSS3DObjectType) => CSS3DObject;
+    render: () => void;
+    /**
+     * 强制标脏并重新渲染所有 objects
+     */
+    forceRender: () => void;
+    private _addEventListener;
+    private _removeEventListener;
+    /**
+     * 将插件 DOM 挂载到指定容器
+     */
+    appendToFiveContainer(): void;
+    add(...object: THREE.Object3D[]): void;
+    remove(object: THREE.Object3D): void;
+    removeAll(): void;
+    /**
+     * 淡入指定的 CSS3DObject，设置 object.userData.visible = true
+     */
+    fadeInObjects(...objects: THREE.Object3D[]): void;
+    /**
+     * 淡出指定的 CSS3DObject，设置 object.userData.visible = false
+     */
+    fadeOutObjects(...objects: THREE.Object3D[]): void;
+    private _enable;
+    private _disable;
+    /**
+     * 启用插件，让插件能够响应交互
+     */
+    enable(options?: BasePlugin.BaseOptions): void;
+    /**
+     * 禁用插件，让插件停止响应交互
+     */
+    disable(options?: BasePlugin.BaseOptions): void;
+    /**
+     * 显示场景，设置 scene.visible = true
+     */
+    show(options?: BasePlugin.BaseOptions): void;
+    /**
+     * 隐藏场景，设置 scene.visible = false
+     */
+    hide(options?: BasePlugin.BaseOptions): void;
+    /** 销毁插件，移除所有副作用 */
+    dispose: () => void;
+}

package/plugins/CSS3DPlugin/index.d.ts

@@ -0,0 +1,5 @@
+import type { Five } from '@realsee/five';
+import type * as CSS3DPluginType from './typing';
+import { Controller } from './Controller';
+export declare const CSS3DPlugin: (five: Five, params?: CSS3DPluginType.Params) => Controller;
+export type { CSS3DPluginType, Controller as CSS3DPluginController };

package/plugins/CSS3DPlugin/typing.d.ts

@@ -0,0 +1,32 @@
+import type { BasePlugin } from '../BasePlugin';
+export type PluginData = any;
+export type ServerData = any;
+export interface CreateCSS3DObjectType {
+    id?: string;
+    name?: string;
+    innerHTML: string;
+    sprite?: boolean;
+    normal?: THREE.Vector3;
+    position?: THREE.Vector3;
+    scalar?: number;
+    visible?: boolean;
+    timeout?: number;
+}
+/** 插件配置 */
+export interface Config {
+}
+/** 插件初始化参数 */
+export interface Params {
+    config?: Partial<Config>;
+    initialState?: Partial<State>;
+}
+/** 插件状态 */
+export interface State extends BasePlugin.State {
+    /** 插件是否启用 */
+    enabled: boolean;
+    /** 插件整体是否可见 */
+    visible: boolean;
+}
+/** 插件事件 */
+export interface EventMap extends BasePlugin.EventMap<State, ServerData> {
+}

package/plugins/GaussianSplattingEntranceAnimationPlugin/Controller.d.ts

@@ -0,0 +1,30 @@
+import type { Five } from '@realsee/five';
+import { BasePlugin } from '../BasePlugin';
+import type * as PluginType from './typing';
+import * as THREE from 'three';
+export declare class Controller extends BasePlugin.Controller<PluginType.State, PluginType.EventMap, any, any> {
+    data?: any;
+    state: PluginType.State;
+    private duration;
+    private curveHeight;
+    private pointDuration;
+    boundingAABB: PluginType.BoundingAABB2D | null;
+    private cancelAnimation;
+    private boundsSet;
+    keyframes: PluginType.Keyframe[];
+    private updateState;
+    constructor(five: Five, config?: PluginType.Config);
+    load(): Promise<void>;
+    enable(options?: BasePlugin.BaseOptions): void;
+    disable(options?: BasePlugin.BaseOptions): void;
+    dispose(): void;
+    private extractKeyframes;
+    private computeAABB2D;
+    private findClosestKeyframeToRay;
+    getCameraCurve(): Promise<THREE.CatmullRomCurve3>;
+    private findRenderMesh;
+    setBounding(boundsMin: THREE.Vector3, boundsMax: THREE.Vector3, center?: THREE.Vector3): void;
+    setBounds(): void;
+    startAggregation(): void;
+    playEntrance(): Promise<void>;
+}

package/plugins/GaussianSplattingEntranceAnimationPlugin/index.d.ts

@@ -0,0 +1,5 @@
+import type { Five } from '@realsee/five';
+import type * as GaussianSplattingEntranceAnimationPluginType from './typing';
+import { Controller } from './Controller';
+export declare const GaussianSplattingEntranceAnimationPlugin: (five: Five, config?: GaussianSplattingEntranceAnimationPluginType.Config) => Controller;
+export type { GaussianSplattingEntranceAnimationPluginType, Controller as GaussianSplattingEntranceAnimationController };

package/plugins/GaussianSplattingEntranceAnimationPlugin/typing.d.ts

@@ -0,0 +1,28 @@
+import type { BasePlugin } from '../BasePlugin';
+/** 插件配置 */
+export interface Config {
+    /** 动画持续时间（毫秒），同时控制运镜和着色器特效，默认 5000 */
+    duration?: number;
+    /** 曲线高度（y 值），默认 1.5 */
+    curveHeight?: number;
+    /** 单个点的聚合时长（毫秒），默认 3000。shader 会自动根据此值和 duration 计算高度方向的错开速度，保证最底部的点在总动画结束时刚好聚合完毕 */
+    pointDuration?: number;
+}
+/** 插件状态 */
+export interface State extends BasePlugin.State {
+    /** 插件是否启用 */
+    enabled: boolean;
+    /** 插件整体是否可见 */
+    visible: boolean;
+}
+/** 插件事件 */
+export interface EventMap extends BasePlugin.EventMap<State, any> {
+}
+export interface Keyframe {
+    position: THREE.Vector3;
+    location: number;
+}
+export interface BoundingAABB2D {
+    min: THREE.Vector2;
+    max: THREE.Vector2;
+}

package/plugins/Object3DHelperPlugin/Controller.d.ts

@@ -0,0 +1,99 @@
+import type { Five } from '@realsee/five';
+import { BasePlugin } from '../BasePlugin';
+import * as THREE from 'three';
+import type { Object3DHelperEventMap, Object3DHelperState, ObjectHelperControllers, PositionFrom } from './typing';
+import type { HelperConfig, HelperOffset, Object3DHelperPluginEventMap, Object3DHelperPluginState } from './typing';
+import { Subscribe } from '@realsee/five';
+export declare const PLUGIN = "Object3DHelperPlugin";
+export type AddObject3DHelperConfig = {
+    positionFrom?: PositionFrom;
+    offset?: HelperOffset;
+    /** Helpers 的世界坐标偏移量 */
+    helperOffset?: THREE.Vector3;
+    yAxis?: THREE.Vector3 | (() => THREE.Vector3);
+    xAxis?: THREE.Vector3 | (() => THREE.Vector3);
+    zAxis?: THREE.Vector3 | (() => THREE.Vector3);
+    moveHelper?: HelperConfig<{
+        xArrowEnable?: boolean;
+        yArrowEnable?: boolean;
+        zArrowEnable?: boolean;
+    }>;
+    /** 是否展示 MoveHelper 拖拽时的坐标提示，默认 false */
+    moveHelperTips?: boolean;
+    rotateHelper?: HelperConfig<{
+        yzCircleEnable?: boolean;
+        xzCircleEnable?: boolean;
+        xyCircleEnable?: boolean;
+        angleTipsEnable?: boolean;
+    }>;
+    boundingBoxHelper?: HelperConfig;
+};
+export declare class Object3DHelper {
+    controllers: ObjectHelperControllers;
+    state: Object3DHelperState;
+    hooks: Subscribe<Object3DHelperEventMap>;
+    constructor(controllers?: ObjectHelperControllers);
+    show(options?: {
+        userAction?: boolean;
+    }): void;
+    hide(options?: {
+        userAction?: boolean;
+    }): void;
+    enable(options?: {
+        userAction?: boolean;
+    }): void;
+    disable(options?: {
+        userAction?: boolean;
+    }): void;
+    dispose(): void;
+    setState(state: Partial<Object3DHelperState>, _options?: {
+        userAction?: boolean;
+    }): void;
+    addControllers(controllers: ObjectHelperControllers): void;
+    initialHelperMatrix(): void;
+    private handleEnable;
+    private handleVisible;
+    private handleDispose;
+    private everyControllerDo;
+}
+export declare class Controller extends BasePlugin.Controller<Object3DHelperPluginState, Object3DHelperPluginEventMap & BasePlugin.EventMap<Object3DHelperPluginState, any>, any, any> {
+    name: string;
+    data?: any;
+    state: Object3DHelperState;
+    objectHelperMap: Map<THREE.Object3D, {
+        helper: Object3DHelper;
+        disposers: (() => any)[];
+        helperGroup: THREE.Group;
+    }>;
+    constructor(five: Five);
+    show(options?: {
+        userAction?: boolean;
+    }): Promise<void>;
+    hide(options?: {
+        userAction?: boolean;
+    }): Promise<void>;
+    enable(options?: {
+        userAction?: boolean;
+    }): void;
+    disable(options?: {
+        userAction?: boolean;
+    }): void;
+    dispose(): void;
+    load(_data: any): Promise<void>;
+    setState(state: Partial<Object3DHelperState>, options?: {
+        userAction?: boolean;
+    } & Record<string, any>): void;
+    getObject3DHelper(object3D: THREE.Object3D): {
+        helper: Object3DHelper;
+        disposers: (() => any)[];
+        helperGroup: THREE.Group;
+    } | undefined;
+    addObject3DHelper(object3D: THREE.Object3D, paramsConfig?: AddObject3DHelperConfig): ObjectHelperControllers | undefined;
+    removeObject3DHelper(object3D: THREE.Object3D): void;
+    private handleEnable;
+    private handleVisible;
+    private handleDispose;
+    private everyHelperDo;
+    private actionIfStateIsEnabled;
+    private getConfig;
+}

package/plugins/Object3DHelperPlugin/Controllers/BaseController.d.ts

@@ -0,0 +1,142 @@
+import * as THREE from 'three';
+import { Subscribe } from '@realsee/five';
+import type { SolidGuideOptions } from '../utils/solidGuide';
+import type { HelperEventMap, HelperOffset, InternalHelperEventMap, ScaleCallback } from '../typing';
+import type { BaseHelper } from '../Helper/BaseHelper';
+import DomEvents from '../../thirdParty/domevents';
+export declare let originOpacity: {
+    opacity: number;
+} | null;
+type Config = {
+    offset?: HelperOffset;
+    yAxis?: THREE.Vector3 | (() => THREE.Vector3);
+    xAxis?: THREE.Vector3 | (() => THREE.Vector3);
+    zAxis?: THREE.Vector3 | (() => THREE.Vector3);
+    scaleCallback?: ScaleCallback;
+    /** 实线样式与行为配置（透传给 SolidGuideLine） */
+    solidGuide?: SolidGuideOptions;
+};
+export declare abstract class BaseController<T extends BaseHelper = BaseHelper, K extends THREE.Object3D = THREE.Object3D> {
+    originObject3D: K;
+    hooks: Subscribe<HelperEventMap>;
+    preventTapDefaultEvent: boolean;
+    protected internalHooks: Subscribe<InternalHelperEventMap>;
+    protected readonly disposers: (() => void)[];
+    protected helperObject3D: T;
+    protected camera: THREE.Camera;
+    protected model: THREE.Object3D;
+    protected scene: THREE.Object3D;
+    protected container: HTMLElement;
+    protected domEvents: DomEvents;
+    protected isDragging: boolean;
+    protected enabled: boolean;
+    protected name: string;
+    protected boundingBox?: THREE.Box3;
+    protected config: Config;
+    private onRender;
+    protected cameraHooks: Subscribe<{
+        cameraUpdate: () => any;
+    }>;
+    /** 其他控制器的引用，用于跨控制器状态检查 */
+    protected otherControllers?: {
+        moveController?: BaseController;
+        rotateController?: BaseController;
+        scaleController?: BaseController;
+    };
+    /**
+     * 更新其他控制器的引用
+     */
+    updateOtherControllers(otherControllers: {
+        moveController?: BaseController;
+        rotateController?: BaseController;
+        scaleController?: BaseController;
+    }): void;
+    /**
+     * 获取当前控制器的拖拽状态
+     */
+    getIsDragging(): boolean;
+    constructor(params: {
+        camera: THREE.Camera;
+        model: THREE.Object3D;
+        originObject3D: K;
+        helperObject3D: T;
+        container: HTMLElement;
+        domEvents: DomEvents;
+        scene: THREE.Object3D;
+        onRender?: () => void;
+        sharedHooks?: Subscribe<HelperEventMap>;
+        sharedInternalHooks?: Subscribe<InternalHelperEventMap>;
+        /** 其他控制器的引用，用于跨控制器状态检查 */
+        otherControllers?: {
+            moveController?: BaseController;
+            rotateController?: BaseController;
+            scaleController?: BaseController;
+        };
+    }, config?: Config);
+    initialHelperPosition(): void;
+    initialHelperQuaternion(): void;
+    enable(): void;
+    disable(): void;
+    show(): void;
+    hide(): void;
+    dispose(): void;
+    /**
+     * @description: applyHelperMatrix4
+     * @param {THREE.Matrix4} matrix position 偏移量
+     */
+    applyHelperMatrix4(matrix: THREE.Matrix4): void;
+    /**
+     * @description: applyHelperQuaternion
+     * @param {THREE.Quaternion} quaternion 旋转四元数
+     * @param {THREE.Vector3} origin 旋转中心
+     */
+    applyHelperQuaternion(quaternion: THREE.Quaternion, origin: THREE.Vector3): void;
+    /**
+     * @description: applyHelperScaleMatrix4
+     * @param {THREE.Matrix4} matrix 缩放矩阵
+     * @param {THREE.Vector3} origin 缩放中心
+     */
+    applyHelperScaleMatrix4(matrix: THREE.Matrix4, origin?: THREE.Vector3): void;
+    onWantsTapGesture: (raycaster: THREE.Raycaster) => false | void;
+    updateHelperScale: () => void;
+    onWantsGesture(type: 'press' | 'pan' | string, pointers: {
+        x: number;
+        y: number;
+    }[], final: boolean): false | void;
+    onIntersectionOnModelUpdate(intersection: THREE.Intersection): void;
+    /**
+     * @description: onApplyOriginObjectScale
+     * @param {THREE.Matrix4} params.matrix 缩放矩阵
+     * @param {THREE.Vector3} params.origin 缩放中心
+     */
+    protected onApplyOriginObjectScale(params: {
+        matrix: THREE.Matrix4;
+        origin?: THREE.Vector3;
+    }): void;
+    /**
+     * @description: onApplyOriginObjectRotate
+     * @param {THREE.Quaternion} params.quaternion 旋转四元数
+     * @param {THREE.Vector3} params.origin 旋转中心
+     */
+    protected onApplyOriginObjectRotate(params: {
+        quaternion: THREE.Quaternion;
+        origin: THREE.Vector3;
+    }): void;
+    /**
+     * @description: onApplyOriginObjectPosition
+     * @param {THREE.Matrix4} params.matrix position 偏移量
+     */
+    protected onApplyOriginObjectPosition(params: {
+        matrix: THREE.Matrix4;
+    }): void;
+    protected onSetOriginObjectScale(scale: THREE.Vector3): void;
+    protected onSetOriginObjectRotate(_quaternion: THREE.Quaternion, _origin?: THREE.Vector3): void;
+    protected onSetOriginObjectPosition(position: THREE.Vector3): void;
+    protected render(): void;
+    protected updateOffsetByScale(scale: THREE.Vector3): void;
+    protected hoverListener(object3D: THREE.Object3D | undefined | THREE.Group | (THREE.Object3D | undefined | THREE.Group)[], hoverColor?: THREE.Color | string | number, hoverOpacity?: number): () => void;
+    private getIntersectObject;
+    private getBox;
+    private calculateOffset;
+}
+export {};

package/plugins/Object3DHelperPlugin/Controllers/BoundingBoxController.d.ts

@@ -0,0 +1,16 @@
+import { BaseController } from './BaseController';
+import type { BoundingBoxHelperAbstract } from '../Helper/BaseHelper';
+import * as THREE from 'three';
+export declare class BoundingBoxController<OriginObject3D extends THREE.Object3D = THREE.Object3D> extends BaseController<BoundingBoxHelperAbstract<OriginObject3D>> {
+    protected name: string;
+    constructor(...params: ConstructorParameters<typeof BaseController<BoundingBoxHelperAbstract<OriginObject3D>>>);
+    protected onApplyOriginObjectRotate(params: {
+        quaternion: THREE.Quaternion;
+        origin: THREE.Vector3;
+    }): void;
+    protected onSetOriginObjectRotate(quaternion: THREE.Quaternion, origin?: THREE.Vector3): void;
+    /**
+     * 直接从 object 同步 position 和 quaternion，消除累积误差
+     */
+    private syncWithObject;
+}

package/plugins/Object3DHelperPlugin/Controllers/MoveController.d.ts

@@ -0,0 +1,66 @@
+import { BaseController } from './BaseController';
+import * as THREE from 'three';
+import type { MoveHelperAbstract } from '../Helper/BaseHelper';
+export declare function rayOnLine(params: {
+    raycaster: THREE.Raycaster;
+    line: THREE.Line3;
+    clampToLine?: boolean;
+}): THREE.Vector3;
+export type UseFaceNormalInterface = {
+    /**
+     * 是否使用面的法线，默认为true
+     */
+    enable?: boolean;
+    /**
+     * 期望对齐的方向，默认为Y轴对齐Face的法向向量，即 `{ x: 0, y: 1, z: 0 }`
+     */
+    alignmentVector?: {
+        x?: number;
+        y?: number;
+        z?: number;
+    };
+    /**
+     * 修正后的face normal
+     */
+    fixedFaceNormal?: (face: THREE.Vector3) => THREE.Vector3;
+} | boolean;
+export declare class MoveController<T extends MoveHelperAbstract = MoveHelperAbstract> extends BaseController<T> {
+    get moveByMouseEnable(): boolean;
+    protected name: string;
+    private startInfo?;
+    /** 拖拽时用于显示方向参考的直线（与 ScaleController 一致：Line + LineBasicMaterial） */
+    private dragGuideLine?;
+    private solidGuide;
+    private _moveByMouse;
+    private mouseInfo?;
+    private mousedownEventListenerDisposer?;
+    constructor(...params: ConstructorParameters<typeof BaseController<T>>);
+    dispose(): void;
+    /**
+     * @description: 跟随鼠标移动
+     */
+    moveByMouse(params?: {
+        /** 是否使用面的法线，默认为false */
+        useFaceNormal: UseFaceNormalInterface;
+    }): void;
+    /**
+     * @description: 禁用跟随鼠标移动
+     */
+    disableMoveByMouse(): void;
+    onIntersectionOnModelUpdate(intersection: THREE.Intersection): void;
+    private handleMouseDown;
+    private handleMouseUp;
+    /**
+     * @description: 拖动开始，找出拖的Direction
+     */
+    private dragStart;
+    private dragging;
+    /**
+     * 更新直线缩放，保持视觉上的恒定大小（与 ScaleController 保持一致）
+     */
+    private updateDragGuideLineScale;
+    private move;
+    private dragEnd;
+    private setTipsText;
+    private setTipsPosition;
+}

package/plugins/Object3DHelperPlugin/Controllers/RotateController.d.ts

@@ -0,0 +1,61 @@
+import { BaseController } from './BaseController';
+import type { RotateHelperAbstract } from '../Helper/BaseHelper';
+import * as THREE from 'three';
+export declare class RotateController<T extends RotateHelperAbstract = RotateHelperAbstract> extends BaseController<T> {
+    protected name: string;
+    private get rotateCenter();
+    private startInfo?;
+    private removeListener?;
+    private solidGuide;
+    private snapGuideLines;
+    constructor(...params: ConstructorParameters<typeof BaseController<T>>);
+    setRotateAngle(angle: {
+        x?: number;
+        y?: number;
+        z?: number;
+    }): void;
+    /**
+     * @description 通过改变欧拉角中的某一个值来改变旋转，但保持其他两个轴的旋转不变
+     * @param axis 要修改的轴 ('x' | 'y' | 'z')
+     * @param angle 新的角度值（度）
+     * @returns 新的四元数值
+     */
+    getEulerAngle(axis: 'x' | 'y' | 'z', angle: number): THREE.Quaternion;
+    protected onApplyOriginObjectRotate(params: {
+        quaternion: THREE.Quaternion;
+        origin: THREE.Vector3;
+    }): void;
+    protected onApplyOriginObjectScale(params: {
+        matrix: THREE.Matrix4;
+        origin?: THREE.Vector3;
+    }): void;
+    /**
+     * @description: 拖动开始，找出拖的Direction
+     */
+    private dragStart;
+    private getMatrix;
+    private getMatrixAngle;
+    private parseAngleByDirection;
+    private dragging;
+    private rotate;
+    private dragEnd;
+    private updateOtherHelpers;
+    private getAngleHelper;
+    private setAngleHelperStart;
+    private setAngleHelperLength;
+    private setTipsAngle;
+    private setTipsPosition;
+    /**
+     * 从 quaternion 提取绕指定轴的旋转角度
+     * 通过投影分解，不受万向锁影响
+     */
+    private extractAxisAngle;
+    /**
+     * 显示吸附辅助线：在旋转平面上显示两条轴线
+     */
+    private showSnapGuideLines;
+    /**
+     * 移除吸附辅助线
+     */
+    private removeSnapGuideLines;
+}