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

package/vue/hooks/useFiveAction.d.ts

@@ -0,0 +1,178 @@
+import { Pose, PanoId, Pano } from "@realsee/five";
+/**
+ * Five 命令集合
+ */
+interface FiveActionVueCallbacks {
+    /**
+     * 移动相机。（不触发点位移动）
+     * @description
+     * 如果动画中途被打断（用户触发行为，或者调用 setState, load, changeMode）的等
+     * 会 Promise.reject。运动完成则 Promise.resolve
+     * @param pose - 相机目标位置
+     * @param duration - 动画触发的时常
+     * @returns Promise 是否移动成功
+     */
+    updateCamera(pose: Pose, duration: number): 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;
+    /**
+     * 强制渲染
+     * @description
+     * 调用 `render()` 和 `needsRender()` 均可在按需渲染时，使得画面渲染一次
+     * 区别在于：
+     * - `needsRender()` 为在下帧渲染画面
+     * - `render()` 在当前帧渲染画面
+     * 推荐使用 `needsRender()`, 可以更加流畅。但是如果需要截图等同步操作，可以使用 `render()`
+     *
+     * @param callback - 渲染完成回调
+     */
+    render(callback?: () => void): void;
+    /**
+     * 下一帧渲染
+     * @description
+     * 调用 `render()` 和 `needsRender()` 均可在按需渲染时，使得画面渲染一次
+     * 区别在于：
+     * - `needsRender()` 为在下帧渲染画面
+     * - `render()` 在当前帧渲染画面
+     * 推荐使用 `needsRender()`, 可以更加流畅。但是如果需要截图等同步操作，可以使用 `render()`
+     */
+    needsRender(): void;
+    /**
+     * 预加载点位图片资源
+     * @param pano - 观察点
+     * @param callback - 加载完成回调, 并传递加载用时。
+     * @returns 加载完成的 Promise 参数同 callback
+     */
+    preloadPano(pano: Pano | PanoId | number, callback?: (costs: number) => void): Promise<number>;
+    /**
+    * 计算三维空间的点对应到屏幕的二维坐标
+    * @description
+    * 调用 `project2d()` 和 `useFiveProject2d()` 均可用于计算三维空间的点对应到屏幕的二维坐标
+    * 区别在于：
+    * - `project2d()` 只计算一次，入参改变或 cameraUpdate 时 不会更新值
+    * - `useFiveProject2d()` 通过 watch 监听入参和 cameraUpdate 变化，自动更新返回值
+    */
+    project2d(vector3: THREE.Vector3, testModel?: boolean | undefined): THREE.Vector2 | null;
+}
+/**
+ * Five Vue Hooks: 使用 Five 的命令
+ *
+ * @function updateCamera
+ * ```
+ * 移动相机。（不触发点位移动）
+ * 如果动画中途被打断（用户触发行为，或者调用 setState, load, changeMode）的等
+ * 会 Promise.reject。运动完成则 Promise.resolve
+ *
+ * // params pose - 相机目标位置
+ * // params duration - 动画触发的时常
+ * // params Promise - 是否移动成功
+ * updateCamera(pose: Pose, duration: number): Promise<void>
+ * ```
+ *
+ * @function initBasisLoader
+ * ```
+ * 初始化 initBasisLoader
+ * 同初始化的 initBasisLoader 参数。用于初始化 basisLoader。
+ * basisLoader 只会初始化一次，一旦初始化则不会再修改。
+ *
+ * // param transcoderResourcePath
+ * // 如果不设置，使用默认解析器 basis 解析器。
+ * // 可以传入解析器的 `resourcePath`, 则使用指定的解析器
+ * initBasisLoader(transcoderResourcePath?: string): void,
+ * ```
+ *
+ * @function getPixels
+ * ```
+ * 获取画面中的像素颜色
+ * // param x - 获取像素区域的起始坐标 x
+ * // param y - 获取像素区域的起始坐标 y
+ * // param width - 获取像素区域的宽度
+ * // param height - 获取像素区域的高度
+ * // param pixelRatio - 获取区域的像素比
+ * // returns rgba颜色平铺的 Uint8Array
+ * getPixels(x: number, y: number, width: number, height: number, pixelRatio?: number): Uint8Array,
+ * ```
+ *
+ * @function render
+ * ```
+ * 强制渲染
+ * 调用 render() 和 needsRender() 均可在按需渲染时，使得画面渲染一次
+ * 区别在于：
+ * - needsRender() 为在下帧渲染画面
+ * - render() 在当前帧渲染画面
+ * 推荐使用 needsRender(), 可以更加流畅。但是如果需要截图等同步操作，可以使用 render()
+ *
+ * // param callback 渲染完成回调
+ * render(callback?: () => void): void,
+ * ```
+ *
+ * @function needsRender
+ * ```
+ * 下一帧渲染
+ * 调用 render() 和 needsRender() 均可在按需渲染时，使得画面渲染一次
+ * 区别在于：
+ * - needsRender() 为在下帧渲染画面
+ * - render() 在当前帧渲染画面
+ * 推荐使用 needsRender(), 可以更加流畅。但是如果需要截图等同步操作，可以使用 render()
+ * needsRender(): void,
+ * ```
+ *
+ * @function preloadPano
+ * ```
+ * 预加载点位图片资源
+ * // param panoId - 观察点
+ * // param callback - 加载完成回调, 并传递加载用时。
+ * // returns 加载完成的 Promise 参数同 callback
+ * preloadPano(panoId: WorkPanoId, callback?: (costs: number) => void): Promise<number>
+ * ```
+ *
+ * @function project2d
+ * ```
+ * 计算三维空间的点对应到屏幕的二维坐标
+ * 调用 `project2d()` 和 `useFiveProject2d()` 均可用于计算三维空间的点对应到屏幕的二维坐标
+ * 区别在于：
+ * - `project2d()` 只计算一次，入参改变或 cameraUpdate 时 不会更新值
+ * - `useFiveProject2d()` 通过 watch 监听入参和 cameraUpdate 变化，自动更新返回值
+ * project2d(vector3: THREE.Vector3, testModel?: boolean ): THREE.Vector2
+ * ```
+ *
+ * @example
+ * ```
+ * const { updateCamera, initBasisLoader, getPixels, render, needsRender, preloadPano, project2d } = useFiveAction();
+ * ```
+ */
+declare function useFiveAction(): FiveActionVueCallbacks;
+export { useFiveAction, FiveActionVueCallbacks };

package/vue/hooks/useFiveCameraDirection.d.ts

@@ -0,0 +1,8 @@
+import * as THREE from "three";
+import { Ref } from "vue";
+/**
+ * Five Vue Hooks: 得到当前相机的方向（单位向量）
+ * @returns  当前相机方向的单位向量
+ */
+declare function useFiveCameraDirection(): Ref<THREE.Vector3>;
+export { useFiveCameraDirection };

package/vue/hooks/useFiveCameraRaycaster.d.ts

@@ -0,0 +1,8 @@
+import * as THREE from "three";
+import { Ref } from "vue";
+/**
+ * Five Vue Hooks: 得到当前相机的方向（射线对象）
+ * @returns 当前相机方向的射线对象
+ */
+declare function useFiveCameraRaycaster(): Ref<THREE.Raycaster>;
+export { useFiveCameraRaycaster };

package/vue/hooks/useFiveCurrentObserver.d.ts

@@ -0,0 +1,12 @@
+import { WorkObserver } from "@realsee/five";
+import { Ref } from "vue";
+/**
+ * Five Vue Hooks: Five 的当前观测点
+ * @returns 当前观测点, 如果 work 未加载则为 null
+ * @example
+ * ```
+ * const observer = useFiveCurrentObserver();
+ * ```
+ */
+declare function useFiveCurrentObserver(): Ref<WorkObserver | undefined>;
+export { useFiveCurrentObserver };

package/vue/hooks/useFiveCurrentState.d.ts

@@ -0,0 +1,16 @@
+import { State } from "@realsee/five";
+import { Ref } from "vue";
+/**
+ * Five Vue Hooks: Five 的实时状态
+ * @returns
+ * [ currentState: Five 的实时状态, setState: 设置 Five 的状态 ]
+ * @example
+ * ```
+ * const [ currentState, setState ] = useFiveCurrentState;
+ * ```
+ */
+declare function useFiveCurrentState(): [
+    currentState: Ref<State>,
+    setState: (state: Partial<State> | ((prevState: State) => Partial<State>), immediately?: boolean, userAction?: boolean) => void
+];
+export { useFiveCurrentState };

package/vue/hooks/useFiveEventCallback.d.ts

@@ -0,0 +1,11 @@
+import { EventCallback } from "@realsee/five";
+/**
+ * Five Vue Hooks: Five 事件监听
+ * 具体事件列表 请查看 Five.EventCallback
+ * @example
+ * ```
+ * useFiveEventCallback("cameraUpdate", pose => {});
+ * ```
+ */
+declare function useFiveEventCallback<T extends keyof EventCallback>(name: T, callback: EventCallback[T]): void;
+export { useFiveEventCallback };

package/vue/hooks/useFiveFloor.d.ts

@@ -0,0 +1,16 @@
+import { Ref } from "vue";
+/**
+ * Five Vue Hooks: Five 楼层
+ * @returns
+ * [ shownFloor: Five 当前显示的楼层， null 为都显示, showFloor: 设置显示楼层，不传参数为都显示 ]
+ * @example
+ * ```
+ * const [ shownFloor, showFloor ] = useFiveHelper;
+ * ```
+ */
+declare function useFiveFloor(): [
+    shownFloor: Ref<number | null>,
+    totalFloorLength: Ref<number>,
+    showFloor: (floorIndex?: number) => void
+];
+export { useFiveFloor };

package/vue/hooks/useFiveHelper.d.ts

@@ -0,0 +1,15 @@
+import { Ref } from "vue";
+/**
+ * Five Vue Hooks: Five 帮助元素的隐藏/显示
+ * @returns
+ * [ helperVisible: Five 帮助元素是否显示, toggleHelperVisible: 设置 帮助元素的隐藏/显示 ]
+ * @example
+ * ```
+ * const [ helperVisible, toggleHelperVisible ] = useFiveHelper;
+ * ```
+ */
+declare function useFiveHelper(): [
+    helperVisible: Ref<boolean>,
+    toggleHelperVisible: (visible: boolean) => void
+];
+export { useFiveHelper };

package/vue/hooks/useFiveModel.d.ts

@@ -0,0 +1,7 @@
+import { Model } from "@realsee/five";
+import { Ref } from "vue";
+/**
+ * Five Vue Hooks: 获取当前模型
+ */
+declare function useFiveModel(): Ref<Model>;
+export { useFiveModel };

package/vue/hooks/useFiveModelBounding.d.ts

@@ -0,0 +1,7 @@
+import * as THREE from "three";
+import { Ref } from "vue";
+/**
+ * Five Vue Hooks: 获取当前模型的包围盒
+ */
+declare function useFiveModelBounding(): Ref<THREE.Box3>;
+export { useFiveModelBounding };

package/vue/hooks/useFiveModelIntersectRaycaster.d.ts

@@ -0,0 +1,23 @@
+import { Intersection } from "@realsee/five";
+import * as THREE from "three";
+import { Ref } from "vue";
+type FiveModelIntersectRaycaster = (raycaster: Ref<THREE.Raycaster> | THREE.Raycaster) => Ref<Intersection[]>;
+/**
+ * Five Vue Hooks: 获取当前模型碰撞检测方法
+ *
+ * @function fiveModelIntersectRaycaster
+ * ```
+ * 计算模型射线碰撞检测
+ * // param raycaster THREE 射线对象
+ * // param floors 和某一楼层做碰撞检测， 不传为和所有楼层做碰撞检测
+ * // returns 返回碰撞
+ * intersectRaycaster(raycaster: THREE.Raycaster, floors?: number | number[]): Intersection[]
+ * ```
+ * @example
+ * ```
+ * const fiveModelIntersectRaycaster = useFiveModelIntersectRaycaster();
+ * const intersects = fiveModelIntersectRaycaster(raycaster);
+ * ```
+ */
+declare function useFiveModelIntersectRaycaster(): FiveModelIntersectRaycaster;
+export { useFiveModelIntersectRaycaster, FiveModelIntersectRaycaster };

package/vue/hooks/useFiveModelReadyState.d.ts

@@ -0,0 +1,9 @@
+import { Ref } from "vue";
+/**
+ * Five Vue Hooks: 获取当前模型加载状态
+ * @returns
+ * "Loaded": 加载完成
+ * "Empty" 加载未完成
+ */
+declare function useFiveModelReadyState(): Ref<"Loaded" | "Empty">;
+export { useFiveModelReadyState };

package/vue/hooks/useFiveProject2d.d.ts

@@ -0,0 +1,26 @@
+import * as THREE from "three";
+import { Ref } from "vue";
+type Project2d = (vector3: THREE.Vector3 | Ref<THREE.Vector3>, testModel: boolean) => Ref<THREE.Vector2 | null>;
+/**
+ * Five Vue Hooks: 计算三维坐标对应到屏幕二维坐标
+ *
+ * @function project2d
+ * ```
+ * 计算三维坐标对应到屏幕二维坐标
+ * `useFiveProject2d()` 通过 watch 监听入参和 cameraUpdate 变化，自动更新返回值
+ * 多次调用时会创建多个 watch 监听，推荐 const { project2d } = useFiveAction();
+ * // param vector 三维的坐标
+ * // param testModel 是否和模型检测，如果检测，则被模型遮挡会返回 null
+ * // returns 三维的坐标 或者 null
+ * project2d(vector: THREE.Vector3 | Ref<THREE.Vector3>, testModel: boolean)
+ * v2: Ref<THREE.Vector2 | null>
+ * ```
+ *
+ * @example
+ * ```
+ * const project2d  = useFiveProject2d();
+ * project2d(new THREE.Vector3(0, 0, 0));
+ * ```
+ */
+declare function useFiveProject2d(): Project2d;
+export { useFiveProject2d, Project2d };

package/vue/hooks/useFiveScene.d.ts

@@ -0,0 +1,6 @@
+import { Scene } from "@realsee/five";
+/**
+ * Five Vue Hooks: 获取scene
+ */
+declare function useFiveScene(): Scene;
+export { useFiveScene };

package/vue/hooks/useFiveState.d.ts

@@ -0,0 +1,16 @@
+import { State } from "@realsee/five";
+import { Ref } from "vue";
+/**
+ * Five Vue Hooks: Five 的目标状态
+ * @returns
+ * [ currentState: Five 的目标状态, setState: 设置 Five 的状态 ]
+ * @example
+ * ```
+ * const [ state, setState ] = useFiveState;
+ * ```
+ */
+declare function useFiveState(): [
+    curState: Ref<State>,
+    setState: (state: Partial<State> | ((prevState: State) => Partial<State>), immediately?: boolean, userAction?: boolean) => void
+];
+export { useFiveState };

package/vue/hooks/useFiveWork.d.ts

@@ -0,0 +1,30 @@
+import { Work, Works, State } from "@realsee/five";
+import { Ref, DeepReadonly } from "vue";
+/**
+ * Five Vue Hooks: 获取/设置当前的 Work
+ *
+ * @returns
+ * [ work: 获取当前的 Work, loadWork: 设置 Work ]
+
+* @function loadWork
+ * ```
+ * 加载 Work 数据
+ * // param work Work 数据
+ * // param state 初始化姿态
+ * //  - "inherit" 使用当前姿态
+ * //  - "initial" 使用 Work 数据中的 initial 姿态
+ * //  - State 自定义姿态
+ * // param duration 切换时间
+ * (work: Work, state?: "inherit" | "initial" | Partial<Omit<State, "offset">>, duration?: number) => void
+ * ```
+ *
+ * @example
+ * ```
+ * const [ works, loadWorks ] = useFiveWorks;
+ * ```
+ */
+declare function useFiveWorks(): [
+    works: DeepReadonly<Ref<Works | undefined>>,
+    loadWorks: (work: Work | Work[], state?: "inherit" | "initial" | Partial<Omit<State, "offset">>, duration?: number, userAction?: boolean) => Promise<void>
+];
+export { useFiveWorks };