@realsee/five 6.7.0-alpha.2 → 6.7.0-alpha.21

package/five/index.d.ts

@@ -23,15 +23,16 @@ export declare type AjaxResponseType = "arraybuffer" | "blob" | "text";
 export declare type AjaxResponseTypeMapping<K extends AjaxResponseType> = K extends "arraybuffer" ? ArrayBuffer : K extends "blob" ? Blob : K extends "text" ? string : never;
 
 export declare interface AnimationFrame {
-    callback: (time: number, deltaTime: number, ...args: any[]) => void;
+    callback: (time: number, deltaTime: number, ...requestAnimationFrameArgs: RequestAnimationFrameArgs) => void;
     once: boolean;
     delay: number;
     order: number;
+    calls: number;
 }
 
-export declare interface AnimationFrameContext {
-    requestAnimationFrame(...args: any[]): any;
-    cancelAnimationFrame(requestId: any): void;
+export declare interface AnimationFrameContext<Args extends any[] = any[], RequestId = any> {
+    requestAnimationFrame(fn: (...args: RequestAnimationFrameArgs<Args>) => void): RequestId;
+    cancelAnimationFrame(requestId: RequestId): void;
 }
 
 export declare class AnimationFrameLoop {
@@ -48,7 +49,7 @@ export declare class AnimationFrameLoop {
     start(): void;
     stop(): void;
     setContext(context: AnimationFrameContext | null): void;
-    getContext<T extends AnimationFrameContext>(): T | null;
+    getContext<T extends AnimationFrameContext = AnimationFrameContext>(): T | null;
     setLoopType(type: AnimationFrameLoopType): void;
     getLoopType(): AnimationFrameLoopType;
     private requestAnimationFrame;
@@ -75,6 +76,14 @@ export declare interface BaseEvent {
     defaultPrevented: boolean;
 }
 
+export declare class BoundingMesh extends PBMMesh {
+    constructor(options?: {
+        name?: string;
+    });
+    update(renderer: THREE_2.WebGLRenderer, camera: Camera, modelScene: ModelScene): boolean;
+    dispose(): void;
+}
+
 export declare interface BoundingVolume {
     type: 'box' | 'sphere' | 'regin';
     applyMatrix4(matrix: THREE_2.Matrix4): this;
@@ -540,9 +549,7 @@ export declare class Five extends Subscribe<EventTypes> {
     plugins: {
         [key: string]: FivePluginInstance<any>;
     };
-    ident: string;
-    /** 包围盒子 */
-    private boundingMesh;
+    readonly fiveId: string;
     private stopAnimationLoop?;
     private fps;
     private helperGroup;
@@ -566,6 +573,7 @@ export declare class Five extends Subscribe<EventTypes> {
     private _builtinRenderer;
     private _buildInRendererType;
     constructor(initArgs?: FiveInitArgs);
+    get ident(): string;
     get panoIndex(): number;
     /**
      * 析构 five 对象。
@@ -586,6 +594,10 @@ export declare class Five extends Subscribe<EventTypes> {
      * ```
      */
     setViewport(viewport: Viewport): void;
+    /**
+     * 获取 boundingMesh
+     */
+    get boundingMesh(): BoundingMesh;
     /**
      * 帮助元素显示/隐藏
      */
@@ -807,7 +819,8 @@ export declare class Five extends Subscribe<EventTypes> {
      */
     exitFullscreen(): void;
     private throwError;
-    private loadModels;
+    private bindModel;
+    private bindWorkFetcher;
     private commonParams;
     private applyController;
     /** 移除事件绑定 */
@@ -848,6 +861,22 @@ export declare class Five extends Subscribe<EventTypes> {
         phi: number;
         lookAtVector: THREE_2.Vector3;
     };
+    /**
+     * 增加后处理PASS
+     * @param pass - 要添加的Pass实例
+     */
+    addPass(pass: Pass): void;
+    /**
+     * 移除后处理Pass
+     * @param pass - 要移除的Pass实例
+     */
+    removePass(pass: Pass): void;
+    /**
+     * 在指定位置插入后处理Pass
+     * @param pass - 要插入的Pass实例
+     * @param index - 插入位置的索引
+     */
+    insertPass(pass: Pass, index: number): void;
     /**
      * @deprecated
      * use five.effect instead
@@ -1045,32 +1074,45 @@ export declare interface FiveInitArgs {
 }
 
 export declare interface FiveLoadOptions {
+    /** 替换 / 追加 */
+    mode?: 'replace' | "add";
     /** 切换运动时间 */
     duration?: number;
     /** 切换运动全景图效果 */
     effect?: MovePanoEffect;
-    model?: {
-        light?: boolean;
-        /**
-         * 模型贴图的配置参数
-         * @description
-         * 可以动态对配置在 `work` 数据中的模型贴图在 runtime 做 url 调整。
-         * 平衡加载时间和图片质量
-         */
-        textureOptions?: TextureOptions;
-        /** 模型 3d-tile 参数 */
-        "3d-tiles"?: Tile3dOptions;
-    };
+    model?: ModelOptions;
     /**
      * @deprecated
      * 请通过 model.textureOptions 设置
      */
-    textureOptions?: TextureOptions;
+    textureOptions?: ModelOptions['textureOptions'];
     /**
      * @deprecated
      * 请通过 model.textureOptions 设置
      */
-    "3d-tiles"?: Tile3dOptions;
+    "3d-tiles"?: ModelOptions['3d-tiles'];
+}
+
+/**
+ * FivePass
+ *
+ * Five引擎优化的Pass基类
+ * 支持G-Buffer注入，避免重复渲染场景
+ */
+export declare class FivePass extends Pass {
+    dependencies: ('depth' | 'normal' | 'color')[];
+    constructor(dependencies?: ['depth' | 'normal' | 'color']);
+    /**
+     * G-Buffer纹理集合
+     * 包含depth、normal、color等纹理
+     * 由EffectComposer在render时注入
+     */
+    gbuffer?: Map<'depth' | 'normal' | 'color', THREE_2.Texture>;
+    /**
+     * 设置G-Buffer
+     * @param gbuffer - G-Buffer纹理集合
+     */
+    setGBuffer(gbuffer: Map<'depth' | 'normal' | 'color', THREE_2.Texture>): void;
 }
 
 /**
@@ -1119,6 +1161,23 @@ export declare interface FloorplanControllerCustomInitArgs {
     intersectMeshCreator?: () => IntersectMeshInterface;
 }
 
+/**
+ * FullScreenQuad
+ *
+ * 用于全屏渲染的辅助类
+ */
+export declare class FullScreenQuad {
+    private _mesh;
+    private static camera;
+    private static geometry;
+    private _scene;
+    constructor(material?: THREE_2.Material);
+    get material(): THREE_2.Material | THREE_2.Material[];
+    set material(value: THREE_2.Material | THREE_2.Material[]);
+    dispose(): void;
+    render(renderer: THREE_2.WebGLRenderer): void;
+}
+
 export declare interface GestureEvent extends StateEvent {
     target: EventTarget | null;
     pointerType: 'touch' | 'pen' | 'mouse' | 'kinect';
@@ -1838,6 +1897,7 @@ export declare interface LooseWork {
         base_url?: string;
         pano_high_cube_base_url?: string;
         pano_cube_base_url?: string;
+        pattern?: LooseWorkPanorama;
         info?: LooseWorkPanorama[];
         list?: LooseWorkPanorama[];
     };
@@ -1865,6 +1925,8 @@ export declare interface LooseWorkModel {
     file_url?: string;
     material_textures?: string[];
     material_base_url?: string;
+    up_axis?: string;
+    coordinate?: NonNullable<TilesetHeader['rootMeta']>['coordinate'];
     tiles?: {
         type?: 'point_cloud' | 'mesh' | string;
         name?: string;
@@ -1883,6 +1945,7 @@ export declare interface LooseWorkModel {
 
 export declare interface LooseWorkObserver {
     active?: boolean;
+    loadable?: boolean;
     index?: number;
     visible_nodes?: number[];
     visibleNodes?: number[];
@@ -1904,10 +1967,16 @@ export declare interface LooseWorkObserver {
     derived_id_str?: string;
 }
 
-export declare interface LooseWorkPanorama extends Record<CubeFace, string> {
+export declare interface LooseWorkPanorama {
     active?: boolean;
     loadable?: boolean;
     index?: number;
+    right?: string;
+    left?: string;
+    up?: string;
+    down?: string;
+    front?: string;
+    back?: string;
     video?: LooseWorkVideo;
     tiles?: number[];
     size_list?: number[];
@@ -2044,6 +2113,7 @@ export declare interface Model {
  * 通过 json_xxxxxx(<dataURL>) 方式返回。
  */
 export declare class Model extends THREE_2.Object3D {
+    fiveId: string;
     parent: ModelScene | null;
     needsRender: boolean;
     children: ViewLayer[];
@@ -2065,14 +2135,14 @@ export declare class Model extends THREE_2.Object3D {
     /** 模型细化进度 */
     refineProgress: [number, number];
     /** 初始化完成 */
-    initReady: Promise<void>;
+    initReady: Promise<Model>;
     /** 初次加载完成 */
-    loadedReady: Promise<void>;
+    loadedReady: Promise<Model>;
     /** 外接盒子的大小 */
     boundingBox: THREE_2.Box3;
     /** 所有楼层 */
     floorLength: number;
-    constructor(work: Work, options?: {
+    constructor(fiveId: string, work: Work, options?: {
         light?: boolean;
         textureOptions?: TextureOptions;
     });
@@ -2170,9 +2240,26 @@ export declare interface ModelEvent extends BaseEvent {
     error: Error | null;
 }
 
-export declare interface ModelLike extends THREE_2.Object3D {
-    update?(renderer: THREE_2.WebGLRenderer, camera: Camera, modelScene: ModelScene): boolean;
-    dispose?: () => void;
+export declare interface ModelOptions {
+    /** 模型是否感光 */
+    light?: boolean;
+    /** 模型 3d-tile 参数 */
+    "3d-tiles"?: (Partial<ParameterTilesetValue> & {
+        viewerRequestVolume?: BoundingVolume | BoundingVolumeJson;
+        showLayers?: boolean | string[];
+    }) | ((viewLayer: ViewLayer, model: Model) => void | (Partial<ParameterTilesetValue> & {
+        viewerRequestVolume?: BoundingVolume | BoundingVolumeJson;
+        showLayers?: boolean | string[];
+    }));
+    /**
+     * 模型贴图的配置参数
+     * @description
+     * 可以动态对配置在 `work` 数据中的模型贴图在 runtime 做 url 调整。
+     * 平衡加载时间和图片质量
+     */
+    textureOptions?: TextureOptions;
+    /** 强制显示模型，不等待加载完 */
+    forceReplaceImmediately?: boolean;
 }
 
 export declare type Models = Model[] & {
@@ -2228,13 +2315,48 @@ export declare type Models = Model[] & {
     resetBrightness(): void;
 };
 
+export declare interface ModelScene {
+    dispatchEvent(event: {
+        type: 'model.create';
+        model: Model;
+    }): void;
+    dispatchEvent(event: {
+        type: 'model.dispose';
+        model: Model;
+    }): void;
+    dispatchEvent(event: {
+        type: string;
+        [attachment: string]: any;
+    }): void;
+    addEventListener(type: 'model.create', listener: (event: THREE_2.Event & {
+        type: 'model.create';
+        model: Model;
+    }) => void): void;
+    addEventListener(type: 'model.dispose', listener: (event: THREE_2.Event & {
+        type: 'model.dispose';
+        model: Model;
+    }) => void): void;
+    addEventListener(type: string, listener: (event: THREE_2.Event) => void): void;
+    removeEventListener(type: 'model.create', listener: (event: THREE_2.Event & {
+        type: 'model.create';
+        model: Model;
+    }) => void): void;
+    removeEventListener(type: 'model.dispose', listener: (event: THREE_2.Event & {
+        type: 'model.dispose';
+        model: Model;
+    }) => void): void;
+    removeEventListener(type: string, listener: (event: THREE_2.Event) => void): void;
+}
+
 export declare class ModelScene extends THREE_2.Scene {
+    fiveId: string;
     needsRender: boolean;
-    children: ModelLike[];
     /** 自动细化 */
     autoRefine: boolean;
     /** 包围盒 */
     boundingBox: THREE_2.Box3;
+    /** 包围盒 Mesh */
+    boundingMesh: BoundingMesh;
     /** 加载完成 */
     loaded: boolean;
     /** 细化完成 */
@@ -2245,9 +2367,12 @@ export declare class ModelScene extends THREE_2.Scene {
     parameter: Parameter;
     /** 模型列表 */
     readonly models: Models;
-    constructor();
-    add(...objects: ModelLike[]): this;
-    remove(...objects: ModelLike[]): this;
+    private readonly shownModels;
+    private updateModelMap;
+    constructor(options: {
+        fiveId: string;
+    });
+    setModels(works: Works, options: ModelOptions): Model[];
     /**
      * 计算模型射线碰撞检测
      * @param raycaster - THREE 射线对象
@@ -2276,6 +2401,7 @@ export declare class ModelScene extends THREE_2.Scene {
      * Use `.parameter.reset('brightness')` instead
      */
     resetBrightness(): void;
+    dispose(): void;
 }
 
 export declare interface ModelSceneEvent extends BaseEvent {
@@ -2333,8 +2459,9 @@ export declare type MotionValue<K extends string> = Record<K, number>;
  * - `spread` 通过扩散方式变化
  * - `zoomin` 通过放大变化
  * - `zoomout` 通过缩小变化
+ * - `model` 通过过度到模型
  */
-export declare type MovePanoEffect = "fly" | "instant" | "fade" | "montage" | "spread" | "zoomin" | "zoomout";
+export declare type MovePanoEffect = "fly" | "instant" | "fade" | "montage" | "spread" | "zoomin" | "zoomout" | "model";
 
 /**
  * 点位移动参数
@@ -2344,6 +2471,8 @@ export declare interface MovePanoOptions extends Partial<Omit<State, "offset" |
      * 动画模式
      */
     effect?: MovePanoEffect;
+    /** 走点图片过度策略 */
+    effectEasing?: (progress: number) => number;
     /**
      * 运动耗时
      * @description
@@ -2607,7 +2736,9 @@ export declare interface PanoramaControllerCustomInitArgs extends PanoramaLikeCo
      */
     panoTapTriggerRadius?: number;
     /** 地面观察点标识自定义创建器 */
-    panoCircleMeshCreator?: (pano: Pano) => PanoCircleMeshInterface;
+    panoCircleMeshCreator?: (observer: WorkObserver, options: {
+        aerialObserverMinHeight: number;
+    }) => PanoCircleMeshInterface;
     /** 基于模型调整 地面观察点 的位置 */
     adjustPanoCircleMeshPositionBasedOnModel?: boolean;
     /**
@@ -2646,6 +2777,8 @@ export declare interface PanoramaLikeControllerCustomInitArgs {
     moveSpeed?: number;
     /** 鼠标焦点环自定义创建器 */
     intersectMeshCreator?: () => IntersectMeshInterface;
+    /** 航拍点最小高度 */
+    aerialObserverMinHeight?: number;
 }
 
 export declare function panoStringify(pano: Pano): PanoId;
@@ -2780,7 +2913,6 @@ export declare interface ParameterTilesetValue {
     requestOrder: TileRequestOrder;
     /** 模型屏幕空间误差计算最大值 */
     maxScreenSpaceError: number;
-    memoryAdjustedOverflow: number;
     memoryAdjustedScreenSpaceError: boolean;
     /** 缓存相机 */
     cacheCameras: readonly (Camera | THREE_2.PerspectiveCamera)[];
@@ -2812,6 +2944,22 @@ export declare type ParseOptions = {
  */
 export declare function parseWork(obj: Work | LoosePanoWork | LooseWork | string | any, options?: ParseOptions): Work;
 
+/**
+ * Pass基类
+ *
+ * three.js的Pass接口，用于EffectComposer
+ */
+export declare class Pass {
+    enabled: boolean;
+    needsSwap: boolean;
+    clear: boolean;
+    renderToScreen: boolean;
+    constructor();
+    setSize(width: number, height: number): void;
+    render(renderer: THREE_2.WebGLRenderer, writeBuffer: THREE_2.WebGLRenderTarget, readBuffer: THREE_2.WebGLRenderTarget, deltaTime?: number, maskActive?: boolean): void;
+    static FullScreenQuad: typeof FullScreenQuad;
+}
+
 export declare type PBMAlphaMode = 'OPAQUE' | 'MASK' | 'BLEND';
 
 export declare interface PBMClipperParameter {
@@ -3210,6 +3358,8 @@ export declare interface RenderEvent extends BaseEvent {
     needsRender: boolean;
 }
 
+export declare type RequestAnimationFrameArgs<Args extends any[] = any[]> = [domHighResTimeStamp: number, ...args: Args];
+
 export declare interface ResolvedParameterValue extends ParameterValue {
     versions: string[];
     version: string;
@@ -3654,14 +3804,6 @@ declare interface Tile3DOptions {
 export { Tile3DOptions as Tile3DModelLoaderOptions }
 export { Tile3DOptions }
 
-export declare type Tile3dOptions = (Partial<ParameterTilesetValue> & {
-    viewerRequestVolume?: BoundingVolume | BoundingVolumeJson;
-    showLayers?: boolean | string[];
-}) | ((viewLayer: ViewLayer, model: Model, modelIndex: number) => void | (Partial<ParameterTilesetValue> & {
-    viewerRequestVolume?: BoundingVolume | BoundingVolumeJson;
-    showLayers?: boolean | string[];
-}));
-
 export declare class TileCache {
     private options;
     private cacheNodeMap;
@@ -3782,6 +3924,10 @@ export declare class Tileset {
     pointLength: number;
     floorLength: number;
     constructor(header: TilesetHeader, options: TilesetOptions);
+    /**
+     * 通过当前的内存使用，推测 maxScreenSpaceError
+     * @param frameState
+     */
     private adjustScreenSpaceError;
     private getTraverser;
     /** Release resources */
@@ -3816,7 +3962,6 @@ export declare type TilesetFrameState = {
     maxRequests: number;
     requestOrder: TileRequestOrder;
     maxScreenSpaceError: number;
-    memoryAdjustedOverflow: number;
     memoryAdjustedScreenSpaceError: boolean;
     maxMemoryUsage: number;
 };
@@ -4079,6 +4224,8 @@ export declare interface WorkImage extends WorkCubeImage {
     sizeList: readonly number[];
     /** 瓦片信息 */
     tiles: readonly WorkTile[];
+    /** 点位视频 */
+    video?: WorkVideo;
 }
 
 /** 初始化位姿参数 */
@@ -4133,6 +4280,10 @@ export declare interface WorkModel {
     textures?: readonly string[];
     /** 模型贴图文件地址的父目录 */
     textureBase?: string;
+    /** 指定上方向，对于 obj， ply 等定义不明确的需要指定上方向 */
+    upAxis?: string;
+    /** 模型的地理坐标数据 */
+    coordinate?: NonNullable<TilesetHeader['rootMeta']>['coordinate'];
     /** 3d tile */
     layers: readonly WorkModelLayer[];
 }
@@ -4141,14 +4292,20 @@ export declare interface WorkModelJson {
     file_url?: string;
     material_textures?: string[];
     material_base_url?: string;
+    up_axis?: string;
     layers?: WorkModelLayerJson[];
 }
 
 export declare interface WorkModelLayer {
+    /** work */
     work: Work;
+    /** 模型类型 point_cloud mesh */
     type: 'point_cloud' | 'mesh';
+    /** 模型名称 */
     name: string;
+    /** 指定上方向 */
     upAxis: string;
+    /** 如果 tileset.json 地址 */
     tileset: string;
 }
 
@@ -4172,22 +4329,24 @@ export declare interface WorkObserver {
      * @example
      * `${workCode}[${panoIndex}]`
      */
-    panoId: string;
+    panoId: PanoId;
     /** 点位所在楼层 */
     floorIndex: number;
     /** 点位 derived_id */
-    derivedId?: number;
+    derivedId: number;
     /** 点位 derived_id_str */
-    derivedIdStr?: string;
+    derivedIdStr: string;
     /** 点位是否激活可用 */
     active: boolean;
     /** 点位是否可加载 */
     loadable: boolean;
     /** 点位全景图 */
     images: WorkImage;
-    /** 点位视频 */
-    video?: WorkVideo;
-    /** 可以看到的相关点位序号 */
+    /**
+     * @deprecated
+     * 可以看到的相关点位序号
+     * 数据和 accessibleNodes 一致，使用 accessibleNodes
+     */
     visibleNodes: readonly number[];
     /** 可以连通的相关点位序号 */
     accessibleNodes: readonly number[];
@@ -4204,6 +4363,8 @@ export declare interface WorkObserver {
 export declare interface WorkObserverJson {
     index: number;
     floor_index: number;
+    derived_id: number;
+    derived_id_str: string;
     position: number[];
     standing_position: number[];
     quaternion: {