@realsee/five/docs/documents/features_state.html

Realsee Renderer SDK

<!DOCTYPE html><html class="default" lang="en" data-base="../"><head><meta charset="utf-8"/><meta http-equiv="x-ua-compatible" content="IE=edge"/><title>features/state | 如视 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/state</a></li></ul></div><div class="tsd-panel tsd-typography"><h1 id="state-状态" class="tsd-anchor-link">State (状态)<a href="#state-状态" 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>: State 是 Five 的核心状态对象，描述了当前的显示模式、观察点位以及相机的空间姿态。</li>
<li><strong>Schema</strong>: 包含 Pose (相机姿态) 和 Mode (模式) 等属性的接口。</li>
<li><strong>Concepts</strong>: Camera Pose, Coordinate System, Mode Specifics。</li>
<li><strong>Examples</strong>: 状态获取与更新。</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/types/state.d.ts">State</a></p>
</blockquote>
<p><strong>State</strong> 类型定义如下（继承自 <code>Pose</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">&quot;three&quot;</span><span class="hl-1">;</span><br/><span class="hl-10">import</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">&quot;@realsee/five&quot;</span><span class="hl-1">;</span><br/><br/><span class="hl-3">interface</span><span class="hl-1"> </span><span class="hl-7">Pose</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">/** 相机看向的目标中心点坐标 */</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-3">interface</span><span class="hl-1"> </span><span class="hl-7">State</span><span class="hl-1"> </span><span class="hl-3">extends</span><span class="hl-1"> </span><span class="hl-7">Pose</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">/** 当前点位的唯一标识 (workCode) */</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">panoIndex</span><span class="hl-1">: </span><span class="hl-7">number</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>
<ul>
<li><strong>Camera Pose (相机姿态)</strong>: Five 使用球坐标系 (Spherical) + 笛卡尔偏移 (Cartesian Offset) 来描述相机位置。
<ul>
<li>相机始终位于以 <code>offset</code> 为中心、<code>distance</code> 为半径的球面上。</li>
<li><strong>longitude</strong>: 球面上的经度（水平旋转）。</li>
<li><strong>latitude</strong>: 球面上的纬度（垂直旋转）。</li>
<li><strong>offset</strong>: 相机“看向”的点，也是球心。</li>
<li><strong>distance</strong>: 相机到 <code>offset</code> 的距离。</li>
</ul>
</li>
<li><strong>Coordinate System (坐标系)</strong>:
<ul>
<li>采用 Y-Up 右手坐标系（与 Three.js 默认一致）。</li>
<li>单位长度为米。</li>
</ul>
</li>
<li><strong>Mode Specifics (模式特性)</strong>:
<ul>
<li><strong>Panorama</strong>: <code>distance</code> 通常为 0，即相机位置与 <code>offset</code> 重合（第一人称视角）。</li>
<li><strong>Floorplan/Mapview</strong>: <code>offset</code> 通常位于模型中心，<code>distance</code> 大于模型包围盒半径（第三人称上帝视角）。</li>
</ul>
</li>
<li><strong>State vs CurrentState</strong>:
<ul>
<li><strong>five.state</strong>: <strong>目标状态</strong>。表示相机最终应该到达的状态。当调用 <code>setState</code> 或用户交互结束时，此值即为最终结果。通常用于 UI 同步（如高亮当前模式按钮）。</li>
<li><strong>five.getCurrentState()</strong>: <strong>瞬时状态</strong>。表示当前渲染帧相机的实际状态。在动画过渡过程中，<code>currentState</code> 会不断变化直至追赶上 <code>state</code>。通常用于需要实时反馈的场景（如罗盘旋转）。</li>
</ul>
</li>
</ul>
<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="快速上手-quick-example" class="tsd-anchor-link">快速上手 (Quick Example)<a href="#快速上手-quick-example" 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>setState</code> 更新状态：</p>
<pre><code class="ts"><span class="hl-8">// 切换到户型图模式，并旋转相机到 45 度</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">&#39;Floorplan&#39;</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-6">longitude:</span><span class="hl-1"> </span><span class="hl-6">Math</span><span class="hl-1">.</span><span class="hl-4">PI</span><span class="hl-1"> / </span><span class="hl-11">4</span><br/><span class="hl-1">});</span>
</code><button type="button">Copy</button></pre>

<h3 id="详细示例-detailed-example" class="tsd-anchor-link">详细示例 (Detailed Example)<a href="#详细示例-detailed-example" 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>获取当前状态并基于此修改：</p>
<pre><code class="ts"><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">state</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><br/><br/><span class="hl-8">// 在当前状态基础上，向右旋转 90 度，并略微拉远距离</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">longitude:</span><span class="hl-1"> </span><span class="hl-6">state</span><span class="hl-1">.</span><span class="hl-6">longitude</span><span class="hl-1"> + </span><span class="hl-6">Math</span><span class="hl-1">.</span><span class="hl-4">PI</span><span class="hl-1"> / </span><span class="hl-11">2</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-6">distance:</span><span class="hl-1"> </span><span class="hl-6">state</span><span class="hl-1">.</span><span class="hl-6">distance</span><span class="hl-1"> + </span><span class="hl-11">2.0</span><br/><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>
<ol>
<li><strong>单位混淆</strong>: <code>longitude</code> 和 <code>latitude</code> 使用<strong>弧度</strong>，而 <code>fov</code> 使用<strong>角度</strong>（度）。</li>
<li><strong>Offset 类型</strong>: <code>offset</code> 必须是 <code>THREE.Vector3</code> 实例。如果在 React 等框架中使用纯对象（Plain Object），Five 内部会自动转换，但在 TypeScript 中需注意类型匹配。</li>
<li><strong>异步更新</strong>: <code>setState</code> 触发的相机运动是异步动画过程。如果需要立即无动画跳转，可传递第二个参数 <code>immediately: true</code>。</li>
<li><strong>JSON 序列化</strong>: <code>State</code> 中的 <code>offset</code> 是 <code>THREE.Vector3</code> 实例，不能直接 <code>JSON.stringify</code>。保存时需手动提取 <code>{ x, y, z }</code>，恢复时需重新构造 <code>new THREE.Vector3(x, y, z)</code>。</li>
</ol>
<pre><code class="typescript"><span class="hl-8">// 保存</span><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">snapshot</span><span class="hl-1"> = {</span><br/><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><br/><span class="hl-1">  </span><span class="hl-6">offset:</span><span class="hl-1"> { </span><span class="hl-6">x:</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">offset</span><span class="hl-1">.</span><span class="hl-6">x</span><span class="hl-1">, </span><span class="hl-6">y:</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">offset</span><span class="hl-1">.</span><span class="hl-6">y</span><span class="hl-1">, </span><span class="hl-6">z:</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">offset</span><span class="hl-1">.</span><span class="hl-6">z</span><span class="hl-1"> }</span><br/><span class="hl-1">};</span><br/><span class="hl-6">localStorage</span><span class="hl-1">.</span><span class="hl-5">setItem</span><span class="hl-1">(</span><span class="hl-9">&#39;fiveState&#39;</span><span class="hl-1">, </span><span class="hl-4">JSON</span><span class="hl-1">.</span><span class="hl-5">stringify</span><span class="hl-1">(</span><span class="hl-6">snapshot</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">saved</span><span class="hl-1"> = </span><span class="hl-4">JSON</span><span class="hl-1">.</span><span class="hl-5">parse</span><span class="hl-1">(</span><span class="hl-6">localStorage</span><span class="hl-1">.</span><span class="hl-5">getItem</span><span class="hl-1">(</span><span class="hl-9">&#39;fiveState&#39;</span><span class="hl-1">)!);</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">saved</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-6">offset:</span><span class="hl-1"> </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-4">THREE</span><span class="hl-1">.</span><span class="hl-5">Vector3</span><span class="hl-1">(</span><span class="hl-6">saved</span><span class="hl-1">.</span><span class="hl-6">offset</span><span class="hl-1">.</span><span class="hl-6">x</span><span class="hl-1">, </span><span class="hl-6">saved</span><span class="hl-1">.</span><span class="hl-6">offset</span><span class="hl-1">.</span><span class="hl-6">y</span><span class="hl-1">, </span><span class="hl-6">saved</span><span class="hl-1">.</span><span class="hl-6">offset</span><span class="hl-1">.</span><span class="hl-6">z</span><span class="hl-1">)</span><br/><span class="hl-1">}, </span><span class="hl-3">true</span><span class="hl-1">);</span>
</code><button type="button">Copy</button></pre>

<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_mode.html">Mode - 模式</a>: 详细了解各种 Mode 的区别。</li>
<li><a href="features_camera-animation.html">Camera Animation</a>: 基于 State 的相机动画控制。</li>
<li><a href="features_five.html">Five</a>: Five 核心类，<code>setState</code> / <code>getCurrentState</code> 的宿主。</li>
<li><a href="features_coordinate-system.html">Coordinate System</a>: 坐标系定义。</li>
</ul>
<hr>
<pre><code class="yaml"><span class="hl-0">tags</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">camera</span><span class="hl-1">, </span><span class="hl-2">state</span><span class="hl-1">, </span><span class="hl-2">pose</span><span class="hl-1">, </span><span class="hl-2">interaction</span><span class="hl-1">, </span><span class="hl-2">save</span><span class="hl-1">, </span><span class="hl-2">restore</span><span class="hl-1">, </span><span class="hl-2">snapshot</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="#state-状态"><span>State (状态)</span></a><ul><li><a href="#schema"><span>Schema</span></a></li><li><a href="#concepts"><span>Concepts</span></a></li><li><a href="#examples"><span>Examples</span></a></li><li><ul><li><a href="#快速上手-quick-example"><span>快速上手 (<wbr/>Quick <wbr/>Example)</span></a></li><li><a href="#详细示例-detailed-example"><span>详细示例 (<wbr/>Detailed <wbr/>Example)</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>