如视 Five SDK
    Preparing search index...

    Five SDK Documentation

    npm version

    • Summary: Five SDK 的文档索引与阅读指南，旨在帮助开发者与 AI 助手快速定位所需信息。
    • Audience: 开发者、AI 辅助编程工具。

    Five 是贝壳如视 (Realsee) 提供的三维空间渲染 SDK。

    Important

    Before writing or updating any documentation, YOU MUST READ AI Documentation Guidelines. 在书写文档时，务必遵循 AI Documentation Guidelines 中的规范。

    当协助用户编写代码或构建 Five 应用时，请遵循以下阅读与检索策略：

    • Initialization (初始化):
      • 阅读 Quick Start 掌握最小化启动流程。
      • 查阅 Parameter 获取 new Five(config) 的完整配置项（如 canvas 尺寸、资源路径、纹理压缩设置）。
    • Data Handling (数据加载):
      • 核心 VR 数据：深入理解 Work 结构，它是 Five 渲染的基础。
      • 外部模型：参考 Load External Model 加载 GLTF/OBJ 等格式。
      • 多场景/沙盘：参考 Multi-Work (Sandbox) 处理复杂场景切换。
    • Interaction & Logic (交互逻辑):
    • State Management (状态管理):
      • 保存/恢复场景：必须 深刻理解 State。它是 Five 的核心快照机制，包含 Pose、Mode 和 PanoIndex。不要尝试手动管理零散的相机参数，应统一使用 State。
    • Coding Standards (代码规范):
      • 优先使用 TypeScript 类型提示。
      • 确保从 @realsee/five 导入核心类与类型 (e.g., import { Five, Mode, Work, State } from "@realsee/five").
    • API Signatures: API Reference 是最权威的接口定义来源，包含方法的参数与返回值。
    • Terminology: 遇到不确定的术语 (e.g., Pose vs State, Observer) 时，务必查阅 Glossary。
    • Core Relationships: 理解 Five (渲染器) 与 Work (数据) 的分离设计。

    最常用的入口文档。

    • Intro: Five SDK 简介与能力概览。
    • Quick Start: 快速集成指南。
    • API Reference: 核心 API 索引 (Five 类, State, Events, Methods)。
    • Glossary: 术语表 (Work, Observer, Pose, etc.)。

    基础架构与生命周期管理。

    • Five: 核心类 Five，管理渲染循环与全局状态。
    • Work: 数据载体，描述三维空间的数据结构 (VR 看房数据)。
    • Panorama UV: 全景图 UV 与空间方向转换工具。
    • Mode: 五种核心浏览模式 (Panorama, Floorplan, Topview, Model, Map)。
    • State: 状态管理 (Pose, Mode, PanoIndex)，用于复原场景。
    • Coordinate System: 坐标系定义 (右手坐标系, Y轴向上)。

    数据加载与资源管理配置。

    画面表现与渲染管线配置。

    用户输入与相机控制。

    复杂配置与功能扩展。

    Keyword Search Tip: Each doc in features/ has a tags yaml block at the bottom with Chinese and English keywords. Use these for keyword matching when the scenario table below doesn't cover your need.

    Scenario Docs Tags
    点击拾取物体 / Object picking Raycast click, hit-test, floor-detection, 碰撞检测, 物体选择
    3D 标签 / HTML overlay on 3D point Screen Project label, HUD, tooltip, 坐标转换, 3D转2D
    全景滤镜 / 色温调节 / Color correction Pano Filter warm, cool, brightness, contrast, saturation, 暖色, 冷色, 饱和度
    加载外部 GLTF/OBJ/FBX 模型 Load External Model gltf, glb, ply, splat, fbx, draco, point-cloud, dispose
    相机巡航 / 自动导览 / Camera fly-through Camera Animation rotate, zoom, auto-tour, 运镜, 旋转, 缩放
    截图 / 放大镜 / Screen capture Get Screen Pixels magnifier, screenshot, color-picker, 取色器
    模型裁切 / 房屋剖面 Clipper clipping-box, section-view, discard, 开盖, 剖面
    流光特效 / Flowing light effect Flowing Light 2D, Flowing Light 3D 光带, 导航路径, 动态路径, instanced
    模糊特效 / Blur effect Gaussian Blur Pass 毛玻璃, 背景虚化, gaussian
    保存/恢复场景状态 State snapshot, save, restore, 快照, 场景还原
    多场景切换 / 沙盘 Multi-Work sandbox, 多户型, 拼接, workCode
    请求鉴权 / CDN 替换 Request Proxy authentication, token, url-rewrite, cors, 私有化
    插件开发 Plugin lifecycle, extension, baseplugin, 状态管理
    事件监听 / 拦截默认行为 Event preventDefault, waitUntil, on, off, gesture, 回调
    手势交互 / 自定义拖拽 Gesture tap, pan, pinch, press, 触摸, 鼠标
    后处理特效 / 自定义 Shader Postprocessing effect-composer, addPass, edl, 描边, 景深
    材质 / 透明度 / 点云样式 Material opacity, pointcloud, roof, ceiling, 天花板, 顶点标记
    模式切换 / 全景↔模型↔户型图 Mode panorama, floorplan, mapview, topview, VR
    全景高清瓦片 / 分片加载 Pano Tile LOD, tile, 按需加载, 高清全景
    图片 CDN / 私有化部署 Image Options avif, webp, cdn, private-deployment
    加载进度 / 首屏优化 Load Progress refined, loaded, loading-bar, 首屏
    • Work: 包含全景图、模型、户型数据的 JSON 对象。
    • Observer: 观察点，通常对应一个全景拍摄点位。
    • PanoIndex: 全景点位的索引下标。
    • Pose: 相机位姿 (Longitude, Latitude, Fov)。
    • Mode: 浏览模式 (Panorama, Model, etc.)。
    tags: [index, readme, guide, map]

    Settings

    Member Visibility

    On This Page

    Five SDK Documentation