@realsee/five
Version:
Realsee Renderer SDK
455 lines (454 loc) • 16.5 kB
TypeScript
import * as THREE from 'three';
import { Model } from "../model";
import { MovePanoOptions } from "../types/movePanoOptions";
import { State } from "../types/state";
import { Pose } from "../types/pose";
import { Intersection } from "../model/intersection";
import { NetworkState, NetworkType } from "../utils/ajax";
import { NetWorkMeta } from "../utils/ajax";
import { Work, WorkModel } from "../work";
import { Mode } from "./mode";
import { XRGestureEvent } from '../utils/event';
import type { Five } from './five';
export type GestureTypes = "pan" | "tap" | "dbltap" | "pinch" | "press" | "mouseWheel" | "mouseMove";
export type WebXRControllerType = 'tap' | 'press' | 'axes' | 'buttonUp' | 'buttonDown';
export type WebXRControllerKey = XRGestureEvent['buttons'];
export interface WebXRControllerParams {
raycaster: {
leftRay: THREE.Raycaster;
rightRay: THREE.Raycaster;
};
}
export interface WebXRAxesParams {
raycaster: {
leftRay?: THREE.Raycaster;
rightRay?: THREE.Raycaster;
};
axesState: {
up: number;
down: number;
left: number;
right: number;
};
deltaTime: number;
}
/**
* 过时的事件列表
*/
export type LegacyEventType = {
/**
* 模态间切换动画开始
* @param panoIndex - 当前点位
* @param pose - 相机姿态
* @param userAction - 是否用户触发
*/
initAnimationWillStart(panoIndex: number, pose: Pose, userAction: boolean): void;
/**
* 模态间切换动画结束
* @param panoIndex - 当前点位
* @param pose - 相机姿态
* @param userAction - 是否用户触发
*/
initAnimationEnded(panoIndex: number, pose: Pose, userAction: boolean): void;
/**
* 意图要触发手势， 可以通过 `return false` 阻止
* @param type - 手势类型
* @param pointers - 手指位置
* @param final - 是否手势结束
* @returns 可以通过 `return false` 阻止
*/
wantsGesture(type: GestureTypes, pointers: {
x: number;
y: number;
delta?: number;
}[], final: boolean): void | false;
/**
* 手势 触发
* @param type - 手势类型
* @param pointers - 手指位置
* @param final - 是否手势结束
*/
gesture(type: GestureTypes, pointers: {
x: number;
y: number;
delta?: number;
}[], final: boolean): void;
/**
* 意图要触发 pan 手势(滑动屏幕)， 可以通过 `return false` 阻止
* @param pose - 意图的相机姿态
* @param final - 是否手势结束
* @returns 可以通过 `return false` 阻止
*/
wantsPanGesture(pose: Pose, final: boolean): void | false;
/**
* pan 手势(滑动屏幕) 被触发
* @param pose - 相机姿态
* @param final - 是否手势结束
*/
panGesture(pose: Pose, final: boolean): void;
/**
* 意图要触发 tap 手势(点击屏幕)， 可以通过 `return false` 阻止
* @param raycaster - 点击对应的三维射线
* @param tapPosition - 点击对应的屏幕位置
* @param final - 是否手势结束
* @returns 可以通过 `return false` 阻止
*/
wantsTapGesture(raycaster: THREE.Raycaster, tapPosition: THREE.Vector2, final: boolean): void | false;
/**
* tap 手势(点击屏幕) 被触发
* @param raycaster - 点击对应的三维射线
* @param tapPosition - 点击对应的屏幕位置
* @param final - 是否手势结束
*/
tapGesture(raycaster: THREE.Raycaster, tapPosition: THREE.Vector2, final: boolean): void;
/**
* 意图要触发 dlbtap 手势(点击屏幕)， 可以通过 `return false` 阻止
* @param raycaster - 点击对应的三维射线
* @param tapPosition - 点击对应的屏幕位置
* @param final - 是否手势结束
* @returns 可以通过 `return false` 阻止
*/
wantsDblTapGesture(raycaster: THREE.Raycaster, tapPosition: THREE.Vector2, final: boolean): void | false;
/**
* dbltap 手势(点击屏幕) 被触发
* @param raycaster - 点击对应的三维射线
* @param tapPosition - 点击对应的屏幕位置
* @param final - 是否手势结束
*/
dblTapGesture(raycaster: THREE.Raycaster, tapPosition: THREE.Vector2, final: boolean): void;
/**
* 意图要触发 pinch 手势(双指缩放)，可以通过 `return false` 阻止
* @param scale - 缩放数值
* @param nextFov - 意图的fov变更
* @param final - 是否手势结束
* @returns 可以通过 `return false` 阻止
*/
wantsPinchGesture(scale: number, nextFov: number, final: boolean): void | false;
/**
* 意图要触发 press 手势(长按屏幕)， 可以通过 `return false` 阻止
* @param raycaster - 长按对应的三维射线
* @param tapPosition - 长按对应的屏幕位置
* @param duration - 长按持续时间
* @param final - 是否手势结束
* @returns 可以通过 `return false` 阻止
*/
wantsPressGesture(raycaster: THREE.Raycaster, tapPosition: THREE.Vector2, duration: number, final: boolean): void | false;
/**
* tap 手势(点击屏幕) 被触发
* @param raycaster - 点击对应的三维射线
* @param tapPosition - 点击对应的屏幕位置
* @param duration - 长按持续时间
* @param final - 是否手势结束
*/
pressGesture(raycaster: THREE.Raycaster, tapPosition: THREE.Vector2, duration: number, final: boolean): void;
/**
* pinch 手势(双指缩放) 被触发
* @param scale - 缩放数值
* @param fov - 意图的fov变更
* @param final - 是否手势结束
*/
pinchGesture(scale: number, fov: number, final: boolean): void;
/**
* 意图要触发 鼠标滚轮 可以通过 `return false` 阻止
* @param delta - 滚轮数值
* @param nextFov - 意图的fov变更
* @param final - 是否手势结束
* @returns 可以通过 `return false` 阻止
*/
wantsMouseWheel(delta: number, nextFov: number, final: boolean): void | false;
/**
* 鼠标滚轮被触发
* @param delta - 滚轮数值
* @param fov - 意图的fov变更
* @param final - 是否手势结束
*/
mouseWheel(delta: number, fov: number, final: boolean): void;
/**
* 意图要触发 pan 手势(滑动屏幕) 的惯性运动, 可以通过 `return false` 阻止
* @param pose - 意图的相机姿态
* @returns 可以通过 `return false` 阻止
*/
wantsInteriaPan(pose: Pose): void | false;
/**
* pan 手势(滑动屏幕) 的惯性运动
* @param pose - 意图的相机姿态
* @param final - 是否手势结束
*/
interiaPan(pose: Pose, final: boolean): void;
/**
* 意图要变化相机的可视角度 可以通过 `return false` 阻止
* @deprecated
* 建议通过 初始化设置的 `defaultFov`, `maxFov`, `minFov` 来限制
* @param fov - 意图要变化相机的可视角度
* @returns 可以通过 `return false` 阻止
*/
wantsChangeCameraFov(fov: number): void | false;
/**
* 相机姿态变化
* @param pose - 相机姿态
* @param userAction - 是否用户触发
*/
cameraUpdate(pose: Pose, userAction: boolean): void;
/**
* 相机姿态中可视角度变化
* @param fov - 相机的可视角度
* @param userAction - 是否用户触发
*/
cameraFovUpdate(fov: Pose["fov"], userAction: boolean): void;
/**
* 相机姿态中相机位置变化
* @param offset - 相机位置
* @param userAction - 是否用户触发
*/
cameraPositionUpdate(offset: Pose["offset"], userAction: boolean): void;
/**
* 相机姿态中相机方向变化
* @param coordinates - 相机姿态的俯仰角和偏航角
* @param userAction - 是否用户触发
*/
cameraDirectionUpdate(coordinates: Pick<Pose, "longitude" | "latitude">, userAction: boolean): void;
/**
* 鼠标焦点环位置被重新计算
* @param intersection - 焦点碰撞结果
* @param mesh - 焦点环 mesh
*/
intersectionOnModelUpdate(intersection: Intersection, mesh: THREE.Object3D): void;
/**
* 意图要展示鼠标焦点环，可以通过 `return false` 阻止
* @param raycaster - 射线
* @returns 可以通过 `return false` 阻止
*/
wantsShowIntersectionOnModel(raycaster: THREE.Raycaster): void | false;
/** 鼠标焦点环被隐藏 */
intersectionHidden(): void;
/**
* 意图要移动到某个点时, 可以通过 return false 阻止
* @param panoIndex - 意图要移动到点位
* @param options - 移动参数
* @param userAction - 是否用户触发
* @returns 可以通过 return false 阻止
*/
wantsMoveToPano(panoIndex: number, options: MovePanoOptions, userAction: boolean): void | false;
/**
* 同 wantsMoveToPano
* @description
* @param panoIndex - 意图要移动到点位
* @param options - 移动参数
* @param userAction - 是否用户触发
* @returns 可以通过 return false 阻止
*/
wantsToMoveToPano(panoIndex: number, options: MovePanoOptions, userAction: boolean): void;
/**
* 观察点位被选择
* @param panoIndex - 选择的点位
*/
panoSelected(panoIndex: number | null): void;
/**
* 开始加载并移动到某个观察点位
* @description
* 可 panoWillArrive 相比
* - moveToPano 在加载全景图资源前触发
* - panoWillArrive 在加载全景图资源后触发
* @param panoIndex - 移动到的点位
* @param userAction - 是否用户触发
*/
moveToPano(panoIndex: number, userAction: boolean): void;
/**
* 移动中， 会告知移动状态（耗时百分比）
* @param panoIndex - 将要移动到的点位下标
* @param prevPanoIndex - 上一个点位下标
* @param progress - 整个过程经度 [0-1]
*/
movingToPano(panoIndex: number, prevPanoIndex: number, progress: number): void;
/**
* 开始加载某个观察点的全景资源
* @param panoIndex - 移动到的点位
*/
panoWillLoad(panoIndex: number): void;
/**
* 某个观察点的全景资源加载完成
* @param panoIndex - 对应的点位
*/
panoLoaded(panoIndex: number): void;
/**
* 开始移动到某个观察点位
* @description
* 和 moveToPano 相比
* - moveToPano 在加载全景图资源前触发
* - panoWillArrive 在加载全景图资源后触发
* @param panoIndex - 移动到点位
* @param pose - 相机姿态
* @param userAction - 是否用户触发
*/
panoWillArrive(panoIndex: number, pose: Pose, userAction: boolean): void;
/**
* 移动到某个观察点位
* @param panoIndex - 移动到点位
* @param pose - 相机姿态
* @param userAction - 是否用户触发
*/
panoArrived(panoIndex: number, pose: Pose, userAction: boolean): void;
/**
* 某个观察点的全景资源加载失败
* @param error - 错误对象
* @param panoIndex - 对应的点位
*/
panoLoadError(error: Error, panoIndex: number): void;
/**
* 移动到某个观察点位被取消
* @description
* 这个有一些情况会导致
* - 移动过程中切换模态
* - 移动过程中 five 被析构
* - 移动过程点击切换到另一个点位
* @param panoIndex - 对应的点位
*/
moveToPanoCanceled(panoIndex: number): void;
/**
* 观察点的全景资源开始加载
* @param panoIndex - 加载点位
*/
textureStartLoad(panoIndex: number): void;
/**
* 观察点的全景资源加载中，可获取到进度
* @param progress - 加载进度 [0-1]
* @param panoIndex - 加载点位下标
*/
textureLoading(progress: number, panoIndex: number): void;
/**
* 观察点的全景资源加载被中止
* @param panoIndex - 加载点位
*/
textureAbort(panoIndex: number): void;
/**
* 观察点的全景资源加载失败
* @param error - 错误对象
* @param panoIndex - 加载点位
*/
textureError(error: Error, panoIndex: number): void;
/**
* 观察点的全景资源加载完成
* @param panoIndex - 加载点位
*/
textureLoaded(panoIndex: number, meta: (NetWorkMeta | null)[]): void;
/**
* webXR模式开始，webxr session完成坐标系矫正
*/
webXRSessionStart(): void;
/**
* webXR模式结束,webxr session销毁
*/
webXRSessionEnd(): void;
/**
* axes代表控制杆，axes数组的0-1元素分别代表左控制器的左（-1）右（1）,左控制器的上（-1）下（1），axes数组的2-3元素同理
*/
webXRControllerEvent(type: WebXRControllerType, key: WebXRControllerKey, params: WebXRControllerParams): void;
/**
* xr控制器的Axes原始实时数据状态
*/
webXRAxesUpdate(type: 'left' | 'right', param: WebXRAxesParams): void;
/**
* xr控制器的控制器射线更新
*/
webXRControllerRayUpdate(raycaster: {
leftRay?: THREE.Raycaster;
rightRay?: THREE.Raycaster;
}): void;
/**
* 准备加载 Work 数据
* @param input - 输入的 work
* @param work - 归一化的标准 work
* @param state - 加载时的姿态
*/
willLoad(input: any, work: Work, state: Partial<State>): void;
/**
* 开始加载 Work 数据
* @param input - 输入的 work
* @param work - 归一化的标准 work
* @param state - 加载时的姿态
*/
load(input: any, work: Work, state: Partial<State>): void;
/**
* 加载完 Work 数据
* @param input - 输入的 work
* @param work - 归一化的标准 work
*/
loaded(input: any, work: Work): void;
/**
* 当目标 state 变化时
* @param state - 当前姿态状态
* @param userAction - 是否用户触发
*/
stateChange(state: State, userAction: boolean): void;
/**
* 当前实时 state 变化时
* @param state - 当前姿态状态
* @param userAction - 是否用户触发
*/
currentStateChange(state: State, userAction: boolean): void;
/**
* 当 setState 方法被调用
* @param state - 当前姿态状态
*/
setState(state: State): void;
/**
* 当 state 被同步完成时
* @param state - 当前姿态状态
*/
stateSynced(state: State): void;
/**
* 模型开始加载
* @param workModel - 归一化的标准 work 中的 model 值
*/
modelWillLoad(workModel: WorkModel): void;
/**
* 模型加载错误
* @param error - 错误对象
* @param model - 加载完的 model
*/
modelLoadError(error: Error, model: Model): void;
/**
* 模型加载完成
* @param model - 加载完的 model
*/
modelLoaded(model: Model): void;
/**
* 模型楼层切换
* @param shownFloor - 模型楼层
*/
modelShownFloorChange(shownFloor: number | null, floorLength: number): void;
/**
* 渲染循环
* @param rendered - 是否渲染了
*/
renderFrame(rendered: boolean): void;
/**
* 意图要切换到某个模态， 可以通过 return false 阻止
* @param mode - 意图要切换到的模态
* @param prevMode - 当前模态
* @returns 可以通过 return false 阻止
*/
wantsChangeMode(mode: Mode, prevMode: Mode): void | false;
/**
* 模态切换完成
* @param mode - 切换到的模态
* @param prevMode - 上本质是一个模态
* @param panoIndex - 初始化动画结束后的点位下标
* @param toPose - 初始化动画结束后的状态
* @param userAction - 是否用户触发
*/
modeChange(mode: Mode, prevMode: Mode, panoIndex: number, toPose: Pose, userAction: boolean): void;
/**
* 帮助元素显应的变换
* @param visible - 帮助元素的是否开启
*/
helpersVisibleChange(visible: boolean): void;
/**
* 网络资源分析
* @param source - 资源地址
* @param state - 状态
* @param detail - 详情
*/
network(source: string, type: NetworkType, state: NetworkState, detail: string): void;
};
export declare function initLegacyEvent(five: Five): void;