@realsee/dnalogel 3.81.13 → 4.0.0-webgpu.3

package/dist/DigitalPerformanceV2Plugin/controller/index.d.ts

@@ -1,401 +0,0 @@
-import type { Five } from '@realsee/five';
-import type { DigitalPerformanceV2PluginConfig, DigitalCameraKeyframe, DigitalCameraPlayer, CameraTransition, CameraCoordinateSpace, CameraState, GroupChapterTimeInfo, GroupProgress } from '../typings';
-import { PerformancePlayground } from '../core/Playground';
-import { type AnimationScriptAdapterOptions } from '../../DigitalPerformancePlugin/animation-script-adapter';
-import type { DigitalScript, DigitalChapter } from '../core/shared';
-/** 播放进度（当前章节内） */
-export interface V2Progress {
-    /** 当前时间(ms) */
-    currentTime: number;
-    /** 当前章节总时长(ms) */
-    totalTime: number;
-    /** 当前章节索引（0-based；无当前章节为 -1） */
-    currentChapterIndex: number;
-    /** 当前动画组内的章节总数 */
-    totalChapters: number;
-}
-export type V2ProgressListener = (progress: V2Progress) => void;
-/** 组级进度监听 */
-export type GroupProgressListener = (progress: GroupProgress) => void;
-/** 运镜关键帧捕获/编辑的可选项 */
-export interface CameraKeyframeOptions {
-    /** 到下一关键帧的过渡缓动（缺省 'linear'） */
-    transition?: CameraTransition;
-    /** 关键帧缩略图 URL（COS 直传得到；运行时忽略） */
-    thumbnail?: string;
-}
-/** 运镜关键帧增删改操作结果（拒绝时 success=false 并保持序列不变） */
-export interface CameraKeyframeResult {
-    success: boolean;
-    /** 失败原因（success=false 时存在） */
-    error?: string;
-    /** 操作后的最新关键帧序列（升序，副本） */
-    keyframes: DigitalCameraKeyframe[];
-}
-/** setTimelineTo 操作结果 */
-export interface SetTimelineResult {
-    success: boolean;
-    error?: string;
-}
-/** 序列化运镜 player 的结果 */
-export interface SerializeCameraResult {
-    success: boolean;
-    error?: string;
-    player?: DigitalCameraPlayer;
-}
-/** 关键帧序列变更监听（携带升序最新序列） */
-export type CameraKeyframesChangedListener = (keyframes: DigitalCameraKeyframe[]) => void;
-/** 当前章节信息（编辑端用） */
-export interface CurrentChapterInfo {
-    /** 当前章节索引（0-based；无当前章节为 -1） */
-    index: number;
-    /** 当前章节名称（无当前章节为空串） */
-    name: string;
-    /** 当前章节总时长(ms)：该章节模型动画时长（排除相机 player） */
-    duration: number;
-}
-/** 当前章节变更监听（携带最新当前章节信息） */
-export type CurrentChapterChangedListener = (info: CurrentChapterInfo) => void;
-/**
- * DigitalPerformanceV2Plugin 控制器（最小可用版）
- *
- * 试点 fork：独立于现有 DigitalPerformancePlugin（Legacy），不修改其既有行为。
- * 本版本提供：剧本加载（复用 Shared_Core 加载 + 模型入场景）、播放/暂停/续播、
- * 基于统一时钟的进度与 seek 预览。相机运镜（CameraTrack/CameraDirector）在后续任务叠加。
- */
-export default class DigitalPerformanceV2PluginController {
-    five: Five;
-    config: DigitalPerformanceV2PluginConfig;
-    readonly NAME = "Dnalogel-DigitalPerformanceV2Plugin";
-    playground: PerformancePlayground;
-    state: {
-        enabled: boolean;
-        playing: boolean;
-        continuousPlaying: boolean;
-        currentChapter: DigitalChapter | null;
-        currentScript: DigitalScript | null;
-        /** 编辑端：当前选中的运镜项下标（无选中为 null）。切换章节时清除。 */
-        selectedShotIndex: number | null;
-    };
-    private progressListeners;
-    private groupProgressListeners;
-    private keyframesChangedListeners;
-    private currentChapterChangedListeners;
-    private nameplate;
-    private unsubNameplateRender;
-    private unsubNameplateCameraUpdate;
-    private unsubClockTick;
-    /**
-     * 进入编辑时的运镜内存态快照：以章节对象为 key，值为该章节相机关键帧的深拷贝；
-     * 值为 null 表示进入编辑时该章节不存在 camera player。null（整体）表示尚未打过快照。
-     */
-    private cameraEditSnapshot;
-    /**
-     * 组级章节时间映射缓存（加法式）：按 currentScript 引用缓存。
-     * - `groupChapterTimeMapCacheScript` 记录缓存对应的 script 引用；
-     * - script 变更 / loadScript 时引用不一致 ⇒ 缓存失效、下次请求重算。
-     */
-    private groupChapterTimeMapCache;
-    private groupChapterTimeMapCacheScript;
-    /**
-     * D-SEEK-LIVE（方案 A）：连播中「跨章 seek」的重定向令牌。
-     * 播放态跨章 seek 时置位 { index, fromTime } 并 abortCurrentPlay；连播循环 await 返回后据此跳转到目标章节继续播放。
-     */
-    private seekRedirect;
-    /**
-     * 加法式：动画组「章节索引 → 楼层」映射（用于 Mapview 只显示当前章节所在楼层）。
-     * - number：该章节单一楼层 ⇒ `five.model.show(floor)`；
-     * - null：该章节内多段动画跨楼层 ⇒ `five.model.show()`（显示全部，避免藏掉其它层的动画）；
-     * - 映射缺项按显示全部处理。
-     * `null`（整体）表示未启用该能力（不触碰楼层可见性）。由消费方经 `setChapterFloorMap` 注入。
-     */
-    private chapterFloorMap;
-    /**
-     * 楼层可见性作用的目标模型（`show(floorIndex)` 的接收者）。
-     * - `null`：回退到 `five.model`（= `modelScene.models[0]`，单 VR 即唯一模型）。
-     * - 沙盘/联合现场：`five.model` 恒为 models[0]，未必是当前播放的子 VR，故消费方须显式注入
-     *   动画所属子 VR 的模型（`five.models.find(m => m.name === resourceCode)`），否则楼层隔离会落到
-     *   错误模型，被播放子 VR 保持全楼层可见（表现为「跨楼层动画所有楼层同时高亮」）。
-     */
-    private chapterFloorModel;
-    /** five 'modeChange' 楼层重放监听的反订阅句柄（chapterFloorMap 启用时挂载，停用/reset/dispose 时清理） */
-    private unsubFloorModeChange;
-    constructor(five: Five, config?: DigitalPerformanceV2PluginConfig);
-    /** 加载剧本：预加载资源 + 将模型加入 five 场景；autoPlay 时自动播放首章 */
-    loadScript(script: DigitalScript): Promise<void>;
-    /**
-     * 加载 raw animation detail。转换逻辑由 dnalogel 与 Legacy 插件共用，随后复用 canonical loadScript。
-     */
-    loadAnimationDetail(detail: unknown, options?: AnimationScriptAdapterOptions): Promise<any>;
-    /** 播放指定章节 */
-    playChapter(chapter: DigitalChapter): Promise<void>;
-    /** 通过索引播放章节 */
-    playChapterByIndex(index: number): Promise<void>;
-    /** 从当前章节连续播放到最后一章（连播中跨章 seek 可经 seekRedirect 令牌无缝重定向） */
-    playAllRemaining(): Promise<void>;
-    /** 从第一章开始按顺序连续播放（用于"重播全部"，保留已捕获的各章节运镜） */
-    playAllFromStart(): Promise<void>;
-    /** 从指定章节索引开始，按顺序连续播放到本动画组最后一章（保留已捕获的各章节运镜） */
-    playFromChapterIndex(index: number): Promise<void>;
-    /**
-     * 编辑态：仅播放当前章节（不连播下一章）。
-     * 章节自然播放到末尾（ended）后，由 controller 执行「进度归零 + 恢复当前章节默认视角」，
-     * SHALL NOT 自动连播下一章节（区别于展示端 playAllRemaining 的章节连续播放）。
-     * 无当前章节时为 no-op。
-     */
-    playCurrentChapterForEdit(): Promise<void>;
-    /** 暂停 */
-    pause(): void;
-    /**
-     * 续播（当前章节）。
-     * - `continue()` / `continue({ prepare: false })`：同步 plain 续播，直接 resume 时钟，返回 `void`（既有语义不变）。
-     * - `continue({ prepare: true })`：先 `await prepareCameraTo(currentChapterTime)` 平滑 glide-back（不计时）再 resume，
-     *   返回 `Promise<void>`。展示端与编辑端均传 `prepare: true` 以保证续播无跳变（D-RESUME）。
-     */
-    continue(): void;
-    continue(options: {
-        prepare?: false;
-    }): void;
-    continue(options: {
-        prepare: true;
-    }): Promise<void>;
-    /**
-     * 编辑态暂停（playing→paused，相机由「导演」交还「用户」拥有）。
-     * 统一 Mapview 后，导演接管期间 five 始终是合法 Mapview orbit 状态，暂停瞬间画面不变、
-     * 且 five 手势天然为正常模型视角（左键绕 target orbit、右键平移），无需特殊转换。见设计 §5.3.1。
-     * 仅供编辑端（camera-mode）暂停路径调用。
-     */
-    pauseForEdit(): void;
-    /**
-     * 编辑态续播（当前章节）：在恢复时钟前先 `await prepareCameraTo(当前时间)`，
-     * 以内插动画平滑回到暂停瞬间对应的运镜视角（无突变 user→director 切换，Req 13.9 / 18.9），
-     * prepare 不计入播放时间（时钟在 prepare 期间不推进）后再 resume。
-     * 章节无运镜关键帧时 prepare 为 no-op。不改变通用 `continue()`/`pause()` 语义。
-     */
-    continueForEdit(): Promise<void>;
-    /** 运镜开关：关闭后播放仅驱动模型动画，不接管 five 相机（立即生效） */
-    setCameraDirectionEnabled(enabled: boolean): void;
-    /**
-     * 人物运动轨迹线开关（默认关闭、不显示）。仅 debug / 特殊需求由业务显式开启。
-     * 立即作用于当前所有 DigitalHuman，并记忆给后续加载的模型。
-     */
-    setTraceVisible(visible: boolean): void;
-    /**
-     * 加法式：设置「章节索引 → 楼层」映射，启用「播放/切章时 Mapview 只显示当前章节所在楼层」。
-     * - number：该章节单一楼层；null：该章节内跨楼层 → 显示全部；映射缺项按显示全部处理。
-     * - 传入非 null：立即对当前章节应用一次；此后在任意章节切换（连播推进 / 切章 / 播放预览切章）时自动应用。
-     * - 传入 null：停用该能力（不再随章节应用），但**不主动恢复**楼层可见性（恢复由 `reset()` 负责）。
-     * 楼层可见性是 five 空间模型的显隐（`five.model.show`），与运镜相机接管相互独立。
-     * 各消费方（workshop 编辑端 / NextVR 展示端）自行从各自数据算好映射注入，保证两端行为一致（parity）。
-     *
-     * @param model 楼层可见性作用的目标模型（缺省/undefined/null 回退到 `five.model`）。
-     *   单 VR 场景无需传（`five.model` 即唯一模型）；沙盘/联合现场须传动画所属子 VR 的模型
-     *   （`five.models.find(m => m.name === resourceCode)`），否则楼层隔离会落到 models[0] 而非播放中的子 VR，
-     *   导致跨楼层动画所有楼层同时高亮。传入 null 时清空目标模型回退到 `five.model`。
-     */
-    setChapterFloorMap(map: Record<number, number | null> | null, model?: {
-        show?: (floorIndex?: number) => void;
-    } | null): void;
-    /** 监听 five 'modeChange'：模态切换后（延后一帧）重放当前章节楼层，避免被外部 UI 覆盖（只挂一次） */
-    private hookFloorModeChange;
-    /** 取消 'modeChange' 楼层重放监听 */
-    private unhookFloorModeChange;
-    /** 按章节楼层映射对指定章节应用楼层可见性（映射未启用时 no-op） */
-    private applyChapterFloor;
-    /**
-     * 显示指定楼层（传 undefined 显示全部）。安全访问 model.show，避免类型/运行时缺失。
-     * 目标模型优先用消费方注入的 `chapterFloorModel`（沙盘下为播放中的子 VR），缺省回退 `five.model`。
-     */
-    private showModelFloor;
-    /**
-     * seek 预览：跳转到指定时间并渲染当前帧（不改变播放/暂停状态）。
-     * - 无当前章节：不改时钟、不渲染，返回失败指示且不抛异常。
-     * - 运镜启用：经 director seek 应用相机；运镜禁用：仅驱动 DigitalHuman。
-     */
-    setTimelineTo(time: number): SetTimelineResult;
-    /**
-     * 在指定时间捕获当前 five 相机为一个运镜关键帧。
-     * - 位姿取自 five 当前 Mapview 状态（target=offset、longitude、latitude、distance）；fov 取自 fiveState（缺省读 five.getCurrentState()）。
-     * - 按 timeStamp 升序插入；同 timeStamp 覆盖。
-     * 拒绝（保持序列不变并返回 error）：未加载 script / 无当前章节 / time 非负有限数校验失败。
-     */
-    addCameraKeyframe(time: number, fiveState?: {
-        fov?: number;
-    }, options?: CameraKeyframeOptions): CameraKeyframeResult;
-    /**
-     * 更新指定下标关键帧：合并 patch 中出现的字段，按 timeStamp 重排序。
-     * 拒绝（保持序列不变）：未加载 script / 无章节 / index 越界 / patch.timeStamp 非负有限数校验失败。
-     */
-    updateCameraKeyframe(index: number, patch: Partial<DigitalCameraKeyframe>): CameraKeyframeResult;
-    /** 移除指定下标关键帧。拒绝（保持序列不变）：未加载 script / 无章节 / index 越界。 */
-    removeCameraKeyframe(index: number): CameraKeyframeResult;
-    /** 获取当前章节的运镜关键帧（升序副本；无章节/无 camera player 时返回空数组） */
-    getCameraKeyframes(): DigitalCameraKeyframe[];
-    /**
-     * 序列化当前章节的运镜 player。
-     * keyframes 按 timeStamp 升序，仅写入已设置的可选字段（不写 undefined 占位）。
-     * 空/无 camera player 返回 keyframes:[]；未加载 script / 无章节 时拒绝并返回 error。
-     */
-    serializeCameraPlayer(): SerializeCameraResult;
-    /**
-     * 序列化全部章节中"含非空关键帧"的运镜 player，按章节索引返回。
-     * 供编辑端按"章节起始动画 id"聚合后整组保存。未加载 script 时返回空数组。
-     */
-    serializeAllCameraPlayers(): Array<{
-        chapterIndex: number;
-        player: DigitalCameraPlayer;
-    }>;
-    /**
-     * 按章节索引批量加载运镜（用于从持久化数据还原）：替换对应章节 camera player 的关键帧。
-     * 调用方负责"对账"（只传锚点命中的章节），越界索引忽略。
-     */
-    loadCameraPlayersByChapterIndex(byChapterIndex: Record<number, {
-        keyframes: DigitalCameraKeyframe[];
-        coordinateSpace?: CameraCoordinateSpace;
-        name?: string;
-    }>): void;
-    /** 注册关键帧序列变更监听（camera-keyframes-changed）；返回反订阅函数 */
-    onCameraKeyframesChanged(listener: CameraKeyframesChangedListener): () => void;
-    /**
-     * 章节默认视角（Chapter_Default_View）。始终为 **Mapview orbit** 视角（与运镜编辑「仅 Mapview」一致）。
-     * - 章节存在 ≥1 个运镜关键帧：返回该章节相机轨道 `sample(0)`（因首帧夹紧，等于首帧 CameraState）。
-     * - 章节存在 0 个运镜关键帧：几何派生一个「frame 该章节模型 t=0」的 Mapview orbit
-     *   （target=模型世界包围盒中心，distance 由包围盒尺寸派生，orbit 朝向沿用 five 当前角度以避免跳变）。
-     *   无可用模型几何时返回 `undefined`（调用方 no-op、保持当前视角）。
-     * 默认视角不单独持久化，完全派生（关键帧 / 模型几何），不在 cameraPlayers 新增字段。
-     */
-    getChapterDefaultView(chapterIndex: number): CameraState | undefined;
-    /**
-     * 应用章节默认视角到 five。
-     * - 章节存在关键帧：经 FiveModelCameraBridge 立即应用 `sample(0)`。
-     * - 章节 0 关键帧：应用几何派生的 Mapview orbit（frame 本章节模型）；无可用几何时 no-op。
-     */
-    applyChapterDefaultView(chapterIndex: number): void;
-    /**
-     * 无运镜章节的默认视角：几何派生一个「frame 该章节模型 t=0」的 Mapview orbit CameraState。
-     * - target = 章节内所有 model player 容器的世界包围盒中心（需先 prepareChapter 将模型渲染到 t=0）。
-     * - distance = 包围盒对角线 × 系数，钳制到 [MIN, MAX]（保证不过近/过远）。
-     * - orbit 朝向（longitude/latitude/fov）沿用 five 当前状态，避免切章时视角朝向突跳；缺省用兜底值。
-     * 无任何可用模型几何（未加载/无 model player/包围盒空）时返回 undefined。
-     */
-    private deriveChapterModelFramingView;
-    /**
-     * 设为当前编辑章节（不开始播放）。该次调用内联动完成：
-     * 切暂停 → `seek(0)`（进度归零、各 DigitalHuman 渲染 t=0）→ 重建 director 轨道到该章节关键帧 →
-     * 应用该章节默认视角 → 读取并更新该章节总时长 → 清除已选中运镜项 → 派发 onCurrentChapterChanged。
-     * 越界索引为 no-op。
-     */
-    setCurrentChapter(chapterIndex: number): void;
-    /** 当前章节信息：{ index, name, duration }；duration 为该章节模型动画时长（排除相机 player） */
-    getCurrentChapterInfo(): CurrentChapterInfo;
-    /** 注册当前章节变更监听（current-chapter-changed）；返回反订阅函数 */
-    onCurrentChapterChanged(listener: CurrentChapterChangedListener): () => void;
-    /**
-     * 进入运镜编辑：对全部章节运镜内存态打一次深快照（供 discardCameraChanges 还原）。
-     * 仅记录内存快照，不触碰持久化、不改相机/播放状态。
-     */
-    beginCameraEditSession(): void;
-    /**
-     * 放弃运镜修改：将运镜内存态还原到 `beginCameraEditSession` 时的快照（不走服务端重载）。
-     * 未打过快照时为 no-op。还原后重建当前章节 director 轨道并派发关键帧变更事件。
-     */
-    discardCameraChanges(): void;
-    /** 当前进度（当前章节内 currentTime/totalTime，单位 ms；含当前章节索引/总章节数） */
-    getProgress(): V2Progress;
-    /** 注册进度监听；返回反订阅函数 */
-    onProgressChanged(listener: V2ProgressListener): () => void;
-    /**
-     * 组级章节时间映射（加法式）：每章 { index, name, startTime, endTime, duration } 逐章累计。
-     * - duration[i] = getChapterModelDuration(chapters[i])（排除 camera player）
-     * - startTime[0]=0、startTime[i]=endTime[i-1]、endTime[i]=startTime[i]+duration[i]
-     * - 未加载 / 空章节组返回 []；纯读，不修改任何引擎状态。
-     * 按 currentScript 引用缓存；loadScript / script 变更时失效重算。
-     */
-    getGroupChapterTimeMap(): GroupChapterTimeInfo[];
-    /**
-     * 组级进度聚合（加法式）：由章节级 getProgress() + getGroupChapterTimeMap() 派生。
-     * - groupTotalTime = Σ duration
-     * - groupCurrentTime = startTime[currentChapterIndex] + clamp(currentTime, 0, duration[idx])（无当前章节为 0）
-     * - 0 ≤ groupCurrentTime ≤ groupTotalTime；percentage ∈ [0,100]（groupTotalTime=0 时为 0）
-     * 纯读，不修改任何引擎状态。
-     */
-    getGroupProgress(): GroupProgress;
-    /**
-     * 注册组级进度监听（加法式，独立监听集合）；返回反订阅函数。
-     * 在既有 emitProgress() 内追加组级广播，每 tick / 章节切换 / pause / seek 时随章节级广播一并触发。
-     */
-    onGroupProgressChanged(listener: GroupProgressListener): () => void;
-    /**
-     * 播放/预览专用：设为当前章节（不开始播放，区别于编辑端 setCurrentChapter）。
-     * 透传 playground.prepareChapter：切模型可见性 + 重绑相机轨道 + 配置时钟时长并 seek 到 fromTime（不 start）。
-     * 不做编辑端默认视角设置 / 选中清理等联动。越界索引为 no-op。
-     */
-    setCurrentChapterForPlayback(index: number, fromTime: number): void;
-    /**
-     * 跳转到组级时间(ms)：映射为 (章节 index, 章节内时间)，必要时切章后 setTimelineTo。
-     * 保留 seek 前的播放/暂停状态（D-SEEK-LIVE，方案 A）：
-     * - 暂停态：跨章则先 setCurrentChapterForPlayback 切章，再 setTimelineTo 预览该帧后交还用户。
-     * - 播放态同章：clock.seek 续播（经 setTimelineTo）。
-     * - 播放态跨章：置 seekRedirect 并 abortCurrentPlay，由连播循环跳到目标章节从 localTime 继续。
-     * 越界钳制到 [0, groupTotalTime]；未加载 script 返回 { success:false } 不抛异常。
-     */
-    seekToGroupTime(groupTimeMs: number): SetTimelineResult;
-    /** 跳转到组级百分比 [0,100]（= seekToGroupTime(clamp(pct,0,100)/100 * groupTotalTime)） */
-    seekToGroupPercentage(percentage: number): SetTimelineResult;
-    /**
-     * 组级时间 → (章节索引, 章节内时间)（加法式内部）。
-     * - g ≤ 0          → { index: 0, localTime: 0 }
-     * - g ≥ groupTotal → { index: last, localTime: duration[last] }
-     * - 否则 startTime[index] ≤ g < endTime[index] 且 localTime = g - startTime[index]
-     * - 零时长章节（start==end）被自动跳过（不会定位其内部）
-     * 前置条件：timeMap 非空。
-     */
-    private mapGroupTimeToChapter;
-    /** 数值钳制工具 */
-    private clamp;
-    /** 当前可用章节 */
-    getChapters(): DigitalChapter[];
-    /** 当前状态快照 */
-    getState(): {
-        playing: boolean;
-        currentChapter: DigitalChapter | null;
-    };
-    /** 实时修改角色名牌；只更新文本和当前剧本，不重新加载模型/动画。 */
-    updateModelName(id: string, value: string): void;
-    private syncNameplates;
-    /** 重置播放（保留已加载资源） */
-    reset(): void;
-    /** 销毁插件、释放资源 */
-    dispose(): void;
-    /** 预加载模型 / 动画 / 道具（复用 Shared_Core 加载） */
-    private preloadResources;
-    private emitProgress;
-    /** 组级进度广播（加法式新增；独立监听集合，既有 onProgressChanged 语义不变） */
-    private emitGroupProgress;
-    /** 编辑前置校验：未加载 script / 无当前章节时返回拒绝结果，否则返回 null */
-    private guardKeyframeEdit;
-    /** 拒绝结果：保持当前序列不变并返回 error */
-    private rejectKeyframe;
-    /** 当前章节的 camera player（不存在返回 null） */
-    private getCameraPlayer;
-    /** 指定章节的 camera player（不存在返回 null） */
-    private cameraPlayerOf;
-    /** 把 camera player 的关键帧序列化为升序、仅含已设置可选字段的副本（Mapview 位姿） */
-    private serializeKeyframes;
-    /** 获取当前章节的 camera player，不存在则创建并挂到章节 players 上 */
-    private ensureCameraPlayer;
-    /** fov 取值：优先 fiveState.fov，否则读 five 当前状态 */
-    private resolveFov;
-    /** 捕获 five 当前 Mapview 位姿（target=offset、longitude、latitude、distance） */
-    private captureCameraPose;
-    /** 关键帧变更后：重建并绑定相机轨道（供 seek 预览/后续播放接管），派发事件，返回成功结果 */
-    private afterKeyframesChanged;
-    private emitKeyframesChanged;
-    private emitCurrentChapterChanged;
-    /** 当前章节索引（0-based；无当前章节为 -1），按引用或名称匹配 */
-    private getCurrentChapterIndex;
-    /** 由指定章节的相机关键帧构建一条 CameraTrack（无章节/无 camera player 返回 null） */
-    private buildChapterCameraTrack;
-    /** 深拷贝关键帧序列（数组字段亦深拷贝），供快照/还原使用（Mapview 位姿） */
-    private cloneKeyframes;
-}

package/dist/DigitalPerformanceV2Plugin/core/CameraDirector.d.ts

@@ -1,61 +0,0 @@
-import type { Five } from '@realsee/five';
-import type { CameraTrack } from './CameraTrack';
-import type { PerformanceClock } from './PerformanceClock';
-import type { CameraState } from '../typings';
-/**
- * CameraDirector —— 运镜导演（统一 Mapview / orbit 参数系）
- *
- * 绑定一条 CameraTrack，订阅统一时钟 tick，采样 CameraState 经 FiveModelCameraBridge 应用到相机。
- * - 逐帧/seek 均以 immediately=true 贴合采样状态（不依赖 five 内插，跟随精确）。
- * - setEnabled(false)：后续播放 tick 不接管相机、保留 five 当前状态。
- * - 空轨道/无关键帧：不接管相机。
- *
- * 由于运镜统一为 Mapview orbit 位姿，导演接管期间 five 始终是合法 Mapview 状态；
- * 暂停只需停止 tick 即把相机「交还用户」——无需任何 look-from→orbit 转换（旧 applyAsOrbit / releaseToUser 已移除）。
- */
-export declare class CameraDirector {
-    private bridge;
-    private track;
-    private clock;
-    private enabled;
-    private unsubTick;
-    constructor(five: Five);
-    /** 绑定/替换轨道（传 null 解绑） */
-    bindTrack(track: CameraTrack | null): void;
-    /** 跟随时钟播放：订阅 onTick → 采样 → 应用（仅在时钟实际播放时接管，编辑期 seek 不接管） */
-    attach(clock: PerformanceClock): void;
-    /** 解除时钟订阅（不清空 track） */
-    detach(): void;
-    /** 编辑端 seek 预览：立即采样并应用到指定时间（不依赖播放状态） */
-    seek(time: number): void;
-    /**
-     * 直接将一个 CameraState 立即应用到 five（immediately=true），不经轨道/时钟。
-     * 供「章节默认视角」等编辑端能力使用。复用既有桥实例。
-     * 不受 enabled 开关与轨道是否有内容影响（调用方自行决定是否调用）。
-     * 应用后 five 即为合法 Mapview 状态，用户可立即正常拖拽（左键 orbit / 右键平移）。
-     */
-    applyCameraStateImmediately(state: CameraState): void;
-    /**
-     * 暂停态 scrub 预览：采样 `track.sample(time)` 并立即应用（预览后交还用户可立即拖拽）。
-     * 仅在 enabled 且 track 有内容时应用；否则 no-op（与 seek 预览的接管前置条件一致）。
-     */
-    previewAt(time: number): void;
-    /**
-     * 运镜开关。仅记录状态，不在此处写 five。
-     * - false：后续播放 tick 不接管相机。
-     * - true：后续播放 tick 按采样接管相机。
-     */
-    setEnabled(enabled: boolean): void;
-    isEnabled(): boolean;
-    /**
-     * 接管前 prepare（无突变 user→director 切换）。
-     * - enabled 且 track 有内容时：经 `bridge.applyAnimated(track.sample(time))` 以内插动画平滑回到目标视角，
-     *   await 过渡稳定后 resolve。暂停后用户拖动过的当前位姿与目标均为 Mapview 状态，动画为 orbit→orbit，干净不摆动。
-     * - 否则：立即 resolve（no-op）。
-     * 不触碰时钟、不改 enabled、不绑定/解绑轨道；调用方负责在时钟 start/resume 前 await，以保证 prepare 不计入播放时间。
-     */
-    prepareTo(time: number): Promise<void>;
-    /** 释放：解订阅并清空轨道 */
-    dispose(): void;
-    private applyAt;
-}

package/dist/DigitalPerformanceV2Plugin/core/CameraSampler.d.ts

@@ -1,53 +0,0 @@
-import * as THREE from 'three';
-import type { CameraTransition, DigitalCameraKeyframe, CameraState } from '../typings';
-/**
- * CameraSampler —— 带插值的运镜采样（共享底座），统一在 five **Mapview**（orbit）参数系下补帧。
- *
- * 关键帧以 orbit 位姿表达：{ target, longitude, latitude, distance, fov }。
- * 相邻帧的区间缓动由「较早」关键帧 kf[i] 的 transition 决定（与 Requirement 2.1 一致）。
- * - target：分量线性插值（Vector3 lerp）
- * - longitude：最短弧角度插值（处理 ±π 环绕）
- * - latitude / distance / fov：线性插值
- * 末帧封顶、首帧夹紧；'instant' 直接 snap 到当前帧；不修改入参。
- *
- * 相对旧的「position+forward / look-from」表示：orbit 参数系下相邻帧的插值是「绕目标点的圆弧运动」，
- * 与用户在 Mapview 编辑时所见一致（绕主体环绕），而非两点间直线 dolly。
- */
-/** 把数值夹紧到 [min, max] */
-export declare function clamp(value: number, min: number, max: number): number;
-/**
- * 二分查找：返回 timeStamp <= time 的最大关键帧下标。
- * 前置：keyframes 非空且按 timeStamp 升序。后置：0 <= 返回 <= length-1；早于首帧返回 0。
- */
-export declare function getKeyframeIndexByTime(time: number, keyframes: ReadonlyArray<{
-    timeStamp: number;
-}>): number;
-/**
- * 缓动函数：把线性进度 p∈[0,1] 映射为缓动后的插值因子。
- * - 'easeInOut' : smoothstep p*p*(3-2p)
- * - 其它（含 'linear' / undefined） : 恒等
- * 端点固定：ease(0)=0、ease(1)=1；值域有界：p∈[0,1] ⇒ 返回 ∈[0,1]。
- */
-export declare function ease(p: number, transition?: CameraTransition): number;
-/**
- * 归一化时间比例：p = clamp((time - curTs) / (nextTs - curTs), 0, 1)。
- * nextTs <= curTs（异常或零长区间）时返回 0，避免除零。
- */
-export declare function normalizedRatio(time: number, curTs: number, nextTs: number): number;
-/** 最短弧角度插值：沿 (-π,π] 的最短方向从 a 插到 b。 */
-export declare function lerpAngle(a: number, b: number, t: number): number;
-/** 采样 orbit 目标点（分量线性插值）。末帧封顶、'instant' 取当前帧。 */
-export declare function sampleTarget(time: number, keyframes: ReadonlyArray<DigitalCameraKeyframe>): THREE.Vector3;
-/** 采样 longitude（最短弧角度插值）。 */
-export declare function sampleLongitude(time: number, keyframes: ReadonlyArray<DigitalCameraKeyframe>): number;
-/** 采样 latitude（线性插值）。 */
-export declare function sampleLatitude(time: number, keyframes: ReadonlyArray<DigitalCameraKeyframe>): number;
-/** 采样 distance（线性插值）。 */
-export declare function sampleDistance(time: number, keyframes: ReadonlyArray<DigitalCameraKeyframe>): number;
-/** 采样 fov（线性插值）；末帧封顶、'instant' 取当前帧。 */
-export declare function sampleFov(time: number, keyframes: ReadonlyArray<DigitalCameraKeyframe>): number;
-/**
- * 组装：按时间采样出统一 CameraState（已插值，Mapview orbit 位姿）。
- * 单关键帧时对任意时间返回该唯一帧位姿。不修改入参。
- */
-export declare function sampleCameraState(time: number, keyframes: ReadonlyArray<DigitalCameraKeyframe>): CameraState;

package/dist/DigitalPerformanceV2Plugin/core/CameraTrack.d.ts

@@ -1,21 +0,0 @@
-import type { CameraState, DigitalCameraKeyframe } from '../typings';
-/**
- * CameraTrack —— 相机轨道
- *
- * 把运镜关键帧序列封装为可按时间采样（含插值）的轨道，委托 CameraSampler 完成补帧。
- * 关键帧统一为 Mapview orbit 位姿 { target, longitude, latitude, distance, fov }。
- */
-export declare class CameraTrack {
-    private keyframes;
-    /** 设置/替换关键帧序列（按 timeStamp 升序，不修改入参数组） */
-    setKeyframes(keyframes: ReadonlyArray<DigitalCameraKeyframe>): void;
-    /** 按时间采样出统一 CameraState（已插值） */
-    sample(time: number): CameraState;
-    /** 本轨道有效时间范围（首帧~末帧 timeStamp） */
-    getTimeRange(): {
-        start: number;
-        end: number;
-    };
-    /** 是否有可用关键帧 */
-    hasContent(): boolean;
-}

package/dist/DigitalPerformanceV2Plugin/core/FiveModelCameraBridge.d.ts

@@ -1,39 +0,0 @@
-import type { Five } from '@realsee/five';
-import type { CameraState } from '../typings';
-/**
- * FiveModelCameraBridge —— CameraState ↔ five **Mapview**（地图态 / orbit）参数的唯一收敛点。
- *
- * 统一运镜采用 Mapview orbit 位姿：相机绕 `target` 旋转，
- *   相机位置 = target − coordinatesToVector(longitude, latitude) × distance，视线恒指向 `target`。
- * 因此「播放逐帧接管」与「暂停交还用户拖拽」处于同一参数系：
- * 暂停瞬间 five 已是合法 Mapview 状态（offset=target、distance>0），用户可直接左键 orbit / 右键平移，
- * 无需任何 look-from→orbit 转换、无跳变。
- *
- * apply：target→offset、longitude/latitude/distance 直传、fov 钳制、mode='Mapview'。
- * capture：从 five 当前 Mapview 位姿反读一个 CameraState。
- *
- * 注：类名沿用历史 `FiveModelCameraBridge`（避免大范围改名）；实际目标模态为 Mapview。
- */
-export declare class FiveModelCameraBridge {
-    private five;
-    constructor(five: Five);
-    /**
-     * 将 CameraState 应用到 five（mode:'Mapview'）。对 `five.setState` 恰好一次。
-     * - fov 钳制到开区间 (0,180)（含 fov<=0 与 NaN），不拒绝、不抛错。
-     * @param immediately five.setState 第二参数。true（缺省）= 立即贴合目标（逐帧驱动/seek 用）；false = 走 five 内插动画。
-     */
-    apply(state: CameraState, immediately?: boolean): void;
-    /**
-     * 加法式：以「走 five 内插动画」的方式应用 CameraState（`apply` 的 immediately=false 分支），
-     * 返回一个在过渡完成后 resolve 的 Promise。
-     * - 映射规则与 `apply` 完全一致，对 `five.setState` 恰好一次，仅第二参数取 false（动画）。
-     * - 完成信号：`five.setState` 返回 void、无可等待对象，故以一次过渡时长（CAMERA_TRANSITION_MS）兜底后 resolve。
-     */
-    applyAnimated(state: CameraState): Promise<void>;
-    /**
-     * 从 five 当前 Mapview 位姿反读一个 CameraState。
-     * five.getCurrentState() 返回 { offset, longitude, latitude, distance, fov }（来自相机 pose），
-     * 其中 offset 即 orbit 目标点（target）。
-     */
-    capture(): CameraState;
-}

package/dist/DigitalPerformanceV2Plugin/core/PerformanceClock.d.ts

@@ -1,55 +0,0 @@
-import type { Five } from '@realsee/five';
-export type ClockTickListener = (time: number, delta: number) => void;
-export type ClockEndedListener = () => void;
-/**
- * PerformanceClock —— 统一章节时钟（共享底座）
- *
- * 以 five 的 'renderFrame' 为唯一节拍源，维护章节内全局播放时间 t 并广播 tick。
- * 取代各 DigitalHuman 内部独立的 requestAnimationFrame 与 Math.max 进度反推。
- *
- * 不变量：0 <= time <= duration；playing 期间相邻 tick 的 time 非递减（封顶 duration）。
- */
-export declare class PerformanceClock {
-    private five;
-    private duration;
-    private time;
-    private playing;
-    private lastFrameTs;
-    private tickListeners;
-    private endedListeners;
-    constructor(five: Five);
-    /**
-     * 启动时钟。
-     * - duration<=0：不订阅 renderFrame、time 置 0、立即触发一次 ended。
-     * - 否则：time = clamp(fromTime, 0, duration)，订阅 renderFrame 作为唯一节拍源。
-     */
-    start(duration: number, fromTime?: number): void;
-    /**
-     * 配置时长但不启动、不订阅 renderFrame（供播放/预览专用切章 prepareChapter 使用）。
-     * 加法式新增：仅设置 duration 并把当前 time 夹紧到新 duration，不改变 playing 状态。
-     */
-    setDuration(duration: number): void;
-    /** 暂停：停止累加并保留当前 time */
-    pause(): void;
-    /** 续播：从保留的 time 继续；续播后首帧 delta 记 0，不产生跳变 */
-    resume(): void;
-    /** 跳转（seek 预览）：不改变播放状态；重置帧基准并广播一次 tick(0) */
-    seek(targetTime: number): void;
-    /** 停止：停表、解订阅、time 归零，可被再次 start */
-    stop(): void;
-    getTime(): number;
-    getDuration(): number;
-    isPlaying(): boolean;
-    /** 注册每帧 tick 监听；返回反订阅函数 */
-    onTick(listener: ClockTickListener): () => void;
-    /** 注册自然结束监听；返回反订阅函数 */
-    onEnded(listener: ClockEndedListener): () => void;
-    /** 释放：解订阅并清空监听 */
-    dispose(): void;
-    private clampTime;
-    private subscribeFrame;
-    private unsubscribeFrame;
-    private onFrame;
-    private emitTick;
-    private emitEnded;
-}