# Five.js

[![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)

贝壳如视三维渲染框架

> **🤖 For AI Assistants (Copilot, Cursor, etc.):**
> **START HERE → Read [llms.txt](./llms.txt)** for a context-optimized documentation index with scenario-based lookup.
> For the full documentation map, see [ai_guides/README.md](./ai_guides/README.md).
> Do NOT use `docs/` directory (auto-generated HTML, redundant and hard to parse).
>
> If this package is installed locally, read `node_modules/@realsee/five/llms.txt` directly.
> If not installed, use a CDN mirror:
> - `https://cdn.jsdelivr.net/npm/@realsee/five@latest/llms.txt`
> - `https://unpkg.com/@realsee/five@latest/llms.txt`
## Introduction

**Five** 是 [贝壳如视(realsee.com)](https://realsee.com) 提供的在浏览器中运行的三维空间渲染 Javascript SDK。基于 [Three.js](https://threejs.org/) 开发，帮助开发者在浏览器中构建高质量的 VR 看房与空间交互应用。

核心能力包括：
*   **全景浏览**: 高分辨率全景图的高效加载与平滑浏览。
*   **空间漫游**: 在三维模型中自由行走、跳转。
*   **模型渲染**: 内置高效的模型加载策略 (3DTile)。
*   **交互事件**: 完善的手势与射线检测系统。

## Installation

通过 npm 或 yarn 安装：

```bash
npm install three@^0.117.1 @realsee/five
# or
yarn add three@^0.117.1 @realsee/five
```

> **注意**: Five 依赖 `three`，目前推荐版本为 `0.117.1`。

## Quick Start

```typescript
import { Five, parseWork } from "@realsee/five";

// 1. 初始化
const five = new Five();
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));
});

// 3. 适配窗口
window.addEventListener('resize', () => five.refresh());
```

## Browser Support

| Browser | Version | Note |
| :--- | :--- | :--- |
| **Chrome** | >= 69 | |
| **Safari** | >= 9 | iOS Safari >= 9 |
| **Firefox** | >= 45 | |
| **Edge** | >= 13 | |
| **Android** | >= 93 | Chrome内核 |

## Documentation

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:**

*   **START HERE → [llms.txt](./llms.txt)** — context-optimized index with scenario → doc mapping and keyword tags.
*   If you need the full documentation map, read [ai_guides/README.md](ai_guides/README.md).

**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.

**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.