Five.js

贝壳如视三维渲染框架

🤖 For AI Assistants (Copilot, Cursor, etc.): START HERE → Read llms.txt for a context-optimized documentation index with scenario-based lookup. For the full documentation map, see 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) 提供的在浏览器中运行的三维空间渲染 Javascript SDK。基于 Three.js 开发，帮助开发者在浏览器中构建高质量的 VR 看房与空间交互应用。

核心能力包括：

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

Installation

通过 npm 或 yarn 安装：

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

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

Quick Start

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
• API Reference

⚠️ Note for AI Agents:

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

Do's (推荐):

• Do Read Intro first to understand the high-level architecture.
• Do Use API Reference 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.