@realsee/five 6.8.0-alpha.3 → 6.8.0-alpha.30

package/line/utils/Line2.d.ts

@@ -0,0 +1,7 @@
+import { LineGeometry } from "./LineGeometry";
+import { LineMaterial } from "./LineMaterial";
+import { LineSegments2 } from "./LineSegments2";
+declare class Line2 extends LineSegments2 {
+    constructor(geometry: LineGeometry, material: LineMaterial);
+}
+export { Line2 };

package/line/utils/LineGeometry.d.ts

@@ -0,0 +1,10 @@
+import * as THREE from "three";
+import { LineSegmentsGeometry } from "./LineSegmentsGeometry";
+declare class LineGeometry extends LineSegmentsGeometry {
+    constructor();
+    setPositions(array: ArrayLike<number>): this;
+    setColors(array: ArrayLike<number>): this;
+    fromLine(line: THREE.Line): this;
+    copy(): this;
+}
+export { LineGeometry };

package/line/utils/LineMaterial.d.ts

@@ -0,0 +1,20 @@
+import * as THREE from "three";
+type LineMaterialParameters = {
+    color?: number | THREE.Vector3;
+    linewidth?: number;
+    dashed?: boolean;
+    dashScale?: number;
+    dashSize?: number;
+    gapSize?: number;
+    resolution?: THREE.Vector2;
+};
+declare class LineMaterial extends THREE.ShaderMaterial {
+    color: number | THREE.Vector3;
+    dashed: boolean;
+    dashScale: number;
+    dashSize: number;
+    gapSize: number;
+    resolution: THREE.Vector2;
+    constructor(parameters: LineMaterialParameters);
+}
+export { LineMaterial, LineMaterialParameters };

package/line/utils/LineSegments2.d.ts

@@ -0,0 +1,11 @@
+import * as THREE from 'three';
+import { LineSegmentsGeometry } from './LineSegmentsGeometry';
+import { LineMaterial } from './LineMaterial';
+declare class LineSegments2 extends THREE.Mesh<LineSegmentsGeometry, LineMaterial> {
+    constructor(geometry: LineSegmentsGeometry, material: LineMaterial);
+    computeLineDistances(): this;
+    raycast(raycaster: THREE.Raycaster, intersects: (THREE.Intersection & {
+        pointOnLine: THREE.Vector3;
+    })[]): void;
+}
+export { LineSegments2 };

package/line/utils/LineSegmentsGeometry.d.ts

@@ -0,0 +1,15 @@
+import * as THREE from "three";
+declare class LineSegmentsGeometry extends THREE.InstancedBufferGeometry {
+    constructor();
+    applyMatrix4(matrix: THREE.Matrix4): this;
+    setPositions(array: ArrayLike<number> | number[]): this;
+    setColors(array: Float32Array | number[]): this;
+    fromWireframeGeometry(geometry: THREE.WireframeGeometry): this;
+    fromEdgesGeometry(geometry: THREE.EdgesGeometry): this;
+    fromMesh(mesh: THREE.Mesh): this;
+    fromLineSegments(lineSegments: THREE.LineSegments): this;
+    computeBoundingBox(): void;
+    computeBoundingSphere(): void;
+    toJSON(): void;
+}
+export { LineSegmentsGeometry };

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
 
@@ -16,8 +23,10 @@
 *   **[Parameter](ai_guides/features/parameter.md)**: Configuration for `new Five(config)`.
 
 ### Data Handling
+*   **[Panorama UV](ai_guides/features/pano-uv.md)**: 全景图 UV 与空间方向转换工具
 *   **[Work](ai_guides/features/work.md)**: Understanding the core data structure (VR data).
 *   **[Load External Model](ai_guides/features/load-external-model.md)**: Loading GLTF/OBJ/etc.
+*   **[Load Progress](ai_guides/features/load-progress.md)**: Monitoring loading status (Loaded vs Refined).
 *   **[Multi-Work](ai_guides/features/multi-work.md)**: Handling multiple works (Sandbox mode).
 *   **[Request Proxy](ai_guides/features/request-proxy.md)**: Intercepting/modifying requests (Auth/CDN).
 *   **[Image Options](ai_guides/features/image-options.md)**: Configuring image resources.
@@ -26,7 +35,7 @@
 *   **[State](ai_guides/features/state.md)**: CRITICAL for saving/restoring scenes (Pose, Mode, PanoIndex).
 *   **[Five](ai_guides/features/five.md)**: The main renderer class.
 *   **[Mode](ai_guides/features/mode.md)**: Viewing modes (Panorama, Model, Floorplan, etc.).
-*   **[Coordinate System](ai_guides/features/coordnate-system.md)**: Coordinate system definitions.
+*   **[Coordinate System](ai_guides/features/coordinate-system.md)**: Coordinate system definitions.
 
 ### Interaction & Animation
 *   **[Event](ai_guides/features/event.md)**: Tap, Gesture, and StateChange events.
@@ -38,8 +47,13 @@
 
 ### 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 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.
 *   **[Get Screen Pixels](ai_guides/features/get-screen-pixels.md)**: Screen capture/magnifier.
@@ -48,9 +62,40 @@
 
 *   **[API Reference](ai_guides/api.md)**: Comprehensive API signature index.
 *   **[Glossary](ai_guides/glossary.md)**: Terminology definitions (Observer, Pose, etc.).
-*   **[Plugin](ai_guides/plugin.md)**: Plugin development guide.
+*   **[Plugin](ai_guides/features/plugin.md)**: Plugin development guide.
+*   **[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.3",
+  "version": "6.8.0-alpha.30",
   "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.0",
     "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/BackgroundPlugin/Controller.d.ts

@@ -0,0 +1,20 @@
+import { BasePlugin } from '@realsee/five/plugins';
+import { Five } from '@realsee/five';
+import type { EventMap, Params, PluginData, State } from './typings';
+export declare class Controller extends BasePlugin.Controller<State, EventMap, any, PluginData> {
+    protected data: PluginData;
+    state: State;
+    private gradientBg?;
+    private groundBg?;
+    private style?;
+    readonly pluginName = "BackgroundPlugin";
+    constructor(five: Five, params?: Params);
+    private _onFiveCameraUpdate;
+    private _addEventListener;
+    private _removeEventListener;
+    load: () => Promise<void>;
+    setState: (state: Partial<State>, options?: BasePlugin.BaseOptions) => void;
+    enable: () => void;
+    disable: (options?: BasePlugin.BaseOptions) => void;
+    dispose: () => void;
+}

package/plugins/BackgroundPlugin/index.d.ts

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

package/plugins/BackgroundPlugin/typings.d.ts

@@ -0,0 +1,44 @@
+import type { BasePlugin } from '@realsee/five/plugins';
+export declare enum WarningCodeType {
+    Warning_1 = "CAN_NOT_DRAW_ZONE"
+}
+export type Mode = 'Idle' | 'View' | 'Marking' | 'Waiting';
+export type Mirror<T extends string> = Record<T, T>;
+export type State = {
+    enabled: boolean;
+};
+export interface PluginDataItem {
+}
+export type PluginData = PluginDataItem;
+export interface Config {
+}
+export interface Params {
+    config?: Partial<Config>;
+    initialState?: Partial<State>;
+}
+export interface EventMap extends BasePlugin.EventMap<State, PluginData> {
+    /**
+     * @param event - event.userAction是否是用户操作
+     * @description enabled 从 false 到 true 的回调
+     */
+    enable: (event: {
+        userAction: boolean;
+    }) => void;
+    /**
+     * @param event - event.userAction是否是用户操作
+     * @description enabled 从 true 到 false 的回调
+     */
+    disable: (event: {
+        userAction: boolean;
+    }) => void;
+    /**
+     * @description 插件 dispose
+     * */
+    dispose: () => void;
+    click: (index: number) => void;
+    /**
+     * @description 历史堆栈更新
+     * @param historyStackLength - 历史堆栈当前数量
+     * */
+    historyLengthChange: (historyStackLength: number) => void;
+}

package/plugins/BasePlugin/index.d.ts

@@ -0,0 +1,119 @@
+import { Five, Subscribe } from '@realsee/five';
+export declare namespace BasePlugin {
+    /**
+     * 基本属性字段
+     */
+    interface State {
+        /**
+         * 插件是否启用
+         */
+        enabled: boolean;
+        /**
+         * 插件UI是否展示
+         */
+        visible?: boolean;
+        /**
+         * 插件的配置项
+         */
+        config?: unknown;
+    }
+    interface BaseOptions {
+        /** 是否是用户行为 */
+        userAction?: boolean;
+    }
+    interface Config {
+        /** 静态资源前缀 */
+        staticPrefix?: string;
+        /** 国际化转换函数 */
+        i18n?: (key: string) => string;
+    }
+    interface StateChangeParams<PluginState> {
+        /** 最新的State */
+        state: PluginState;
+        /** 上一个State */
+        prevState?: PluginState;
+        /** 是否是用户触发 */
+        userAction: boolean;
+    }
+    /**
+     * 插件基本事件
+     */
+    type EventMap<PluginState, PluginData> = {
+        /** 插件被销毁 */
+        dispose: () => void;
+        /** 插件状态变化 */
+        stateChange: (params: StateChangeParams<PluginState>) => void;
+        /** 数据变更 */
+        dataChange: (data: PluginData, prevData?: PluginData) => void;
+        /** 数据加载完成 */
+        dataLoaded: (data: PluginData) => void;
+    };
+    /**
+     * plugin 的基本控制器
+     */
+    abstract class Controller<PluginState extends State, PluginEventMap extends EventMap<PluginState, PluginData>, PluginServerData, PluginData> {
+        five: Five;
+        protected abstract data?: PluginData;
+        /**
+         * 加载插件依赖数据
+         * @param serverData  - 插件数据
+         * @param state  - 插件 State
+         */
+        abstract load?(serverData: PluginServerData, state?: PluginState, userAction?: boolean): Promise<void>;
+        /**
+         * @description 插件事件钩子
+         */
+        hooks: Subscribe<PluginEventMap>;
+        readonly staticPrefix: string;
+        /**
+         * 当前状态
+         * @description
+         * ```text
+         * 可以通过 plugin.state 和 plugin.setState 来获取和设置。
+         * 通过 state 设置后，plugin 会通过合适的动画运动来达到设置的效果。
+         * 来迎合一些通过数据驱动的场景。
+         * ```
+         */
+        abstract state: PluginState;
+        constructor(five: Five, config?: Config);
+        /**
+         * 获取当前的插件状态，如果当初插件内存在需要通过动画变更的 state 值，则通过此方法可以得到中间状态
+         */
+        getCurrentState(): PluginState;
+        /**
+         * 插件自身DOM添加到父容器
+         * @param wrapper - Element元素
+         */
+        appendTo?(wrapper: Element): void;
+        /**
+         * 展示UI
+         */
+        show?(options?: BaseOptions): Promise<void> | void;
+        /**
+         * 隐藏UI
+         */
+        hide?(options?: BaseOptions): Promise<void> | void;
+        /**
+         * 设置state
+         * @param state  - 插件的目标状态
+         * @param options  - 配置项
+         */
+        setState?(state: Partial<PluginState>, options?: BaseOptions): void;
+        /**
+         * @description 获取静态资源的url
+         */
+        absoluteUrl(url: string): string;
+        /**
+         * 启用插件，让插件能够响应交互
+         */
+        abstract enable(options?: BaseOptions): void;
+        /**
+         * 禁用插件，让插件停止响应交互
+         */
+        abstract disable(options?: BaseOptions): void;
+        /**
+         * 插件进行销毁
+         */
+        abstract dispose(): void;
+    }
+}

package/plugins/CSS3DPlugin/Controller.d.ts

@@ -0,0 +1,60 @@
+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;
+    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/DynamicPathLinePlugin/Controller.d.ts

@@ -0,0 +1,167 @@
+import type { Five } from '@realsee/five';
+import { BasePlugin } from '@realsee/five/plugins';
+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;
+    /** config 的原始值 */
+    private _config;
+    get config(): {
+        lineCount: number;
+        spacing: number;
+        lineWidth: number;
+        color: number;
+        speed: number;
+        range: number;
+        waveAmp: number;
+        waveFreq: number;
+        particleCount: number;
+        maxDistance: number;
+        lineYOffset: number;
+        subMeshWidth: number;
+        subMeshColor: number;
+        subMeshOpacity: number;
+        subMeshMaxOpacity: number;
+        subMeshSegmentInterval: number;
+        subMeshHighlightWidth: number;
+    };
+    private paths;
+    private up;
+    private updateState;
+    constructor(five: Five, params?: PluginType.Params);
+    /**
+     * 加载服务端数据
+     */
+    load(serverData: PluginType.ServerData, state?: PluginType.State): Promise<void>;
+    /**
+     * 添加路径
+     */
+    addPath(pathConfig: PluginType.PathConfig): boolean;
+    /**
+     * 移除路径
+     */
+    removePath(pathId: string): boolean;
+    /**
+     * 启用路径
+     */
+    enablePath(pathId: string): boolean;
+    /**
+     * 禁用路径
+     */
+    disablePath(pathId: string): boolean;
+    /**
+     * 显示路径
+     */
+    showPath(pathId: string): boolean;
+    /**
+     * 隐藏路径
+     */
+    hidePath(pathId: string): boolean;
+    /**
+     * 获取所有路径ID
+     */
+    getPathIds(): string[];
+    /**
+     * 获取路径配置
+     */
+    getPathConfig(pathId: string): PluginType.PathConfig | undefined;
+    /**
+     * 清空所有路径
+     */
+    clearAllPaths(): void;
+    private getPositions;
+    private createLines;
+    private createParticleMaterial;
+    private createParticles;
+    /**
+     * 创建子网格面片的几何体
+     */
+    private createSubMeshGeometry;
+    /**
+     * 创建流光的 alpha 贴图
+     * @param segmentCount - 分段数（流光数量）
+     * @param highlightWidthInMeters - 单个高亮带的物理宽度（单位：米）
+     * @param totalLength - 路径总长度（单位：米）
+     * @param baseOpacity - 基础透明度（0-1）
+     * @param maxOpacity - 最大透明度（0-1）
+     * @returns DataTexture
+     */
+    private createAlphaMapTexture;
+    /**
+     * 创建子网格面片的材质
+     */
+    private createSubMeshMaterial;
+    /**
+     * 将路径点投影到屏幕空间
+     */
+    private projectPointsToScreen;
+    /**
+     * 找到最近的屏幕外点
+     */
+    private findNearestOffscreenPoint;
+    /**
+     * 找到最远的屏幕外点（从终点反向搜索）
+     */
+    private findFarestOffscreenPoint;
+    private updatePathAnimation;
+    /**
+     * 启动指定路径的动画
+     * @param pathId - 路径ID
+     * @param options - 配置选项
+     */
+    startPathAnimation(pathId: string, options?: {
+        startPointIndex?: number;
+        fromStart?: boolean;
+    }): boolean;
+    /**
+     * 停止指定路径的动画
+     */
+    stopPathAnimation(pathId: string, saveProgress?: boolean): boolean;
+    private _enable;
+    private _disable;
+    /**
+     * 启用插件
+     */
+    enable(options?: BasePlugin.BaseOptions): void;
+    /**
+     * 禁用插件
+     */
+    disable(options?: BasePlugin.BaseOptions): void;
+    /**
+     * 显示插件
+     */
+    show(options?: BasePlugin.BaseOptions): void;
+    /**
+     * 隐藏插件
+     */
+    hide(options?: BasePlugin.BaseOptions): void;
+    /**
+     * 设置状态
+     */
+    setState(state: Partial<PluginType.State>, options?: BasePlugin.BaseOptions): void;
+    /**
+     * 播放动画
+     */
+    play(fromStart?: boolean): void;
+    /**
+     * 暂停动画
+     */
+    pause(): void;
+    /**
+     * 重置动画状态（不自动开始播放）
+     */
+    reset(): void;
+    highlightPath(pathId: string, highlight: boolean): void;
+    /**
+     * 更新指定路径的屏幕空间投影优化
+     * @param pathId - 路径ID，如果不提供则更新所有路径
+     */
+    updateScreenProjection(pathId?: string): void;
+    private disposePathResources;
+    /**
+     * 销毁插件
+     */
+    dispose(): void;
+}

package/plugins/DynamicPathLinePlugin/index.d.ts

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

package/plugins/DynamicPathLinePlugin/line2/Line2.d.ts

@@ -0,0 +1,7 @@
+import { LineGeometry } from "./LineGeometry";
+import { LineMaterial } from "./LineMaterial";
+import { LineSegments2 } from "./LineSegments2";
+declare class Line2 extends LineSegments2 {
+    constructor(geometry: LineGeometry, material: LineMaterial);
+}
+export { Line2 };