@spatialwalk/avatarkit
Version:
SPAvatar SDK - 3D Gaussian Splatting Avatar Rendering SDK
237 lines • 7.85 kB
TypeScript
/**
* Avatar Core WASM 适配器
*
* 完全替换 FlameComplete3DGSManager，提供 avatar_core_wasm 的完整功能
* 包括牙齿细分、眼部追踪等高级特性
*/
export interface WasmModuleConfig {
baseUrl?: string;
[key: string]: unknown;
}
export interface AvatarCoreOptions {
logLevel?: 'basic' | 'verbose';
enableValidation?: boolean;
enablePerformanceMetrics?: boolean;
retryCount?: number;
baseAssetsPath?: string;
modelFolder?: string;
wasmConfig?: WasmModuleConfig;
wasmPath?: string;
}
interface PerformanceMetrics {
initTime: number;
loadTime: number;
computeFrames: number;
totalComputeTime: number;
averageComputeTime: number;
}
export interface FlameInfo {
vertexCount: number;
faceCount: number;
jointCount: number;
}
export interface CharacterInfo {
pointCount: number;
hasAnimation: boolean;
}
export interface FlameParams {
shape_params?: number[];
expr_params?: number[];
rotation?: number[];
translation?: number[];
neck_pose?: number[];
jaw_pose?: number[];
eyes_pose?: number[];
eyelid?: number[];
has_eyelid?: boolean;
}
export declare class AvatarCoreAdapter {
private options;
private wasmConfig;
private wasmModule;
private memoryManager;
private coreHandle;
private characterHandles;
private animationHandles;
private characterHandle;
private animationHandle;
private totalFrames;
private isInitialized;
private isCharacterLoaded;
private api;
private performanceMetrics;
wasmTime: number;
private errorCodes;
private flameInfo?;
private characterInfo?;
constructor(options?: AvatarCoreOptions);
/**
* 加载 WASM 模块并设置 API
* 每次都创建全新的 WASM 实例，确保 C++ 内存是干净的
*
* 注意：这里使用动态 import() 导入 WASM 模块。
* Vite 在构建时会自动为 WASM 文件和 JS glue 代码添加 hash（如 avatar_core_wasm-CxWuw7eS.wasm），
* 确保浏览器缓存与版本一致，不会有缓存问题。
*
* Hash 的作用机制：
* - WASM 文件内容变化 → hash 自动变化 → URL 变化 → 浏览器拉取新版本
* - WASM 文件内容不变 → hash 保持不变 → URL 不变 → 浏览器使用缓存
* - Emscripten 生成的 JS 内部会使用 hard-coded 的 hash 路径加载 .wasm 文件
*/
loadWASMModule(): Promise<void>;
/**
* 验证 WASM 模块功能
*/
private validateWASMModule;
/**
* 初始化内存视图
*/
private initializeMemoryViews;
/**
* 设置 C API 函数包装
*/
private setupCAPIFunctions;
/**
* 读取当前动画帧的 FlameParams（用于过渡或调试）
*/
/**
* Get current frame parameters
* @param frameIndex Frame index
* @param characterId Optional character ID for multi-character support
*/
getCurrentFrameParams(frameIndex?: number, characterId?: string): Promise<FlameParams>;
/**
* 初始化 Avatar Core 核心
*/
private initializeAvatarCore;
/**
* 加载模板资源（从预加载的 ArrayBuffers）
*/
loadTemplateResourcesFromBuffers(templateResources: Record<string, ArrayBuffer>): Promise<boolean>;
/**
* 加载角色数据（从预加载的 ArrayBuffers）
*/
/**
* Load character from buffers and return handle
* @param shapeBuffer Shape data buffer
* @param pointCloudBuffer Point cloud data buffer
* @param characterId Optional character ID for multi-character support
* @returns Character handle
*/
loadCharacterFromBuffers(shapeBuffer: ArrayBuffer, pointCloudBuffer: ArrayBuffer, characterId?: string): Promise<number>;
private loadAnimationFromData;
/**
* Load animation from ArrayBuffer (for CDN-based dynamic loading)
* @param animData Animation data buffer
* @param characterId Optional character ID for multi-character support
* @returns Animation handle
*/
loadAnimationFromBuffer(animData: ArrayBuffer, characterId?: string): Promise<number>;
switchAnimationFile(animationFile: string): Promise<number>;
/**
* 获取动画总帧数
* @param animationHandle Optional animation handle (for multi-character support)
*/
getAnimationTotalFrames(animationHandle?: number): Promise<number>;
/**
* 从动画中获取指定帧的参数
* @param frameIndex Frame index
* @param characterId Optional character ID for multi-character support
*/
getAnimationFrameParams(frameIndex?: number, characterId?: string): Promise<number>;
/**
* 设置眼部追踪配置（对齐 app 实现）
*/
setEyeTrackingConfig(config: {
enabled: boolean;
auto_eyelid_adjustment?: boolean;
eyelid_threshold?: number;
}): Promise<boolean>;
/**
* 设置眼部追踪目标（高级功能）
*/
setGazeTarget(x: number, y: number, z: number): Promise<boolean>;
/**
* 重置眼部追踪
*/
resetEyeTracking(): Promise<boolean>;
/**
* 查询 FLAME 模型信息
*/
private queryFlameInfo;
/**
* 查询角色信息
*/
private queryCharacterInfo;
/**
* 检查错误码并抛出异常
*/
private checkError;
/**
* 更新进度回调
*/
private updateProgress;
/**
* 获取性能指标
*/
getPerformanceMetrics(): PerformanceMetrics & {
flameInfo?: FlameInfo;
characterInfo?: CharacterInfo;
version?: string;
};
/**
* 释放当前角色和动画资源（但保留 core）
*/
/**
* Remove a specific character by handle
* @param characterHandle Character handle to remove
* @param characterId Optional character ID for cleanup
*/
removeCharacter(characterHandle: number, characterId?: string): void;
/**
* Release current character (legacy method, kept for backward compatibility)
* @deprecated Use removeCharacter() instead for multi-character support
*/
releaseCurrentCharacter(): void;
/**
* 释放所有资源（包括 core）
*/
release(): void;
/**
* 兼容性接口：提供与 FlameComplete3DGSManager 相同的接口
*/
loadFlameModel(_modelData: any): Promise<boolean>;
load3DGSData(_original3DGSPoints: any, _binding: any, _flameFaces: any): Promise<boolean>;
/**
* 计算帧并返回 GPU 友好的 flat 格式（零拷贝，协方差预计算）
* 🚀 性能优化版本：
* - C++ 预计算协方差矩阵
* - 零拷贝直接访问 WASM 内存http://localhost:3000/us/
* - 直接输出 GPU 格式 [pos3, color4, cov6]
*/
/**
* Compute complete frame from animation
* @param params Frame parameters
* @param characterHandle Optional character handle (for multi-character support)
*/
computeCompleteFrameFlat(params?: {
frameIndex?: number;
}, characterHandle?: number): Promise<Float32Array | null>;
/**
* 计算帧并返回 GPU 友好的 flat 格式（从 FLAME 参数）
* 🔑 用于 Realtime: 接受自定义 FLAME 参数并计算 Splat
*/
/**
* Compute frame from Flame parameters
* @param flameParams Flame parameters
* @param characterHandle Optional character handle (for multi-character support)
*/
computeFrameFlatFromParams(flameParams: FlameParams, characterHandle?: number): Promise<Float32Array | null>;
/**
* 获取 WASM 内存使用情况（MB）
* @returns WASM 内存使用量（MB），如果模块未加载则返回 null
*/
getWASMMemoryMB(): number | null;
}
export {};
//# sourceMappingURL=avatarCoreAdapter.d.ts.map