@realsee/five
Version:
Realsee Renderer SDK
520 lines (519 loc) • 17.9 kB
TypeScript
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 };