@realsee/five 5.0.0-alpha.17 → 5.0.0-alpha.171

package/vue/index.d.ts

@@ -0,0 +1,461 @@
+import { AllowedComponentProps } from 'vue';
+import { ComponentCustomProps } from 'vue';
+import { ComponentOptionsMixin } from 'vue';
+import { DeepReadonly } from 'vue';
+import { DefineComponent } from 'vue';
+import { EventCallback } from '@realsee/five';
+import { ExtractPropTypes } from 'vue';
+import { Five } from '@realsee/five';
+import { FiveInitArgs } from '@realsee/five';
+import { Intersection } from '@realsee/five';
+import { Model } from '@realsee/five';
+import { Pose } from '@realsee/five';
+import { PropType } from 'vue';
+import { Ref } from 'vue';
+import { RendererElement } from 'vue';
+import { RendererNode } from 'vue';
+import { Scene } from '@realsee/five';
+import { State } from '@realsee/five';
+import * as THREE_2 from 'three';
+import { VNode } from 'vue';
+import { VNodeProps } from 'vue';
+import { Work } from '@realsee/five';
+import { WorkObserver } from '@realsee/five';
+
+/**
+ * Five 命令集合
+ */
+export declare interface FiveActionVueCallbacks {
+    /**
+     * 移动相机。（不触发点位移动）
+     * @description
+     * 如果动画中途被打断（用户触发行为，或者调用 setState, load, changeMode）的等
+     * 会 Promise.reject。运动完成则 Promise.resolve
+     * @param pose - 相机目标位置
+     * @param duration - 动画触发的时常
+     * @returns Promise 是否移动成功
+     */
+    updateCamera(pose: Pose, duration: number): Promise<void>;
+    /**
+     * 初始化 initBasisLoader
+     * @description
+     * 同初始化的 initBasisLoader 参数。用于初始化 basisLoader。
+     * basisLoader 只会初始化一次，一旦初始化则不会再修改。
+     *
+     * @param transcoderResourcePath - basis 解析器路径
+     * 如果不设置，使用默认解析器 basis 解析器。
+     * 可以传入解析器的 `resourcePath`, 则使用指定的解析器
+     * @example
+     * ```
+     * // 使用默认解析器
+     * initialBasisLoader();
+     *
+     * // 使用指定解析器
+     * // 会调用这个目录下的 basis_transcoder.js basis_transcoder.wasm 文件作为解析器
+     * initialBasisLoader("https://vr-public.realsee-cdn.cn/release/static/image/release/five/basis/");
+     * ```
+     */
+    initBasisLoader(transcoderResourcePath?: string): void;
+    /**
+     * 获取画面中的像素颜色
+     * @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;
+    /**
+     * 强制渲染
+     * @description
+     * 调用 `render()` 和 `needsRender()` 均可在按需渲染时，使得画面渲染一次
+     * 区别在于：
+     * - `needsRender()` 为在下帧渲染画面
+     * - `render()` 在当前帧渲染画面
+     * 推荐使用 `needsRender()`, 可以更加流畅。但是如果需要截图等同步操作，可以使用 `render()`
+     *
+     * @param callback - 渲染完成回调
+     */
+    render(callback?: () => void): void;
+    /**
+     * 下一帧渲染
+     * @description
+     * 调用 `render()` 和 `needsRender()` 均可在按需渲染时，使得画面渲染一次
+     * 区别在于：
+     * - `needsRender()` 为在下帧渲染画面
+     * - `render()` 在当前帧渲染画面
+     * 推荐使用 `needsRender()`, 可以更加流畅。但是如果需要截图等同步操作，可以使用 `render()`
+     */
+    needsRender(): void;
+    /**
+     * 预加载点位图片资源
+     * @param panoIndex - 观察点序号
+     * @param callback - 加载完成回调, 并传递加载用时。
+     * @returns 加载完成的 Promise 参数同 callback
+     */
+    preloadPano(panoIndex: 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 渲染区域组件
+ * @description Five 渲染区域组件，请在 FiveProvider 内使用
+ * @param width - 渲染区域的宽度
+ * @param height - 渲染区域的高度
+ * @returns Vue 元素
+ * @example
+ * ```typescript
+ * <FiveProvider :initialWork="work">
+ *  <FiveCanvas width="512" height="512"/>
+ * </FiveProvider>
+ * ```
+ */
+export declare const FiveCanvas: DefineComponent<    {
+width: {
+type: PropType<number>;
+required: true;
+};
+height: {
+type: PropType<number>;
+required: true;
+};
+}, () => VNode<RendererNode, RendererElement, {
+[key: string]: any;
+}>, unknown, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, VNodeProps & AllowedComponentProps & ComponentCustomProps, Readonly<ExtractPropTypes<    {
+width: {
+type: PropType<number>;
+required: true;
+};
+height: {
+type: PropType<number>;
+required: true;
+};
+}>>, {}>;
+
+export declare type FiveModelIntersectRaycaster = (raycaster: Ref<THREE_2.Raycaster> | THREE_2.Raycaster) => Ref<Intersection[]>;
+
+/**
+ * Five 实例化Five 组件
+ *
+ * 在 FiveProvider 下，可以使用 FiveCanvas 来创建渲染画布。
+ * 以及使用 useFiveState useFiveEventCallback等 Five Vue Composition API 来对 FiveProvider 进行操作
+ * @description Five 创建Five实例的组件
+ * @param FiveProviderComponent - Five 参数
+ * @example
+ * ```typescript
+ * <FiveProvider :initialWork="work">
+ *  <FiveCanvas width="512" height="512"/>
+ * </FiveProvider>
+ * ```
+ */
+export declare const FiveProvider: FiveProviderComponent;
+
+export declare type FiveProviderComponent = DefineComponent<{
+    work: PropType<Work>;
+    initialWork: PropType<Work | Promise<Work>>;
+    initialState: PropType<"inherit" | "initial" | Partial<Omit<State, "offset">>>;
+    initialUserAction: BooleanConstructor;
+    onWorkChange: PropType<(work: Work) => void>;
+    onStateChange: PropType<(state: State, userAction: boolean) => void>;
+    onCurrentStateChange: PropType<(state: State, userAction: boolean) => void>;
+    onError: PropType<(error: Error) => void>;
+    fiveInitArgs: {
+        type: PropType<Omit<FiveInitArgs, "renderer" | "scissor">>;
+        default: () => {};
+    };
+    style: ObjectConstructor;
+}, {
+    five: Readonly<Five>;
+}>;
+
+export declare type Project2d = (vector3: THREE_2.Vector3 | Ref<THREE_2.Vector3>, testModel: boolean) => Ref<THREE_2.Vector2 | null>;
+
+/**
+ * Five Vue Hooks: 获取 five 实例
+ * @description 不到万不得已，并不推荐直接使用。
+ * @deprecated 不到万不得已，并不推荐直接使用。
+ * @returns five 实例
+ */
+export declare function unsafe__useFiveInject(): Five;
+
+/**
+ * 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 panoIndex - 观察点序号
+ * // param callback - 加载完成回调, 并传递加载用时。
+ * // returns 加载完成的 Promise 参数同 callback
+ * preloadPano(panoIndex: number, 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();
+ * ```
+ */
+export declare function useFiveAction(): FiveActionVueCallbacks;
+
+/**
+ * Five Vue Hooks: 得到当前相机的方向（单位向量）
+ * @returns  当前相机方向的单位向量
+ */
+export declare function useFiveCameraDirection(): Ref<THREE_2.Vector3>;
+
+/**
+ * Five Vue Hooks: 得到当前相机的方向（射线对象）
+ * @returns 当前相机方向的射线对象
+ */
+export declare function useFiveCameraRaycaster(): Ref<THREE_2.Raycaster>;
+
+/**
+ * Five Vue Hooks: Five 的当前观测点
+ * @returns 当前观测点, 如果 work 未加载则为 null
+ * @example
+ * ```
+ * const observer = useFiveCurrentObserver();
+ * ```
+ */
+export declare function useFiveCurrentObserver(): Ref<WorkObserver | null>;
+
+/**
+ * Five Vue Hooks: Five 的实时状态
+ * @returns
+ * [ currentState: Five 的实时状态, setState: 设置 Five 的状态 ]
+ * @example
+ * ```
+ * const [ currentState, setState ] = useFiveCurrentState;
+ * ```
+ */
+export declare function useFiveCurrentState(): [
+currentState: Ref<State>,
+setState: (state: Partial<State> | ((prevState: State) => Partial<State>), immediately?: boolean, userAction?: boolean) => void
+];
+
+/**
+ * Five Vue Hooks: Five 事件监听
+ * 具体事件列表 请查看 Five.EventCallback
+ * @example
+ * ```
+ * useFiveEventCallback("cameraUpdate", pose => {});
+ * ```
+ */
+export declare function useFiveEventCallback<T extends keyof EventCallback>(name: T, callback: EventCallback[T]): void;
+
+/**
+ * Five Vue Hooks: Five 楼层
+ * @returns
+ * [ shownFloor: Five 当前显示的楼层， null 为都显示, showFloor: 设置显示楼层，不传参数为都显示 ]
+ * @example
+ * ```
+ * const [ shownFloor, showFloor ] = useFiveHelper;
+ * ```
+ */
+export declare function useFiveFloor(): [
+shownFloor: Ref<number | null>,
+totalFloorLength: Ref<number>,
+showFloor: (floorIndex?: number) => void
+];
+
+/**
+ * Five Vue Hooks: Five 帮助元素的隐藏/显示
+ * @returns
+ * [ helperVisible: Five 帮助元素是否显示, toggleHelperVisible: 设置 帮助元素的隐藏/显示 ]
+ * @example
+ * ```
+ * const [ helperVisible, toggleHelperVisible ] = useFiveHelper;
+ * ```
+ */
+export declare function useFiveHelper(): [
+helperVisible: Ref<boolean>,
+toggleHelperVisible: (visible: boolean) => void
+];
+
+/**
+ * Five Vue Hooks: 获取当前模型
+ */
+export declare function useFiveModel(): Ref<Model>;
+
+/**
+ * Five Vue Hooks: 获取当前模型的包围盒
+ */
+export declare function useFiveModelBounding(): Ref<THREE_2.Box3>;
+
+/**
+ * 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);
+ * ```
+ */
+export declare function useFiveModelIntersectRaycaster(): FiveModelIntersectRaycaster;
+
+/**
+ * Five Vue Hooks: 获取当前模型加载状态
+ * @returns
+ * "Loaded": 加载完成
+ * "Empty" 加载未完成
+ */
+export declare function useFiveModelReadyState(): Ref<"Loaded" | "Empty">;
+
+/**
+ * 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));
+ * ```
+ */
+export declare function useFiveProject2d(): Project2d;
+
+/**
+ * Five Vue Hooks: 获取scene
+ */
+export declare function useFiveScene(): Scene;
+
+/**
+ * Five Vue Hooks: Five 的目标状态
+ * @returns
+ * [ currentState: Five 的目标状态, setState: 设置 Five 的状态 ]
+ * @example
+ * ```
+ * const [ state, setState ] = useFiveState;
+ * ```
+ */
+export declare function useFiveState(): [
+curState: Ref<State>,
+setState: (state: Partial<State> | ((prevState: State) => Partial<State>), immediately?: boolean, userAction?: boolean) => void
+];
+
+/**
+ * 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 [ work, loadWork ] = useFiveWork;
+ * ```
+ */
+export declare function useFiveWork(): [
+work: DeepReadonly<Ref<Work | undefined>>,
+loadWork: (work: Work, state?: "inherit" | "initial" | Partial<Omit<State, "offset">>, duration?: number, userAction?: boolean) => Promise<void>
+];
+
+export { }