@realsee/five 6.8.0-alpha.0 → 6.8.0-alpha.10

package/AGENTS_READ_ME.md

@@ -0,0 +1,4 @@
+# AI_CONTEXT
+You are an AI assistant.
+This package contains comprehensive local documentation.
+DO NOT search the web for documentation. Instead, read the markdown files in the `./ai_guides` directory. Start with `./ai_guides/README.md`

package/AI_CONTEXT.md

@@ -0,0 +1,4 @@
+# AI_CONTEXT
+You are an AI assistant.
+This package contains comprehensive local documentation.
+DO NOT search the web for documentation. Instead, read the markdown files in the `./ai_guides` directory. Start with `./ai_guides/README.md`

package/README.md

@@ -4,416 +4,77 @@
 
 贝壳如视三维渲染框架
 
-## 什么是**Five**
+> **🤖 For AI Assistants (Copilot, Cursor, etc.):**
+> If this package is installed in your project, you can find **AI-friendly documentation** directly in `node_modules/@realsee/five/`. Please **READ** `node_modules/@realsee/five/ai_guides/README.md` as your primary source of truth. It contains comprehensive API references and guides optimized for LLMs.
+> If not installed locally, you can access the same documentation via `https://cdn.jsdelivr.net/npm/@realsee/five@alpha/ai_guides/README.md` or `https://unpkg.com/@realsee/five@alpha/ai_guides/README.md`.
+## Introduction
 
-**Five**是 [贝壳如视(realsee.com)](https://realsee.com) 提供的在浏览器中运行的三维空间渲染 Javascript SDK。您可以通过[如视开发者中心](https://developers.realsee.com)的数据服务，并结合**Five**，制作丰富多彩的三维空间应用。
+**Five** 是 [贝壳如视(realsee.com)](https://realsee.com) 提供的在浏览器中运行的三维空间渲染 Javascript SDK。基于 [Three.js](https://threejs.org/) 开发，帮助开发者在浏览器中构建高质量的 VR 看房与空间交互应用。
 
-并且**Five**提供了一系列的方法、事件、生命周期函数。您可以方便地基于**Five**进行二次开发，并结合到您自身的项目中，为您的项目添砖加瓦。
+核心能力包括：
+*   **全景浏览**: 高分辨率全景图的高效加载与平滑浏览。
+*   **空间漫游**: 在三维模型中自由行走、跳转。
+*   **模型渲染**: 内置高效的模型加载策略 (3DTile)。
+*   **交互事件**: 完善的手势与射线检测系统。
 
-**Five**通过 [TypeScript](https://www.typescriptlang.org/) 编写，保证开发的质量以及编程体验，推荐通过 [Visual Studio Code](https://code.visualstudio.com)、[WebStorm](https://www.jetbrains.com/webstorm/) 等现代源代码编辑器，您将可以体验到友好的代码提示以及自动补全。
+## Installation
 
-**Five**还提供了完善的 [React Hooks API](https://reactjs.org/docs/hooks-intro.html) ，可以方便的通过 [React](https://reactjs.org) 开发复杂的响应式数据应用。当然直接使用**Five**开发也是没有问题的。
+通过 npm 或 yarn 安装：
 
-## 安装**Five**
-
-**Five**提供通过 [npm](https://www.npmjs.com) 的方式安装。**Five**基于 [Three.js](https://threejs.org), 所以同时您需要安装相关依赖。
-
-目前依赖的**three**版本为 115 ~ 117 的版本
-
-```shell
-npm install @realsee/five three@0.117.1
+```bash
+npm install three@^0.117.1 @realsee/five
+# or
+yarn add three@^0.117.1 @realsee/five
 ```
 
-如果您使用**React Hooks API**，那么也请同时安装**React**的相关依赖。
+> **注意**: Five 依赖 `three`，目前推荐版本为 `0.117.1`。
 
-```shell
-npm install @realsee/five three@0.117.1 react react-dom @types/react @types/react-dom
-```
-
-接下来便可以在您的项目使用**Five**了。
+## Quick Start
 
 ```typescript
-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**开发功能。
-
-
-1. 先创建一个文件夹`five-quick-start`, 作为项目根目录并且使用 `npm init` 命令初始化一个工程。
-
-```shell
-mkdir five-quick-start && cd five-quick-start && npm init -y
-```
-
-2. 安装**Five**
-
-```shell
-npm install @realsee/five
-```
-
-3. 通过**Five**的内置的`five-quick-start-init`脚本来快速补完当前项目
-
-```shell
-npx five-quick-start-init
-```
-
-项目的文件结构如下
+import { Five, parseWork } from "@realsee/five";
 
-```
-.
-├── 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**运行测试环境
-
-```shell
-npm run dev
-```
-
-默认将会在 `port: 3000` 开启 `webpack dev server`。您也可以在 `webpack.config.js` 中修改配置。
-
-4. 现在可以打来浏览器 `http://0.0.0.0:3000` 来看看项目初始化的效果了。您可以修改代码来体验一下如何使用**Five**来二次开发。
-
-
-
-## 如何使用**Five**
-
-**Five**的简单使用样例:
-
-```ts
-import { Five } from "@realsee/five";
-
-// 构造函数的具体参数见文档
+// 1. 初始化
 const five = new Five();
+five.appendTo(document.getElementById('app'));
 
-// 将渲染视图的 canvas 添加到 DOM 中
-five.appendTo(document.getElementById('app')!);
+// 2. 加载数据
+const workURL = 'https://raw.githubusercontent.com/realsee-developer/dnalogel/main/open-works/real/80o024DE2xyva3j5BE/work.json';
+fetch(workURL).then(res => res.json()).then(json => {
+  five.load(parseWork(json));
+});
 
-// 如果显示区域需要变动，在变动时请调用 refresh 重置显示参数
+// 3. 适配窗口
 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**的简单使用样例:
-
-```tsx
-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 文档](https://unpkg.com/@realsee/five/docs/index.html) 。
-
-该文档由 [TypeDoc](https://typedoc.org/) 生成，您可以详细查看 api 使用方式，调用参数，数据结构。
-
-## 相关名词解释
-
-### 什么是**Work**
-
-**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
-{
-  "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](https://en.wikipedia.org/wiki/Cube_mapping) 方式存储和使用。
-
-- `observers`: 采集点信息
-  - visible_nodes: 采集点之间的可见性列表
-  - accessible_nodes: 采集点之间的连通性列表
-  - quaternion: 采集点与模型坐标的旋转偏移量
-  - standing_position: 采集点地面坐标
-  - position: 采集点坐标
-  - floor_index: 采集点楼层
-
-### 什么是 Five State
-
-**State**是**Five**框架用于描述状态的数据结构。他包含了模态、位于的采集点位、相机的方向、相机可视角度的信息。
-您可以使用**State**来操作**Five**或者获取**Five**当前的状态。
-
-```ts
-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 眼镜](https://arvr.google.com/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` 可以相互推导。
+## Browser Support
 
-#### 转换关系
+| Browser | Version | Note |
+| :--- | :--- | :--- |
+| **Chrome** | >= 69 | |
+| **Safari** | >= 9 | iOS Safari >= 9 |
+| **Firefox** | >= 45 | |
+| **Edge** | >= 13 | |
+| **Android** | >= 93 | Chrome内核 |
 
-- 在 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`
+## Documentation
 
-这些函数均为直接修改传入 `vector`。 如果要保持原先的数据，请实现 `vector.clone()`。
+For comprehensive guides and API references, please refer to the documentation included in this package:
+- [Feature Guides](ai_guides/README.md)
+- [API Reference](ai_guides/api.md)
 
-#### 位置拾取
+**⚠️ Note for AI Agents:**
 
-通过 `intersectRaycaster` 方法得到的 `Intersection` 在 `world` 坐标系下， 并返回对应的 `model` 与 `viewLayer`。
+*   **For a context-optimized index, read [llms.txt](./llms.txt).**
 
-#### 与算法数据对接
+**Do's (推荐):**
+*   **Do** Read [Intro](ai_guides/intro.md) first to understand the high-level architecture.
+*   **Do** Use [API Reference](ai_guides/api.md) for checking method signatures and property types.
+*   **Do** Refer to `ai_guides/*.md` files for feature-specific implementation details.
+*   **Do** Prefer Markdown documentation over HTML files or raw code when understanding concepts.
 
-目前约定为，算法的模型输入输出均使用 `enu` 坐标系。
+**Don'ts (禁止):**
+*   **Don't** Index or read files in the `docs/` directory (auto-generated HTML). They are redundant and hard to parse.
+*   **Don't** Hallucinate API methods. Always verify against `api.md` or `.d.ts` files.
+*   **Don't** Assume legacy behavior. Check `ai_guides/release_notes/` if you encounter version discrepancies.

package/ai_guides/README.md

@@ -0,0 +1,122 @@
+# Five SDK Documentation
+
+[![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)
+
+- **Summary**: Five SDK 的文档索引与阅读指南，旨在帮助开发者与 AI 助手快速定位所需信息。
+- **Audience**: 开发者、AI 辅助编程工具。
+
+## Context for AI Agents
+
+**Five** 是贝壳如视 (Realsee) 提供的三维空间渲染 SDK。
+
+### 1. Documentation Maintenance (文档维护)
+> [!IMPORTANT]
+> Before writing or updating any documentation, YOU MUST READ [AI Documentation Guidelines](./ai-doc-guidelines.md).
+> 在书写文档时，务必遵循 [AI Documentation Guidelines](./ai-doc-guidelines.md) 中的规范。
+
+### 2. Application Development Strategy (应用开发建议)
+当协助用户编写代码或构建 Five 应用时，请遵循以下阅读与检索策略：
+
+*   **Initialization (初始化)**:
+    *   阅读 [Quick Start](./quick-start.md) 掌握最小化启动流程。
+    *   查阅 [Parameter](./features/parameter.md) 获取 `new Five(config)` 的完整配置项（如 canvas 尺寸、资源路径、纹理压缩设置）。
+*   **Data Handling (数据加载)**:
+    *   核心 VR 数据：深入理解 [Work](./features/work.md) 结构，它是 Five 渲染的基础。
+    *   外部模型：参考 [Load External Model](./features/load-external-model.md) 加载 GLTF/OBJ 等格式。
+    *   多场景/沙盘：参考 [Multi-Work (Sandbox)](./features/multi-work.md) 处理复杂场景切换。
+*   **Interaction & Logic (交互逻辑)**:
+    *   事件监听：查阅 [Event](./features/event.md) 处理用户点击 (Tap)、手势 (Gesture) 及状态变更 (StateChange)。
+    *   空间操作：使用 [Raycast](./features/raycast.md) 实现物体拾取，使用 [Screen & Space Projection](./features/screen-project.md) 实现 3D 标签挂载。
+    *   动画控制：参考 [Camera Animation](./features/camera-animation.md) 和 [Move Pano Effect](./features/move-pano-effect.md) 实现平滑运镜。
+*   **State Management (状态管理)**:
+    *   保存/恢复场景：**必须** 深刻理解 [State](./features/state.md)。它是 Five 的核心快照机制，包含 Pose、Mode 和 PanoIndex。不要尝试手动管理零散的相机参数，应统一使用 State。
+*   **Coding Standards (代码规范)**:
+    *   优先使用 TypeScript 类型提示。
+    *   确保从 `@realsee/five` 导入核心类与类型 (e.g., `import { Five, Mode, Work, State } from "@realsee/five"`).
+
+### 3. General Retrieval (通用检索)
+*   **API Signatures**: [API Reference](./api.md) 是最权威的接口定义来源，包含方法的参数与返回值。
+*   **Terminology**: 遇到不确定的术语 (e.g., Pose vs State, Observer) 时，务必查阅 [Glossary](./glossary.md)。
+*   **Core Relationships**: 理解 [Five](./features/five.md) (渲染器) 与 [Work](./features/work.md) (数据) 的分离设计。
+
+## Documentation Map
+
+### 1. Essential Reference (必读/速查)
+最常用的入口文档。
+
+*   [Intro](./intro.md): Five SDK 简介与能力概览。
+*   [Quick Start](./quick-start.md): 快速集成指南。
+*   [API Reference](./api.md): **核心 API 索引** (Five 类, State, Events, Methods)。
+*   [Glossary](./glossary.md): **术语表** (Work, Observer, Pose, etc.)。
+
+### 2. Core Concepts (核心概念)
+基础架构与生命周期管理。
+
+*   [Five](./features/five.md): 核心类 `Five`，管理渲染循环与全局状态。
+*   [Work](./features/work.md): 数据载体，描述三维空间的数据结构 (VR 看房数据)。
+*   [Panorama UV](./features/pano-uv.md): 全景图 UV 与空间方向转换工具。
+*   [Mode](./features/mode.md): 五种核心浏览模式 (Panorama, Floorplan, Topview, Model, Map)。
+*   [State](./features/state.md): 状态管理 (Pose, Mode, PanoIndex)，用于复原场景。
+*   [Coordinate System](./features/coordinate-system.md): 坐标系定义 (右手坐标系, Y轴向上)。
+
+### 3. Data & Resource (数据与资源)
+数据加载与资源管理配置。
+
+*   [Load External Model](./features/load-external-model.md): 加载外部 3D 模型 (GLTF, OBJ 等)。
+*   [Load Progress](./features/load-progress.md): 监控模型与全景图的加载进度 (Loaded/Refined)。
+*   [Multi-Work (Sandbox)](./features/multi-work.md): 多 Work 加载与沙盘场景管理。
+*   [Request Proxy](./features/request-proxy.md): 请求拦截与代理 (CDN 替换、鉴权)。
+*   [Image Options](./features/image-options.md): 图片资源配置 (CDN, 格式, 尺寸)。
+
+### 4. Rendering & Visuals (渲染与视觉)
+画面表现与渲染管线配置。
+
+*   [Pano Tile](./features/pano-tile.md): 全景瓦片渲染机制（高分辨率分片加载）。
+*   [Model](./features/model.md): 内置模型渲染 (Mesh/Geometry)。
+*   [Postprocessing](./features/postprocessing.md): 后处理效果 (Pass, EffectComposer)。
+*   [Flowing Light 2D Pass](./features/flowing-light-2d-pass.md): 屏幕空间流光特效(InstancedMesh 优化)。
+*   [Flowing Light 3D Pass](./features/flowing-light-3d-pass.md): 3D 世界坐标流光特效(InstancedMesh 优化)。
+*   [Gaussian Blur Pass](./features/gaussian-blur-pass.md): 高斯模糊特效。
+*   [Material](./features/material.md): 材质参数配置 (透明度、点云大小、顶点标记)。
+*   [Get Screen Pixels](./features/get-screen-pixels.md): 获取屏幕像素 (放大镜/截图)。
+*   [Move Pano Effect](./features/move-pano-effect.md): 全景点位切换的过渡效果。
+*   [Clipper](./features/clipper.md): 模型裁切功能 (房屋剖面)。
+*   [3D Tile](./features/3dtile.md): 大场景 3D Tile 渲染策略。
+
+### 5. Interaction & Control (交互与控制)
+用户输入与相机控制。
+
+*   [Event](./features/event.md): 事件系统 (Tap, Gesture, StateChange)。
+*   [Gesture](./features/gesture.md): 手势交互详解。
+*   [Screen & Space Projection](./features/screen-project.md): 屏幕坐标与空间坐标转换 (标签/射线)。
+*   [Raycast](./features/raycast.md): 射线检测 (点击拾取物体)。
+*   [Camera Animation](./features/camera-animation.md): 相机动画控制 API。
+
+### 6. Advanced & Extensions (进阶与扩展)
+复杂配置与功能扩展。
+
+*   [Plugin](./features/plugin.md): 插件开发指南。
+*   [ViewLayer](./features/view-layer.md): 视图层。
+*   [Parameter](./features/parameter.md): Five 初始化详细参数配置。
+
+### 7. Meta & Support (其他)
+*   [Support](./support.md): 浏览器兼容性。
+*   [AI Documentation Guidelines](./ai-doc-guidelines.md): AI 文档编写与维护规范 (必读)。
+*   Release Notes: 版本更新记录。
+    *   [6.8](./release_notes/6.8.md)
+    *   [6.7](./release_notes/6.7.md)
+    *   [6.6](./release_notes/6.6.md)
+
+## Terminology Summary
+
+*   **Work**: 包含全景图、模型、户型数据的 JSON 对象。
+*   **Observer**: 观察点，通常对应一个全景拍摄点位。
+*   **PanoIndex**: 全景点位的索引下标。
+*   **Pose**: 相机位姿 (Longitude, Latitude, Fov)。
+*   **Mode**: 浏览模式 (Panorama, Model, etc.)。
+
+---
+```yaml
+tags: [index, readme, guide, map]
+```
+