@realsee/five 6.8.0-alpha.3 → 6.8.0-alpha.31

package/five/application/events.d.ts

@@ -0,0 +1,69 @@
+import { StateEvent, WorksEvent, ModelEvent, ModelSceneEvent, ModelTileEvent, ModeChangeEvent, PanoEvent, RenderEvent, ObjectEvent, NetworkResourceEvent } from "../utils/event";
+import type { ControllerEventTypes } from "../controllers/events";
+import type { LegacyEventType } from "./events-legacy";
+declare const PROXY_CONTROLLER_EVENT_NAMES: readonly ["gesture.pan", "gesture.tap", "gesture.dbltap", "gesture.press", "gesture.pinch", "gesture.mousewheel", "gesture.mousemove", "gesture.momentum", "gesture.fire", "initAnimation.start", "initAnimation.end", "camera.update", "intersect.update", "pano.select", "pano.moveTo", "pano.moving", "pano.arrived", "pano.cancel", "pano.error", "pano.prepare", "pano.texture.load", "pano.texture.progress", "pano.texture.success", "pano.texture.error", "pano.texture.abort", "xr.session.start", "xr.session.end", "xr.gesture.tap", "xr.gesture.press", "xr.gesture.buttonUp", "xr.gesture.buttonDown", "xr.controller.update"];
+/**
+ * Five 事件列表
+ * @description
+ * 具体事件列表 请查看 {@link EventCallback}
+ */
+type EventTypes = Pick<ControllerEventTypes, typeof PROXY_CONTROLLER_EVENT_NAMES[number]> & LegacyEventType & {
+    /** 请求点位 */
+    "pano.request"(event: PanoEvent): void;
+    /** 内部错误 */
+    "error"(error: Error): void;
+    /** 请求 work数据 */
+    "works.request"(event: WorksEvent): void;
+    /** 加载 work */
+    "works.load"(event: WorksEvent): void;
+    /** 加载 work 并 controller ready */
+    "works.ready"(event: WorksEvent): void;
+    /** 设置 state */
+    "state.set"(event: StateEvent): void;
+    /** 当 state 变化 */
+    "state.change"(event: StateEvent): void;
+    /** 当 state 同步完成 */
+    "state.synced"(event: StateEvent): void;
+    /** 当前 state 变化 */
+    "currentState.change"(event: StateEvent): void;
+    /** 当模型加载 */
+    "model.request"(event: ModelEvent): void;
+    /** 当模型修改楼层 */
+    "model.load"(event: ModelEvent): void;
+    /** 当模型错误 */
+    "model.error"(event: ModelEvent): void;
+    /** 当模型修改楼层 */
+    "model.changeShownFloor"(event: ModelEvent): void;
+    /** 模型加载完成 */
+    "models.load"(event: ModelSceneEvent): void;
+    /** 模型细化完成 */
+    "models.refined"(event: ModelSceneEvent): void;
+    /** 模型加载完成 */
+    "models.tileLoad"(event: ModelTileEvent): void;
+    /** 模型加载完成 */
+    "models.tileUnload"(event: ModelTileEvent): void;
+    /** 渲染前 */
+    "render.prepare"(event: RenderEvent): void;
+    /** 渲染后 */
+    "render"(event: RenderEvent): void;
+    /** 请求改变 mode */
+    "mode.change.request"(event: ModeChangeEvent): void;
+    /** 改变 mode */
+    "mode.change"(event: ModeChangeEvent): void;
+    /** 改变 helpers 元素可见 */
+    "helpers.visible"(event: ObjectEvent): void;
+    /** 网络资源 */
+    "network.resource"(event: NetworkResourceEvent): void;
+    /** 当前 fps 变化 */
+    "fps"(fps: number): void;
+    /** five 被析构。 插件中请监听用于自身析构 */
+    "dispose"(): void;
+};
+/**
+ * Five 事件列表
+ * @description
+ * 可以通过 `five.on(METHOD_NAME, METHOD)` 调用
+ */
+interface EventCallback extends EventTypes {
+}
+export { PROXY_CONTROLLER_EVENT_NAMES, ControllerEventTypes, EventTypes, EventCallback, };

package/five/application/five.d.ts

@@ -0,0 +1,519 @@
+import * as THREE from "three";
+import { Camera } from "../core/camera";
+import { Scene } from "../core/scene";
+import { Pano, PanoId } from "../utils/pano";
+import { ModelScene, Model, Models } from "../model";
+import { Subscribe } from "../utils/subscribe";
+import { Works, Work, LooseWork, LooseWorkWithExtrinsics, WorkObserver } from "../work";
+import { ImageOptions, TextureOptions } from "../types/imageOptions";
+import { Pose } from "../types/pose";
+import { State } from "../types/state";
+import { Viewport } from "../types/viewport";
+import { MovePanoEffect } from "../types/movePanoEffect";
+import { MovePanoOptions } from "../types/movePanoOptions";
+import { Mode } from "./mode";
+import { type Pass } from '../renderer';
+import { EventTypes } from "./events";
+import { FivePluginInstance } from "../types/plugin";
+import type { FiveInitArgs } from "./fiveInitArgs";
+import type { FiveLoadOptions } from "./fiveLoadOptions";
+/**
+ * 如视 VR Web展示器
+ *
+ * @example
+ * ```
+ * // 初始化构造函数
+ * const five = new Five();
+ * // 将绘制区域添加到页面上
+ * five.appendTo(document.body);
+ * // 加载 Work 数据
+ * five.load({...});
+ * ```
+ */
+declare class Five extends Subscribe<EventTypes> {
+    static get version(): string;
+    static get dracoPath(): string;
+    static set dracoPath(path: string);
+    static get ktx2Path(): string;
+    static set ktx2Path(path: string);
+    static get useNativeImageBitmap(): boolean;
+    static set useNativeImageBitmap(enable: boolean);
+    /**
+     * Five 的显示模式，可以通过 `five.changeMode` `five.setState` 来切换
+     * @description
+     * ```text
+     * Panorama 全景图游走模式
+     * Model 模型游走模式
+     * Floorplan 模型查看模式
+     * Topview 户型图模式
+     * VRPanorama VR眼镜模式
+     * XRPanorama VR硬件模式
+     * ```
+     */
+    static Mode: {
+        readonly Panorama: "Panorama";
+        readonly Model: "Model";
+        readonly Floorplan: "Floorplan";
+        readonly Topview: "Topview";
+        readonly Mapview: "Mapview";
+        readonly VRPanorama: "VRPanorama";
+        readonly XRPanorama: "XRPanorama";
+    };
+    /**
+     * 自动播放状态是否暂停
+     * @description
+     * 可以通过 `five.play` `five.pause` 方法播放或暂停
+     */
+    paused: boolean;
+    /** 当前点位序号 */
+    pano: Pano;
+    /** 当前展示的模式 */
+    currentMode: Mode;
+    /** 非模型部分使用的 `THREE.Scene` */
+    scene: Scene;
+    /** 内部模型部分使用的 `THREE.Scene` */
+    modelScene: ModelScene;
+    /** 供外部放置需要在xr场景下产生遮挡的物体们*/
+    xrCustomObjectsScene: THREE.Scene;
+    /** 内部使用的 `Camera` */
+    camera: Camera;
+    /**
+     * 当前设置的 `viewport`
+     * @description
+     * 可通过初始化，或者 setScissor 方式设置
+     * `viewport` 是将屏幕中的内容渲染到 `renderer` 的指定区域。
+     * 页面整体长宽均为 `1`。通过类似 css 的 `left` `bottom` `width` `height` 来确定区域。
+     * @example
+     * ```
+     * viewport: { left: 0.75, bottom: 0, width: 0.25, height: 1 }
+     * ```
+     */
+    viewport: Viewport;
+    /**
+     * 当前使用的 THREE.WebGLRenderer。
+     * @description
+     * 如果初始化时传入了 `renderer` 则直接时该值
+     * 否则会通过 `preserveDrawingBuffer` `backgroundColor` `backgroundAlpha` `antialias` 创建一个 `THREE.WebGLRenderer`
+     */
+    renderer?: THREE.WebGLRenderer;
+    /**
+     * 是否需要渲染
+     * @description
+     * 如果初始化设置了 `onlyRenderIfNeeds: true`, 则会激活按需渲染
+     * 可以通过设置 `five.needsRender = true` 来告知，five 会在下一帧渲染画面。
+     */
+    needsRender: boolean;
+    /**
+     * 是否按需渲染
+     */
+    onlyRenderIfNeeds: boolean;
+    /** 是否显示 Powered By Realsee */
+    poweredByRealsee: boolean;
+    /** 背景颜色 */
+    backgroundColor: THREE.Color;
+    /** 背景透明度 */
+    backgroundAlpha: number;
+    /**
+     * 全景图的配置参数
+     * @description
+     * 可以动态对配置在 `work` 数据中的全景图片在 runtime 做 url 调整。
+     * 平衡加载时间和图片质量
+     */
+    imageOptions: ImageOptions;
+    /**
+     * 模型贴图的配置参数
+     * @description
+     * 可以动态对配置在 `work` 数据中的模型贴图在 runtime 做 url 调整。
+     * 平衡加载时间和图片质量
+     */
+    textureOptions: TextureOptions;
+    /**
+     * 模型贴图的配置参数
+     * @description
+     * 可以动态对配置在 `work` 数据中的模型贴图在 runtime 做 url 调整。
+     * 平衡加载时间和图片质量
+     */
+    videoTexture: THREE.VideoTexture;
+    /**
+     * 当前状态
+     * @description
+     * ```text
+     * five 设置了以下状态
+     *
+     * - mode: Mode
+     * - panoIndex: number
+     * - longitude: number
+     * - latitude: number
+     * - fov: number
+     * - offset: THREE.Vector3
+     *
+     * 可以通过 five.state 和 five.setState 来获取和设置。
+     * 通过 state 设置后，five 会通过合适的动画运动来达到设置的位置。
+     * 来迎合一些通过数据驱动的场景。
+     * ```
+     */
+    state: State;
+    /** 插件暴露的方法 */
+    plugins: {
+        [key: string]: FivePluginInstance<any>;
+    };
+    readonly fiveId: string;
+    private stopAnimationLoop?;
+    private fps;
+    private helperGroup;
+    private modeChangeDuration;
+    private enableWheel;
+    private controller?;
+    private destroyed;
+    private stateSynced;
+    private controllerInits;
+    private extraElements;
+    private getPixelsRenderTarget;
+    private readyCallbacks;
+    private syncingState;
+    private loadWorkTask;
+    private requestProxy;
+    private networkSubscribe;
+    private analysis?;
+    private currentUpdateArgs;
+    private fiveRenderer;
+    private adaptiveLuminancePass;
+    private eyeDomeLightingPass;
+    private pbmGaussianSplattingRenderMesh;
+    constructor(initArgs?: FiveInitArgs);
+    get ident(): string;
+    get panoIndex(): number;
+    get panoId(): PanoId;
+    /**
+     * 析构 five 对象。
+     * @description
+     * 一旦调用了析构方法，则不能再使用当前 five 对象了。
+     * 你可以新建一个新的。
+     */
+    dispose(): void;
+    /**
+     * 设置 `viewport`
+     * @param viewport - 指定区域
+     * `scissor` 是将屏幕中的内容渲染到 `renderer` 的指定区域。
+     * 请确保在 five 初始化时传入 `renderer` 对象
+     * 页面整体长宽均为 `1`。通过类似 css 的 `left` `bottom` `width` `height` 来确定区域。
+     * @example
+     * ```
+     * five.setViewport({ left: 0.75, bottom: 0, width: 0.25, height: 1 })
+     * ```
+     */
+    setViewport(viewport: Viewport): void;
+    /**
+     * 获取 boundingMesh
+     */
+    get boundingMesh(): import("..").BoundingMesh;
+    /**
+     * 帮助元素显示/隐藏
+     */
+    get helperVisible(): boolean;
+    set helperVisible(visible: boolean);
+    updateConfiguration(args: Pick<FiveInitArgs, "panorama" | "model" | "floorplan" | "topview" | "mapview" | "vrPanorama" | 'xrPanorama' | "imageOptions" | "textureOptions">, refresh?: boolean): void;
+    /**
+     * 将显示区域加载到页面 DOM 中
+     * @description
+     * 如果你是传入的 `renderer`. 则你需要自行来方式显示区域该方法并不生效
+     *
+     * @param element - 加载到页面的 DOM 元素
+     * @param size - 显示区域尺寸 默认铺满这个 DOM 元素
+     */
+    appendTo(element: HTMLElement, size?: {
+        width?: number;
+        height?: number;
+    }): void;
+    /**
+     * 设置显示区域尺寸
+     * @description
+     * 如果你是传入的 `renderer`. 则你需要自行来设置显示区域尺寸，该方法并不生效
+     *
+     * @param size - 显示区域尺寸 默认铺满这个 DOM 元素
+     * @param pixelRatio - 像素比 默认继承之前的设置
+     */
+    refresh(size?: {
+        width?: number;
+        height?: number;
+    }, pixelRatio?: number): void;
+    /**
+     * 绑定一个额外 DOM 区域，接受触控/鼠标事件
+     * @returns 解除该绑定
+     */
+    addExtraElement(element: HTMLElement): () => void;
+    /**
+     * 解除绑定的一个额外 DOM 区域
+     */
+    removeExtraElement(element: HTMLElement): void;
+    getSize(target: THREE.Vector2): THREE.Vector2;
+    getDrawingBufferSize(target: THREE.Vector2): THREE.Vector2;
+    /**
+     * 移动相机。（不触发点位移动）
+     * @description
+     * 如果动画中途被打断（用户触发行为，或者调用 setState, load, changeMode）的等
+     * 会 Promise.reject。运动完成则 Promise.resolve
+     * @param pose - 相机目标位置
+     * @param duration - 动画触发的时常
+     * @param userAction - 是否用户触发
+     * @returns Promise 是否移动成功
+     */
+    updateCamera(pose: Partial<Pose>, duration: number, userAction?: boolean): Promise<void>;
+    /**
+     * 通过帧动画移动相机。（不触发点位移动）
+     * @description
+     * 如果动画中途被打断（用户触发行为，或者调用 setState, load, changeMode）的等
+     * 会 Promise.reject。运动完成则 Promise.resolve
+     * @param keyframes - 动画帧
+     * @param duration - 动画触发的时常
+     * @param userAction - 是否用户触发
+     * @returns Promise 是否移动成功
+     */
+    updateCameraWithKeyframes(keyframes: {
+        progress: number;
+        value: Pose;
+        key?: string;
+    }[], duration: number, userAction?: boolean): Promise<void>;
+    /** 当前加载的 work 数据 */
+    get works(): Works;
+    get work(): Work;
+    get observers(): readonly WorkObserver[];
+    get models(): Models;
+    get model(): Model;
+    /**
+     * 加载 Work 数据
+     * @param inputWork - Work 数据
+     * @param state - 初始化姿态
+     *  - "inherit" 使用当前姿态
+     *  - "initial" 使用 Work 数据中的 initial 姿态
+     *  - State 自定义姿态
+     * @param options - 切换时间, 切换效果
+     */
+    load(inputWork: string | Work | LooseWork | string[] | Work[] | LooseWork[] | LooseWorkWithExtrinsics[] | Promise<Work | LooseWork | Work[] | LooseWork[] | LooseWorkWithExtrinsics[]>, state?: "inherit" | "initial" | Partial<State>, options?: number | FiveLoadOptions, userAction?: boolean): Promise<void>;
+    private load_;
+    reset(): Promise<void>;
+    reset_(): Promise<void>;
+    /**
+     * 切换模态
+     * @param mode - 切换到的模态
+     * @param state - 切换完成时的姿态
+     * @param options - 模态切换动画用时
+     * @param userAction - 是否时用户动作触发 默认 true
+     * @param force - 必须重新初始化 controller
+     */
+    changeMode<T extends Mode>(mode: T, state?: Partial<Omit<State, "mode">>, options?: number | {
+        duration?: number;
+        effect?: MovePanoEffect;
+    }, userAction?: boolean, force?: boolean): Promise<void>;
+    /**
+     * 获取画面中的像素颜色
+     * @param x - 获取像素区域的起始坐标 x
+     * @param y - 获取像素区域的起始坐标 y
+     * @param width - 获取像素区域的宽度
+     * @param height - 获取像素区域的高度
+     * @param pixelRatio - 获取区域的像素比
+     * @param flipY - 是否Y轴翻转
+     * @param buffer - 存储数组
+     * @returns rgba颜色平铺的 Uint8Array
+     */
+    getPixels<T extends Uint8Array | Uint8ClampedArray = Uint8Array>(x: number, y: number, width: number, height: number, pixelRatio?: number, flipY?: boolean, buffer?: T): T;
+    /**
+     * 获取画面中的像素颜色
+     * @param options - 参数
+     * @returns
+     */
+    getPixels<T extends Uint8Array | Uint8ClampedArray = Uint8Array>(options: {
+        /** 获取像素区域的起始坐标 x */
+        x: number;
+        /** 获取像素区域的起始坐标 y */
+        y: number;
+        /** 获取像素区域的宽度 */
+        width: number;
+        /** 获取像素区域的高度 */
+        height: number;
+        /** 获取区域的像素比 */
+        pixelRatio?: number;
+        helperVisible?: boolean;
+        skipPanorama?: boolean;
+        /** 是否Y轴翻转 */
+        flipY?: boolean;
+        /** 存储数组 */
+        buffer?: T;
+    }): T;
+    /**
+     * 获取显示用的画布（Canvas DOM节点）
+     */
+    getElement(): HTMLCanvasElement | undefined;
+    /**
+     * 强制渲染
+     * @description
+     * 调用 `five.render()` 和设置 `five.needsRender = true` 均可在按需渲染时，使得画面渲染一次
+     * 区别在于：
+     * - `five.needsRender = true` 为在下帧渲染画面
+     * - `five.render()` 在当前帧渲染画面
+     * 推荐使用 `five.needsRender = true`, 可以更加流畅。但是如果需要截图等同步操作，可以使用 `five.render()`
+     *
+     * @param callback - 渲染完成回调
+     */
+    render(callback?: () => void): void;
+    updateTime(time: number, deltaTime: number, ...args: any[]): void;
+    /**
+     * 暂停自动播放
+     */
+    pause(): void;
+    play(): void;
+    /**
+     * 转化到 Panorama 模态，并移动到对应序号的观察点。
+     * @param pano - 观察点序号
+     * @param options - 移动点位参数
+     * @param userAction - 是否用户触犯
+     */
+    moveToPano(pano: Pano | PanoId | number, options?: MovePanoOptions, userAction?: boolean): Promise<void>;
+    /**
+     * 预加载点位图片资源
+     * @param pano - 观察点序号
+     * @param callback - 加载完成回调, 并传递加载用时。
+     * @returns 加载完成的 Promise 参数同 callback
+     */
+    preloadPano(pano: Pano | PanoId | number, callback?: (costs: number) => void): Promise<number>;
+    /**
+     * 计算三维坐标对应到屏幕的二维坐标
+     * @description
+     * 如果三维坐标不在屏幕中，则返回 null
+     * @param vector - 三维坐标
+     * @param testModel - 是否计算模型遮挡
+     * @returns 二维坐标 或者 null
+     */
+    project2d(vector: THREE.Vector3, testModel?: boolean): THREE.Vector2 | null;
+    getCurrentState(): State;
+    /**
+     * 设置 State
+     * @description
+     * ```text
+     * five 设置了以下状态
+     *
+     * - mode: Mode
+     * - panoIndex: number
+     * - longitude: number
+     * - latitude: number
+     * - distance: number
+     * - fov: number
+     * - offset: THREE.Vector3
+     *
+     * 可以通过 five.state 和 five.setState 来获取和设置。
+     * 通过 state 设置后，five 会通过合适的动画运动来达到设置的位置。
+     * 来迎合一些通过数据驱动的场景。
+     * ```
+     * @param state - 目标状态
+     * @param immediately - 是否马上转换，马上转换会尽快达到目标状态，尽量减少中间状态，更少动画。
+     * @param userAction - 是否是用户触发的动作
+     */
+    setState(state: Partial<State>, immediately?: boolean, userAction?: boolean): void;
+    private syncState;
+    /**
+     * 当前页面静态
+     */
+    ready(args?: {
+        tile?: boolean;
+    }): Promise<void>;
+    /**
+     * 请求全屏
+     */
+    requestFullscreen(): void;
+    /**
+     * 退出全屏
+     */
+    exitFullscreen(): void;
+    private throwError;
+    private bindModel;
+    private bindWorkFetcher;
+    private commonParams;
+    private applyController;
+    /** 移除事件绑定 */
+    private removeEventListeners;
+    get internalLightsEnabled(): boolean;
+    set internalLightsEnabled(value: boolean);
+    /**
+     * @deprecated
+     * use Viewport instead.
+     */
+    get scissor(): Viewport;
+    /**
+     * @deprecated
+     * use setViewport instead.
+     */
+    setScissor(scissor: Viewport): void;
+    /**
+     * @deprecated
+     * 获取当前相机姿态, 可以使用 getCurrentState 代替
+     */
+    getPose(): Pose;
+    /**
+     * 获取当前相机经纬度
+     * @deprecated 请使用使用 getPose
+     */
+    getLongitudeAndLatitude(): Pick<Pose, "longitude" | "latitude">;
+    /**
+     * 获取当前相机位置
+     * @deprecated 请使用使用 getPose
+     */
+    getOffset(): Pose["offset"];
+    /**
+     * 获取当前相机的姿态（用于内部的 python 脚本截图）
+     * @deprecated 这是用于内部的 python 脚本截图
+     */
+    getCameraLocal(): {
+        theta: number;
+        phi: number;
+        lookAtVector: THREE.Vector3;
+    } | null;
+    /**
+     * 增加后处理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;
+    /**
+     * 设置渲染模式
+     */
+    get renderMode(): "default" | "ssaa" | "point-cloud-high-quality";
+    set renderMode(value: "default" | "ssaa" | "point-cloud-high-quality");
+    /** 开启 HQ */
+    get enableHQ(): boolean;
+    set enableHQ(enable: boolean);
+    /** 开启 edl */
+    get enableEDL(): boolean;
+    set enableEDL(enable: boolean);
+    /** 开启 AdaptiveLuminance */
+    get enableAdaptiveLuminance(): boolean;
+    set enableAdaptiveLuminance(enable: boolean);
+    /**
+     * @deprecated
+     * 不可用
+     */
+    get enableIOSEDR(): boolean;
+    set enableIOSEDR(enable: boolean);
+    /**
+     * @deprecated
+     * 不可用
+     */
+    get enablePostProcessing(): boolean;
+    set enablePostProcessing(enable: boolean);
+    /**
+     * @deprecated
+     * use five.modelScene.needsRender instead
+     */
+    get modelSceneNeedsRender(): boolean;
+    set modelSceneNeedsRender(needsRender: boolean);
+}
+export { Five, FiveInitArgs };