@realsee/five 6.8.0-alpha.3 → 6.8.0-alpha.31

package/docs/documents/features_state.html

@@ -6,6 +6,9 @@
 <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>
@@ -48,7 +51,7 @@
 
 <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">tate</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">tate</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>
+<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>
@@ -56,13 +59,20 @@
 <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">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>
+<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>

package/docs/documents/features_view-layer.html

@@ -0,0 +1,158 @@
+<!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/view-layer | 如视 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/view-layer</a></li></ul></div><div class="tsd-panel tsd-typography"><h1 id="viewlayer-视图层" class="tsd-anchor-link">ViewLayer (视图层)<a href="#viewlayer-视图层" 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>: ViewLayer 是 Model 的组成部分，负责管理具体的 3D 资源（如 Mesh 或 PointCloud），支持独立的渲染配置和可见性控制。</li>
+<li><strong>Schema</strong>: 继承自 <code>Tile3D</code>，由 <code>Model</code> 统一管理。</li>
+<li><strong>Concepts</strong>: Layer Fallback, 3DTile Integration, Parameter Inheritance.</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/model/view-layer.d.ts">ViewLayer</a>, <a href="../../five/model/view-layer.d.ts">ViewLayerInit</a></p>
+</blockquote>
+<p>ViewLayer 是一个具体的渲染图层，它对应一个具体的 3D 数据源（通常是一个 <code>.gltf</code> / <code>.b3dm</code> / <code>.pnts</code> 等 Tileset 入口）。</p>
+<pre><code class="typescript"><span class="hl-8">// 简化定义</span><br/><span class="hl-3">interface</span><span class="hl-1"> </span><span class="hl-7">ViewLayer</span><span class="hl-1"> </span><span class="hl-3">extends</span><span class="hl-1"> </span><span class="hl-7">Tile3D</span><span class="hl-1"> {</span><br/><span class="hl-1">  </span><span class="hl-8">/** 图层名称 (如 &#39;mesh&#39;, &#39;point_cloud&#39;) */</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">type</span><span class="hl-1">: </span><span class="hl-9">&quot;point_cloud&quot;</span><span class="hl-1"> | </span><span class="hl-9">&quot;mesh&quot;</span><span class="hl-1"> | </span><span class="hl-9">&quot;gaussian_splatting&quot;</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">parameter</span><span class="hl-1">: </span><span class="hl-7">Parameter</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">visible</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">/** 对应的 Tileset URL */</span><br/><span class="hl-1">  </span><span class="hl-6">tilesetUrl</span><span class="hl-1">: </span><span class="hl-7">string</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="1-viewlayer-vs-workmodel" class="tsd-anchor-link">1. ViewLayer vs Work.Model<a href="#1-viewlayer-vs-workmodel" 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>ViewLayer</code> 的生成逻辑严格依赖于 <code>Work</code> 数据中的定义，但也包含了向后兼容的 Fallback 机制。</p>
+<h4 id="数据来源-data-source" class="tsd-anchor-link">数据来源 (Data Source)<a href="#数据来源-data-source" 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></h4>
+<ol>
+<li>
+<p><strong>优先使用 <code>work.model.layers</code></strong>:
+这是标准的定义方式。<code>work.model.layers</code> 是一个数组，每个元素显式定义了一个 Layer 的 <code>name</code>, <code>type</code>, <code>tileset</code> (URL) 等信息。
+Five 会遍历这个数组，为每一项创建一个 <code>ViewLayer</code> 实例。</p>
+</li>
+<li>
+<p><strong>Fallback to <code>work.model.file</code></strong>:
+如果 <code>work.model.layers</code> 中没有定义 <code>mesh</code> 类型的层，且 <code>work.model.file</code> 存在（旧版数据字段），Five 会自动创建一个 <strong>虚拟的 Mesh Layer</strong>。</p>
+<ul>
+<li><strong>Name</strong>: 默认为 <code>model</code> (或其他内部标识)。</li>
+<li><strong>Type</strong>: <code>mesh</code>。</li>
+<li><strong>URL</strong>: 指向 <code>work.model.file</code>。</li>
+<li><strong>UpAxis</strong>: 根据文件后缀自动推断 (如 <code>.obj</code> 可能需要特殊处理)。</li>
+</ul>
+</li>
+</ol>
+<blockquote>
+<p><strong>总结</strong>: <code>ViewLayer</code> 是 <code>work.model</code> 数据的运行时表现。<code>layers</code> 字段提供了精细的控制，而 <code>file</code> 字段提供了旧数据的兼容支持。</p>
+</blockquote>
+<h3 id="2-viewlayer-vs-3dtile" class="tsd-anchor-link">2. ViewLayer vs 3DTile<a href="#2-viewlayer-vs-3dtile" 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>ViewLayer</code> 本质上是一个 <strong>3DTile</strong> 加载器实例（继承自 <code>Tile3D</code>）。</p>
+<ul>
+<li><strong>加载机制</strong>: 每个 ViewLayer 独立维护一个 3DTiles 的遍历器 (Traverser) 和调度器 (Scheduler)。这意味着 Mesh 层、PointCloud 层和 GaussianSplatting 层是独立加载、独立计算 LOD (Level of Detail) 的。</li>
+<li><strong>空间变换</strong>: ViewLayer 负责处理数据的坐标系转换 (如 ECEF 转 ENU，Y-Up 转 Z-Up)，确保不同格式的数据在 Five 场景中正确对齐。</li>
+</ul>
+<h3 id="3-viewlayer-model-modelscene-parameter" class="tsd-anchor-link">3. ViewLayer, Model, ModelScene &amp; Parameter<a href="#3-viewlayer-model-modelscene-parameter" 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 渲染架构的核心层级关系，<code>Parameter</code> 在其中起到了“胶水”的作用。</p>
+<h4 id="层级关系-hierarchy" class="tsd-anchor-link">层级关系 (Hierarchy)<a href="#层级关系-hierarchy" 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></h4>
+<pre><code class="mermaid"><span class="hl-1">graph TD</span><br/><span class="hl-1">  Scene[ModelScene] --&gt;|包含| Model[Model]</span><br/><span class="hl-1">  Model --&gt;|包含| LayerA[ViewLayer (Mesh)]</span><br/><span class="hl-1">  Model --&gt;|包含| LayerB[ViewLayer (PointCloud)]</span>
+</code><button type="button">Copy</button></pre>
+
+<h4 id="parameter-的作用-inheritance" class="tsd-anchor-link">Parameter 的作用 (Inheritance)<a href="#parameter-的作用-inheritance" 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></h4>
+<p><code>Parameter</code> 系统贯穿了上述三层，实现了**“配置继承与覆盖”**。</p>
+<ol>
+<li><strong>ModelScene (全局配置)</strong>:
+<ul>
+<li>持有 <code>five.modelScene.parameter</code>。</li>
+<li>定义了场景级的默认值（如：默认显存上限 <code>512MB</code>）。</li>
+</ul>
+</li>
+<li><strong>Model (模型级配置)</strong>:
+<ul>
+<li>持有 <code>model.parameter</code>。</li>
+<li>可以覆盖全局配置（如：特定模型需要 <code>1024MB</code> 显存）。</li>
+</ul>
+</li>
+<li><strong>ViewLayer (图层级配置)</strong>:
+<ul>
+<li>持有 <code>viewLayer.parameter</code>。</li>
+<li><strong>最具体的控制点</strong>。它在计算最终值时，会依次继承 <code>Model</code> 和 <code>ModelScene</code> 的配置。</li>
+</ul>
+</li>
+</ol>
+<p><strong>示例场景</strong>:</p>
+<ul>
+<li>如果你想让<strong>整个场景</strong>变暗，设置 <code>modelScene.parameter.set('opacity', 0.5)</code>。</li>
+<li>如果你只想让<strong>点云层</strong>变暗，保留模型层亮度，设置 <code>pointCloudLayer.parameter.set('opacity', 0.5)</code>。</li>
+</ul>
+<h3 id="4-visibility-control-可见性控制" class="tsd-anchor-link">4. Visibility Control (可见性控制)<a href="#4-visibility-control-可见性控制" 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 <strong>不会</strong>加载所有图层，而是根据优先级<strong>仅加载一个</strong>图层，以节省资源。
+优先级顺序：<code>mesh</code> &gt; <code>point_cloud</code> &gt; 其他类型。</p>
+<p><strong>可见性与内存管理 (Visibility &amp; Memory)</strong>:</p>
+<ul>
+<li><strong>显示 (Show)</strong>: 当图层设置为可见 (<code>visible = true</code>) 时，Five 会开始加载该图层的资源。</li>
+<li><strong>隐藏 (Hide)</strong>: 当图层设置为隐藏 (<code>visible = false</code>) 时，Five 会<strong>释放该图层占用的所有内存资源</strong> (Geometry, Texture 等)。这意味着“隐藏”等同于“卸载”。</li>
+</ul>
+<p>Five 提供了两种层级的可见性控制方式：</p>
+<ol>
+<li>
+<p><strong>初始化配置 (Load Options)</strong>:
+在 <code>five.load</code> 时，通过 <code>model[&quot;3d-tiles&quot;].showLayers</code> 参数指定初始显示的图层。</p>
+<ul>
+<li><code>true</code> (默认): 使用上述的默认优先级策略（仅加载一个最佳图层）。</li>
+<li><code>string[]</code>: 仅显示名称在数组中的图层（例如 <code>['mesh', 'point_cloud']</code> 可以强制同时显示模型和点云）。</li>
+</ul>
+</li>
+<li>
+<p><strong>运行时控制 (Runtime Control)</strong>:
+加载完成后，可以直接修改 <code>viewLayer.visible</code> 属性来切换可见性。</p>
+</li>
+</ol>
+<h2 id="configuration" class="tsd-anchor-link">Configuration<a href="#configuration" 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>
+<p>ViewLayer 的配置主要通过其 <code>parameter</code> 属性进行。</p>
+<h3 id="common-configuration" class="tsd-anchor-link">Common Configuration<a href="#common-configuration" 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>
+<table>
+<thead>
+<tr>
+<th style="text-align:left">Parameter</th>
+<th style="text-align:left">Type</th>
+<th style="text-align:left">Description</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td style="text-align:left"><code>visible</code></td>
+<td style="text-align:left"><code>boolean</code></td>
+<td style="text-align:left">控制图层的可见性 (也可直接修改 <code>viewLayer.visible</code>)。</td>
+</tr>
+<tr>
+<td style="text-align:left"><code>opacity</code></td>
+<td style="text-align:left"><code>number</code></td>
+<td style="text-align:left">图层透明度 (0.0 - 1.0)。</td>
+</tr>
+<tr>
+<td style="text-align:left"><code>pointSize</code></td>
+<td style="text-align:left"><code>number</code></td>
+<td style="text-align:left">(仅点云) 点的大小。</td>
+</tr>
+</tbody>
+</table>
+<blockquote>
+<p>更多配置项请参考 <a href="features_parameter.html">Parameter</a> 和 <a href="features_3dtile.html">3DTile Params</a>。</p>
+</blockquote>
+<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-访问-viewlayer" class="tsd-anchor-link">1. 访问 ViewLayer<a href="#1-访问-viewlayer" 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>
+<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">model</span><span class="hl-1"> = </span><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-6">model</span><span class="hl-1">;</span><br/><br/><span class="hl-8">// 遍历所有图层</span><br/><span class="hl-6">model</span><span class="hl-1">.</span><span class="hl-6">viewLayers</span><span class="hl-1">.</span><span class="hl-5">forEach</span><span class="hl-1">(</span><span class="hl-6">layer</span><span class="hl-1"> </span><span class="hl-3">=&gt;</span><span class="hl-1"> {</span><br/><span class="hl-1">  </span><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">`Layer Name: </span><span class="hl-3">${</span><span class="hl-6">layer</span><span class="hl-12">.</span><span class="hl-6">name</span><span class="hl-3">}</span><span class="hl-9">, Type: </span><span class="hl-3">${</span><span class="hl-6">layer</span><span class="hl-12">.</span><span class="hl-6">type</span><span class="hl-3">}</span><span class="hl-9">`</span><span class="hl-1">);</span><br/><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">pointCloudLayer</span><span class="hl-1"> = </span><span class="hl-6">model</span><span class="hl-1">.</span><span class="hl-6">viewLayers</span><span class="hl-1">.</span><span class="hl-5">find</span><span class="hl-1">(</span><span class="hl-6">layer</span><span class="hl-1"> </span><span class="hl-3">=&gt;</span><span class="hl-1"> </span><span class="hl-6">layer</span><span class="hl-1">.</span><span class="hl-6">type</span><span class="hl-1"> === </span><span class="hl-9">&#39;point_cloud&#39;</span><span class="hl-1">);</span>
+</code><button type="button">Copy</button></pre>
+
+<h3 id="2-独立控制图层可见性" class="tsd-anchor-link">2. 独立控制图层可见性<a href="#2-独立控制图层可见性" 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>
+<pre><code class="typescript"><span class="hl-8">// 方式 A: 运行时控制</span><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">meshLayer</span><span class="hl-1"> = </span><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-6">model</span><span class="hl-1">.</span><span class="hl-6">viewLayers</span><span class="hl-1">.</span><span class="hl-5">find</span><span class="hl-1">(</span><span class="hl-6">layer</span><span class="hl-1"> </span><span class="hl-3">=&gt;</span><span class="hl-1"> </span><span class="hl-6">layer</span><span class="hl-1">.</span><span class="hl-6">type</span><span class="hl-1"> === </span><span class="hl-9">&#39;mesh&#39;</span><span class="hl-1">);</span><br/><br/><span class="hl-10">if</span><span class="hl-1"> (</span><span class="hl-6">meshLayer</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">meshLayer</span><span class="hl-1">.</span><span class="hl-6">visible</span><span class="hl-1"> = </span><span class="hl-3">false</span><span class="hl-1">;</span><br/><span class="hl-1">  </span><span class="hl-8">// 或者通过 parameter 设置</span><br/><span class="hl-1">  </span><span class="hl-8">// meshLayer.parameter.set(&#39;visible&#39;, false);</span><br/><span class="hl-1">}</span><br/><br/><span class="hl-8">// 方式 B: 加载时控制 (初始化时仅显示 mesh)</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">work</span><span class="hl-1">, {</span><br/><span class="hl-1">  </span><span class="hl-6">model:</span><span class="hl-1"> {</span><br/><span class="hl-1">    </span><span class="hl-9">&quot;3d-tiles&quot;</span><span class="hl-6">:</span><span class="hl-1"> {</span><br/><span class="hl-1">      </span><span class="hl-6">showLayers:</span><span class="hl-1"> [</span><span class="hl-9">&#39;mesh&#39;</span><span class="hl-1">] </span><span class="hl-8">// 仅显示 mesh 层，隐藏 point_cloud 等其他层</span><br/><span class="hl-1">    }</span><br/><span class="hl-1">  }</span><br/><span class="hl-1">});</span>
+</code><button type="button">Copy</button></pre>
+
+<h3 id="3-修改特定图层的渲染参数" class="tsd-anchor-link">3. 修改特定图层的渲染参数<a href="#3-修改特定图层的渲染参数" 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>
+<pre><code class="typescript"><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">pointCloudLayer</span><span class="hl-1"> = </span><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-6">model</span><span class="hl-1">.</span><span class="hl-6">viewLayers</span><span class="hl-1">.</span><span class="hl-5">find</span><span class="hl-1">(</span><span class="hl-6">layer</span><span class="hl-1"> </span><span class="hl-3">=&gt;</span><span class="hl-1"> </span><span class="hl-6">layer</span><span class="hl-1">.</span><span class="hl-6">type</span><span class="hl-1"> === </span><span class="hl-9">&#39;point_cloud&#39;</span><span class="hl-1">);</span><br/><br/><span class="hl-10">if</span><span class="hl-1"> (</span><span class="hl-6">pointCloudLayer</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">pointCloudLayer</span><span class="hl-1">.</span><span class="hl-6">parameter</span><span class="hl-1">.</span><span class="hl-5">set</span><span class="hl-1">(</span><span class="hl-9">&#39;pointSize&#39;</span><span class="hl-1">, </span><span class="hl-11">2.0</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">pointCloudLayer</span><span class="hl-1">.</span><span class="hl-6">parameter</span><span class="hl-1">.</span><span class="hl-5">set</span><span class="hl-1">(</span><span class="hl-9">&#39;maxMemoryUsage&#39;</span><span class="hl-1">, </span><span class="hl-11">128</span><span class="hl-1">);</span><br/><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_model.html">Model</a>: ViewLayer 的父级容器。</li>
+<li><a href="features_work.html">Work</a>: 定义 ViewLayer 数据结构的数据源。</li>
+<li><a href="features_parameter.html">Parameter</a>: 控制 ViewLayer 渲染表现的配置系统。</li>
+<li><a href="features_3dtile.html">3DTile</a>: ViewLayer 的底层技术实现。</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">图层切换</span><span class="hl-1">, </span><span class="hl-2">分层渲染</span><span class="hl-1">, </span><span class="hl-2">viewlayer</span><span class="hl-1">, </span><span class="hl-2">model</span><span class="hl-1">, </span><span class="hl-2">3dtile</span><span class="hl-1">, </span><span class="hl-2">parameter</span><span class="hl-1">, </span><span class="hl-2">layer</span><span class="hl-1">, </span><span class="hl-2">mesh</span><span class="hl-1">, </span><span class="hl-2">point-cloud</span><span class="hl-1">, </span><span class="hl-2">gaussian-splatting</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="#viewlayer-视图层"><span>View<wbr/>Layer (视图层)</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="#1-viewlayer-vs-workmodel"><span>1. <wbr/>View<wbr/>Layer vs <wbr/>Work.<wbr/>Model</span></a></li><li><ul><li><a href="#数据来源-data-source"><span>数据来源 (<wbr/>Data <wbr/>Source)</span></a></li></ul></li><li><a href="#2-viewlayer-vs-3dtile"><span>2. <wbr/>View<wbr/>Layer vs 3<wbr/>D<wbr/>Tile</span></a></li><li><a href="#3-viewlayer-model-modelscene-parameter"><span>3. <wbr/>View<wbr/>Layer, <wbr/>Model, <wbr/>Model<wbr/>Scene &amp; <wbr/>Parameter</span></a></li><li><ul><li><a href="#层级关系-hierarchy"><span>层级关系 (<wbr/>Hierarchy)</span></a></li><li><a href="#parameter-的作用-inheritance"><span>Parameter 的作用 (<wbr/>Inheritance)</span></a></li></ul></li><li><a href="#4-visibility-control-可见性控制"><span>4. <wbr/>Visibility <wbr/>Control (可见性控制)</span></a></li></ul></li><li><a href="#configuration"><span>Configuration</span></a></li><li><ul><li><a href="#common-configuration"><span>Common <wbr/>Configuration</span></a></li></ul></li><li><a href="#examples"><span>Examples</span></a></li><li><ul><li><a href="#1-访问-viewlayer"><span>1. 访问 <wbr/>View<wbr/>Layer</span></a></li><li><a href="#2-独立控制图层可见性"><span>2. 独立控制图层可见性</span></a></li><li><a href="#3-修改特定图层的渲染参数"><span>3. 修改特定图层的渲染参数</span></a></li></ul></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>

package/docs/documents/features_work.html

@@ -6,13 +6,74 @@
 <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">&quot;three&quot;</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">&quot;@realsee/five&quot;</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/><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 */</span><br/><span class="hl-1">  </span><span class="hl-6">type</span><span class="hl-1">: </span><span class="hl-9">&#39;point_cloud&#39;</span><span class="hl-1"> | </span><span class="hl-9">&#39;mesh&#39;</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>
+<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-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">&quot;@realsee/five&quot;</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">&#39;up&#39;</span><span class="hl-1"> | </span><span class="hl-9">&#39;down&#39;</span><span class="hl-1"> | </span><span class="hl-9">&#39;left&#39;</span><span class="hl-1"> | </span><span class="hl-9">&#39;right&#39;</span><span class="hl-1"> | </span><span class="hl-9">&#39;front&#39;</span><span class="hl-1"> | </span><span class="hl-9">&#39;back&#39;</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">&#39;top-left&#39;</span><span class="hl-1"> | </span><span class="hl-9">&#39;bottom-left&#39;</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">&#39;top-left&#39;</span><span class="hl-1"> | </span><span class="hl-9">&#39;bottom-left&#39;</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">&#39;top-left&#39;</span><span class="hl-1"> | </span><span class="hl-9">&#39;bottom-left&#39;</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">&#39;top-left&#39;</span><span class="hl-1"> | </span><span class="hl-9">&#39;bottom-left&#39;</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">&#39;point_cloud&#39;</span><span class="hl-1"> | </span><span class="hl-9">&#39;mesh&#39;</span><span class="hl-1"> | </span><span class="hl-9">&#39;gaussian_splatting&#39;</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>
@@ -62,7 +123,7 @@
 <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">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>
+<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="#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>
+</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>