@realsee/dnalogel 3.81.13 → 4.0.0-webgpu.4

package/dist/types/DigitalPerformancePlugin/core/DigitalPerformanceNameplate.d.ts

@@ -0,0 +1,115 @@
+import { Five } from '@realsee/five-webgpu';
+import { DigitalModelPlayer } from './DigitalStateMachine.js';
+import * as THREE from 'three/webgpu';
+export declare const DEFAULT_DIGITAL_PERFORMANCE_NAME_MAX_LENGTH = 30;
+/** 规范化名牌文本，使用 Unicode code point 计数，避免 emoji 被截成半个字符。 */
+export declare function normalizeDigitalPerformanceName(value: unknown, maxLength?: number): string;
+export interface DigitalPerformanceNameplateBinding {
+    id: string;
+    player: DigitalModelPlayer;
+    /** 用于计算包围盒和世界坐标的数字人模型根节点。 */
+    model: THREE.Object3D;
+}
+export interface DigitalPerformanceNameplateRenderContext {
+    id: string;
+    text: string;
+    player: DigitalModelPlayer;
+    model: THREE.Object3D;
+}
+export interface DigitalPerformanceNameplateOptions {
+    /** 名牌最多展示的 Unicode 字符数，默认 30。 */
+    maxLength?: number;
+    /** 相对模型包围盒顶部的世界坐标偏移，默认 [0, 0.12, 0]。 */
+    offset?: [number, number, number];
+    /** 自定义名牌文本，默认使用 displayName ?? name。 */
+    getText?: (player: DigitalModelPlayer) => string | undefined | null;
+    /** 自定义名牌元素；不传时创建默认气泡 div。 */
+    createElement?: (context: DigitalPerformanceNameplateRenderContext) => HTMLElement;
+    /** 自定义名牌更新逻辑；不传时将 textContent 更新为当前文本。 */
+    updateElement?: (element: HTMLElement, context: DigitalPerformanceNameplateRenderContext) => void;
+    /** 名牌元素 class。 */
+    className?: string;
+    /** 名牌元素的额外内联样式。 */
+    style?: Record<string, string>;
+    /** overlay 容器 class。 */
+    containerClassName?: string;
+    /** overlay 容器的额外内联样式。 */
+    containerStyle?: Record<string, string>;
+    /**
+     * 调试：是否显示每个绑定模型的世界包围盒（THREE.BoxHelper），用于核对名牌锚点。
+     * 默认 false，不影响名牌本身。
+     */
+    debugBoundingBox?: boolean;
+}
+/**
+ * DigitalPerformance 的 2D 名牌层。
+ *
+ * 它只负责「模型世界坐标 → 播放器 overlay DOM」和名牌生命周期，
+ * 由 Legacy/V2 controller 在各自的模型帧更新完成后调用 update()，因此两个播放器共用同一套 DOM 规则。
+ */
+export declare class DigitalPerformanceNameplate {
+    private readonly five;
+    private options;
+    private parent;
+    private container;
+    private bindings;
+    private nameOverrides;
+    private enabled;
+    /** 是否由本层自动挂载到 five canvas 父容器（插件内置模式），无需调用方提供容器。 */
+    private autoMount;
+    private readonly onResize;
+    private readonly anchor;
+    private readonly box;
+    private readonly offset;
+    private readonly debugBoxes;
+    private debugBoxesVisible;
+    constructor(five: Five, options?: DigitalPerformanceNameplateOptions);
+    /** 将 overlay 挂到 Five canvas 的父级或业务提供的全屏相对定位容器。 */
+    mount(parent: HTMLElement, options?: DigitalPerformanceNameplateOptions): void;
+    /**
+     * 内置自动挂载：把 overlay 挂到 five canvas 的父容器（与 canvas 同级），调用方无需提供容器。
+     * canvas 尚未进入 DOM 时不报错，会在后续 update() 中自动重试挂载。
+     */
+    enableAutoMount(options?: DigitalPerformanceNameplateOptions): void;
+    /** 移除 overlay，但保留 bindings；重新挂载（含换容器）时会复用 bindings。 */
+    unmount(): void;
+    /** 更新当前章节的角色绑定；id 是角色唯一键，同一模型复用时也不会互相覆盖。 */
+    setBindings(bindings: DigitalPerformanceNameplateBinding[]): void;
+    /** 实时更新指定角色名称，不需要重新加载模型或动画资源。 */
+    updateName(id: string, value: string): void;
+    setEnabled(enabled: boolean): void;
+    /**
+     * 调试：显示/隐藏每个绑定模型的世界包围盒（THREE.BoxHelper）。
+     * 包围盒与名牌锚点使用的是同一个 Box3（setFromObject(model)），用于核对名牌定位。
+     * 默认关闭；不影响名牌本身。
+     */
+    setBoundingBoxVisible(visible: boolean): void;
+    /** 应用 `options.debugBoundingBox`；未配置时保持现状（不覆盖运行时的 setBoundingBoxVisible）。 */
+    private applyDebugBoundingBoxOption;
+    isEnabled(): boolean;
+    /** 在数字人模型变换完成后调用，更新所有当前章节名牌的位置和可见性。 */
+    update(): void;
+    dispose(): void;
+    /** 内置自动挂载的实际执行：解析 five canvas 的父容器并 mount；条件不满足时静默跳过。 */
+    private tryAutoMount;
+    private getMaxLength;
+    private getText;
+    private ensureElement;
+    private applyElementContent;
+    private hideElement;
+    private applyContainerStyle;
+    private applyElementStyle;
+    /**
+     * 注入名牌气泡箭头的伪元素样式。
+     * 该样式是模块级全局资源（选择器为 .digital-performance-nameplate::after），
+     * 因此只在 mount 时按 id 幂等注入一次，而不是在每个名牌元素创建时重复注入。
+     * 当调用方完全自定义了 className 时，箭头选择器不会命中，也就无需注入。
+     */
+    private injectArrowStyle;
+    private isObjectVisible;
+    /** 同步单个绑定的调试包围盒；未开启时 no-op。 */
+    private syncDebugBox;
+    private removeDebugBox;
+    private clearDebugBoxes;
+    private getScreenPosition;
+}

package/dist/types/DigitalPerformancePlugin/core/DigitalPlayground.d.ts

@@ -0,0 +1,52 @@
+import { DigitalHuman } from './DigitalHuman.js';
+import { DigitalScript, DigitalChapter } from './DigitalStateMachine.js';
+import * as THREE from 'three/webgpu';
+export declare class DigitalPlayground {
+    script: DigitalScript | null;
+    currentChapter: DigitalChapter | null;
+    private digitalHumanMap;
+    private digitalItemMap;
+    private skeletalAnimationMap;
+    private generation;
+    private modelLoads;
+    private animationLoads;
+    private itemLoads;
+    private disposed;
+    /** 运动轨迹线开关（默认关闭）。应用到已加载及后续加载的所有 DigitalHuman。 */
+    private showTrace;
+    constructor(debugMode?: boolean);
+    setScript(script: DigitalScript): void;
+    loadModel(url: string, id?: string): Promise<DigitalHuman>;
+    loadModels(urls: string[], ids?: string[]): Promise<DigitalHuman[]>;
+    /** Use the first clip in each animation asset; reject assets without animation. */
+    loadAnimation(url: string): Promise<THREE.AnimationClip>;
+    loadAnimations(urls: string[]): Promise<THREE.AnimationClip[]>;
+    getAnimation(url: string): THREE.AnimationClip | null;
+    getDigitalHuman(url: string, id?: string): DigitalHuman | null;
+    playByChapter(chapter: DigitalChapter): Promise<any[]>;
+    loadItems(urls: string[], offsets?: Map<string, {
+        position: number[];
+        rotation: number[];
+    }>): Promise<any[]>;
+    loadItem(url: string, offset?: {
+        position: number[];
+        rotation: number[];
+    }): Promise<THREE.Object3D>;
+    getDigitalItem(url: string): any | null;
+    pause(): void;
+    continue(): void;
+    reset(): void;
+    setTimelineTo(time: number): void;
+    /**
+     * 运动轨迹线开关（默认关闭）。作用于当前所有 DigitalHuman，并记忆给后续加载的模型。
+     * 仅 debug / 特殊需求由业务经插件显式开启。
+     */
+    setTraceVisible(visible: boolean): void;
+    /**
+     * 销毁 playground
+     */
+    dispose(): void;
+    private clearResources;
+    private ensureCurrent;
+    private loadGLTF;
+}

package/dist/types/DigitalPerformancePlugin/core/DigitalStateMachine.d.ts

@@ -0,0 +1,152 @@
+import * as THREE from 'three/webgpu';
+interface DigitalScript {
+    name: string;
+    uuid: string;
+    assets: {
+        models: string[];
+        animations: string[];
+    };
+    chapters: DigitalChapter[];
+}
+interface DigitalDataPlayer {
+    name: string;
+    type: 'data';
+    data: DigitalModelKeyframe[];
+}
+interface DigitalModelPlayerItem {
+    name: string;
+    initialMatrix: number[];
+    attachedBone: string;
+    model: string;
+    keyframes: DigitalItemKeyframe[];
+}
+interface DigitalEffectKeyframe {
+    timeStamp: number;
+    image: string;
+    visible: boolean;
+}
+interface DigitalModelPlayerEffect {
+    type: 'frameSequence';
+    position: number[];
+    keyframes: DigitalEffectKeyframe[];
+}
+interface DigitalModelPlayer {
+    id: string;
+    /** 兼容已有 name；业务需要独立展示字段时优先使用 displayName。 */
+    name: string;
+    displayName?: string;
+    type: 'model';
+    model: string;
+    keyframes: DigitalModelKeyframe[];
+    items: DigitalModelPlayerItem[];
+    effects: DigitalModelPlayerEffect[];
+}
+interface DigitalSubTitlePlayer {
+    name: string;
+    type: 'subTitle';
+    keyframes: DigitalSubTitleKeyframe[];
+}
+interface DigitalCameraPlayer {
+    name: string;
+    type: 'camera';
+    keyframes: DigitalCameraKeyframe[];
+}
+interface DigitalChapter {
+    name: string;
+    players: Array<DigitalModelPlayer | DigitalSubTitlePlayer | DigitalCameraPlayer>;
+}
+interface DigitalItemKeyframe {
+    timeStamp: number;
+    visible: boolean;
+}
+interface DigitalCameraKeyframe {
+    timeStamp: number;
+    matrix: number[];
+    fov: number;
+}
+interface DigitalSubTitleKeyframe {
+    visible: boolean;
+    timeStamp: number;
+    title: string;
+    content: string;
+    audio?: string;
+    image?: string;
+}
+interface DigitalModelKeyframe {
+    visible: boolean;
+    timeStamp: number;
+    animation?: {
+        url: string;
+        repeat: boolean;
+        isOver?: boolean;
+        switchDuration?: number;
+        duration?: number;
+        item?: {
+            url: string;
+            position?: number[];
+            name?: string;
+            rotation?: number[];
+        };
+    };
+    position: number[];
+    interpolationType?: 'linear' | 'parabola';
+    quaternion: number[];
+    scale: number[];
+    adddon?: {
+        text?: string;
+        audio?: string;
+    };
+}
+interface DigitalDataKeyframe {
+    timeStamp: number;
+    data: any;
+}
+interface DigitalModelState {
+    translation: THREE.Vector3;
+    quaternion: THREE.Quaternion;
+    scale: THREE.Vector3;
+    animation?: DigitalModelKeyframe['animation'];
+    keyframeIndex: number;
+    visible: boolean;
+    isFinal: boolean;
+}
+interface DigitalSubTitleState {
+    title: string;
+    content: string;
+    audio?: string;
+    image?: string;
+    keyframeIndex: number;
+}
+interface DigitalCameraState {
+    matrix: number[];
+    fov: number;
+    transitionType: 'linear' | 'instant';
+}
+interface DigitalDataState {
+    currentFrameData: DigitalDataKeyframe['data'];
+    nextFrameData: DigitalDataKeyframe['data'] | null;
+    progress: number;
+}
+interface DigitalItemState {
+    timeStamp: number;
+    visible: boolean;
+}
+interface DigitalEffectState {
+    image: string;
+    visible: boolean;
+}
+type KeyframeType<T> = T extends 'model' ? DigitalModelKeyframe : T extends 'camera' ? DigitalCameraKeyframe : T extends 'subtitle' ? DigitalSubTitleKeyframe : T extends 'data' ? DigitalDataKeyframe : T extends 'item' ? DigitalItemKeyframe : T extends 'effect' ? DigitalEffectKeyframe : never;
+type StateType<T> = T extends 'model' ? DigitalModelState : T extends 'camera' ? DigitalCameraState : T extends 'subtitle' ? DigitalSubTitleState : T extends 'data' ? DigitalDataState : T extends 'item' ? DigitalItemState : T extends 'effect' ? DigitalEffectState : never;
+declare class DigitalStateMachine {
+    constructor();
+    getStateByTime<T extends 'model' | 'camera' | 'subtitle' | 'data' | 'item' | 'effect'>(time: number, keyframes: Array<KeyframeType<T>>, type: T): StateType<T>;
+    private getDataStateByTime;
+    private getEffectStateByTime;
+    private getItemStateByTime;
+    private getCameraStateByTime;
+    private getSubtitleStateByTime;
+    private getModelStateByTime;
+    private getKeyframeIndexByTime;
+}
+export { DigitalStateMachine };
+export type { DigitalModelPlayerEffect, DigitalEffectKeyframe, DigitalDataState, DigitalModelPlayerItem, DigitalDataPlayer, DigitalCameraKeyframe, DigitalChapter, DigitalModelKeyframe, DigitalScript, DigitalSubTitleKeyframe, DigitalModelPlayer, DigitalSubTitlePlayer, DigitalCameraPlayer, DigitalModelState, DigitalSubTitleState, DigitalCameraState, KeyframeType, StateType, };

package/dist/types/DigitalPerformancePlugin/core/Trace.d.ts

@@ -0,0 +1,9 @@
+import * as THREE from 'three/webgpu';
+export declare class Trace {
+    tracePoints: THREE.Vector3[];
+    curve: THREE.CatmullRomCurve3;
+    constructor();
+    addPoint(point: THREE.Vector3): void;
+    clear(): void;
+    getPoints(): THREE.Vector3[];
+}

package/dist/types/DigitalPerformancePlugin/index.d.ts

@@ -0,0 +1,17 @@
+import { Five } from '@realsee/five-webgpu';
+import { default as DigitalPerformancePluginController } from './controller/index.js';
+export { DigitalPerformanceNameplate, normalizeDigitalPerformanceName, DEFAULT_DIGITAL_PERFORMANCE_NAME_MAX_LENGTH, } from './core/DigitalPerformanceNameplate.js';
+export type { DigitalPerformanceNameplateBinding, DigitalPerformanceNameplateOptions, DigitalPerformanceNameplateRenderContext, } from './core/DigitalPerformanceNameplate.js';
+export { DigitalHuman } from './core/DigitalHuman.js';
+export { DigitalPlayground } from './core/DigitalPlayground.js';
+export { DigitalStateMachine } from './core/DigitalStateMachine.js';
+export type { DigitalScript, DigitalChapter, DigitalModelPlayer, DigitalSubTitlePlayer, DigitalCameraPlayer, DigitalModelKeyframe, DigitalSubTitleKeyframe, DigitalCameraKeyframe, DigitalModelState, DigitalSubTitleState, DigitalCameraState, DigitalModelPlayerItem, DigitalModelPlayerEffect, DigitalEffectKeyframe, DigitalDataState, DigitalDataPlayer, KeyframeType, StateType, DigitalPerformancePluginConfig, GlobalProgress, ChapterTimeInfo, ChapterLocation, ProgressListener, ProgressBarEvents, ExtendedAnimationConfig, DigitalItemKeyframe, DigitalItemState, DigitalEffectState, TracePoint, TraceManager } from './typings/index.js';
+export { transformAnimationDetailToDigitalScript, AnimationScriptAdapterSafetyError } from './animation-script-adapter.js';
+export type { LegacyScriptTransformer, AnimationScriptAdapterOptions } from './animation-script-adapter.js';
+export { getEffectivePointActionDuration, getMovementActionDuration, isConverterSafeMovementMatrix, hasMovementV2Signal, classifyMovementTrack, MOVEMENT_SCHEMA_VERSION, MOVEMENT_POSITION_EPSILON, MOVEMENT_OCCURRENCE_EPSILON } from './movement-track-classifier.js';
+export type { MovementPosition, PointAction, MovementConfig, TrackPoint, MovementTrackProjection, CanonicalMovementTrackPlan, MovementTrackConflictReason, MovementTrackClassification } from './movement-track-classifier.js';
+export { transformScriptData } from './transform-script-data.js';
+export type DigitalPerformancePluginExportInterface = InstanceType<typeof DigitalPerformancePluginController>;
+export type DigitalPerformancePluginParamsInterface = ConstructorParameters<typeof DigitalPerformancePluginController>[1];
+export declare const DigitalPerformancePlugin: (five: Five, params?: DigitalPerformancePluginParamsInterface) => DigitalPerformancePluginController;
+export default DigitalPerformancePlugin;

package/dist/types/DigitalPerformancePlugin/typings/index.d.ts

@@ -0,0 +1,87 @@
+import { DigitalChapter } from '../core/DigitalStateMachine.js';
+import { DigitalPerformanceNameplateOptions } from '../core/DigitalPerformanceNameplate.js';
+import type * as THREE from 'three/webgpu';
+export type { DigitalScript, DigitalChapter, DigitalModelPlayer, DigitalSubTitlePlayer, DigitalCameraPlayer, DigitalModelKeyframe, DigitalSubTitleKeyframe, DigitalCameraKeyframe, DigitalModelState, DigitalSubTitleState, DigitalCameraState, DigitalModelPlayerItem, DigitalModelPlayerEffect, DigitalEffectKeyframe, DigitalDataState, DigitalDataPlayer, KeyframeType, StateType, } from '../core/DigitalStateMachine.js';
+export interface DigitalPerformancePluginConfig {
+    autoPlay?: boolean;
+    loop?: boolean;
+    debug?: boolean;
+    /**
+     * 是否展示模型头顶的 2D 气泡名牌（默认 true）。
+     * 插件会内置挂载到 five canvas 的父容器，调用方无需提供容器，仅需声明是否展示。
+     */
+    showNameplate?: boolean;
+    /** 内置名牌的自定义配置（class / 内联样式 / 文本 / 自定义渲染器等）。仅 showNameplate 为真时生效。 */
+    nameplateOptions?: DigitalPerformanceNameplateOptions;
+}
+export interface GlobalProgress {
+    currentTime: number;
+    totalTime: number;
+    percentage: number;
+    currentChapterIndex: number;
+    currentChapterTime: number;
+    currentChapter?: DigitalChapter;
+}
+export interface ChapterTimeInfo {
+    chapterIndex: number;
+    chapterName: string;
+    startTime: number;
+    duration: number;
+    endTime: number;
+    chapter: DigitalChapter;
+}
+export interface ChapterLocation {
+    chapterIndex: number;
+    chapterTime: number;
+    chapter: DigitalChapter;
+}
+export type ProgressListener = (progress: GlobalProgress) => void;
+export interface ProgressBarEvents {
+    'progress-changed': ProgressListener;
+    'chapter-changed': (chapterIndex: number, chapter: DigitalChapter) => void;
+    'seek-started': (targetTime: number) => void;
+    'seek-completed': (actualTime: number) => void;
+    'playback-started': (startTime: number) => void;
+    'playback-completed': () => void;
+}
+export interface ExtendedAnimationConfig {
+    url: string;
+    repeat: boolean;
+    switchDuration?: number;
+    isOver?: boolean;
+}
+export interface DigitalItemKeyframe {
+    visible: boolean;
+    timeStamp: number;
+    position?: number[];
+    quaternion?: number[];
+    scale?: number[];
+}
+export interface DigitalItemState {
+    visible: boolean;
+    translation?: THREE.Vector3;
+    quaternion?: THREE.Quaternion;
+    scale?: THREE.Vector3;
+    keyframeIndex: number;
+    isFinal: boolean;
+}
+export interface DigitalEffectState {
+    visible: boolean;
+    image?: string;
+    intensity?: number;
+    color?: THREE.Color;
+    scale?: THREE.Vector3;
+    keyframeIndex: number;
+    isFinal: boolean;
+}
+export interface TracePoint {
+    position: THREE.Vector3;
+    timestamp: number;
+}
+export interface TraceManager {
+    tracePoints: THREE.Vector3[];
+    maxPoints: number;
+    addPoint(point: THREE.Vector3): void;
+    clear(): void;
+    getPoints(): THREE.Vector3[];
+}