Five.js

贝壳如视三维渲染框架

什么是Five

Five是贝壳如视(realsee.com) 提供的在浏览器中运行的三维空间渲染 Javascript SDK。您可以通过如视开发者中心的数据服务，并结合Five，制作丰富多彩的三维空间应用。

并且Five提供了一系列的方法、事件、生命周期函数。您可以方便地基于Five进行二次开发，并结合到您自身的项目中，为您的项目添砖加瓦。

Five通过 TypeScript 编写，保证开发的质量以及编程体验，推荐通过 Visual Studio Code、WebStorm 等现代源代码编辑器，您将可以体验到友好的代码提示以及自动补全。

Five还提供了完善的 React Hooks API ，可以方便的通过 React 开发复杂的响应式数据应用。当然直接使用Five开发也是没有问题的。

安装Five

Five提供通过 npm 的方式安装。Five基于 Three.js, 所以同时您需要安装相关依赖。

目前依赖的three版本为 115 ~ 117 的版本

npm install @realsee/five three@0.117.1

如果您使用React Hooks API，那么也请同时安装React的相关依赖。

npm install @realsee/five three@0.117.1 react react-dom @types/react @types/react-dom

接下来便可以在您的项目使用Five了。

import { Five } from "@realsee/five";
// 如果您使用 React Hoos API
import { useFiveState } from "@realsee/five/react";

浏览器兼容性

Safari	Safari on iOS	Chrome	Chrome for Android	Edge	Firefox
>= 9	>= 9	>= 49	>= 93	>= 13	>= 45

快速上手

Five提供了快速上手体验的项目生成工具，您可以通过他熟悉Five的功能以及尝试基于Five开发功能。

先创建一个文件夹five-quick-start, 作为项目根目录并且使用 npm init 命令初始化一个工程。

mkdir five-quick-start && cd five-quick-start && npm init -y

安装Five

npm install @realsee/five

通过Five的内置的five-quick-start-init脚本来快速补完当前项目

npx five-quick-start-init

项目的文件结构如下

.
├── README.md
├── assets                   静态文件（测试数据）
│   ├── data0.json
│   └── data1.json
├── index.html               页面模版
├── index.tsx                逻辑代码
├── package.json             npm 包管理描述
├── tsconfig.json            typescript 配置
├── webpack.config.js        webpack 开发环境配置
└── webpack.production.js    webpack 生产配置

通npm script运行测试环境

npm run dev

默认将会在 port: 3000 开启 webpack dev server。您也可以在 webpack.config.js 中修改配置。

现在可以打来浏览器 http://0.0.0.0:3000 来看看项目初始化的效果了。您可以修改代码来体验一下如何使用Five来二次开发。

如何使用Five

Five的简单使用样例:

import { Five } from "@realsee/five";

// 构造函数的具体参数见文档
const five = new Five();

// 将渲染视图的 canvas 添加到 DOM 中
five.appendTo(document.getElementById('app')!);

// 如果显示区域需要变动，在变动时请调用 refresh 重置显示参数
window.addEventListener('resize', () => five.refresh());

// 获取三维空间的 Work 数据，加载进来
// Work 数据可以通过如视开发者中心获取
fetch(`./work.json`)
  .then(res => res.json())
  .then(work => five.load(work));

其他的 Five API 待补充

在React框架中使用Five

在React框架中使用Five的简单使用样例:

import * as React from "react";
import * as ReactDOM from "react-dom";
import {Five, Work, parseWork} from "@realsee/five";
import {createFiveProvider, FiveCanvas} from "@realsee/five/react";

// 创建 Provider, 参数与 new Five 参数类似
// 构造函数的具体参数见文档
const FiveProvider = createFiveProvider();

const App: React.FC = () => {

  // 声明 State: Work
  const [work, setWork] = React.useState<Work | null>(null);

  // 声明 State: Size<{width, height}>
  const [size, setSize] = React.useState({
    width: window.innerWidth,
    height: window.innerHeight
  })

  // 获取三维空间的 Work 数据，加载进来
  const loadWork = React.useCallback((url: string) => {
    fetch(url)
            .then(res => res.json())
            .then(data => setWork(parseWork(data)));
  }, []);

  React.useEffect(() => {
    loadWork("./data0.json");
  }, []);

  // 如果显示区域需要变动，在变动时请调用 FiveCanvas 的 size
  React.useEffect(() => {
    const onResize = () => {
      setSize({
        width: window.innerWidth,
        height: window.innerHeight
      });
    }
    window.addEventListener("resize", onResize, false);
    return () => window.removeEventListener("resize", onResize, false);
  });

  if (work) {
    {/*
      在 FiveProvider 内承载一个 Five 实例，
      在他内部的组件可以使用 Five React Hook API 来获取/设置/操作 他
      一个页面中也可以有多个 FiveProvider
    */}
    return <FiveProvider initialWork={work}>
      {/*
        将渲染视图的 canvas 添加到 DOM 中
        FiveCanvas 需要出现在 FiveProvider 内，他将渲染 FiveProvider 的视图
        这样的设计可以实现不同的 DOM 层级结构
        在 FiveProvider 内的其他组件也可以使用 Five React Hook API 来获取/设置/操作 他外部的 FiveProvider
      */}
      <FiveCanvas width={size.width} height={size.height}/>
    </FiveProvider>
  }
  return null;
}

ReactDOM.render(<App></App>, document.getElementById("app"));

其他的Five React Hook API文档建设中...

Five API文档

欢迎查看 Five API 文档。

该文档由 TypeDoc 生成，您可以详细查看 api 使用方式，调用参数，数据结构。

相关名词解释

什么是Work

Work是如视开发者中心提供的对于一个三维空间的描述。是通过如视硬件设备（如视扫描仪、如视Lite全景相机、如视VR App ）扫描并处理之后用于三维空间展示的数据。

Work以JSON作为数据格式Five框架可以解析Work数据并展示。一个Five实例每次可以载入并展示一个Work。并且也可以在不同的Work之间动态切换。

Work的数据样例如下

{
  "initial": {
    "mode": "Panorama",
    "pano_index": 6,
    "longitude": 2.6869287662553916,
    "latitude": 0,
    "fov": 95
  },
  "model": {
    "file_url": "https:\/\/vrlab-public.ljcdn.com\/release\/auto3dhd\/a62e1ebf7d013f7df117551a14af79fc\/model\/auto3d-DJaa08PIzN4JYluXQ1j2VS.at3d",
    "material_textures": [
      "https:\/\/vrlab-public.ljcdn.com\/release\/auto3dhd\/a62e1ebf7d013f7df117551a14af79fc\/materials\/texture_0.jpg",
      "https:\/\/vrlab-public.ljcdn.com\/release\/auto3dhd\/a62e1ebf7d013f7df117551a14af79fc\/materials\/texture_1.jpg",
      "https:\/\/vrlab-public.ljcdn.com\/release\/auto3dhd\/a62e1ebf7d013f7df117551a14af79fc\/materials\/texture_2.jpg",
      "https:\/\/vrlab-public.ljcdn.com\/release\/auto3dhd\/a62e1ebf7d013f7df117551a14af79fc\/materials\/texture_3.jpg",
      "https:\/\/vrlab-public.ljcdn.com\/release\/auto3dhd\/a62e1ebf7d013f7df117551a14af79fc\/materials\/texture_4.jpg",
      "https:\/\/vrlab-public.ljcdn.com\/release\/auto3dhd\/a62e1ebf7d013f7df117551a14af79fc\/materials\/texture_5.jpg",
      "https:\/\/vrlab-public.ljcdn.com\/release\/auto3dhd\/a62e1ebf7d013f7df117551a14af79fc\/materials\/texture_6.jpg",
      "https:\/\/vrlab-public.ljcdn.com\/release\/auto3dhd\/a62e1ebf7d013f7df117551a14af79fc\/materials\/texture_7.jpg",
      "https:\/\/vrlab-public.ljcdn.com\/release\/auto3dhd\/a62e1ebf7d013f7df117551a14af79fc\/materials\/texture_8.jpg",
      "https:\/\/vrlab-public.ljcdn.com\/release\/auto3dhd\/a62e1ebf7d013f7df117551a14af79fc\/materials\/texture_9.jpg"
    ]
  },
  "panorama": {
    "list": [
      {
        "up": "https:\/\/vrlab-public.ljcdn.com\/release\/auto3dhd\/a62e1ebf7d013f7df117551a14af79fc\/images\/cube_2048\/0\/2257f0f0b29d5b00ff01934ce51aaa35\/0_u.jpg",
        "down": "https:\/\/vrlab-public.ljcdn.com\/release\/auto3dhd\/a62e1ebf7d013f7df117551a14af79fc\/images\/cube_2048\/0\/2257f0f0b29d5b00ff01934ce51aaa35\/0_d.jpg",
        "left": "https:\/\/vrlab-public.ljcdn.com\/release\/auto3dhd\/a62e1ebf7d013f7df117551a14af79fc\/images\/cube_2048\/0\/2257f0f0b29d5b00ff01934ce51aaa35\/0_l.jpg",
        "right": "https:\/\/vrlab-public.ljcdn.com\/release\/auto3dhd\/a62e1ebf7d013f7df117551a14af79fc\/images\/cube_2048\/0\/2257f0f0b29d5b00ff01934ce51aaa35\/0_r.jpg",
        "front": "https:\/\/vrlab-public.ljcdn.com\/release\/auto3dhd\/a62e1ebf7d013f7df117551a14af79fc\/images\/cube_2048\/0\/2257f0f0b29d5b00ff01934ce51aaa35\/0_f.jpg",
        "back": "https:\/\/vrlab-public.ljcdn.com\/release\/auto3dhd\/a62e1ebf7d013f7df117551a14af79fc\/images\/cube_2048\/0\/2257f0f0b29d5b00ff01934ce51aaa35\/0_b.jpg"
      },
      {
        "up": "https:\/\/vrlab-public.ljcdn.com\/release\/auto3dhd\/a62e1ebf7d013f7df117551a14af79fc\/images\/cube_2048\/1\/ecb554bb1c122fa90186d176ccfecde4\/1_u.jpg",
        "down": "https:\/\/vrlab-public.ljcdn.com\/release\/auto3dhd\/a62e1ebf7d013f7df117551a14af79fc\/images\/cube_2048\/1\/ecb554bb1c122fa90186d176ccfecde4\/1_d.jpg",
        "left": "https:\/\/vrlab-public.ljcdn.com\/release\/auto3dhd\/a62e1ebf7d013f7df117551a14af79fc\/images\/cube_2048\/1\/ecb554bb1c122fa90186d176ccfecde4\/1_l.jpg",
        "right": "https:\/\/vrlab-public.ljcdn.com\/release\/auto3dhd\/a62e1ebf7d013f7df117551a14af79fc\/images\/cube_2048\/1\/ecb554bb1c122fa90186d176ccfecde4\/1_r.jpg",
        "front": "https:\/\/vrlab-public.ljcdn.com\/release\/auto3dhd\/a62e1ebf7d013f7df117551a14af79fc\/images\/cube_2048\/1\/ecb554bb1c122fa90186d176ccfecde4\/1_f.jpg",
        "back": "https:\/\/vrlab-public.ljcdn.com\/release\/auto3dhd\/a62e1ebf7d013f7df117551a14af79fc\/images\/cube_2048\/1\/ecb554bb1c122fa90186d176ccfecde4\/1_b.jpg"
      }
    ],
  },
  "observers": [
    {
      "visible_nodes": [ 1 ],
      "accessible_nodes": [ 1 ],
      "quaternion": {
        "w": 0.45076583925142194,
        "x": 0.010070951976936936,
        "y": -0.8925839597148215,
        "z": -0.0016154299986102319
      },
      "standing_position": [
        -6.956049919128418,
        -1.3924440682333898,
        1.6591600179672241
      ],
      "position": [
        -6.956049919128418,
        -0.10312400013208389,
        1.6591600179672241
      ],
      "floor_index": 0
    },
    {
      "visible_nodes": [ 0 ],
      "accessible_nodes": [ 0 ],
      "index": 1,
      "quaternion": {
        "w": -0.9884643083591809,
        "x": -0.0038900979633806664,
        "y": 0.1512670435365699,
        "z": -0.006439990839033269
      },
      "standing_position": [
        -6.176340103149414,
        -1.380554749576384,
        2.179759979248047
      ],
      "position": [
        -6.176340103149414,
        -0.10025200247764587,
        2.179759979248047
      ],
      "floor_index": 0,
    }
  ]
}

Work 的数据说明

initial: 初始化数据，是一个 State 数据。描述Work被加载初始状态的位姿，也叫做VR的初始视角
- mode: 模态
- pano_index: 初始化点位
- longitude: 相机的水平角
- latitude: 相机的偏航角
- fov: 相机垂直方向的可视角度
model: 三维模型
- file_url: 三维模型的资源地址，文件为 .at3d 为如视定制的模型格式
- material_textures: 三维模型的贴图资源地址
panorama: 全景彩色信息
- list:
  - up / down / left / right / front / back: 全景彩色信息以 cubemap 方式存储和使用。
observers: 采集点信息
- visible_nodes: 采集点之间的可见性列表
- accessible_nodes: 采集点之间的连通性列表
- quaternion: 采集点与模型坐标的旋转偏移量
- standing_position: 采集点地面坐标
- position: 采集点坐标
- floor_index: 采集点楼层

什么是 Five State

State是Five框架用于描述状态的数据结构。他包含了模态、位于的采集点位、相机的方向、相机可视角度的信息。您可以使用State来操作Five或者获取Five当前的状态。

interface State {
  "mode": Five.Mode,
  "panoIndex": number,
  "longitude": number,
  "latitude": number,
  "fov": number,
  "distanace": number,
  "offset": THREE.Vector3,
}

State的数据描述

mode: 当前的模态 Five 常用有 5 种模态，可以使用 Five.Mode 获得
- Panorama: 全景游走模态，该模态下视图将在采集点间游走，手势操作可以旋转/放大视角/切换采集点，适合查看采集的全景信息。
- Floorplan: 空间总览模态, 该模态下视图以模型为中心，手势操作可以旋转/放大模型/切换楼层，适合查看模型的整体效果。
- Topview: 户型图模态，该模态下视图以模型为中心，垂直俯视模型，手势操作可以平移/放大模型/切换楼层，适合查看模型平面结构。
- Model: 模型游走模态，该模态下视图将在模型中自由游走，手势操作可以旋转/放大视角/位移，适合查看模型的细节，做一些定位操作。
- Mapview: 地图模态, 该模态下视图将类似三维地图，手势操作可以旋转/放大视角/位移，适合查看模型的细节。适合展示小区，工厂等较大的模型。
- VRPanorama: VR 眼镜模态，该模态下可以使用 Cardboard 眼镜或者他的第三方衍生产品，实现 VR 虚拟显示效果。
- XRPanorama: XR 眼镜模态，该模态下可以使用头戴显示设备比如 Pico, Meta Quest 等，实现沉浸式体验。
panoIndex: 采集点位
longitude / latitude: 相机的水平角 / 相机的偏航角（弧度），我们使用类似经纬度的方式描述相机位置。
fov: 相机垂直方向的可视角度 (角度)
distance: 相机距 offset 的距离
offset: 相机看向的目标

模型坐标的转换说明

目前涉及到的模型类型 at3d / domez / 3d-tile(b3dm, pnts, glb)

枚举说明

world: five.scene 场景下的坐标。属于 view 下的绝对坐标。坐标的上方向是 Y 轴，单位米。
local: 单个模型的相对坐标。坐标的上方向是 Y 轴，单位米。单个模型受到 work.transform 的影响会产生一定的位姿变化进行项目拼接（比如沙盘项目）。这种情况下，会与 world 有一定偏转。
enu: 模型描述坐标（East-North-Up）。坐标的上方向是 Z 轴，单位米。需要在算法模型输入/输出时使用这个坐标系。
ecef: 模型在地球的坐标系（Earth-centered, Earth-fixed）。坐标的上方向是 Z 轴并且固定是北，单位米。
lla: 模型在地球的经纬高度 (Latitude-Longitude-Altitude)。经纬度单位是弧度，高度单位是米。

数据来源

转换:

local 与 world 的转换依赖 work.transform
local 与 enu 的转换是固定的 yUp 转 zUp
enu 与 ecef 依赖 tileset.json 中 rootMeta.coordinate.pose_ecef_to_enu / rootMeta.coordinate.pose_enu_to_ecef。如果缺损，则使用 a=6378137.0;invf=298.257223563 的椭球近似计算
lla 通过 a=6378137.0;invf=298.257223563 的椭球近似计算

椭球近似计算: (enu + lla) 与 ecef 可以相互推导。

转换关系

在 five 环境下，通过 viewLayer 对象，即 five.models[number].viewLayer[number].scene 转化。提供对应方法。
- localToWorld(vector: THREE.Vector3): THREE.Vector3
- worldToLocal(vector: THREE.Vector3): THREE.Vector3
- localToEnu(vector: THREE.Vector3): THREE.Vector3
- enuToLocal(vector: THREE.Vector3): THREE.Vector3
- localToEcef(vector: THREE.Vector3): THREE.Vector3
- ecefToLocal(vector: THREE.Vector3): THREE.Vector3
- localToLla(vector: THREE.Vector3): THREE.Vector3
- llaToLocal(vector: THREE.Vector3): THREE.Vector3
- worldToEnu(vector: THREE.Vector3): THREE.Vector3
- enuToWorld(vector: THREE.Vector3): THREE.Vector3
- worldToEcef(vector: THREE.Vector3): THREE.Vector3
- ecefToWorld(vector: THREE.Vector3): THREE.Vector3
- worldToLla(vector: THREE.Vector3): THREE.Vector3
- llaToWorld(vector: THREE.Vector3): THREE.Vector3

这些函数均为直接修改传入 vector。如果要保持原先的数据，请实现 vector.clone()。

位置拾取

通过 intersectRaycaster 方法得到的 Intersection 在 world 坐标系下，并返回对应的 model 与 viewLayer。

与算法数据对接

目前约定为，算法的模型输入输出均使用 enu 坐标系。

@realsee/five

Five.js

什么是Five

安装Five

浏览器兼容性

快速上手

如何使用Five

在React框架中使用Five

Five API文档

相关名词解释

什么是Work

什么是 Five State

模型坐标的转换说明

枚举说明

数据来源

转换关系

位置拾取

与算法数据对接

Readme

Keywords

Package Sidebar

Install

Weekly Downloads

Version

License

Unpacked Size

Total Files

Last publish

Collaborators

@realsee/five

Five.js

什么是Five

安装Five

浏览器兼容性

快速上手

如何使用Five

在React框架中使用Five

Five API文档

相关名词解释

什么是Work

什么是 Five State

模型坐标的转换说明

枚举说明

数据来源

转换关系

位置拾取

与算法数据对接

Readme

Keywords

Package Sidebar

Install

DownloadsWeekly Downloads

Version

License

Unpacked Size

Total Files

Last publish

Collaborators

Weekly Downloads