@realsee/five
Version:
Realsee Renderer SDK
130 lines (123 loc) • 43.9 kB
HTML
<html class="default" lang="en" data-base="../"><head><meta charset="utf-8"/><meta http-equiv="x-ua-compatible" content="IE=edge"/><title>features/work | 如视 Five SDK</title><meta name="description" content="Documentation for 如视 Five SDK"/><meta name="viewport" content="width=device-width, initial-scale=1"/><link rel="stylesheet" href="../assets/style.css"/><link rel="stylesheet" href="../assets/highlight.css"/><script defer src="../assets/main.js"></script><script async src="../assets/icons.js" id="tsd-icons-script"></script><script async src="../assets/search.js" id="tsd-search-script"></script><script async src="../assets/navigation.js" id="tsd-nav-script"></script><script async src="../assets/hierarchy.js" id="tsd-hierarchy-script"></script></head><body><script>document.documentElement.dataset.theme = localStorage.getItem("tsd-theme") || "os";document.body.style.display="none";setTimeout(() => window.app?app.showPage():document.body.style.removeProperty("display"),500)</script><header class="tsd-page-toolbar"><div class="tsd-toolbar-contents container"><a href="../index.html" class="title">如视 Five SDK</a><div id="tsd-toolbar-links"></div><button id="tsd-search-trigger" class="tsd-widget" aria-label="Search"><svg width="16" height="16" viewBox="0 0 16 16" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-search"></use></svg></button><dialog id="tsd-search" aria-label="Search"><input role="combobox" id="tsd-search-input" aria-controls="tsd-search-results" aria-autocomplete="list" aria-expanded="true" autocapitalize="off" autocomplete="off" placeholder="Search the docs" maxLength="100"/><ul role="listbox" id="tsd-search-results"></ul><div id="tsd-search-status" aria-live="polite" aria-atomic="true"><div>Preparing search index...</div></div></dialog><a href="#" class="tsd-widget menu" id="tsd-toolbar-menu-trigger" data-toggle="menu" aria-label="Menu"><svg width="16" height="16" viewBox="0 0 16 16" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-menu"></use></svg></a></div></header><div class="container container-main"><div class="col-content"><div class="tsd-page-title"><ul class="tsd-breadcrumb" aria-label="Breadcrumb"><li><a href="" aria-current="page">features/work</a></li></ul></div><div class="tsd-panel tsd-typography"><h1 id="work-vr-数据实体" class="tsd-anchor-link">Work (VR 数据实体)<a href="#work-vr-数据实体" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h1>
<ul>
<li><strong>Summary</strong>: Work 是 Five 中最核心的数据实体,代表一个完整的 VR 项目,包含渲染场景所需的所有资源与配置。</li>
<li><strong>Schema</strong>: 包含 Observer, Model, Initial 等核心数据的接口。</li>
<li><strong>Concepts</strong>: Work Entity, Observer, WorkCode, Parsing。</li>
<li><strong>Examples</strong>: 数据加载、访问与多 Work 管理。</li>
</ul>
<h2 id="schema" class="tsd-anchor-link">Schema<a href="#schema" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h2>
<blockquote>
<p><strong>Definition</strong>: <a href="../../five/work/work.d.ts">Work</a>, <a href="../../five/work/looseWorkType.d.ts">LooseWork</a>, <a href="../../five/work/workJsonType.d.ts">WorkJson</a></p>
</blockquote>
<p><code>Work</code> 及其相关核心接口定义如下:</p>
<pre><code class="ts"><span class="hl-10">import</span><span class="hl-1"> </span><span class="hl-3">*</span><span class="hl-1"> </span><span class="hl-10">as</span><span class="hl-1"> </span><span class="hl-6">THREE</span><span class="hl-1"> </span><span class="hl-10">from</span><span class="hl-1"> </span><span class="hl-9">"three"</span><span class="hl-1">;</span><br/><span class="hl-10">import</span><span class="hl-1"> </span><span class="hl-10">type</span><span class="hl-1"> { </span><span class="hl-6">Mode</span><span class="hl-1"> } </span><span class="hl-10">from</span><span class="hl-1"> </span><span class="hl-9">"@realsee/five"</span><span class="hl-1">;</span><br/><br/><span class="hl-3">type</span><span class="hl-1"> </span><span class="hl-7">CubeFace</span><span class="hl-1"> = </span><span class="hl-9">'up'</span><span class="hl-1"> | </span><span class="hl-9">'down'</span><span class="hl-1"> | </span><span class="hl-9">'left'</span><span class="hl-1"> | </span><span class="hl-9">'right'</span><span class="hl-1"> | </span><span class="hl-9">'front'</span><span class="hl-1"> | </span><span class="hl-9">'back'</span><span class="hl-1">;</span><br/><br/><span class="hl-8">/** Work 实体:VR 项目的根对象 */</span><br/><span class="hl-10">export</span><span class="hl-1"> </span><span class="hl-3">interface</span><span class="hl-1"> </span><span class="hl-7">Work</span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-8">/** 唯一标识 (Work ID) */</span><br/><span class="hl-1"> </span><span class="hl-6">workCode</span><span class="hl-1">: </span><span class="hl-7">string</span><span class="hl-1">;</span><br/><span class="hl-1"> </span><span class="hl-8">/** 项目名称 */</span><br/><span class="hl-1"> </span><span class="hl-6">name</span><span class="hl-1">: </span><span class="hl-7">string</span><span class="hl-1">;</span><br/><span class="hl-1"> </span><span class="hl-8">/** 资源加载的基础路径 (Base URL) */</span><br/><span class="hl-1"> </span><span class="hl-6">baseURL</span><span class="hl-1">: </span><span class="hl-7">string</span><span class="hl-1">;</span><br/><span class="hl-1"> </span><span class="hl-8">/** 数据签发人 */</span><br/><span class="hl-1"> </span><span class="hl-6">issuer</span><span class="hl-1">: </span><span class="hl-7">string</span><span class="hl-1">;</span><br/><span class="hl-1"> </span><span class="hl-8">/** 过期时间 */</span><br/><span class="hl-1"> </span><span class="hl-6">expire</span><span class="hl-1">: </span><span class="hl-7">Date</span><span class="hl-1">;</span><br/><span class="hl-1"> </span><span class="hl-8">/** 允许访问的安全域名列表 */</span><br/><span class="hl-1"> </span><span class="hl-6">allowHosts</span><span class="hl-1">: </span><span class="hl-3">readonly</span><span class="hl-1"> </span><span class="hl-7">string</span><span class="hl-1">[];</span><br/><br/><span class="hl-1"> </span><span class="hl-8">/** 初始化参数 (默认模态、视角等) */</span><br/><span class="hl-1"> </span><span class="hl-6">initial</span><span class="hl-1">: </span><span class="hl-7">WorkInitial</span><span class="hl-1">;</span><br/><span class="hl-1"> </span><span class="hl-8">/** 相对位姿 (用于多 Work 拼接时的坐标变换) */</span><br/><span class="hl-1"> </span><span class="hl-6">transform</span><span class="hl-1">: </span><span class="hl-7">THREE</span><span class="hl-1">.</span><span class="hl-7">Matrix4</span><span class="hl-1">;</span><br/><br/><span class="hl-1"> </span><span class="hl-8">/** 模型参数 (3D 模型资源信息) */</span><br/><span class="hl-1"> </span><span class="hl-6">model</span><span class="hl-1">?: </span><span class="hl-7">WorkModel</span><span class="hl-1">;</span><br/><span class="hl-1"> </span><span class="hl-8">/** 全景点位信息 (所有可观测点位的列表) */</span><br/><span class="hl-1"> </span><span class="hl-6">observers</span><span class="hl-1">: </span><span class="hl-3">readonly</span><span class="hl-1"> </span><span class="hl-7">WorkObserver</span><span class="hl-1">[];</span><br/><span class="hl-1">}</span><br/><br/><span class="hl-8">/** 观察点:空间中可驻足观看的点位 */</span><br/><span class="hl-10">export</span><span class="hl-1"> </span><span class="hl-3">interface</span><span class="hl-1"> </span><span class="hl-7">WorkObserver</span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-8">/** 所属 Work 引用 */</span><br/><span class="hl-1"> </span><span class="hl-6">work</span><span class="hl-1">: </span><span class="hl-7">Work</span><span class="hl-1">;</span><br/><span class="hl-1"> </span><span class="hl-8">/** 在 observers 数组中的索引 */</span><br/><span class="hl-1"> </span><span class="hl-6">index</span><span class="hl-1">: </span><span class="hl-7">number</span><span class="hl-1">;</span><br/><span class="hl-1"> </span><span class="hl-8">/** 点位序号 (通常与 index 相同) */</span><br/><span class="hl-1"> </span><span class="hl-6">panoIndex</span><span class="hl-1">: </span><span class="hl-7">number</span><span class="hl-1">;</span><br/><span class="hl-1"> </span><span class="hl-8">/** 点位唯一 ID (通常格式为 `${workCode}[${panoIndex}]`) */</span><br/><span class="hl-1"> </span><span class="hl-6">panoId</span><span class="hl-1">: </span><span class="hl-7">string</span><span class="hl-1">;</span><br/><br/><span class="hl-1"> </span><span class="hl-8">/** 点位是否激活可用 */</span><br/><span class="hl-1"> </span><span class="hl-6">active</span><span class="hl-1">: </span><span class="hl-7">boolean</span><span class="hl-1">;</span><br/><span class="hl-1"> </span><span class="hl-8">/** 点位是否可加载 */</span><br/><span class="hl-1"> </span><span class="hl-6">loadable</span><span class="hl-1">: </span><span class="hl-7">boolean</span><span class="hl-1">;</span><br/><br/><span class="hl-1"> </span><span class="hl-8">/** 点位所在楼层索引 */</span><br/><span class="hl-1"> </span><span class="hl-6">floorIndex</span><span class="hl-1">: </span><span class="hl-7">number</span><span class="hl-1">;</span><br/><br/><span class="hl-1"> </span><span class="hl-8">/** 点位在模型坐标系下的观察位置 (用于渲染相机位置) */</span><br/><span class="hl-1"> </span><span class="hl-6">position</span><span class="hl-1">: </span><span class="hl-7">THREE</span><span class="hl-1">.</span><span class="hl-7">Vector3</span><span class="hl-1">;</span><br/><span class="hl-1"> </span><span class="hl-8">/** 点位在模型坐标系下的地面位置 (用于导航和 UI 定位) */</span><br/><span class="hl-1"> </span><span class="hl-6">standingPosition</span><span class="hl-1">: </span><span class="hl-7">THREE</span><span class="hl-1">.</span><span class="hl-7">Vector3</span><span class="hl-1">;</span><br/><span class="hl-1"> </span><span class="hl-8">/** 点位和模型的旋转对齐四元数 */</span><br/><span class="hl-1"> </span><span class="hl-6">quaternion</span><span class="hl-1">: </span><span class="hl-7">THREE</span><span class="hl-1">.</span><span class="hl-7">Quaternion</span><span class="hl-1">;</span><br/><span class="hl-1"> </span><span class="hl-8">/** 点位和模型的旋转对齐矩阵 */</span><br/><span class="hl-1"> </span><span class="hl-6">matrix</span><span class="hl-1">: </span><span class="hl-7">THREE</span><span class="hl-1">.</span><span class="hl-7">Matrix4</span><span class="hl-1">;</span><br/><br/><span class="hl-1"> </span><span class="hl-8">/** 可连通的相关点位序号 (用于全景游走) */</span><br/><span class="hl-1"> </span><span class="hl-6">accessibleNodes</span><span class="hl-1">: </span><span class="hl-3">readonly</span><span class="hl-1"> </span><span class="hl-7">number</span><span class="hl-1">[];</span><br/><br/><span class="hl-1"> </span><span class="hl-8">/** 点位全景图资源信息 */</span><br/><span class="hl-1"> </span><span class="hl-6">images</span><span class="hl-1">: </span><span class="hl-7">WorkImage</span><span class="hl-1">;</span><br/><br/><span class="hl-1"> </span><span class="hl-8">/** 获取点位的全局坐标 */</span><br/><span class="hl-1"> </span><span class="hl-5">getWorldPosition</span><span class="hl-1">(</span><span class="hl-3">this</span><span class="hl-1">: </span><span class="hl-7">WorkObserver</span><span class="hl-1">): </span><span class="hl-7">THREE</span><span class="hl-1">.</span><span class="hl-7">Vector3</span><span class="hl-1">;</span><br/><br/><span class="hl-1"> </span><span class="hl-8">/** 获取点位的全局地面坐标 */</span><br/><span class="hl-1"> </span><span class="hl-5">getWorldStandingPosition</span><span class="hl-1">(</span><span class="hl-3">this</span><span class="hl-1">: </span><span class="hl-7">WorkObserver</span><span class="hl-1">): </span><span class="hl-7">THREE</span><span class="hl-1">.</span><span class="hl-7">Vector3</span><span class="hl-1">;</span><br/><br/><span class="hl-1"> </span><span class="hl-8">/** 将方向向量转化为全景图 uv */</span><br/><span class="hl-1"> </span><span class="hl-5">vectorToEquirectangularUv</span><span class="hl-1">(</span><span class="hl-6">vector</span><span class="hl-1">: </span><span class="hl-7">THREE</span><span class="hl-1">.</span><span class="hl-7">Vector3</span><span class="hl-1">, </span><span class="hl-6">uvOrigin</span><span class="hl-1">?: </span><span class="hl-9">'top-left'</span><span class="hl-1"> | </span><span class="hl-9">'bottom-left'</span><span class="hl-1">): </span><span class="hl-7">THREE</span><span class="hl-1">.</span><span class="hl-7">Vector2</span><span class="hl-1">;</span><br/><span class="hl-1"> </span><span class="hl-8">/** 将全景图 uv 转化为方向向量 */</span><br/><span class="hl-1"> </span><span class="hl-5">equirectangularUvToVector</span><span class="hl-1">(</span><span class="hl-6">uv</span><span class="hl-1">: </span><span class="hl-7">THREE</span><span class="hl-1">.</span><span class="hl-7">Vector2</span><span class="hl-1">, </span><span class="hl-6">uvOrigin</span><span class="hl-1">?: </span><span class="hl-9">'top-left'</span><span class="hl-1"> | </span><span class="hl-9">'bottom-left'</span><span class="hl-1">): </span><span class="hl-7">THREE</span><span class="hl-1">.</span><span class="hl-7">Vector3</span><span class="hl-1">;</span><br/><span class="hl-1"> </span><span class="hl-8">/** 将方向向量转化为获六视图 uv */</span><br/><span class="hl-1"> </span><span class="hl-5">vectorToCubemapUv</span><span class="hl-1">(</span><span class="hl-6">vector</span><span class="hl-1">: </span><span class="hl-7">THREE</span><span class="hl-1">.</span><span class="hl-7">Vector3</span><span class="hl-1">, </span><span class="hl-6">uvOrigin</span><span class="hl-1">?: </span><span class="hl-9">'top-left'</span><span class="hl-1"> | </span><span class="hl-9">'bottom-left'</span><span class="hl-1">): [</span><span class="hl-13">cubeFace</span><span class="hl-1">: </span><span class="hl-7">CubeFace</span><span class="hl-1">, </span><span class="hl-13">cubemapUv</span><span class="hl-1">: </span><span class="hl-7">THREE</span><span class="hl-1">.</span><span class="hl-7">Vector2</span><span class="hl-1">];</span><br/><span class="hl-1"> </span><span class="hl-8">/** 将六视图 uv 转化为方向向量 */</span><br/><span class="hl-1"> </span><span class="hl-5">cubemapUvToVector</span><span class="hl-1">(</span><span class="hl-6">cubeFace</span><span class="hl-1">: </span><span class="hl-7">CubeFace</span><span class="hl-1">, </span><span class="hl-6">uv</span><span class="hl-1">: </span><span class="hl-7">THREE</span><span class="hl-1">.</span><span class="hl-7">Vector2</span><span class="hl-1">, </span><span class="hl-6">uvOrigin</span><span class="hl-1">?: </span><span class="hl-9">'top-left'</span><span class="hl-1"> | </span><span class="hl-9">'bottom-left'</span><span class="hl-1">): </span><span class="hl-7">THREE</span><span class="hl-1">.</span><span class="hl-7">Vector3</span><span class="hl-1">;</span><br/><span class="hl-1">}</span><br/><br/><span class="hl-8">/** 初始化位姿参数 */</span><br/><span class="hl-10">export</span><span class="hl-1"> </span><span class="hl-3">interface</span><span class="hl-1"> </span><span class="hl-7">WorkInitial</span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-6">work</span><span class="hl-1">: </span><span class="hl-7">Work</span><span class="hl-1">;</span><br/><span class="hl-1"> </span><span class="hl-8">/** 模态 */</span><br/><span class="hl-1"> </span><span class="hl-6">mode</span><span class="hl-1">?: </span><span class="hl-7">Mode</span><span class="hl-1">;</span><br/><span class="hl-1"> </span><span class="hl-8">/** 点位序号 */</span><br/><span class="hl-1"> </span><span class="hl-6">panoIndex</span><span class="hl-1">?: </span><span class="hl-7">number</span><span class="hl-1">;</span><br/><span class="hl-1"> </span><span class="hl-8">/** 相机水平角 */</span><br/><span class="hl-1"> </span><span class="hl-6">longitude</span><span class="hl-1">?: </span><span class="hl-7">number</span><span class="hl-1">;</span><br/><span class="hl-1"> </span><span class="hl-8">/** 相机俯仰角 */</span><br/><span class="hl-1"> </span><span class="hl-6">latitude</span><span class="hl-1">?: </span><span class="hl-7">number</span><span class="hl-1">;</span><br/><span class="hl-1"> </span><span class="hl-8">/** 相机可视角度(垂直)*/</span><br/><span class="hl-1"> </span><span class="hl-6">fov</span><span class="hl-1">?: </span><span class="hl-7">number</span><span class="hl-1">;</span><br/><span class="hl-1"> </span><span class="hl-8">/** 相机观察点位置 [x, y, z] */</span><br/><span class="hl-1"> </span><span class="hl-6">offset</span><span class="hl-1">?: </span><span class="hl-7">THREE</span><span class="hl-1">.</span><span class="hl-7">Vector3</span><span class="hl-1">;</span><br/><span class="hl-1"> </span><span class="hl-8">/** 相机距离观察点距离 */</span><br/><span class="hl-1"> </span><span class="hl-6">distance</span><span class="hl-1">?: </span><span class="hl-7">number</span><span class="hl-1">;</span><br/><span class="hl-1">}</span><br/><br/><span class="hl-8">/** 模型数据 */</span><br/><span class="hl-10">export</span><span class="hl-1"> </span><span class="hl-3">interface</span><span class="hl-1"> </span><span class="hl-7">WorkModel</span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-8">/** work */</span><br/><span class="hl-1"> </span><span class="hl-6">work</span><span class="hl-1">: </span><span class="hl-7">Work</span><span class="hl-1">;</span><br/><span class="hl-1"> </span><span class="hl-8">/** 模型文件地址 at3d / domez */</span><br/><span class="hl-1"> </span><span class="hl-6">file</span><span class="hl-1">?: </span><span class="hl-7">string</span><span class="hl-1">;</span><br/><span class="hl-1"> </span><span class="hl-8">/** 模型贴图文件地址 */</span><br/><span class="hl-1"> </span><span class="hl-6">textures</span><span class="hl-1">?: </span><span class="hl-3">readonly</span><span class="hl-1"> </span><span class="hl-7">string</span><span class="hl-1">[];</span><br/><span class="hl-1"> </span><span class="hl-8">/** 模型贴图文件地址的父目录 */</span><br/><span class="hl-1"> </span><span class="hl-6">textureBase</span><span class="hl-1">?: </span><span class="hl-7">string</span><span class="hl-1">;</span><br/><span class="hl-1"> </span><span class="hl-8">/** 指定上方向,对于 obj, ply 等定义不明确的需要指定上方向 */</span><br/><span class="hl-1"> </span><span class="hl-6">upAxis</span><span class="hl-1">?: </span><span class="hl-7">string</span><span class="hl-1">;</span><br/><span class="hl-1"> </span><span class="hl-8">/** 3d tile */</span><br/><span class="hl-1"> </span><span class="hl-6">layers</span><span class="hl-1">: </span><span class="hl-3">readonly</span><span class="hl-1"> </span><span class="hl-7">WorkModelLayer</span><span class="hl-1">[];</span><br/><span class="hl-1">}</span><br/><br/><span class="hl-8">/** 模型图层信息 */</span><br/><span class="hl-10">export</span><span class="hl-1"> </span><span class="hl-3">interface</span><span class="hl-1"> </span><span class="hl-7">WorkModelLayer</span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-8">/** work */</span><br/><span class="hl-1"> </span><span class="hl-6">work</span><span class="hl-1">: </span><span class="hl-7">Work</span><span class="hl-1">;</span><br/><span class="hl-1"> </span><span class="hl-8">/** 模型类型 point_cloud mesh gaussian_splatting */</span><br/><span class="hl-1"> </span><span class="hl-6">type</span><span class="hl-1">: </span><span class="hl-9">'point_cloud'</span><span class="hl-1"> | </span><span class="hl-9">'mesh'</span><span class="hl-1"> | </span><span class="hl-9">'gaussian_splatting'</span><span class="hl-1">;</span><br/><span class="hl-1"> </span><span class="hl-8">/** 模型名称 */</span><br/><span class="hl-1"> </span><span class="hl-6">name</span><span class="hl-1">: </span><span class="hl-7">string</span><span class="hl-1">;</span><br/><span class="hl-1"> </span><span class="hl-8">/** 指定上方向 */</span><br/><span class="hl-1"> </span><span class="hl-6">upAxis</span><span class="hl-1">: </span><span class="hl-7">string</span><span class="hl-1">;</span><br/><span class="hl-1"> </span><span class="hl-8">/** tileset.json 地址 */</span><br/><span class="hl-1"> </span><span class="hl-6">tileset</span><span class="hl-1">: </span><span class="hl-7">string</span><span class="hl-1">;</span><br/><span class="hl-1">}</span><br/><br/><span class="hl-8">/** 全景图资源信息 */</span><br/><span class="hl-10">export</span><span class="hl-1"> </span><span class="hl-3">interface</span><span class="hl-1"> </span><span class="hl-7">WorkImage</span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-6">work</span><span class="hl-1">: </span><span class="hl-7">Work</span><span class="hl-1">;</span><br/><span class="hl-1"> </span><span class="hl-8">/** 分辨率表 */</span><br/><span class="hl-1"> </span><span class="hl-6">sizeList</span><span class="hl-1">: </span><span class="hl-3">readonly</span><span class="hl-1"> </span><span class="hl-7">number</span><span class="hl-1">[];</span><br/><span class="hl-1"> </span><span class="hl-8">/** 瓦片信息 */</span><br/><span class="hl-1"> </span><span class="hl-6">tiles</span><span class="hl-1">: </span><span class="hl-3">readonly</span><span class="hl-1"> </span><span class="hl-7">WorkTile</span><span class="hl-1">[];</span><br/><span class="hl-1"> </span><span class="hl-8">/** 缩略图/预览图等 */</span><br/><span class="hl-1"> [</span><span class="hl-6">key</span><span class="hl-1">: </span><span class="hl-7">string</span><span class="hl-1">]: </span><span class="hl-7">any</span><span class="hl-1">;</span><br/><span class="hl-1">}</span>
</code><button type="button">Copy</button></pre>
<h2 id="concepts" class="tsd-anchor-link">Concepts<a href="#concepts" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h2>
<h3 id="work-entity-项目实体" class="tsd-anchor-link">Work Entity (项目实体)<a href="#work-entity-项目实体" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3>
<p>Work 是 Five 渲染内容的基石。它不仅包含资源地址,还包含空间结构数据。由于数据通常带有数字签名(防止篡改),开发者<strong>不应手动修改</strong> Work 对象中的属性,尤其是资源路径和坐标数据。</p>
<h3 id="data-types-数据类型" class="tsd-anchor-link">Data Types (数据类型)<a href="#data-types-数据类型" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3>
<p>Five 中有三种与 Work 相关的类型,它们分别对应不同的使用场景:</p>
<ul>
<li><strong>LooseWork (宽泛数据)</strong>:
<ul>
<li><strong>来源</strong>: 通常是服务端下发的原始 JSON 数据。</li>
<li><strong>特点</strong>: 结构宽松,允许缺省值(如使用默认模态)、简写(如 URL 模板)和非标准类型(如数组表示向量)。</li>
<li><strong>用途</strong>: 作为 <code>parseWork(json)</code> 的输入。</li>
</ul>
</li>
<li><strong>Work (运行时实体)</strong>:
<ul>
<li><strong>来源</strong>: 由 <code>parseWork</code> 解析生成。</li>
<li><strong>特点</strong>: 结构严谨,数据已标准化(如 URL 已补全,向量转为 <code>THREE.Vector3</code>),且被冻结(不可变)。</li>
<li><strong>用途</strong>: Five 内部渲染使用的核心对象,传给 <code>five.load(work)</code>。</li>
</ul>
</li>
<li><strong>WorkJson (标准序列化)</strong>:
<ul>
<li><strong>来源</strong>: 由 <code>workToJson(work)</code> 生成。</li>
<li><strong>特点</strong>: 纯 JSON 结构,去除了运行时对象(如 THREE.Vector3),但保留了标准化的数据结构。</li>
<li><strong>用途</strong>: 用于数据持久化存储或跨端传输。</li>
</ul>
</li>
</ul>
<h3 id="layers-vs-file-数据源关系" class="tsd-anchor-link">Layers vs File (数据源关系)<a href="#layers-vs-file-数据源关系" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3>
<p><code>WorkModel</code> 提供了两种定义模型数据的方式,其中 <code>layers</code> 是现代标准,<code>file</code> 主要用于兼容旧数据或简单场景。</p>
<ul>
<li><strong><code>layers</code></strong>: (推荐) 数组结构,用于定义多层级、多类型的模型资源。
<ul>
<li>支持 <strong>3DTiles</strong> 格式的分块加载。</li>
<li>支持多种类型混合:<code>mesh</code> (模型), <code>point_cloud</code> (点云), <code>gaussian_splatting</code> (高斯泼溅)。</li>
<li><strong>默认行为</strong>: 列表中的所有图层默认都会被加载并显示。</li>
</ul>
</li>
<li><strong><code>file</code></strong>: (兼容) 字符串路径,用于定义单文件的 Mesh 模型。
<ul>
<li>仅支持部分格式(如 <code>.at3d</code>, <code>.obj</code>, <code>.glb</code>)。</li>
<li>不支持点云或高斯泼溅。</li>
</ul>
</li>
</ul>
<p><strong>加载优先级与兼容逻辑 (Fallback)</strong>:</p>
<p>Five 在运行时会将 <code>file</code> 视为一个虚拟的 <code>mesh</code> 图层。加载逻辑如下:</p>
<ol>
<li>
<p><strong>优先加载 Layers</strong>:
Five 会遍历 <code>work.model.layers</code> 并加载其中定义的所有图层(包括 Mesh, PointCloud, GaussianSplatting 等)。</p>
</li>
<li>
<p><strong>File 的条件加载</strong>:
检查当前已加载的图层中是否存在 <code>type: 'mesh'</code> 的图层。</p>
<ul>
<li><strong>存在 Mesh 层</strong>: 忽略 <code>work.model.file</code> 字段(认为 <code>layers</code> 已经提供了更高精度的模型)。</li>
<li><strong>不存在 Mesh 层</strong>: 如果 <code>work.model.file</code> 有值,Five 会自动创建一个临时的 Mesh ViewLayer 来加载该文件。</li>
</ul>
</li>
</ol>
<h3 id="observer-观察点" class="tsd-anchor-link">Observer (观察点)<a href="#observer-观察点" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3>
<p>Observer 是 VR 空间中预设的观察位置。在 <strong>Panorama (全景)</strong> 模式下,相机必须停留在某个 Observer 上。</p>
<ul>
<li><strong>position</strong>: 相机镜头的物理位置。</li>
<li><strong>standingPosition</strong>: 对应的地面位置(脚底)。通常用于下绘制点位图标,或计算点位间的导航距离。</li>
<li><strong>accessibleNodes</strong>: 定义了该点位可以“走到”哪些相邻点位,构成了全景游走的图结构。</li>
</ul>
<h3 id="workcode-唯一标识" class="tsd-anchor-link">WorkCode (唯一标识)<a href="#workcode-唯一标识" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3>
<p><code>workCode</code> 是 Work 的全局唯一标识符。</p>
<ul>
<li><strong>单 Work 场景</strong>: 通常不需要显式关注。</li>
<li><strong>多 Work 场景</strong>: 当 Five 同时加载多个 Work(如拼接的大型空间)时,必须通过 <code>workCode</code> 来区分不同 Work 下的同名属性(如 <code>panoIndex</code>)。</li>
</ul>
<h3 id="parsing-数据解析" class="tsd-anchor-link">Parsing (数据解析)<a href="#parsing-数据解析" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3>
<p>从服务端获取的原始 JSON 数据(LooseWork)可能包含相对路径或简写。<code>parseWork</code> 函数负责将其标准化为严格的 <code>Work</code> 对象,处理 URL 拼接、默认值填充和数据校验。</p>
<h2 id="examples" class="tsd-anchor-link">Examples<a href="#examples" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h2>
<h3 id="1-解析与加载-work" class="tsd-anchor-link">1. 解析与加载 Work<a href="#1-解析与加载-work" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3>
<p>最基础的用法是从 API 获取数据并加载。</p>
<pre><code class="ts"><span class="hl-10">import</span><span class="hl-1"> { </span><span class="hl-6">Five</span><span class="hl-1">, </span><span class="hl-6">parseWork</span><span class="hl-1"> } </span><span class="hl-10">from</span><span class="hl-1"> </span><span class="hl-9">"@realsee/five"</span><span class="hl-1">;</span><br/><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">five</span><span class="hl-1"> = </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-5">Five</span><span class="hl-1">();</span><br/><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-5">appendTo</span><span class="hl-1">(</span><span class="hl-6">document</span><span class="hl-1">.</span><span class="hl-5">getElementById</span><span class="hl-1">(</span><span class="hl-9">"app"</span><span class="hl-1">));</span><br/><br/><span class="hl-8">// 1. 获取数据</span><br/><span class="hl-5">fetch</span><span class="hl-1">(</span><span class="hl-9">"https://vrlab-public.ljcdn.com/release/web/work.json"</span><span class="hl-1">)</span><br/><span class="hl-1"> .</span><span class="hl-5">then</span><span class="hl-1">(</span><span class="hl-6">res</span><span class="hl-1"> </span><span class="hl-3">=></span><span class="hl-1"> </span><span class="hl-6">res</span><span class="hl-1">.</span><span class="hl-5">json</span><span class="hl-1">())</span><br/><span class="hl-1"> .</span><span class="hl-5">then</span><span class="hl-1">(</span><span class="hl-6">json</span><span class="hl-1"> </span><span class="hl-3">=></span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-8">// 2. 解析数据</span><br/><span class="hl-1"> </span><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">work</span><span class="hl-1"> = </span><span class="hl-5">parseWork</span><span class="hl-1">(</span><span class="hl-6">json</span><span class="hl-1">);</span><br/><span class="hl-1"> </span><span class="hl-8">// 3. 加载到 Five</span><br/><span class="hl-1"> </span><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-5">load</span><span class="hl-1">(</span><span class="hl-6">work</span><span class="hl-1">);</span><br/><span class="hl-1"> });</span>
</code><button type="button">Copy</button></pre>
<h3 id="2-访问-work-数据" class="tsd-anchor-link">2. 访问 Work 数据<a href="#2-访问-work-数据" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3>
<p>加载完成后,可以通过 <code>five.work</code> 访问当前数据。</p>
<pre><code class="ts"><span class="hl-8">// 获取所有观察点</span><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">observers</span><span class="hl-1"> = </span><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-6">work</span><span class="hl-1">.</span><span class="hl-6">observers</span><span class="hl-1">;</span><br/><br/><span class="hl-8">// 获取当前所在的观察点</span><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">currentPanoIndex</span><span class="hl-1"> = </span><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-6">state</span><span class="hl-1">.</span><span class="hl-6">panoIndex</span><span class="hl-1">;</span><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">currentObserver</span><span class="hl-1"> = </span><span class="hl-6">observers</span><span class="hl-1">[</span><span class="hl-6">currentPanoIndex</span><span class="hl-1">];</span><br/><br/><span class="hl-6">console</span><span class="hl-1">.</span><span class="hl-5">log</span><span class="hl-1">(</span><span class="hl-9">"当前点位坐标:"</span><span class="hl-1">, </span><span class="hl-6">currentObserver</span><span class="hl-1">.</span><span class="hl-6">position</span><span class="hl-1">);</span><br/><span class="hl-6">console</span><span class="hl-1">.</span><span class="hl-5">log</span><span class="hl-1">(</span><span class="hl-9">"可通往的点位:"</span><span class="hl-1">, </span><span class="hl-6">currentObserver</span><span class="hl-1">.</span><span class="hl-6">accessibleNodes</span><span class="hl-1">);</span>
</code><button type="button">Copy</button></pre>
<h3 id="3-多-work-加载与管理" class="tsd-anchor-link">3. 多 Work 加载与管理<a href="#3-多-work-加载与管理" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3>
<p>Five 支持同时加载多个 Work,常用于楼盘小区的多个样板间拼接,或大型商业空间的区域拼接。</p>
<pre><code class="ts"><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">work1</span><span class="hl-1"> = </span><span class="hl-5">parseWork</span><span class="hl-1">(</span><span class="hl-6">json1</span><span class="hl-1">);</span><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">work2</span><span class="hl-1"> = </span><span class="hl-5">parseWork</span><span class="hl-1">(</span><span class="hl-6">json2</span><span class="hl-1">);</span><br/><br/><span class="hl-8">// 同时加载两个 Work</span><br/><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-5">load</span><span class="hl-1">([</span><span class="hl-6">work1</span><span class="hl-1">, </span><span class="hl-6">work2</span><span class="hl-1">]);</span><br/><br/><span class="hl-8">// 切换到指定 Work 的指定点位</span><br/><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-5">setState</span><span class="hl-1">({</span><br/><span class="hl-1"> </span><span class="hl-6">mode:</span><span class="hl-1"> </span><span class="hl-9">"Panorama"</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-6">workCode:</span><span class="hl-1"> </span><span class="hl-6">work2</span><span class="hl-1">.</span><span class="hl-6">workCode</span><span class="hl-1">, </span><span class="hl-8">// 必须指定 workCode</span><br/><span class="hl-1"> </span><span class="hl-6">panoIndex:</span><span class="hl-1"> </span><span class="hl-11">0</span><br/><span class="hl-1">});</span>
</code><button type="button">Copy</button></pre>
<h3 id="4-追加与替换-work" class="tsd-anchor-link">4. 追加与替换 Work<a href="#4-追加与替换-work" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3>
<p>可以使用 <code>load</code> 方法的参数来控制是替换当前场景还是追加到当前场景。</p>
<pre><code class="ts"><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">work3</span><span class="hl-1"> = </span><span class="hl-5">parseWork</span><span class="hl-1">(</span><span class="hl-6">json3</span><span class="hl-1">);</span><br/><br/><span class="hl-8">// 追加 Work (保留原有场景)</span><br/><span class="hl-8">// 第二个参数 "inherit" 表示保持当前相机视角和模态不变,不重置为新 Work 的初始视角</span><br/><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-5">load</span><span class="hl-1">(</span><span class="hl-6">work3</span><span class="hl-1">, </span><span class="hl-9">"inherit"</span><span class="hl-1">, { </span><span class="hl-6">mode:</span><span class="hl-1"> </span><span class="hl-9">"add"</span><span class="hl-1"> });</span><br/><br/><span class="hl-8">// 替换 Work (清空原有场景) - 默认行为</span><br/><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-5">load</span><span class="hl-1">(</span><span class="hl-6">work3</span><span class="hl-1">, </span><span class="hl-9">"inherit"</span><span class="hl-1">, { </span><span class="hl-6">mode:</span><span class="hl-1"> </span><span class="hl-9">"replace"</span><span class="hl-1"> });</span>
</code><button type="button">Copy</button></pre>
<h2 id="common-pitfalls" class="tsd-anchor-link">Common Pitfalls<a href="#common-pitfalls" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h2>
<ul>
<li><strong>数据不可变性</strong>: Work 数据包含签名信息,直接修改 <code>work.observers[0].position.x = 100</code> 虽不会报错,但可能导致渲染异常或签名验证失败。请视 Work 为只读对象。</li>
<li><strong>坐标系</strong>: Five 使用 <strong>Y-Up 右手坐标系</strong>,单位为<strong>米</strong>。与 Three.js 默认坐标系一致。</li>
<li><strong>跨域问题 (CORS)</strong>: <code>baseURL</code> 指向的资源服务器必须配置正确的 CORS 头,否则 WebGL 无法加载纹理。</li>
<li><strong>parseWork 必选</strong>: 永远不要尝试手动构造 <code>Work</code> 对象,总是使用 <code>parseWork</code>。服务端数据结构可能会升级,<code>parseWork</code> 会处理兼容性。</li>
</ul>
<h2 id="related" class="tsd-anchor-link">Related<a href="#related" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h2>
<ul>
<li><a href="features_state.html">State</a>: 了解如何通过 State 切换点位。</li>
<li><a href="features_mode.html">Mode</a>: 了解不同模态下 Work 数据的表现。</li>
</ul>
<hr>
<pre><code class="yaml"><span class="hl-0">tags</span><span class="hl-1">: [</span><span class="hl-2">VR数据</span><span class="hl-1">, </span><span class="hl-2">数据加载</span><span class="hl-1">, </span><span class="hl-2">点位</span><span class="hl-1">, </span><span class="hl-2">全景点</span><span class="hl-1">, </span><span class="hl-2">数据结构</span><span class="hl-1">, </span><span class="hl-2">多work</span><span class="hl-1">, </span><span class="hl-2">work</span><span class="hl-1">, </span><span class="hl-2">core</span><span class="hl-1">, </span><span class="hl-2">entity</span><span class="hl-1">, </span><span class="hl-2">observer</span><span class="hl-1">, </span><span class="hl-2">parseWork</span><span class="hl-1">, </span><span class="hl-2">workCode</span><span class="hl-1">, </span><span class="hl-2">JSON</span><span class="hl-1">, </span><span class="hl-2">load</span><span class="hl-1">]</span>
</code><button type="button">Copy</button></pre>
</div></div><div class="col-sidebar"><div class="page-menu"><div class="tsd-navigation settings"><details class="tsd-accordion"><summary class="tsd-accordion-summary"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-chevronDown"></use></svg><h3>Settings</h3></summary><div class="tsd-accordion-details"><div class="tsd-filter-visibility"><span class="settings-label">Member Visibility</span><ul id="tsd-filter-options"><li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-inherited" name="inherited" checked/><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></svg><span>Inherited</span></label></li></ul></div><div class="tsd-theme-toggle"><label class="settings-label" for="tsd-theme">Theme</label><select id="tsd-theme"><option value="os">OS</option><option value="light">Light</option><option value="dark">Dark</option></select></div></div></details></div><details open class="tsd-accordion tsd-page-navigation"><summary class="tsd-accordion-summary"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-chevronDown"></use></svg><h3>On This Page</h3></summary><div class="tsd-accordion-details"><a href="#work-vr-数据实体"><span>Work (<wbr/>VR 数据实体)</span></a><ul><li><a href="#schema"><span>Schema</span></a></li><li><a href="#concepts"><span>Concepts</span></a></li><li><ul><li><a href="#work-entity-项目实体"><span>Work <wbr/>Entity (项目实体)</span></a></li><li><a href="#data-types-数据类型"><span>Data <wbr/>Types (数据类型)</span></a></li><li><a href="#layers-vs-file-数据源关系"><span>Layers vs <wbr/>File (数据源关系)</span></a></li><li><a href="#observer-观察点"><span>Observer (观察点)</span></a></li><li><a href="#workcode-唯一标识"><span>Work<wbr/>Code (唯一标识)</span></a></li><li><a href="#parsing-数据解析"><span>Parsing (数据解析)</span></a></li></ul></li><li><a href="#examples"><span>Examples</span></a></li><li><ul><li><a href="#1-解析与加载-work"><span>1. 解析与加载 <wbr/>Work</span></a></li><li><a href="#2-访问-work-数据"><span>2. 访问 <wbr/>Work 数据</span></a></li><li><a href="#3-多-work-加载与管理"><span>3. 多 <wbr/>Work 加载与管理</span></a></li><li><a href="#4-追加与替换-work"><span>4. 追加与替换 <wbr/>Work</span></a></li></ul></li><li><a href="#common-pitfalls"><span>Common <wbr/>Pitfalls</span></a></li><li><a href="#related"><span>Related</span></a></li></ul></div></details></div><div class="site-menu"><nav class="tsd-navigation"><a href="../modules.html">如视 Five SDK</a><ul class="tsd-small-nested-navigation" id="tsd-nav-container"><li>Loading...</li></ul></nav></div></div></div><footer><p class="tsd-generator">Generated using <a href="https://typedoc.org/" target="_blank">TypeDoc</a></p></footer><div class="overlay"></div></body></html>