@realsee/five 5.0.0-alpha.11 → 5.0.0-alpha.112

package/README.md

@@ -1,32 +1,36 @@
-# Five -- 贝壳如视三维渲染框架
+# Five.js
 
-## 什么是 Five
+[![npm version](https://img.shields.io/npm/v/@realsee/five.svg?style=flat-square&logo=npm&label=npm%20install%20@realsee/five)](https://www.npmjs.com/package/@realsee/five)
 
-Five 是 [贝壳如视(realsee.com)](https://realsee.com) 提供的在浏览器中运行的三维空间渲染 Javascript SDK。您可以通过[如视开放平台](http://developers.realsee.com)的数据服务，并结合 Five，制作丰富多才的三维空间应用。
+贝壳如视三维渲染框架
 
-并且 Five 提供了一系列的方法、事件、生命周期函数。您可以方便地基于 Five 进行二次开发，并结合到您自身的项目中，为您的项目添砖加瓦。
+## 什么是**Five**
 
-Five 通过 typescript 编写，保证开发的质量以及编程体验，推荐通过 [vs code](https://code.visualstudio.com)、[webstorm](https://www.jetbrains.com/webstorm/) 等现代编辑器 / IDE，您将可以体验到友好的代码提示以及自动补全。
+**Five**是 [贝壳如视(realsee.com)](https://realsee.com) 提供的在浏览器中运行的三维空间渲染 Javascript SDK。您可以通过[如视开发者中心](https://developers.realsee.com)的数据服务，并结合**Five**，制作丰富多彩的三维空间应用。
 
-Five 还提供了完善的 [React Hooks API](https://reactjs.org/docs/hooks-intro.html)，可以方便的通过 [React](https://reactjs.org) 开发复杂的响应式数据应用。当然直接使用 Five 开发也是没有问题的。
+并且**Five**提供了一系列的方法、事件、生命周期函数。您可以方便地基于**Five**进行二次开发，并结合到您自身的项目中，为您的项目添砖加瓦。
 
-## 安装 Five
+**Five**通过 [TypeScript](https://www.typescriptlang.org/) 编写，保证开发的质量以及编程体验，推荐通过 [Visual Studio Code](https://code.visualstudio.com)、[WebStorm](https://www.jetbrains.com/webstorm/) 等现代源代码编辑器，您将可以体验到友好的代码提示以及自动补全。
 
-Five 提供通过 [npm](https://www.npmjs.com) 的方式安装。Five 基于 [three.js](https://threejs.org), 所以同时您需要安装相关依赖。
+**Five**还提供了完善的 [React Hooks API](https://reactjs.org/docs/hooks-intro.html) ，可以方便的通过 [React](https://reactjs.org) 开发复杂的响应式数据应用。当然直接使用**Five**开发也是没有问题的。
 
-THREE 目前的依赖版本为 115 ~ 117 的版本
+## 安装**Five**
+
+**Five**提供通过 [npm](https://www.npmjs.com) 的方式安装。**Five**基于 [Three.js](https://threejs.org), 所以同时您需要安装相关依赖。
+
+目前依赖的**three**版本为 115 ~ 117 的版本
 
 ```shell
-npm install @realsee/five@next three@0.117.1
+npm install @realsee/five three@0.117.1
 ```
 
-如果您使用 React Hooks API，那么也请同时安装 React 的相关依赖。
+如果您使用**React Hooks API**，那么也请同时安装**React**的相关依赖。
 
 ```shell
-npm install @realsee/five@next three@0.117.1 react react-dom @types/react @types/react-dom
+npm install @realsee/five three@0.117.1 react react-dom @types/react @types/react-dom
 ```
 
-接下来便可以在您的项目使用 Five 了。
+接下来便可以在您的项目使用**Five**了。
 
 ```typescript
 import { Five } from "@realsee/five";
@@ -35,24 +39,30 @@ 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**提供了快速上手体验的项目生成工具，您可以通过他熟悉**Five**的功能以及尝试基于**Five**开发功能。
 
 
-1. 先创建一个文件夹(five-quick-start), 作为项目根目录并且使用 `npm init` 命令初始化一个工程。
+1. 先创建一个文件夹`five-quick-start`, 作为项目根目录并且使用 `npm init` 命令初始化一个工程。
 
 ```shell
 mkdir five-quick-start && cd five-quick-start && npm init -y
 ```
 
-2. 安装 Five
+2. 安装**Five**
 
 ```shell
-npm install @realsee/five@next
+npm install @realsee/five
 ```
 
-3. 通过 Five 的内置 Quick-Start 脚本。补完当前项目
+3. 通过**Five**的内置的`five-quick-start-init`脚本来快速补完当前项目
 
 ```shell
 npx five-quick-start-init
@@ -74,7 +84,7 @@ npx five-quick-start-init
 └── webpack.production.js    webpack 生产配置
 ```
 
-通过 npm-script 运行测试环境
+通**npm script**运行测试环境
 
 ```shell
 npm run dev
@@ -82,15 +92,15 @@ npm run dev
 
 默认将会在 `port: 3000` 开启 `webpack dev server`。您也可以在 `webpack.config.js` 中修改配置。
 
-4. 现在可以打来浏览器 `http://0.0.0.0:3000` 来看看项目初始化的效果了。您可以修改代码来体验一下如何使用 Five 来二次开发。
+4. 现在可以打来浏览器 `http://0.0.0.0:3000` 来看看项目初始化的效果了。您可以修改代码来体验一下如何使用**Five**来二次开发。
 
 
 
-## 如何使用 Five
+## 如何使用**Five**
 
-Five 的简单使用样例:
+**Five**的简单使用样例:
 
-```typescript
+```ts
 import { Five } from "@realsee/five";
 
 // 构造函数的具体参数见文档
@@ -103,7 +113,7 @@ five.appendTo(document.getElementById('app')!);
 window.addEventListener('resize', () => five.refresh());
 
 // 获取三维空间的 Work 数据，加载进来
-// Work 数据可以通过如视开放平台获取
+// Work 数据可以通过如视开发者中心获取
 fetch(`./work.json`)
   .then(res => res.json())
   .then(work => five.load(work));
@@ -112,15 +122,15 @@ fetch(`./work.json`)
 其他的 Five API 待补充
 
 
-## 在 React 框架中使用 Five
+## 在**React**框架中使用**Five**
 
-在 React 框架中使用 Five 的简单使用样例:
+在**React**框架中使用**Five**的简单使用样例:
 
-```typescript
+```tsx
 import * as React from "react";
 import * as ReactDOM from "react-dom";
-import { Five, parseWork } from "@realsee/five";
-import { createFiveProvider, FiveCanvas } from "@realsee/five/react";
+import {Five, Work, parseWork} from "@realsee/five";
+import {createFiveProvider, FiveCanvas} from "@realsee/five/react";
 
 // 创建 Provider, 参数与 new Five 参数类似
 // 构造函数的具体参数见文档
@@ -140,8 +150,8 @@ const App: React.FC = () => {
   // 获取三维空间的 Work 数据，加载进来
   const loadWork = React.useCallback((url: string) => {
     fetch(url)
-      .then(res => res.json())
-      .then(data => setWork(parseWork(data)));
+            .then(res => res.json())
+            .then(data => setWork(parseWork(data)));
   }, []);
 
   React.useEffect(() => {
@@ -166,15 +176,15 @@ const App: React.FC = () => {
       在他内部的组件可以使用 Five React Hook API 来获取/设置/操作 他
       一个页面中也可以有多个 FiveProvider
     */}
-    return <FiveProvider initalWork={work}>
+    return <FiveProvider initialWork={work}>
       {/*
         将渲染视图的 canvas 添加到 DOM 中
         FiveCanvas 需要出现在 FiveProvider 内，他将渲染 FiveProvider 的视图
         这样的设计可以实现不同的 DOM 层级结构
         在 FiveProvider 内的其他组件也可以使用 Five React Hook API 来获取/设置/操作 他外部的 FiveProvider
       */}
-      <FiveCanvas width={size.width} height={size.height}></FiveCanvas>
-    </StoreProvider>;
+      <FiveCanvas width={size.width} height={size.height}/>
+    </FiveProvider>
   }
   return null;
 }
@@ -182,24 +192,24 @@ const App: React.FC = () => {
 ReactDOM.render(<App></App>, document.getElementById("app"));
 ```
 
-其他的 Five React Hook API 待补充
+其他的**Five React Hook API**文档建设中...
 
-## Five API 文档
+## **Five API**文档
 
-欢迎查看 [Five API 文档](./docs)。
+欢迎查看 [Five API 文档](https://unpkg.com/@realsee/five/docs/index.html) 。
 
-该文档由 typedoc 生成，您可以详细查看 api 使用方式，调用参数，数据结构。
+该文档由 [TypeDoc](https://typedoc.org/) 生成，您可以详细查看 api 使用方式，调用参数，数据结构。
 
 ## 相关名词解释
 
-### 什么是 Work
+### 什么是**Work**
 
-Work 是[如视开放平台](http://developers.realsee.com) 提供的对于一个三维空间的描述。
-是通过如视硬件设备（[如视扫描仪](https://realsee.com/website/product/hardware)、[如视Lite全景相机](https://realsee.com/website/product/lite)、[如视VR APP](https://realsee.com/website/mobile)）扫描并处理之后用于三维空间展示的数据。
+**Work**是[如视开发者中心](https://developers.realsee.com) 提供的对于一个三维空间的描述。
+是通过如视硬件设备（[如视扫描仪](https://realsee.com/website/product/hardware) 、[如视**Lite**全景相机](https://realsee.com/website/product/lite) 、[如视VR App](https://realsee.com/website/mobile) ）扫描并处理之后用于三维空间展示的数据。
 
-Work 以 `JSON` 作为数据格式，Five 框架可以解析 Work 数据并展示。一个 Five 实例每次可以载入并展示一个 Work。并且也可以在 Work 之间动态切换。
+**Work**以`JSON`作为数据格式**Five**框架可以解析**Work**数据并展示。一个**Five**实例每次可以载入并展示一个**Work**。并且也可以在不同的**Work**之间动态切换。
 
-Work 的数据样例如下
+**Work**的数据样例如下
 
 ```json
 {
@@ -293,24 +303,24 @@ Work 的数据样例如下
 }
 ```
 
-Work 的数据说明:
+Work 的数据说明
 
-- initial: 初始化数据，是一个 `State` 数据。描述 Work 被加载初始状态的位姿。
+- `initial`: 初始化数据，是一个 `State` 数据。描述**Work**被加载初始状态的位姿，也叫做VR的初始视角
   - mode: 模态
   - pano_index: 初始化点位
   - longitude: 相机的水平角
   - latitude: 相机的偏航角
   - fov: 相机垂直方向的可视角度
 
-- model: 三维模型
+- `model`: 三维模型
   - file_url: 三维模型的资源地址，文件为 `.at3d` 为如视定制的模型格式
   - material_textures: 三维模型的贴图资源地址
 
-- panorama: 全景彩色信息
+- `panorama`: 全景彩色信息
   - list:
     - up / down / left / right / front / back: 全景彩色信息以 [cubemap](https://en.wikipedia.org/wiki/Cube_mapping) 方式存储和使用。
 
-- observers: 采集点信息
+- `observers`: 采集点信息
   - visible_nodes: 采集点之间的可见性列表
   - accessible_nodes: 采集点之间的连通性列表
   - quaternion: 采集点与模型坐标的旋转偏移量
@@ -318,12 +328,12 @@ Work 的数据说明:
   - position: 采集点坐标
   - floor_index: 采集点楼层
 
-### 什么是 State
+### 什么是 Five State
 
-State 是 Five 框架用于描述状态的数据结构。他包含了模态、位于的采集点位、相机的方向、相机可视角度的信息。
-您可以使用 State 来操作 Five 或者获取 Five 当前的状态。
+**State**是**Five**框架用于描述状态的数据结构。他包含了模态、位于的采集点位、相机的方向、相机可视角度的信息。
+您可以使用**State**来操作**Five**或者获取**Five**当前的状态。
 
-```typescript
+```ts
 interface State {
   "mode": Five.Mode,
   "panoIndex": number,
@@ -333,18 +343,20 @@ interface State {
 }
 ```
 
-State 的数据描述
+**State**的数据描述
+
+- `mode`: 当前的模态
+  Five 常用有 5 种模态，可以使用 `Five.Mode` 获得
+    - Panorama: 全景游走模态，该模态下视图将在采集点间游走，手势操作可以旋转/放大视角/切换采集点，适合查看采集的全景信息。
+    - Floorplan: 空间总览模态, 该模态下视图以模型为中心，手势操作可以旋转/放大模型/切换楼层，适合查看模型的整体效果。
+    - Topview: 户型图模态，该模态下视图以模型为中心，垂直俯视模型，手势操作可以平移/放大模型/切换楼层，适合查看模型平面结构。
+    - Model: 模型游走模态，该模态下视图将在模型中自由游走，手势操作可以旋转/放大视角/位移，适合查看模型的细节，做一些定位操作。
+    - VRPanorama: VR 眼镜模态，该模态下可以使用 [Cardboard 眼镜](https://arvr.google.com/cardboard/) 或者他的第三方衍生产品，实现 VR 虚拟显示效果。
+
+- `panoIndex`: 采集点位
 
-- mode: 当前的模态
-  Five 有 5 种模态，可以使用 `Five.Mode` 获得
-    - Floorplan: 模型查看模式, 该模式下视图以模型为中心，手势操作可以旋转/放大模型/切换楼层，适合查看模型的整体效果。
-    - Topview: 户型图模式，该模式下视图以模型为中心，垂直俯视模型，手势操作可以平移/放大模型/切换楼层，适合查看模型平面结构。
-    - Panorama: 全景图游走模式，该模式下视图将在采集点间游走，手势操作可以旋转/放大视角/切换采集点，适合查看采集的全景信息。
-    - Model: 模型游走模式，该模式下视图将在模型中自由游走，手势操作可以旋转/放大视角/位移，适合查看模型的细节，做一些定位操作。
-    - VRPanorama: VR 眼镜模式，该模式下可以使用 [Cardboard 眼镜](https://arvr.google.com/cardboard/) 或者他的第三方衍生产品，实现 VR 虚拟显示效果。
+- `longitude` / `latitude`: 相机的水平角 / 相机的偏航角（弧度），我们使用类似经纬度的方式描述相机位置。
 
-- panoIndex: 采集点位
+- `fov`: 相机垂直方向的可视角度 (角度)
 
-- longitude / latitude: 相机的水平角 / 相机的偏航角（弧度），我们使用类似经纬度的方式描述相机位置。
 
-- fov: 相机垂直方向的可视角度 (角度)

package/docs/.nojekyll

@@ -0,0 +1 @@
+TypeDoc added this file to prevent GitHub Pages from using Jekyll. You can turn off this behavior by setting the `githubPages` option to false.

package/docs/assets/highlight.css

@@ -0,0 +1,134 @@
+:root {
+    --light-hl-0: #000000;
+    --dark-hl-0: #D4D4D4;
+    --light-hl-1: #AF00DB;
+    --dark-hl-1: #C586C0;
+    --light-hl-2: #001080;
+    --dark-hl-2: #9CDCFE;
+    --light-hl-3: #A31515;
+    --dark-hl-3: #CE9178;
+    --light-hl-4: #008000;
+    --dark-hl-4: #6A9955;
+    --light-hl-5: #795E26;
+    --dark-hl-5: #DCDCAA;
+    --light-hl-6: #0070C1;
+    --dark-hl-6: #4FC1FF;
+    --light-hl-7: #0000FF;
+    --dark-hl-7: #569CD6;
+    --light-hl-8: #267F99;
+    --dark-hl-8: #4EC9B0;
+    --light-hl-9: #800000;
+    --dark-hl-9: #808080;
+    --light-hl-10: #FF0000;
+    --dark-hl-10: #9CDCFE;
+    --light-hl-11: #000000FF;
+    --dark-hl-11: #D4D4D4;
+    --light-hl-12: #0451A5;
+    --dark-hl-12: #9CDCFE;
+    --light-hl-13: #098658;
+    --dark-hl-13: #B5CEA8;
+    --light-hl-14: #EE0000;
+    --dark-hl-14: #D7BA7D;
+    --light-hl-15: #000000;
+    --dark-hl-15: #C8C8C8;
+    --light-code-background: #F5F5F5;
+    --dark-code-background: #1E1E1E;
+}
+
+@media (prefers-color-scheme: light) { :root {
+    --hl-0: var(--light-hl-0);
+    --hl-1: var(--light-hl-1);
+    --hl-2: var(--light-hl-2);
+    --hl-3: var(--light-hl-3);
+    --hl-4: var(--light-hl-4);
+    --hl-5: var(--light-hl-5);
+    --hl-6: var(--light-hl-6);
+    --hl-7: var(--light-hl-7);
+    --hl-8: var(--light-hl-8);
+    --hl-9: var(--light-hl-9);
+    --hl-10: var(--light-hl-10);
+    --hl-11: var(--light-hl-11);
+    --hl-12: var(--light-hl-12);
+    --hl-13: var(--light-hl-13);
+    --hl-14: var(--light-hl-14);
+    --hl-15: var(--light-hl-15);
+    --code-background: var(--light-code-background);
+} }
+
+@media (prefers-color-scheme: dark) { :root {
+    --hl-0: var(--dark-hl-0);
+    --hl-1: var(--dark-hl-1);
+    --hl-2: var(--dark-hl-2);
+    --hl-3: var(--dark-hl-3);
+    --hl-4: var(--dark-hl-4);
+    --hl-5: var(--dark-hl-5);
+    --hl-6: var(--dark-hl-6);
+    --hl-7: var(--dark-hl-7);
+    --hl-8: var(--dark-hl-8);
+    --hl-9: var(--dark-hl-9);
+    --hl-10: var(--dark-hl-10);
+    --hl-11: var(--dark-hl-11);
+    --hl-12: var(--dark-hl-12);
+    --hl-13: var(--dark-hl-13);
+    --hl-14: var(--dark-hl-14);
+    --hl-15: var(--dark-hl-15);
+    --code-background: var(--dark-code-background);
+} }
+
+body.light {
+    --hl-0: var(--light-hl-0);
+    --hl-1: var(--light-hl-1);
+    --hl-2: var(--light-hl-2);
+    --hl-3: var(--light-hl-3);
+    --hl-4: var(--light-hl-4);
+    --hl-5: var(--light-hl-5);
+    --hl-6: var(--light-hl-6);
+    --hl-7: var(--light-hl-7);
+    --hl-8: var(--light-hl-8);
+    --hl-9: var(--light-hl-9);
+    --hl-10: var(--light-hl-10);
+    --hl-11: var(--light-hl-11);
+    --hl-12: var(--light-hl-12);
+    --hl-13: var(--light-hl-13);
+    --hl-14: var(--light-hl-14);
+    --hl-15: var(--light-hl-15);
+    --code-background: var(--light-code-background);
+}
+
+body.dark {
+    --hl-0: var(--dark-hl-0);
+    --hl-1: var(--dark-hl-1);
+    --hl-2: var(--dark-hl-2);
+    --hl-3: var(--dark-hl-3);
+    --hl-4: var(--dark-hl-4);
+    --hl-5: var(--dark-hl-5);
+    --hl-6: var(--dark-hl-6);
+    --hl-7: var(--dark-hl-7);
+    --hl-8: var(--dark-hl-8);
+    --hl-9: var(--dark-hl-9);
+    --hl-10: var(--dark-hl-10);
+    --hl-11: var(--dark-hl-11);
+    --hl-12: var(--dark-hl-12);
+    --hl-13: var(--dark-hl-13);
+    --hl-14: var(--dark-hl-14);
+    --hl-15: var(--dark-hl-15);
+    --code-background: var(--dark-code-background);
+}
+
+.hl-0 { color: var(--hl-0); }
+.hl-1 { color: var(--hl-1); }
+.hl-2 { color: var(--hl-2); }
+.hl-3 { color: var(--hl-3); }
+.hl-4 { color: var(--hl-4); }
+.hl-5 { color: var(--hl-5); }
+.hl-6 { color: var(--hl-6); }
+.hl-7 { color: var(--hl-7); }
+.hl-8 { color: var(--hl-8); }
+.hl-9 { color: var(--hl-9); }
+.hl-10 { color: var(--hl-10); }
+.hl-11 { color: var(--hl-11); }
+.hl-12 { color: var(--hl-12); }
+.hl-13 { color: var(--hl-13); }
+.hl-14 { color: var(--hl-14); }
+.hl-15 { color: var(--hl-15); }
+pre, code { background: var(--code-background); }