iflow-engine-base 3.12.9 → 3.12.18

package/dist/index.d.ts

@@ -24,7 +24,6 @@ declare class Annotation3d {
     private readonly engine;
     private readonly rootGroup;
     private readonly records;
-    private readonly textureLoader;
     private readonly occlusionRaycaster;
     private readonly normalizer;
     private readonly materialFactory;
@@ -38,6 +37,8 @@ declare class Annotation3d {
     constructor(engine: any);
     add(config: Annotation3dData): string;
     addMany(configs: Annotation3dData[]): string[];
+    /** 将 PathDraw 的通用路径数据转换为可持久化的 Annotation3D 折线标记。 */
+    addPath(pathData: PathDrawData, options?: Annotation3dPathOptions): string;
     pickPoint(): Promise<AnnotationPoint3d | null>;
     update(id: string, patch: Partial<Annotation3dData>): boolean;
     remove(id: string): boolean;
@@ -80,9 +81,6 @@ export declare interface Annotation3dEffect {
     glow?: AnnotationGlowEffect;
     flow?: AnnotationFlowEffect;
     pulse?: AnnotationPulseEffect;
-    ripple?: AnnotationRippleEffect;
-    pillar?: AnnotationPillarEffect;
-    baseRing?: AnnotationBaseRingEffect;
     layers?: AnnotationLayersEffect;
     scan?: AnnotationScanEffect;
 }
@@ -120,6 +118,18 @@ export declare interface Annotation3dPanel {
     actions?: Record<string, (ctx: AnnotationActionContext) => void>;
 }
 
+/** 将 PathDraw 路径转换为 Annotation3D 线标记时使用的配置。 */
+export declare interface Annotation3dPathOptions {
+    id?: string;
+    pointSource?: 'samples' | 'points';
+    visible?: boolean;
+    selectable?: boolean;
+    style?: Annotation3dStyle;
+    effect?: Annotation3dEffect;
+    panel?: Annotation3dPanel;
+    data?: any;
+}
+
 /** 点线面体统一样式。 */
 export declare interface Annotation3dStyle {
     color?: string;
@@ -129,7 +139,11 @@ export declare interface Annotation3dStyle {
     lineWidth?: number;
     fillColor?: string;
     fillOpacity?: number;
-    point?: AnnotationPointStyle;
+    iconPoint?: AnnotationIconPointStyle;
+    textPoint?: AnnotationTextPointStyle;
+    iconTextPoint?: AnnotationIconTextPointStyle;
+    ripplePoint?: AnnotationRipplePointStyle;
+    pillarPoint?: AnnotationPillarPointStyle;
     leaderPoint?: AnnotationLeaderPointStyle;
     line?: AnnotationLineStyle;
     curve?: AnnotationCurveStyle;
@@ -138,7 +152,7 @@ export declare interface Annotation3dStyle {
 }
 
 /** 支持的三维标记类型。 */
-export declare type Annotation3dType = 'point' | 'leaderPoint' | 'polyline' | 'curve3d' | 'polygon' | 'extrudePolygon' | 'box';
+export declare type Annotation3dType = 'iconPoint' | 'textPoint' | 'iconTextPoint' | 'ripplePoint' | 'pillarPoint' | 'leaderPoint' | 'polyline' | 'curve3d' | 'polygon' | 'extrudePolygon' | 'box';
 
 /** 面板 action 回调上下文。 */
 export declare interface AnnotationActionContext {
@@ -150,13 +164,6 @@ export declare interface AnnotationActionContext {
     originalEvent: MouseEvent;
 }
 
-/** 底环效果配置。 */
-declare interface AnnotationBaseRingEffect {
-    enabled: boolean;
-    radius?: number;
-    rotateSpeed?: number;
-}
-
 /**
  * 标注联合类型
  */
@@ -171,6 +178,13 @@ declare interface AnnotationCurveStyle {
     closed?: boolean;
 }
 
+/** DOM 点标记相对三维锚点的屏幕布局。 */
+declare interface AnnotationDomPointLayoutStyle {
+    screenAnchor?: 'center' | 'top' | 'right' | 'bottom' | 'left';
+    offsetX?: number;
+    offsetY?: number;
+}
+
 /** 流动效果配置。 */
 declare interface AnnotationFlowEffect {
     enabled: boolean;
@@ -200,6 +214,40 @@ declare interface AnnotationGradientStop {
     alpha?: number;
 }
 
+/** 纯图标点标记样式，尺寸单位为屏幕像素。 */
+declare interface AnnotationIconPointStyle extends AnnotationDomPointLayoutStyle {
+    icon?: string;
+    width?: number;
+    height?: number;
+    opacity?: number;
+    rotation?: number;
+    objectFit?: 'contain' | 'cover' | 'fill' | 'none' | 'scale-down';
+    background?: AnnotationPointBackgroundStyle;
+}
+
+/** 图标与文字组合点标记样式。 */
+declare interface AnnotationIconTextPointStyle extends AnnotationDomPointLayoutStyle {
+    icon?: string;
+    iconWidth?: number;
+    iconHeight?: number;
+    iconOpacity?: number;
+    iconObjectFit?: 'contain' | 'cover' | 'fill' | 'none' | 'scale-down';
+    text?: string;
+    textColor?: string;
+    fontSize?: number;
+    fontFamily?: string;
+    fontWeight?: number | string;
+    lineHeight?: number;
+    maxTextWidth?: number;
+    textAlign?: 'left' | 'center' | 'right';
+    whiteSpace?: 'normal' | 'nowrap' | 'pre-line';
+    placement?: 'top' | 'right' | 'bottom' | 'left';
+    gap?: number;
+    align?: 'start' | 'center' | 'end';
+    backgroundScope?: 'none' | 'text' | 'all';
+    background?: AnnotationPointBackgroundStyle;
+}
+
 /**
  * 标注实例（包含 DOM 元素）
  */
@@ -250,6 +298,13 @@ declare interface AnnotationLeaderPointStyle {
     anchorRingColor?: string;
     iconBackgroundColor?: string;
     iconBackgroundOpacity?: number;
+    icon?: string;
+    iconWidth?: number;
+    iconHeight?: number;
+    text?: string;
+    textColor?: string;
+    fontSize?: number;
+    fontWeight?: number | string;
 }
 
 /** 线样式。 */
@@ -390,11 +445,34 @@ declare interface AnnotationPanelOffset3d {
     z?: number;
 }
 
-/** 光柱效果配置。 */
-declare interface AnnotationPillarEffect {
-    enabled: boolean;
+/** 独立光柱点标记样式，几何尺寸使用世界单位。 */
+declare interface AnnotationPillarPointStyle {
     height?: number;
-    width?: number;
+    radiusTop?: number;
+    radiusBottom?: number;
+    radialSegments?: number;
+    openEnded?: boolean;
+    color?: string;
+    opacity?: number;
+    gradientStartColor?: string;
+    gradientEndColor?: string;
+    gradientStartAlpha?: number;
+    gradientEndAlpha?: number;
+    glowIntensity?: number;
+    pulseEnabled?: boolean;
+    pulseSpeed?: number;
+    pulseMinOpacity?: number;
+    pulseMaxOpacity?: number;
+    showBaseRing?: boolean;
+    baseRingInnerRadius?: number;
+    baseRingOuterRadius?: number;
+    baseRingColor?: string;
+    baseRingOpacity?: number;
+    baseRingSegments?: number;
+    baseRingPulseSpeed?: number;
+    offsetX?: number;
+    offsetY?: number;
+    offsetZ?: number;
 }
 
 /** 三维空间点。 */
@@ -404,14 +482,17 @@ declare interface AnnotationPoint3d {
     z: number;
 }
 
-/** 点位样式。 */
-declare interface AnnotationPointStyle {
-    mode?: 'sprite' | 'hybrid';
-    icon?: string;
-    size?: number;
-    iconSize?: number;
-    billboard?: boolean;
-    anchorY?: number;
+/** 文字或图文点标记使用的背景样式。 */
+declare interface AnnotationPointBackgroundStyle {
+    enabled?: boolean;
+    color?: string;
+    opacity?: number;
+    borderColor?: string;
+    borderWidth?: number;
+    borderRadius?: number;
+    paddingX?: number;
+    paddingY?: number;
+    boxShadow?: string;
 }
 
 /** 面样式。 */
@@ -438,12 +519,26 @@ declare interface AnnotationPulseEffect {
     maxOpacity?: number;
 }
 
-/** 波纹扩散效果配置。 */
-declare interface AnnotationRippleEffect {
-    enabled: boolean;
+/** 独立扩散波纹点标记样式，半径与线宽使用世界单位。 */
+declare interface AnnotationRipplePointStyle {
+    color?: string;
+    opacity?: number;
     count?: number;
     speed?: number;
+    startRadius?: number;
     maxRadius?: number;
+    ringWidth?: number;
+    segments?: number;
+    showCenter?: boolean;
+    centerRadius?: number;
+    centerColor?: string;
+    centerOpacity?: number;
+    rotationX?: number;
+    rotationY?: number;
+    rotationZ?: number;
+    offsetX?: number;
+    offsetY?: number;
+    offsetZ?: number;
 }
 
 /** 扫描效果配置。 */
@@ -453,6 +548,20 @@ declare interface AnnotationScanEffect {
     width?: number;
 }
 
+/** 纯文字点标记样式。 */
+declare interface AnnotationTextPointStyle extends AnnotationDomPointLayoutStyle {
+    text?: string;
+    color?: string;
+    fontSize?: number;
+    fontFamily?: string;
+    fontWeight?: number | string;
+    lineHeight?: number;
+    maxWidth?: number;
+    textAlign?: 'left' | 'center' | 'right';
+    whiteSpace?: 'normal' | 'nowrap' | 'pre-line';
+    background?: AnnotationPointBackgroundStyle;
+}
+
 /**
  * 标注类型枚举
  */
@@ -693,6 +802,7 @@ declare type CalibrationVector3Array = [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;
@@ -2469,6 +2579,7 @@ declare class EngineKernelV2 {
     private _fpsLastSwitch;
     private _lowFpsCount;
     private _highFpsCount;
+    private frameLockEnabled;
     private readonly _idleFrameInterval;
     private _lastIdleFrameTime;
     private readonly _idleFrameRateExemptionReasons;
@@ -2544,6 +2655,7 @@ declare class EngineKernelV2 {
     modelExplode: ModelExplode;
     /** 材质编辑器，提供 DOM 面板、材质修改记录读取和一键还原能力。 */
     materialTool: MaterialTool;
+    pathDraw: PathDrawManager;
     rxQuotaListMapper: RxQuotaListMapper;
     filterLoaderModel: FilterLoaderModel;
     models: any[];
@@ -2560,14 +2672,23 @@ declare class EngineKernelV2 {
     updateVersionDisplay(): void;
     bindControlEvents(control: any): void;
     requestComposerRender(): void;
+    /**
+     * 设置自动锁帧状态；开启后引擎空闲时限制为 1 FPS，关闭后持续全帧渲染。
+     */
+    setFrameLock(enabled: boolean): void;
+    /**
+     * 获取自动锁帧状态。
+     */
+    isFrameLockEnabled(): boolean;
     /**
      * 为持续交互或动画登记空闲限帧豁免；同一原因可重复设置，多个原因会独立共存。
      */
     setIdleFrameRateExempt(reason: string, exempt: boolean): void;
     /**
      * 通过 viewToken 解析 3D 模型地址，再复用现有 loaderModule URL 加载逻辑。
+     * 解析得到多个模型地址时，共用同一份加载选项，包括是否加载边线。
      */
-    loadModelByViewToken(viewToken: string, options?: any): Promise<void>;
+    loadModelByViewToken(viewToken: string, options?: LoadModelOptions): Promise<void>;
     /**
      * 对指定 url 的 3D 模型应用整体校准矩阵。
      */
@@ -4066,7 +4187,7 @@ declare class InteractionModule {
     handelKeyEscDown(): void;
     handleMouseMove(event: any): void;
     handleMouseUp(event: any): void;
-    getCatchMeshs(event: any, retainShow?: boolean): THREE.Mesh<THREE.BufferGeometry<THREE.NormalBufferAttributes, THREE.BufferGeometryEventMap>, THREE.Material | THREE.Material[], THREE.Object3DEventMap>[] | null;
+    getCatchMeshs(event: any, retainShow?: boolean): THREE.Mesh<THREE.BufferGeometry<THREE.NormalBufferAttributes, THREE.BufferGeometryEventMap>, THREE.Material<THREE.MaterialEventMap> | THREE.Material<THREE.MaterialEventMap>[], THREE.Object3DEventMap>[] | null;
     handleMouseClick(event: any): void;
     /** 根据模型地址和运行时节点 ID 获取点击构件的 GUID。 */
     private getNodeGuid;
@@ -4146,18 +4267,34 @@ declare interface InteractionOptions720 {
     maxFov?: number;
 }
 
-/**
- * 播放配置接口
- */
+/** 漫游播放配置；duration 仅统计运动时间，不包含关键帧停留时间。 */
 declare interface IPlayOptions {
-    /** 总播放时长（毫秒），不包括停留时间 */
     duration?: number;
-    /** 是否循环播放 */
+    speed?: number;
+    playbackRate?: number;
+    /** @deprecated 保留旧调用兼容，当前时间轴固定按距离分配。 */
+    timing?: RoamingTimingMode;
+    /** @deprecated 保留旧调用兼容，当前位置固定使用直线插值。 */
+    positionInterpolation?: RoamingPositionInterpolation;
+    /** @deprecated 保留旧调用兼容，当前朝向固定使用方向向量线性插值。 */
+    rotationInterpolation?: RoamingRotationInterpolation;
+    /** @deprecated 保留旧调用兼容，当前播放固定使用线性时间。 */
+    easing?: RoamingEasing;
+    /** @deprecated 当前播放不再生成平滑曲线。 */
+    smoothTension?: number;
+    /** @deprecated 旋转量不再参与移动时长计算。 */
+    rotationWeight?: number;
     loop?: boolean;
-    /** 播放完成的回调 */
-    onComplete?: () => void;
-    /** 每个点播放完成的回调 */
+    loopMode?: RoamingLoopMode;
+    loopCount?: number;
+    direction?: RoamingDirection;
+    maxFrameDelta?: number;
+    onUpdate?: (state: IRoamingPlaybackState) => void;
     onPointComplete?: (pointIndex: number) => void;
+    onLoop?: (loopIndex: number) => void;
+    onComplete?: () => void;
+    onStateChange?: (state: IRoamingPlaybackState) => void;
+    onError?: (error: Error) => void;
 }
 
 declare interface IPoint3 {
@@ -4166,13 +4303,25 @@ declare interface IPoint3 {
     z: number;
 }
 
-/**
- * 路径点位接口
- * 继承自相机姿态，增加停留时间属性
- */
+/** 对外只读的播放状态快照。 */
+declare interface IRoamingPlaybackState {
+    status: RoamingStatus;
+    progress: number;
+    currentTime: number;
+    totalTime: number;
+    playbackRate: number;
+    loopIndex: number;
+    fromPointIndex: number | null;
+    toPointIndex: number | null;
+}
+
+/** 单个漫游关键帧，duration 表示从上一关键帧到当前关键帧的运动时长。 */
 declare interface IRoamingPoint extends ICameraPose {
-    /** 停留时间（毫秒） */
+    id?: string;
+    name?: string;
     stayTime?: number;
+    duration?: number;
+    easing?: RoamingEasing;
 }
 
 declare interface IssueCameraPose {
@@ -4813,7 +4962,7 @@ declare class LoaderModule {
     private engine;
     constructor(engine: any);
     /**
-     * 批量加载模型 URL。
+     * 按独立批次加载模型 URL，并在当前批次注册完成后统一启动首轮加载。
      */
     loadModels(urls: string[], options?: LoadModelOptions): Promise<void>;
     /**
@@ -5030,6 +5179,8 @@ declare type LoadingStyle2d = 1 | 2;
 export declare interface LoadModelOptions {
     /** URL 是否为未加密的轻量化整包 ZIP；开启后会先解压并转成本地虚拟 URL 再加载 */
     isZipPackage?: boolean;
+    /** 是否加载轻量化模型边线；默认为 true，关闭后不会请求 edge 数据包 */
+    loadEdge?: boolean;
     /** 是否要加载解单定额映射数据 */
     loadQuotaList?: boolean;
     /** 自定义模型 ID，若不提供则自动生成 UUID */
@@ -5571,6 +5722,20 @@ declare class MiniMap {
     dispose(): void;
 }
 
+export declare interface ModelAnimationInfo {
+    name: string;
+    duration: number;
+}
+
+export declare interface ModelAnimationOptions {
+    loop?: boolean;
+    repetitions?: number;
+    timeScale?: number;
+    clampWhenFinished?: boolean;
+    fadeIn?: number;
+    stopOthers?: boolean;
+}
+
 /** 三维模型点击事件中的单个构件数据。 */
 export declare interface ModelClickEventItem {
     url: string;
@@ -5767,6 +5932,8 @@ declare class ModelEdge {
     private groupVisibleBeforeExplode;
     private highlightVisibleBeforeExplode;
     private getModelEntry;
+    /** 判断模型是否允许加载边线；旧模型记录未包含该字段时按允许处理。 */
+    private shouldLoadModelEdge;
     private getFilteredIdSet;
     private getOrCreateItemIndex;
     private getEdgePointsByIndex;
@@ -6206,9 +6373,12 @@ declare class ModelMapperBatch {
 /** 管理独立于 BIM 主模型的第三方 GLB 摆放、编辑与场景持久化。 */
 declare class ModelPlace {
     private readonly engine;
-    private readonly loader;
+    private loader;
+    private dracoLoader;
+    private dracoDecoderPath;
     private readonly modelList;
     private readonly modelTransforms;
+    private readonly animationClock;
     private transformControl;
     private transformHelper;
     private selectedModelId;
@@ -6217,6 +6387,7 @@ declare class ModelPlace {
     private isRestoring;
     private isUndoing;
     private isPasting;
+    private activeLoadCount;
     private readonly pendingModelIds;
     private bimHighlightDisabledBeforeEditing;
     private selectionPointerDown;
@@ -6226,7 +6397,14 @@ declare class ModelPlace {
     constructor(engine: any);
     /** 释放控制柄、事件和已加载模型；引擎销毁时应调用。 */
     dispose(): void;
-    /** 每帧同步相机切换后的控制柄相机与尺寸，避免透视模式仍按正交投影显示。 */
+    /**
+     * 设置 Draco 解码器目录；相对路径会按 SDK 静态资源规则解析。
+     * 路径应指向包含 draco_decoder.js、draco_wasm_wrapper.js 和 draco_decoder.wasm 的目录。
+     */
+    setDracoDecoderPath(path?: string | null): void;
+    /** 获取当前实际使用的 Draco 解码器目录。 */
+    getDracoDecoderPath(): string;
+    /** 每帧同步控制柄并推进第三方模型动画。 */
     update(): void;
     /**
      * 加载 GLB 并放入场景。未指定 position 时，调用方需在开启捕捉的视图中单击确认落点。
@@ -6251,6 +6429,21 @@ declare class ModelPlace {
         materialIndex: number;
         materialName: string;
     }>;
+    /** 查询 GLB 内可播放的动画片段；数组首项即默认动画。 */
+    getModelAnimations(modelId: string): ModelAnimationInfo[];
+    /** 播放指定动画；未传名称时播放 GLB 的第一个默认片段。 */
+    playAnimation(modelId: string, animationName?: string, options?: ModelAnimationOptions): ModelAnimationInfo;
+    /** 停止指定动画；未传名称时停止该模型的全部动画。 */
+    stopAnimation(modelId: string, animationName?: string): void;
+    /**
+     * 实时更新模型位置和方向，不写入撤销历史，适用于遥测刷新和路径动画。
+     * direction 默认把模型本地 +Z 轴对准目标方向，可通过 forwardAxis 调整模型前向轴。
+     */
+    updateModelPose(modelId: string, pose: ModelPoseOptions): SceneModelData;
+    /** 高频更新模型位置的便捷接口。 */
+    updateModelPosition(modelId: string, position: THREE.Vector3Tuple): SceneModelData;
+    /** 高频更新模型方向的便捷接口。 */
+    updateModelDirection(modelId: string, direction: THREE.Vector3Tuple, forwardAxis?: THREE.Vector3Tuple): SceneModelData;
     /** 删除模型及其场景对象。 */
     deleteModel(modelId: string): void;
     /** 清空场景中的全部第三方模型并释放资源；该操作可通过 undo 撤回。 */
@@ -6266,6 +6459,11 @@ declare class ModelPlace {
     /** 撤回最近一次会改变模型状态的操作。 */
     undo(): Promise<boolean>;
     private loadRecord;
+    /** 创建挂载 Draco 解码能力的 GLTFLoader，普通 GLB 仍沿用同一加载入口。 */
+    private createGltfLoader;
+    /** 创建独立解码器实例，便于管理器销毁或切换资源目录时释放 worker。 */
+    private createDracoLoader;
+    private resolveDracoDecoderPath;
     /** 加载模型资源并创建记录，调用方可决定何时正式加入模型列表。 */
     private createRecord;
     /** 将已加载对象登记为正式模型，使其可被选中、导出和撤回。 */
@@ -6312,6 +6510,8 @@ declare class ModelPlace {
     private normalizeData;
     private cloneData;
     private createId;
+    /** 统一停止动画并释放模型资源，避免模型删除后动画混合器继续持有场景对象。 */
+    private removeRecord;
     private removeObject;
     private requestRender;
 }
@@ -6333,6 +6533,13 @@ export declare interface ModelPlaceSelectionEvent {
     object: THREE.Object3D;
 }
 
+export declare interface ModelPoseOptions {
+    position?: THREE.Vector3Tuple;
+    rotation?: THREE.EulerTuple;
+    direction?: THREE.Vector3Tuple;
+    forwardAxis?: THREE.Vector3Tuple;
+}
+
 declare class ModelProperties {
     private engine;
     extended‌: Map<string, any>;
@@ -6351,9 +6558,19 @@ declare class ModelToolModule {
     private engine;
     private highlightMaterial;
     private translucentMaterial;
+    private pickBoxMaterial;
     private customModelColorRecords;
     private customInstanceColorBatches;
     constructor(engine_: any);
+    /**
+     * 为名称匹配的普通构件新增透明拾取 Box，并追加到原节点 infos 中。
+     * @param names 构件名称关键词，任一关键词被包含即视为匹配
+     * @param minSize Box 三个方向的最小尺寸，单位为米
+     * @returns 成功新增的拾取 Box 数量
+     */
+    addPickBoxByNames(names: string[], minSize?: number): number;
+    /** 合并节点已有的本地包围盒，作为拾取 Box 的位置和尺寸来源。 */
+    private getNodeLocalBox;
     split_merge_model(model: any): void;
     un_split_merge_model(model: any): void;
     private shouldKeepSplitState;
@@ -6931,157 +7148,317 @@ declare class PanoramaLoader {
     dispose(): void;
 }
 
+/** 可序列化的通用路径数据，不包含 Three.js 运行时对象。 */
+export declare interface PathDrawData {
+    version: 1;
+    id: string;
+    lineType: PathDrawLineType;
+    coordinateSystem: 'world';
+    closed: false;
+    roundedRadius: number;
+    points: PathDrawPointData[];
+    samples: PathDrawVector3[];
+    length: number;
+}
+
+export declare type PathDrawLineType = 'bezier' | 'straight' | 'rounded';
+
+/** 管理模型表面采点、路径预览、点位编辑和通用数据导出。 */
+declare class PathDrawManager {
+    readonly type = "path-draw";
+    private readonly engine;
+    private readonly root;
+    private readonly pointsGroup;
+    private readonly points;
+    private readonly history;
+    private options;
+    private lineType;
+    private roundedRadius;
+    private line;
+    private previewLine;
+    private previewMarker;
+    private transformControl;
+    private transformHelper;
+    private selectedPointId;
+    private panel;
+    private pointsList;
+    private statusElement;
+    private addButton;
+    private completeButton;
+    private radiusInput;
+    private mode;
+    private active;
+    private closing;
+    private transformDragging;
+    private suppressNextCanvasClick;
+    private controlsEnabledBeforeDrag;
+    private pointSequence;
+    private pathId;
+    private readonly onKeyDown;
+    constructor(engine: any);
+    /** 打开路径编辑器；重复打开会先彻底清理上一次会话。 */
+    open(options?: PathDrawOptions): void;
+    /** 点击“添加点”后进入单次拾取，成功落点会立即回到编辑状态。 */
+    startAddPoint(): boolean;
+    /** 切换路径线型并记录为一条可撤销操作。 */
+    setLineType(lineType: PathDrawLineType): void;
+    /** 撤销最近一次采点、删点、移动、坐标或线型修改。 */
+    undo(): boolean;
+    /** 清空当前路径但保留编辑器，清空操作本身可以撤销。 */
+    clear(): void;
+    /** 返回与 Three.js 解耦的路径快照；少于两个点时路径尚未成立。 */
+    getPathData(): PathDrawData | null;
+    /** 完成并返回路径数据，回调结束后关闭编辑器和所有临时对象。 */
+    complete(): PathDrawData | null;
+    /** 判断编辑器当前是否处于打开状态。 */
+    isActive(): boolean;
+    /** 关闭功能并清除点位、UI、线条、操作柄、历史和事件监听。 */
+    close(): void;
+    private closeInternal;
+    /** 引擎销毁时释放长期持有的 Three.js 资源。 */
+    dispose(): void;
+    /** 相机类型切换后同步操作柄相机，保证正交与透视视图都可编辑。 */
+    update(): void;
+    /** 行为系统切换到其他工具时，按关闭语义清理整个路径会话。 */
+    disActive(): void;
+    /** 拾取状态更新虚线预览；编辑状态不接管模型悬浮反馈。 */
+    handleMouseMove(event: any): void;
+    /** 拾取状态提交一个点，编辑状态则选择场景中的点位。 */
+    handleMouseClick(event: any): void;
+    /** Esc 只退出本次拾取；再次操作仍保留已绘制路径。 */
+    handelKeyEscDown(): void;
+    private activateBehavior;
+    private restoreDefaultBehavior;
+    private ensureTransformControl;
+    private detachTransformControl;
+    private createPointRecord;
+    private selectPoint;
+    private clearSelection;
+    private getSelectedPoint;
+    private getCatchPoint;
+    private pickPointMesh;
+    private updatePreview;
+    private clearPreview;
+    private refreshAll;
+    private refreshLine;
+    /** 使用 Line2 保证 WebGL 环境下的像素线宽真实生效。 */
+    private updateLineObject;
+    private syncLineResolution;
+    private disposeLine;
+    private buildSamplePoints;
+    /** 使用 De Casteljau 算法支持任意数量的贝塞尔控制点。 */
+    private sampleBezier;
+    /** 每个折点分别截取进出线段，并用二次曲线生成稳定圆角。 */
+    private sampleRoundedPolyline;
+    private calculateLength;
+    private getPointRole;
+    private getRoleLabel;
+    private saveHistory;
+    private createSnapshot;
+    private restoreSnapshot;
+    private clearPointRecords;
+    private removePoint;
+    private updatePointCoordinate;
+    private createPanel;
+    private createIconButton;
+    private refreshPanel;
+    private renderPointRows;
+    private setButtonDisabled;
+    private setStatus;
+    private handleKeyDown;
+    private isTextInputTarget;
+    private emitChange;
+    private requestRender;
+    private toPlainVector;
+}
+
+export declare interface PathDrawOptions {
+    id?: string;
+    lineType?: PathDrawLineType;
+    lineColor?: string;
+    previewColor?: string;
+    pointColor?: string;
+    selectedPointColor?: string;
+    pointSize?: number;
+    /** 线条屏幕宽度，单位为 CSS 像素。 */
+    lineWidth?: number;
+    sampleCount?: number;
+    roundedRadius?: number;
+    historyLimit?: number;
+    onChange?: (data: PathDrawData | null) => void;
+    onComplete?: (data: PathDrawData) => void;
+}
+
+export declare interface PathDrawPointData {
+    id: string;
+    order: number;
+    role: PathDrawPointRole;
+    position: PathDrawVector3;
+}
+
+export declare type PathDrawPointRole = 'start' | 'control' | 'end';
+
+export declare interface PathDrawVector3 {
+    x: number;
+    y: number;
+    z: number;
+}
+
 /**
- * PathRoaming - 路径漫游管理器
+ * 商业级关键帧漫游时间轴。
  *
- * 功能：
- * 1. 保存相机点位（包括位置、旋转、目标点）
- * 2. 删除点位
- * 3. 跳转到指定点位
- * 4. 完整播放路径动画
- * 5. 设置每个点位的停留时间
+ * 所有运动、停留和循环统一由一个播放头驱动；关键帧在播放前编译，运行期间不修改源数据。
  */
 declare class PathRoaming {
-    private engine;
-    /** 点位列表 */
+    private readonly engine;
     private points;
-    /** 是否正在播放 */
-    private isPlaying;
-    /** 动画帧ID */
+    private status;
+    private options;
+    private activePointIndices;
+    private activePoints;
+    private segments;
     private animationFrameId;
-    /** 播放开始时间 */
-    private playStartTime;
-    /** 当前播放的起止点位索引 */
-    private playFromIndex;
-    private playToIndex;
-    /** 当前播放配置 */
-    private playOptions;
-    /** 停留定时器ID */
-    private stayTimerId;
-    /** 播放范围的结束索引 */
-    private playRangeToIndex;
+    private animationSessionId;
+    private lastFrameTime;
+    private playhead;
+    private totalTime;
+    private loopIndex;
+    private currentPose;
+    private completedSegmentIndices;
+    private orientationUp;
     constructor(engine: any);
-    /**
-     * 初始化管理器
-     */
+    /** 初始化漫游管理器。 */
     init(): void;
-    /**
-     * 获取当前相机点位
-     * @returns 当前相机的姿态信息
-     */
+    /** 读取当前相机并生成可持久化关键帧。 */
     getCurrentPoint(): IRoamingPoint;
-    /**
-     * 添加点位
-     * @param point 可选，如果不传则使用当前相机位置
-     * @param stayTime 停留时间（毫秒），默认0
-     * @returns 添加后的点位列表长度
-     */
+    /** 将当前相机姿态添加为关键帧。 */
     addPoint(stayTime?: number): number;
-    /**
-     * 批量添加点位
-     * @param points 点位数组
-     * @returns 添加后的点位列表长度
-     */
+    /** 添加一个指定姿态的关键帧。 */
+    addKeyframe(point: IRoamingPoint): number;
+    /** 批量追加关键帧。 */
     addPoints(points: IRoamingPoint[]): number;
-    /**
-     * 保存点位清单（别名方法）
-     * @param points 点位数组
-     * @returns 添加后的点位列表长度
-     */
+    /** 兼容旧接口，继续采用追加语义。 */
     savePoints(points: IRoamingPoint[]): number;
-    /**
-     * 删除指定索引的点位
-     * @param index 点位索引
-     * @returns 是否删除成功
-     */
+    /** 使用新关键帧集合完整替换当前数据。 */
+    setPoints(points: IRoamingPoint[]): number;
+    /** 删除指定关键帧。 */
     removePoint(index: number): boolean;
-    /**
-     * 清空所有点位
-     */
+    /** 清空全部关键帧。 */
     clearPoints(): void;
-    /**
-     * 获取所有点位
-     * @returns 点位数组
-     */
+    /** 返回关键帧深拷贝，调用方修改结果不会污染内部时间轴。 */
     getPoints(): IRoamingPoint[];
-    /**
-     * 获取点位数量
-     * @returns 点位数量
-     */
+    /** 获取关键帧数量。 */
     getPointCount(): number;
-    /**
-     * 更新指定索引的点位
-     * @param index 点位索引
-     * @param point 新的点位信息
-     * @returns 是否更新成功
-     */
+    /** 更新指定关键帧。 */
     updatePoint(index: number, point: IRoamingPoint): boolean;
-    /**
-     * 跳转到指定点位（无动画）
-     * @param index 点位索引
-     * @returns 是否跳转成功
-     */
+    /** 更新关键帧的停留时间。 */
+    setPointStayTime(index: number, stayTime: number): boolean;
+    /** 将关键帧序列化为 JSON。 */
+    serialize(pretty?: boolean): string;
+    /** 从 JSON 导入关键帧；replace=false 时采用追加模式。 */
+    deserialize(serialized: string, replace?: boolean): number;
+    /** 无动画跳转到指定关键帧。 */
     jumpToPoint(index: number): boolean;
-    /**
-     * 播放路径动画
-     * @param options 播放配置
-     * @returns 是否开始播放
-     */
+    /** 从第一帧到最后一帧播放完整时间轴。 */
     play(options?: IPlayOptions): boolean;
-    /**
-     * 播放指定范围的路径
-     * @param fromIndex 起始索引
-     * @param toIndex 结束索引
-     * @param options 播放配置
-     * @returns 是否开始播放
-     */
+    /** 播放指定关键帧范围，支持正向和反向。 */
     playRange(fromIndex: number, toIndex: number, options?: IPlayOptions): boolean;
-    /**
-     * 停止播放
-     */
+    /** 暂停并保留播放头、当前姿态和循环状态。 */
+    pause(): boolean;
+    /** 从暂停位置继续播放。 */
+    resume(): boolean;
+    /** 停止在当前姿态，并把最终状态一次性同步给控制器。 */
     stop(): void;
-    /**
-     * 暂停播放（保留当前位置）
-     */
-    pause(): void;
-    /**
-     * 获取是否正在播放
-     */
+    /** 设置播放倍速，运行中即时生效。 */
+    setPlaybackRate(playbackRate: number): boolean;
+    /** 跳到时间轴归一化进度；默认不补发跨越关键帧的完成回调。 */
+    seek(progress: number, emitPointCallbacks?: boolean): boolean;
+    /** 获取当前播放状态快照。 */
+    getState(): IRoamingPlaybackState;
+    /** 兼容旧接口。 */
     getIsPlaying(): boolean;
-    /**
-     * 动画循环
-     */
-    private readonly animate;
-    /**
-     * 段播放完成处理
-     */
-    private onSegmentComplete;
-    /**
-     * 移动到下一段
-     */
-    private moveToNextSegment;
-    /**
-     * 播放完成处理
-     */
-    private onPlayComplete;
-    /**
-     * 插值计算两个相机姿态之间的中间姿态
-     * @param from 起始姿态
-     * @param to 结束姿态
-     * @param t 进度（0-1）
-     * @returns 插值后的姿态
-     */
-    private interpolatePose;
-    /**
-     * 缓入缓出函数（三次方）
-     * @param t 输入值（0-1）
-     * @returns 缓动后的值
-     */
-    private easeInOutCubic;
-    /**
-     * 销毁管理器
-     */
+    /** 释放动画和关键帧数据。 */
     dispose(): void;
+    /** 校验范围、编译时间轴并启动播放。 */
+    private startPlayback;
+    /** 使用帧间增量推进全局播放头，浏览器失焦后限制单次跳跃。 */
+    private readonly animate;
+    /** 根据循环策略重建下一轮时间轴。 */
+    private advanceLoop;
+    /** 完成播放并保持终点姿态。 */
+    private completePlayback;
+    /** 将当前关键帧顺序编译成包含运动和停留的不可变片段。 */
+    private compileTimeline;
+    /** 只按相机直线移动距离分配时间，旋转量不再改变移动速度。 */
+    private getSegmentWeights;
+    /** 按折线累计距离生成全局匀速时间轴；原地转向仅占一个最小帧时长。 */
+    private getSegmentDurations;
+    /** 根据播放头计算并应用当前姿态。 */
+    private applyPlayhead;
+    /** 位置、目标点和方向向量全部按同一个线性进度插值。 */
+    private interpolateSegment;
+    /** 所有空间向量统一使用直线插值，不再生成曲线或过冲。 */
+    private interpolateTrackVector;
+    /** 将关键帧观察向量线性插值后归一化，再据此生成相机姿态。 */
+    private interpolateDirectionRotation;
+    /** 记录首帧参考上方向，整段动画不再额外插值滚转角。 */
+    private prepareOrientationTrack;
+    /** 关键帧端点也按方向向量生成姿态，避免端点采用另一套旋转规则。 */
+    private createEndpointPose;
+    /** 使用位置到目标点的方向向量生成相机姿态。 */
+    private createLookAtQuaternion;
+    /** 使用相机本地 -Z 轴对准方向，并在接近极点时保持右方向连续。 */
+    private createDirectionQuaternion;
+    /** 直接更新相机；只有相机类型切换时才调用完整恢复流程。 */
+    private applyPose;
+    /** 返回给定播放时间所在片段，停留时间属于其前面的运动片段。 */
+    private findSegment;
+    /** 补发播放头跨越的关键帧完成事件，并保证每轮只触发一次。 */
+    private reportCompletedSegments;
+    /** 跳播回退时重建已完成集合，避免后续回调丢失或重复。 */
+    private rebuildCompletedSegments;
+    /** 规范化播放配置，并兼容旧版 loop 布尔值。 */
+    private resolvePlayOptions;
+    /** 规范化外部关键帧，并以四元数作为旋转的权威数据。 */
+    private normalizePoint;
+    /** 当外部四元数无效时才回退到欧拉角，避免 NaN 进入渲染循环。 */
+    private normalizeQuaternion;
+    /** 创建连续关键帧索引，并按播放方向排序。 */
+    private createPointIndexRange;
+    /** 播放期间修改关键帧会先停止时间轴，避免编译数据与源数据不一致。 */
+    private stopForMutation;
+    /** 源关键帧变化后立即失效编译缓存，禁止旧时间轴继续 seek 或 resume。 */
+    private invalidateTimeline;
+    /** 切换状态并通知外部。 */
+    private setStatus;
+    /** 发送逐帧更新。 */
+    private emitUpdate;
+    /** 发送状态变更。 */
+    private emitStateChange;
+    /** 统一报告配置或数据错误。 */
+    private emitError;
+    /** 播放启动失败时优先使用本次调用提供的错误回调。 */
+    private failPlayback;
+    /** 用户回调异常不能中断引擎动画循环。 */
+    private invokeCallback;
+    /** 取消当前动画帧。 */
+    private cancelAnimationFrame;
+    /** 播放期间解除引擎空闲限帧。 */
+    private setFrameRateExempt;
+    private isValidPointIndex;
+    private isEasing;
+    private interpolateOptionalNumber;
+    private clonePoint;
+    private normalizeVector;
+    private normalizeDirection;
+    private normalizeOptionalPositiveNumber;
+    private toFiniteNumber;
+    private toPositiveNumber;
+    private toNonNegativeNumber;
+    private toVector3;
+    private fromVector3;
+    private toQuaternion;
+    private fromQuaternion;
 }
 
 /**
@@ -7524,6 +7901,20 @@ declare class RenderModuleGaussian {
  */
 export declare function resolveSdkAsset(path: string, moduleUrl?: string): string;
 
+declare type RoamingDirection = 'forward' | 'backward';
+
+declare type RoamingEasing = 'linear' | 'easeIn' | 'easeOut' | 'easeInOut';
+
+declare type RoamingLoopMode = 'none' | 'repeat' | 'pingPong';
+
+declare type RoamingPositionInterpolation = 'linear' | 'smooth';
+
+declare type RoamingRotationInterpolation = 'direction' | 'auto' | 'lookAt' | 'slerp' | 'euler';
+
+declare type RoamingStatus = 'idle' | 'playing' | 'paused';
+
+declare type RoamingTimingMode = 'uniform' | 'distance' | 'keyframe';
+
 /** 漫游视角拖拽方向：1 为默认方向，-1 为反向。 */
 export declare interface RoamLookDirection {
     horizontal?: 1 | -1;