npm - @realsee/five - Versions diffs - 6.9.0-alpha.0 → 6.9.0-alpha.1 - Mend

@realsee/five 6.9.0-alpha.0 → 6.9.0-alpha.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (266) hide show

package/docs/documents/features_request-proxy.html CHANGED Viewed

@@ -10,7 +10,7 @@
 <blockquote>
 <p><strong>Definition</strong>: <a href="../../five/application/fiveInitArgs.d.ts">FiveInitArgs</a></p>
 </blockquote>
-<pre><code class="typescript"><span class="hl-3">interface</span><span class="hl-1"> </span><span class="hl-7">FiveInitArgs</span><span class="hl-1"> {</span><br/><span class="hl-1">  </span><span class="hl-8">/**</span><br/><span class="hl-8">   * 请求代理函数</span><br/><span class="hl-8">   * </span><span class="hl-3">@description</span><span class="hl-8"> 在 Five 内部发起任何网络请求（如加载图片、模型、配置）之前调用。</span><br/><span class="hl-8">   * </span><span class="hl-3">@param</span><span class="hl-8"> </span><span class="hl-6">url</span><span class="hl-8"> - 原始请求 URL</span><br/><span class="hl-8">   * </span><span class="hl-3">@returns</span><span class="hl-8"> 修改后的 URL (string) 或异步返回修改后的 URL (Promise&lt;string&gt;)</span><br/><span class="hl-8">   */</span><br/><span class="hl-1">  </span><span class="hl-5">requestProxy</span><span class="hl-1">?: (</span><span class="hl-6">url</span><span class="hl-1">: </span><span class="hl-7">string</span><span class="hl-1">) </span><span class="hl-3">=&gt;</span><span class="hl-1"> </span><span class="hl-7">string</span><span class="hl-1"> | </span><span class="hl-7">Promise</span><span class="hl-1">&lt;</span><span class="hl-7">string</span><span class="hl-1">&gt;;</span><br/><span class="hl-1">}</span>
+<pre><code class="typescript"><span class="hl-8">interface</span><span class="hl-1"> </span><span class="hl-9">FiveInitArgs</span><span class="hl-1"> {</span><br/><span class="hl-1">  </span><span class="hl-7">/**</span><br/><span class="hl-7">   * 请求代理函数</span><br/><span class="hl-7">   * </span><span class="hl-8">@description</span><span class="hl-7"> 在 Five 内部发起任何网络请求（如加载图片、模型、配置）之前调用。</span><br/><span class="hl-7">   * </span><span class="hl-8">@param</span><span class="hl-7"> </span><span class="hl-5">url</span><span class="hl-7"> - 原始请求 URL</span><br/><span class="hl-7">   * </span><span class="hl-8">@returns</span><span class="hl-7"> 修改后的 URL (string) 或异步返回修改后的 URL (Promise&lt;string&gt;)</span><br/><span class="hl-7">   */</span><br/><span class="hl-1">  </span><span class="hl-4">requestProxy</span><span class="hl-1">?: (</span><span class="hl-5">url</span><span class="hl-1">: </span><span class="hl-9">string</span><span class="hl-1">) </span><span class="hl-8">=&gt;</span><span class="hl-1"> </span><span class="hl-9">string</span><span class="hl-1"> | </span><span class="hl-9">Promise</span><span class="hl-1">&lt;</span><span class="hl-9">string</span><span class="hl-1">&gt;;</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>
@@ -46,17 +46,17 @@
 <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-基础用法：cdn-域名替换" class="tsd-anchor-link">1. 基础用法：CDN 域名替换<a href="#1-基础用法：cdn-域名替换" 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>将图片资源请求分散到不同的 CDN 节点，加速加载。</p>
-<pre><code class="typescript"><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">five</span><span class="hl-1"> = </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-5">Five</span><span class="hl-1">({</span><br/><span class="hl-1">  </span><span class="hl-5">requestProxy</span><span class="hl-6">:</span><span class="hl-1"> (</span><span class="hl-6">url</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-8">// 简单的字符串替换示例</span><br/><span class="hl-1">    </span><span class="hl-10">return</span><span class="hl-1"> </span><span class="hl-6">url</span><span class="hl-1">.</span><span class="hl-5">replace</span><span class="hl-1">(</span><span class="hl-9">&#39;//vrlab-public.ljcdn.com/&#39;</span><span class="hl-1">, </span><span class="hl-9">&#39;//vr-public.realsee-cdn.cn/&#39;</span><span class="hl-1">);</span><br/><span class="hl-1">  }</span><br/><span class="hl-1">});</span>
+<pre><code class="typescript"><span class="hl-8">const</span><span class="hl-1"> </span><span class="hl-6">five</span><span class="hl-1"> = </span><span class="hl-8">new</span><span class="hl-1"> </span><span class="hl-4">Five</span><span class="hl-1">({</span><br/><span class="hl-1">  </span><span class="hl-4">requestProxy</span><span class="hl-5">:</span><span class="hl-1"> (</span><span class="hl-5">url</span><span class="hl-1">) </span><span class="hl-8">=&gt;</span><span class="hl-1"> {</span><br/><span class="hl-1">    </span><span class="hl-7">// 简单的字符串替换示例</span><br/><span class="hl-1">    </span><span class="hl-11">return</span><span class="hl-1"> </span><span class="hl-5">url</span><span class="hl-1">.</span><span class="hl-4">replace</span><span class="hl-1">(</span><span class="hl-10">&#39;//vrlab-public.ljcdn.com/&#39;</span><span class="hl-1">, </span><span class="hl-10">&#39;//vr-public.realsee-cdn.cn/&#39;</span><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="2-进阶用法：异步鉴权-async-auth" class="tsd-anchor-link">2. 进阶用法：异步鉴权 (Async Auth)<a href="#2-进阶用法：异步鉴权-async-auth" 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>对于需要动态获取 Token 的场景，可以使用 <code>Promise</code> 异步返回 URL。</p>
-<pre><code class="typescript"><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">five</span><span class="hl-1"> = </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-5">Five</span><span class="hl-1">({</span><br/><span class="hl-1">  </span><span class="hl-5">requestProxy</span><span class="hl-6">:</span><span class="hl-1"> </span><span class="hl-3">async</span><span class="hl-1"> (</span><span class="hl-6">url</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-8">// 仅对私有桶资源进行签名</span><br/><span class="hl-1">    </span><span class="hl-10">if</span><span class="hl-1"> (</span><span class="hl-6">url</span><span class="hl-1">.</span><span class="hl-5">includes</span><span class="hl-1">(</span><span class="hl-9">&#39;private-bucket&#39;</span><span class="hl-1">)) {</span><br/><span class="hl-1">      </span><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">token</span><span class="hl-1"> = </span><span class="hl-10">await</span><span class="hl-1"> </span><span class="hl-5">fetchToken</span><span class="hl-1">(); </span><span class="hl-8">// 假设 fetchToken 是一个获取鉴权的异步函数</span><br/><span class="hl-1">      </span><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">separator</span><span class="hl-1"> = </span><span class="hl-6">url</span><span class="hl-1">.</span><span class="hl-5">includes</span><span class="hl-1">(</span><span class="hl-9">&#39;?&#39;</span><span class="hl-1">) ? </span><span class="hl-9">&#39;&amp;&#39;</span><span class="hl-1"> : </span><span class="hl-9">&#39;?&#39;</span><span class="hl-1">;</span><br/><span class="hl-1">      </span><span class="hl-10">return</span><span class="hl-1"> </span><span class="hl-9">`</span><span class="hl-3">${</span><span class="hl-6">url</span><span class="hl-3">}${</span><span class="hl-6">separator</span><span class="hl-3">}</span><span class="hl-9">token=</span><span class="hl-3">${</span><span class="hl-6">token</span><span class="hl-3">}</span><span class="hl-9">`</span><span class="hl-1">;</span><br/><span class="hl-1">    }</span><br/><span class="hl-1">    </span><span class="hl-10">return</span><span class="hl-1"> </span><span class="hl-6">url</span><span class="hl-1">;</span><br/><span class="hl-1">  }</span><br/><span class="hl-1">});</span>
+<pre><code class="typescript"><span class="hl-8">const</span><span class="hl-1"> </span><span class="hl-6">five</span><span class="hl-1"> = </span><span class="hl-8">new</span><span class="hl-1"> </span><span class="hl-4">Five</span><span class="hl-1">({</span><br/><span class="hl-1">  </span><span class="hl-4">requestProxy</span><span class="hl-5">:</span><span class="hl-1"> </span><span class="hl-8">async</span><span class="hl-1"> (</span><span class="hl-5">url</span><span class="hl-1">) </span><span class="hl-8">=&gt;</span><span class="hl-1"> {</span><br/><span class="hl-1">    </span><span class="hl-7">// 仅对私有桶资源进行签名</span><br/><span class="hl-1">    </span><span class="hl-11">if</span><span class="hl-1"> (</span><span class="hl-5">url</span><span class="hl-1">.</span><span class="hl-4">includes</span><span class="hl-1">(</span><span class="hl-10">&#39;private-bucket&#39;</span><span class="hl-1">)) {</span><br/><span class="hl-1">      </span><span class="hl-8">const</span><span class="hl-1"> </span><span class="hl-6">token</span><span class="hl-1"> = </span><span class="hl-11">await</span><span class="hl-1"> </span><span class="hl-4">fetchToken</span><span class="hl-1">(); </span><span class="hl-7">// 假设 fetchToken 是一个获取鉴权的异步函数</span><br/><span class="hl-1">      </span><span class="hl-8">const</span><span class="hl-1"> </span><span class="hl-6">separator</span><span class="hl-1"> = </span><span class="hl-5">url</span><span class="hl-1">.</span><span class="hl-4">includes</span><span class="hl-1">(</span><span class="hl-10">&#39;?&#39;</span><span class="hl-1">) ? </span><span class="hl-10">&#39;&amp;&#39;</span><span class="hl-1"> : </span><span class="hl-10">&#39;?&#39;</span><span class="hl-1">;</span><br/><span class="hl-1">      </span><span class="hl-11">return</span><span class="hl-1"> </span><span class="hl-10">`</span><span class="hl-8">${</span><span class="hl-5">url</span><span class="hl-8">}${</span><span class="hl-5">separator</span><span class="hl-8">}</span><span class="hl-10">token=</span><span class="hl-8">${</span><span class="hl-5">token</span><span class="hl-8">}</span><span class="hl-10">`</span><span class="hl-1">;</span><br/><span class="hl-1">    }</span><br/><span class="hl-1">    </span><span class="hl-11">return</span><span class="hl-1"> </span><span class="hl-5">url</span><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>
 <p>在开发阶段，将特定资源重定向到本地文件。</p>
-<pre><code class="typescript"><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">proxyMap</span><span class="hl-1">: </span><span class="hl-7">Record</span><span class="hl-1">&lt;</span><span class="hl-7">string</span><span class="hl-1">, </span><span class="hl-7">string</span><span class="hl-1">&gt; = {};</span><br/><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">five</span><span class="hl-1"> = </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-5">Five</span><span class="hl-1">({</span><br/><span class="hl-1">  </span><span class="hl-5">requestProxy</span><span class="hl-6">:</span><span class="hl-1"> (</span><span class="hl-6">url</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-8">// 如果该 URL 在映射表中存在（例如通过 &lt;input type=&quot;file&quot;&gt; 加载的本地 Blob URL），则使用映射值</span><br/><span class="hl-1">    </span><span class="hl-10">if</span><span class="hl-1"> (</span><span class="hl-6">proxyMap</span><span class="hl-1">[</span><span class="hl-6">url</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">`[Proxy] Redirecting </span><span class="hl-3">${</span><span class="hl-6">url</span><span class="hl-3">}</span><span class="hl-9"> -&gt; </span><span class="hl-3">${</span><span class="hl-6">proxyMap</span><span class="hl-12">[</span><span class="hl-6">url</span><span class="hl-12">]</span><span class="hl-3">}</span><span class="hl-9">`</span><span class="hl-1">);</span><br/><span class="hl-1">      </span><span class="hl-10">return</span><span class="hl-1"> </span><span class="hl-6">proxyMap</span><span class="hl-1">[</span><span class="hl-6">url</span><span class="hl-1">];</span><br/><span class="hl-1">    }</span><br/><span class="hl-1">    </span><span class="hl-10">return</span><span class="hl-1"> </span><span class="hl-6">url</span><span class="hl-1">;</span><br/><span class="hl-1">  }</span><br/><span class="hl-1">});</span>
+<pre><code class="typescript"><span class="hl-8">const</span><span class="hl-1"> </span><span class="hl-6">proxyMap</span><span class="hl-1">: </span><span class="hl-9">Record</span><span class="hl-1">&lt;</span><span class="hl-9">string</span><span class="hl-1">, </span><span class="hl-9">string</span><span class="hl-1">&gt; = {};</span><br/><br/><span class="hl-8">const</span><span class="hl-1"> </span><span class="hl-6">five</span><span class="hl-1"> = </span><span class="hl-8">new</span><span class="hl-1"> </span><span class="hl-4">Five</span><span class="hl-1">({</span><br/><span class="hl-1">  </span><span class="hl-4">requestProxy</span><span class="hl-5">:</span><span class="hl-1"> (</span><span class="hl-5">url</span><span class="hl-1">) </span><span class="hl-8">=&gt;</span><span class="hl-1"> {</span><br/><span class="hl-1">    </span><span class="hl-7">// 如果该 URL 在映射表中存在（例如通过 &lt;input type=&quot;file&quot;&gt; 加载的本地 Blob URL），则使用映射值</span><br/><span class="hl-1">    </span><span class="hl-11">if</span><span class="hl-1"> (</span><span class="hl-5">proxyMap</span><span class="hl-1">[</span><span class="hl-5">url</span><span class="hl-1">]) {</span><br/><span class="hl-1">      </span><span class="hl-5">console</span><span class="hl-1">.</span><span class="hl-4">log</span><span class="hl-1">(</span><span class="hl-10">`[Proxy] Redirecting </span><span class="hl-8">${</span><span class="hl-5">url</span><span class="hl-8">}</span><span class="hl-10"> -&gt; </span><span class="hl-8">${</span><span class="hl-5">proxyMap</span><span class="hl-12">[</span><span class="hl-5">url</span><span class="hl-12">]</span><span class="hl-8">}</span><span class="hl-10">`</span><span class="hl-1">);</span><br/><span class="hl-1">      </span><span class="hl-11">return</span><span class="hl-1"> </span><span class="hl-5">proxyMap</span><span class="hl-1">[</span><span class="hl-5">url</span><span class="hl-1">];</span><br/><span class="hl-1">    }</span><br/><span class="hl-1">    </span><span class="hl-11">return</span><span class="hl-1"> </span><span class="hl-5">url</span><span class="hl-1">;</span><br/><span class="hl-1">  }</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>

package/docs/documents/features_screen-project.html CHANGED Viewed

@@ -9,7 +9,7 @@
 <blockquote>
 <p><strong>Definition</strong>: <a href="../../five/application/five.d.ts">Five</a></p>
 </blockquote>
-<pre><code class="typescript"><span class="hl-8">// defined in Five class</span><br/><span class="hl-3">interface</span><span class="hl-1"> </span><span class="hl-7">Five</span><span class="hl-1"> {</span><br/><span class="hl-1">  </span><span class="hl-8">/**</span><br/><span class="hl-8">   * 计算三维坐标对应到屏幕的二维坐标</span><br/><span class="hl-8">   * </span><span class="hl-3">@param</span><span class="hl-8"> </span><span class="hl-6">vector</span><span class="hl-8"> - 三维空间坐标 (World Space)</span><br/><span class="hl-8">   * </span><span class="hl-3">@param</span><span class="hl-8"> </span><span class="hl-6">testModel</span><span class="hl-8"> - 是否进行模型遮挡检测 (默认 false)。如果为 true，且该点被模型遮挡，则返回 null。</span><br/><span class="hl-8">   * </span><span class="hl-3">@returns</span><span class="hl-8"> 二维屏幕坐标 (相对于 Canvas 左上角) 或 null (如果点在视野外或被遮挡)</span><br/><span class="hl-8">   */</span><br/><span class="hl-1">  </span><span class="hl-5">project2d</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">testModel</span><span class="hl-1">?: </span><span class="hl-7">boolean</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-7">null</span><span class="hl-1">;</span><br/><span class="hl-1">}</span>
+<pre><code class="typescript"><span class="hl-7">// defined in Five class</span><br/><span class="hl-8">interface</span><span class="hl-1"> </span><span class="hl-9">Five</span><span class="hl-1"> {</span><br/><span class="hl-1">  </span><span class="hl-7">/**</span><br/><span class="hl-7">   * 计算三维坐标对应到屏幕的二维坐标</span><br/><span class="hl-7">   * </span><span class="hl-8">@param</span><span class="hl-7"> </span><span class="hl-5">vector</span><span class="hl-7"> - 三维空间坐标 (World Space)</span><br/><span class="hl-7">   * </span><span class="hl-8">@param</span><span class="hl-7"> </span><span class="hl-5">testModel</span><span class="hl-7"> - 是否进行模型遮挡检测 (默认 false)。如果为 true，且该点被模型遮挡，则返回 null。</span><br/><span class="hl-7">   * </span><span class="hl-8">@returns</span><span class="hl-7"> 二维屏幕坐标 (相对于 Canvas 左上角) 或 null (如果点在视野外或被遮挡)</span><br/><span class="hl-7">   */</span><br/><span class="hl-1">  </span><span class="hl-4">project2d</span><span class="hl-1">(</span><span class="hl-5">vector</span><span class="hl-1">: </span><span class="hl-9">THREE</span><span class="hl-1">.</span><span class="hl-9">Vector3</span><span class="hl-1">, </span><span class="hl-5">testModel</span><span class="hl-1">?: </span><span class="hl-9">boolean</span><span class="hl-1">): </span><span class="hl-9">THREE</span><span class="hl-1">.</span><span class="hl-9">Vector2</span><span class="hl-1"> | </span><span class="hl-9">null</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>
@@ -57,7 +57,7 @@
 <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-空间标签-3d-point-to-dom-label" class="tsd-anchor-link">1. 空间标签 (3D Point to DOM Label)<a href="#1-空间标签-3d-point-to-dom-label" 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>最典型的应用场景是在 3D 场景中的某个物体上方显示一个 HTML 标签。</p>
-<pre><code class="typescript"><span class="hl-10">import</span><span class="hl-1"> { </span><span class="hl-6">Five</span><span class="hl-1">, </span><span class="hl-6">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/><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/><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">five</span><span class="hl-1"> = </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-5">Five</span><span class="hl-1">();</span><br/><span class="hl-8">// ... 初始化 five ...</span><br/><br/><span class="hl-8">// 1. 创建标签 DOM 元素</span><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">label</span><span class="hl-1"> = </span><span class="hl-6">document</span><span class="hl-1">.</span><span class="hl-5">createElement</span><span class="hl-1">(</span><span class="hl-9">&quot;div&quot;</span><span class="hl-1">);</span><br/><span class="hl-6">label</span><span class="hl-1">.</span><span class="hl-6">textContent</span><span class="hl-1"> = </span><span class="hl-9">&quot;Living Room&quot;</span><span class="hl-1">;</span><br/><span class="hl-6">label</span><span class="hl-1">.</span><span class="hl-6">style</span><span class="hl-1">.</span><span class="hl-6">position</span><span class="hl-1"> = </span><span class="hl-9">&quot;absolute&quot;</span><span class="hl-1">;</span><br/><span class="hl-6">label</span><span class="hl-1">.</span><span class="hl-6">style</span><span class="hl-1">.</span><span class="hl-6">padding</span><span class="hl-1"> = </span><span class="hl-9">&quot;4px 8px&quot;</span><span class="hl-1">;</span><br/><span class="hl-6">label</span><span class="hl-1">.</span><span class="hl-6">style</span><span class="hl-1">.</span><span class="hl-6">background</span><span class="hl-1"> = </span><span class="hl-9">&quot;rgba(0, 0, 0, 0.6)&quot;</span><span class="hl-1">;</span><br/><span class="hl-6">label</span><span class="hl-1">.</span><span class="hl-6">style</span><span class="hl-1">.</span><span class="hl-6">color</span><span class="hl-1"> = </span><span class="hl-9">&quot;white&quot;</span><span class="hl-1">;</span><br/><span class="hl-6">label</span><span class="hl-1">.</span><span class="hl-6">style</span><span class="hl-1">.</span><span class="hl-6">borderRadius</span><span class="hl-1"> = </span><span class="hl-9">&quot;4px&quot;</span><span class="hl-1">;</span><br/><span class="hl-6">label</span><span class="hl-1">.</span><span class="hl-6">style</span><span class="hl-1">.</span><span class="hl-6">pointerEvents</span><span class="hl-1"> = </span><span class="hl-9">&quot;none&quot;</span><span class="hl-1">; </span><span class="hl-8">// 避免阻挡鼠标事件</span><br/><span class="hl-6">label</span><span class="hl-1">.</span><span class="hl-6">style</span><span class="hl-1">.</span><span class="hl-6">transform</span><span class="hl-1"> = </span><span class="hl-9">&quot;translate(-50%, -100%)&quot;</span><span class="hl-1">; </span><span class="hl-8">// 居中并显示在点上方</span><br/><span class="hl-6">label</span><span class="hl-1">.</span><span class="hl-6">style</span><span class="hl-1">.</span><span class="hl-6">display</span><span class="hl-1"> = </span><span class="hl-9">&quot;none&quot;</span><span class="hl-1">; </span><span class="hl-8">// 默认隐藏</span><br/><span class="hl-6">document</span><span class="hl-1">.</span><span class="hl-6">body</span><span class="hl-1">.</span><span class="hl-5">appendChild</span><span class="hl-1">(</span><span class="hl-6">label</span><span class="hl-1">); </span><span class="hl-8">// 添加到 container (注意 container 的定位 context)</span><br/><br/><span class="hl-8">// 2. 定义目标空间坐标 (例如客厅中心)</span><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">targetPosition</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-11">1.5</span><span class="hl-1">, </span><span class="hl-11">2.0</span><span class="hl-1">, -</span><span class="hl-11">3.0</span><span class="hl-1">);</span><br/><br/><span class="hl-8">// 3. 在每一帧渲染时更新标签位置</span><br/><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-5">on</span><span class="hl-1">(</span><span class="hl-9">&quot;render.prepare&quot;</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-8">// 计算屏幕坐标</span><br/><span class="hl-1">  </span><span class="hl-8">// 参数2: false 表示不检测遮挡 (性能更好)；true 表示如果被墙挡住则隐藏</span><br/><span class="hl-1">  </span><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">screenPos</span><span class="hl-1"> = </span><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-5">project2d</span><span class="hl-1">(</span><span class="hl-6">targetPosition</span><span class="hl-1">, </span><span class="hl-3">true</span><span class="hl-1">);</span><br/><br/><span class="hl-1">  </span><span class="hl-10">if</span><span class="hl-1"> (</span><span class="hl-6">screenPos</span><span class="hl-1"> === </span><span class="hl-3">null</span><span class="hl-1">) {</span><br/><span class="hl-1">    </span><span class="hl-8">// 如果返回 null，说明点在相机背面，或者被遮挡（如果开启了 testModel）</span><br/><span class="hl-1">    </span><span class="hl-6">label</span><span class="hl-1">.</span><span class="hl-6">style</span><span class="hl-1">.</span><span class="hl-6">display</span><span class="hl-1"> = </span><span class="hl-9">&quot;none&quot;</span><span class="hl-1">;</span><br/><span class="hl-1">  } </span><span class="hl-10">else</span><span class="hl-1"> {</span><br/><span class="hl-1">    </span><span class="hl-6">label</span><span class="hl-1">.</span><span class="hl-6">style</span><span class="hl-1">.</span><span class="hl-6">display</span><span class="hl-1"> = </span><span class="hl-9">&quot;block&quot;</span><span class="hl-1">;</span><br/><span class="hl-1">    </span><span class="hl-8">// 更新 DOM 位置</span><br/><span class="hl-1">    </span><span class="hl-8">// 注意：screenPos 是相对于 Canvas 的坐标。</span><br/><span class="hl-1">    </span><span class="hl-8">// 如果 Canvas 占满全屏，直接使用即可。</span><br/><span class="hl-1">    </span><span class="hl-8">// 如果 Canvas 有偏移，需加上 Canvas 的 offset。</span><br/><span class="hl-1">    </span><span class="hl-6">label</span><span class="hl-1">.</span><span class="hl-6">style</span><span class="hl-1">.</span><span class="hl-6">left</span><span class="hl-1"> = </span><span class="hl-9">`</span><span class="hl-3">${</span><span class="hl-6">screenPos</span><span class="hl-12">.</span><span class="hl-6">x</span><span class="hl-3">}</span><span class="hl-9">px`</span><span class="hl-1">;</span><br/><span class="hl-1">    </span><span class="hl-6">label</span><span class="hl-1">.</span><span class="hl-6">style</span><span class="hl-1">.</span><span class="hl-6">top</span><span class="hl-1"> = </span><span class="hl-9">`</span><span class="hl-3">${</span><span class="hl-6">screenPos</span><span class="hl-12">.</span><span class="hl-6">y</span><span class="hl-3">}</span><span class="hl-9">px`</span><span class="hl-1">;</span><br/><span class="hl-1">  }</span><br/><span class="hl-1">});</span>
+<pre><code class="typescript"><span class="hl-11">import</span><span class="hl-1"> { </span><span class="hl-5">Five</span><span class="hl-1">, </span><span class="hl-5">Mode</span><span class="hl-1"> } </span><span class="hl-11">from</span><span class="hl-1"> </span><span class="hl-10">&quot;@realsee/five&quot;</span><span class="hl-1">;</span><br/><span class="hl-11">import</span><span class="hl-1"> </span><span class="hl-8">*</span><span class="hl-1"> </span><span class="hl-11">as</span><span class="hl-1"> </span><span class="hl-5">THREE</span><span class="hl-1"> </span><span class="hl-11">from</span><span class="hl-1"> </span><span class="hl-10">&quot;three&quot;</span><span class="hl-1">;</span><br/><br/><span class="hl-8">const</span><span class="hl-1"> </span><span class="hl-6">five</span><span class="hl-1"> = </span><span class="hl-8">new</span><span class="hl-1"> </span><span class="hl-4">Five</span><span class="hl-1">();</span><br/><span class="hl-7">// ... 初始化 five ...</span><br/><br/><span class="hl-7">// 1. 创建标签 DOM 元素</span><br/><span class="hl-8">const</span><span class="hl-1"> </span><span class="hl-6">label</span><span class="hl-1"> = </span><span class="hl-5">document</span><span class="hl-1">.</span><span class="hl-4">createElement</span><span class="hl-1">(</span><span class="hl-10">&quot;div&quot;</span><span class="hl-1">);</span><br/><span class="hl-5">label</span><span class="hl-1">.</span><span class="hl-5">textContent</span><span class="hl-1"> = </span><span class="hl-10">&quot;Living Room&quot;</span><span class="hl-1">;</span><br/><span class="hl-5">label</span><span class="hl-1">.</span><span class="hl-5">style</span><span class="hl-1">.</span><span class="hl-5">position</span><span class="hl-1"> = </span><span class="hl-10">&quot;absolute&quot;</span><span class="hl-1">;</span><br/><span class="hl-5">label</span><span class="hl-1">.</span><span class="hl-5">style</span><span class="hl-1">.</span><span class="hl-5">padding</span><span class="hl-1"> = </span><span class="hl-10">&quot;4px 8px&quot;</span><span class="hl-1">;</span><br/><span class="hl-5">label</span><span class="hl-1">.</span><span class="hl-5">style</span><span class="hl-1">.</span><span class="hl-5">background</span><span class="hl-1"> = </span><span class="hl-10">&quot;rgba(0, 0, 0, 0.6)&quot;</span><span class="hl-1">;</span><br/><span class="hl-5">label</span><span class="hl-1">.</span><span class="hl-5">style</span><span class="hl-1">.</span><span class="hl-5">color</span><span class="hl-1"> = </span><span class="hl-10">&quot;white&quot;</span><span class="hl-1">;</span><br/><span class="hl-5">label</span><span class="hl-1">.</span><span class="hl-5">style</span><span class="hl-1">.</span><span class="hl-5">borderRadius</span><span class="hl-1"> = </span><span class="hl-10">&quot;4px&quot;</span><span class="hl-1">;</span><br/><span class="hl-5">label</span><span class="hl-1">.</span><span class="hl-5">style</span><span class="hl-1">.</span><span class="hl-5">pointerEvents</span><span class="hl-1"> = </span><span class="hl-10">&quot;none&quot;</span><span class="hl-1">; </span><span class="hl-7">// 避免阻挡鼠标事件</span><br/><span class="hl-5">label</span><span class="hl-1">.</span><span class="hl-5">style</span><span class="hl-1">.</span><span class="hl-5">transform</span><span class="hl-1"> = </span><span class="hl-10">&quot;translate(-50%, -100%)&quot;</span><span class="hl-1">; </span><span class="hl-7">// 居中并显示在点上方</span><br/><span class="hl-5">label</span><span class="hl-1">.</span><span class="hl-5">style</span><span class="hl-1">.</span><span class="hl-5">display</span><span class="hl-1"> = </span><span class="hl-10">&quot;none&quot;</span><span class="hl-1">; </span><span class="hl-7">// 默认隐藏</span><br/><span class="hl-5">document</span><span class="hl-1">.</span><span class="hl-5">body</span><span class="hl-1">.</span><span class="hl-4">appendChild</span><span class="hl-1">(</span><span class="hl-5">label</span><span class="hl-1">); </span><span class="hl-7">// 添加到 container (注意 container 的定位 context)</span><br/><br/><span class="hl-7">// 2. 定义目标空间坐标 (例如客厅中心)</span><br/><span class="hl-8">const</span><span class="hl-1"> </span><span class="hl-6">targetPosition</span><span class="hl-1"> = </span><span class="hl-8">new</span><span class="hl-1"> </span><span class="hl-6">THREE</span><span class="hl-1">.</span><span class="hl-4">Vector3</span><span class="hl-1">(</span><span class="hl-3">1.5</span><span class="hl-1">, </span><span class="hl-3">2.0</span><span class="hl-1">, -</span><span class="hl-3">3.0</span><span class="hl-1">);</span><br/><br/><span class="hl-7">// 3. 在每一帧渲染时更新标签位置</span><br/><span class="hl-5">five</span><span class="hl-1">.</span><span class="hl-4">on</span><span class="hl-1">(</span><span class="hl-10">&quot;render.prepare&quot;</span><span class="hl-1">, () </span><span class="hl-8">=&gt;</span><span class="hl-1"> {</span><br/><span class="hl-1">  </span><span class="hl-7">// 计算屏幕坐标</span><br/><span class="hl-1">  </span><span class="hl-7">// 参数2: false 表示不检测遮挡 (性能更好)；true 表示如果被墙挡住则隐藏</span><br/><span class="hl-1">  </span><span class="hl-8">const</span><span class="hl-1"> </span><span class="hl-6">screenPos</span><span class="hl-1"> = </span><span class="hl-5">five</span><span class="hl-1">.</span><span class="hl-4">project2d</span><span class="hl-1">(</span><span class="hl-5">targetPosition</span><span class="hl-1">, </span><span class="hl-8">true</span><span class="hl-1">);</span><br/><br/><span class="hl-1">  </span><span class="hl-11">if</span><span class="hl-1"> (</span><span class="hl-5">screenPos</span><span class="hl-1"> === </span><span class="hl-8">null</span><span class="hl-1">) {</span><br/><span class="hl-1">    </span><span class="hl-7">// 如果返回 null，说明点在相机背面，或者被遮挡（如果开启了 testModel）</span><br/><span class="hl-1">    </span><span class="hl-5">label</span><span class="hl-1">.</span><span class="hl-5">style</span><span class="hl-1">.</span><span class="hl-5">display</span><span class="hl-1"> = </span><span class="hl-10">&quot;none&quot;</span><span class="hl-1">;</span><br/><span class="hl-1">  } </span><span class="hl-11">else</span><span class="hl-1"> {</span><br/><span class="hl-1">    </span><span class="hl-5">label</span><span class="hl-1">.</span><span class="hl-5">style</span><span class="hl-1">.</span><span class="hl-5">display</span><span class="hl-1"> = </span><span class="hl-10">&quot;block&quot;</span><span class="hl-1">;</span><br/><span class="hl-1">    </span><span class="hl-7">// 更新 DOM 位置</span><br/><span class="hl-1">    </span><span class="hl-7">// 注意：screenPos 是相对于 Canvas 的坐标。</span><br/><span class="hl-1">    </span><span class="hl-7">// 如果 Canvas 占满全屏，直接使用即可。</span><br/><span class="hl-1">    </span><span class="hl-7">// 如果 Canvas 有偏移，需加上 Canvas 的 offset。</span><br/><span class="hl-1">    </span><span class="hl-5">label</span><span class="hl-1">.</span><span class="hl-5">style</span><span class="hl-1">.</span><span class="hl-5">left</span><span class="hl-1"> = </span><span class="hl-10">`</span><span class="hl-8">${</span><span class="hl-5">screenPos</span><span class="hl-12">.</span><span class="hl-5">x</span><span class="hl-8">}</span><span class="hl-10">px`</span><span class="hl-1">;</span><br/><span class="hl-1">    </span><span class="hl-5">label</span><span class="hl-1">.</span><span class="hl-5">style</span><span class="hl-1">.</span><span class="hl-5">top</span><span class="hl-1"> = </span><span class="hl-10">`</span><span class="hl-8">${</span><span class="hl-5">screenPos</span><span class="hl-12">.</span><span class="hl-5">y</span><span class="hl-8">}</span><span class="hl-10">px`</span><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="2-屏幕点击转射线-screen-to-ray" class="tsd-anchor-link">2. 屏幕点击转射线 (Screen to Ray)<a href="#2-屏幕点击转射线-screen-to-ray" 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>
@@ -65,7 +65,7 @@
 <blockquote>
 <p><strong>注意</strong>: 更多射线检测细节请参考 <a href="features_raycast.html">Raycast</a>。</p>
 </blockquote>
-<pre><code class="typescript"><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/><br/><span class="hl-8">// 假设 container 是 five 的容器元素</span><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">container</span><span class="hl-1"> = </span><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-5">getElement</span><span class="hl-1">()!.</span><span class="hl-6">parentElement</span><span class="hl-1">!;</span><br/><br/><span class="hl-6">container</span><span class="hl-1">.</span><span class="hl-5">addEventListener</span><span class="hl-1">(</span><span class="hl-9">&quot;click&quot;</span><span class="hl-1">, (</span><span class="hl-6">event</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-3">const</span><span class="hl-1"> </span><span class="hl-4">raycaster</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">Raycaster</span><span class="hl-1">();</span><br/><span class="hl-1">  </span><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">mouse</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">Vector2</span><span class="hl-1">();</span><br/><br/><span class="hl-1">  </span><span class="hl-8">// 1. 计算 NDC 坐标 (x, y 范围 [-1, 1])</span><br/><span class="hl-1">  </span><span class="hl-8">// event.clientX/Y 是相对于视口的坐标</span><br/><span class="hl-1">  </span><span class="hl-8">// getBoundingClientRect 用于获取容器的位置</span><br/><span class="hl-1">  </span><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">rect</span><span class="hl-1"> = </span><span class="hl-6">container</span><span class="hl-1">.</span><span class="hl-5">getBoundingClientRect</span><span class="hl-1">();</span><br/><br/><span class="hl-1">  </span><span class="hl-6">mouse</span><span class="hl-1">.</span><span class="hl-6">x</span><span class="hl-1"> = ((</span><span class="hl-6">event</span><span class="hl-1">.</span><span class="hl-6">clientX</span><span class="hl-1"> - </span><span class="hl-6">rect</span><span class="hl-1">.</span><span class="hl-6">left</span><span class="hl-1">) / </span><span class="hl-6">rect</span><span class="hl-1">.</span><span class="hl-6">width</span><span class="hl-1">) * </span><span class="hl-11">2</span><span class="hl-1"> - </span><span class="hl-11">1</span><span class="hl-1">;</span><br/><span class="hl-1">  </span><span class="hl-6">mouse</span><span class="hl-1">.</span><span class="hl-6">y</span><span class="hl-1"> = -((</span><span class="hl-6">event</span><span class="hl-1">.</span><span class="hl-6">clientY</span><span class="hl-1"> - </span><span class="hl-6">rect</span><span class="hl-1">.</span><span class="hl-6">top</span><span class="hl-1">) / </span><span class="hl-6">rect</span><span class="hl-1">.</span><span class="hl-6">height</span><span class="hl-1">) * </span><span class="hl-11">2</span><span class="hl-1"> + </span><span class="hl-11">1</span><span class="hl-1">; </span><span class="hl-8">// 注意 Y 轴翻转</span><br/><br/><span class="hl-1">  </span><span class="hl-8">// 2. 从相机发射射线</span><br/><span class="hl-1">  </span><span class="hl-6">raycaster</span><span class="hl-1">.</span><span class="hl-5">setFromCamera</span><span class="hl-1">(</span><span class="hl-6">mouse</span><span class="hl-1">, </span><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-6">camera</span><span class="hl-1">);</span><br/><br/><span class="hl-1">  </span><span class="hl-8">// 3. 进行相交检测</span><br/><span class="hl-1">  </span><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">intersects</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-5">intersectRaycaster</span><span class="hl-1">(</span><span class="hl-6">raycaster</span><span class="hl-1">);</span><br/><br/><span class="hl-1">  </span><span class="hl-10">if</span><span class="hl-1"> (</span><span class="hl-6">intersects</span><span class="hl-1">.</span><span class="hl-6">length</span><span class="hl-1"> &gt; </span><span class="hl-11">0</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">&quot;Hit point:&quot;</span><span class="hl-1">, </span><span class="hl-6">intersects</span><span class="hl-1">[</span><span class="hl-11">0</span><span class="hl-1">].</span><span class="hl-6">point</span><span class="hl-1">);</span><br/><span class="hl-1">  }</span><br/><span class="hl-1">});</span>
+<pre><code class="typescript"><span class="hl-11">import</span><span class="hl-1"> </span><span class="hl-8">*</span><span class="hl-1"> </span><span class="hl-11">as</span><span class="hl-1"> </span><span class="hl-5">THREE</span><span class="hl-1"> </span><span class="hl-11">from</span><span class="hl-1"> </span><span class="hl-10">&quot;three&quot;</span><span class="hl-1">;</span><br/><br/><span class="hl-7">// 假设 container 是 five 的容器元素</span><br/><span class="hl-8">const</span><span class="hl-1"> </span><span class="hl-6">container</span><span class="hl-1"> = </span><span class="hl-5">five</span><span class="hl-1">.</span><span class="hl-4">getElement</span><span class="hl-1">()!.</span><span class="hl-5">parentElement</span><span class="hl-1">!;</span><br/><br/><span class="hl-5">container</span><span class="hl-1">.</span><span class="hl-4">addEventListener</span><span class="hl-1">(</span><span class="hl-10">&quot;click&quot;</span><span class="hl-1">, (</span><span class="hl-5">event</span><span class="hl-1">) </span><span class="hl-8">=&gt;</span><span class="hl-1"> {</span><br/><span class="hl-1">  </span><span class="hl-8">const</span><span class="hl-1"> </span><span class="hl-6">raycaster</span><span class="hl-1"> = </span><span class="hl-8">new</span><span class="hl-1"> </span><span class="hl-6">THREE</span><span class="hl-1">.</span><span class="hl-4">Raycaster</span><span class="hl-1">();</span><br/><span class="hl-1">  </span><span class="hl-8">const</span><span class="hl-1"> </span><span class="hl-6">mouse</span><span class="hl-1"> = </span><span class="hl-8">new</span><span class="hl-1"> </span><span class="hl-6">THREE</span><span class="hl-1">.</span><span class="hl-4">Vector2</span><span class="hl-1">();</span><br/><br/><span class="hl-1">  </span><span class="hl-7">// 1. 计算 NDC 坐标 (x, y 范围 [-1, 1])</span><br/><span class="hl-1">  </span><span class="hl-7">// event.clientX/Y 是相对于视口的坐标</span><br/><span class="hl-1">  </span><span class="hl-7">// getBoundingClientRect 用于获取容器的位置</span><br/><span class="hl-1">  </span><span class="hl-8">const</span><span class="hl-1"> </span><span class="hl-6">rect</span><span class="hl-1"> = </span><span class="hl-5">container</span><span class="hl-1">.</span><span class="hl-4">getBoundingClientRect</span><span class="hl-1">();</span><br/><br/><span class="hl-1">  </span><span class="hl-5">mouse</span><span class="hl-1">.</span><span class="hl-5">x</span><span class="hl-1"> = ((</span><span class="hl-5">event</span><span class="hl-1">.</span><span class="hl-5">clientX</span><span class="hl-1"> - </span><span class="hl-5">rect</span><span class="hl-1">.</span><span class="hl-5">left</span><span class="hl-1">) / </span><span class="hl-5">rect</span><span class="hl-1">.</span><span class="hl-5">width</span><span class="hl-1">) * </span><span class="hl-3">2</span><span class="hl-1"> - </span><span class="hl-3">1</span><span class="hl-1">;</span><br/><span class="hl-1">  </span><span class="hl-5">mouse</span><span class="hl-1">.</span><span class="hl-5">y</span><span class="hl-1"> = -((</span><span class="hl-5">event</span><span class="hl-1">.</span><span class="hl-5">clientY</span><span class="hl-1"> - </span><span class="hl-5">rect</span><span class="hl-1">.</span><span class="hl-5">top</span><span class="hl-1">) / </span><span class="hl-5">rect</span><span class="hl-1">.</span><span class="hl-5">height</span><span class="hl-1">) * </span><span class="hl-3">2</span><span class="hl-1"> + </span><span class="hl-3">1</span><span class="hl-1">; </span><span class="hl-7">// 注意 Y 轴翻转</span><br/><br/><span class="hl-1">  </span><span class="hl-7">// 2. 从相机发射射线</span><br/><span class="hl-1">  </span><span class="hl-5">raycaster</span><span class="hl-1">.</span><span class="hl-4">setFromCamera</span><span class="hl-1">(</span><span class="hl-5">mouse</span><span class="hl-1">, </span><span class="hl-5">five</span><span class="hl-1">.</span><span class="hl-5">camera</span><span class="hl-1">);</span><br/><br/><span class="hl-1">  </span><span class="hl-7">// 3. 进行相交检测</span><br/><span class="hl-1">  </span><span class="hl-8">const</span><span class="hl-1"> </span><span class="hl-6">intersects</span><span class="hl-1"> = </span><span class="hl-5">five</span><span class="hl-1">.</span><span class="hl-5">model</span><span class="hl-1">.</span><span class="hl-4">intersectRaycaster</span><span class="hl-1">(</span><span class="hl-5">raycaster</span><span class="hl-1">);</span><br/><br/><span class="hl-1">  </span><span class="hl-11">if</span><span class="hl-1"> (</span><span class="hl-5">intersects</span><span class="hl-1">.</span><span class="hl-5">length</span><span class="hl-1"> &gt; </span><span class="hl-3">0</span><span class="hl-1">) {</span><br/><span class="hl-1">    </span><span class="hl-5">console</span><span class="hl-1">.</span><span class="hl-4">log</span><span class="hl-1">(</span><span class="hl-10">&quot;Hit point:&quot;</span><span class="hl-1">, </span><span class="hl-5">intersects</span><span class="hl-1">[</span><span class="hl-3">0</span><span class="hl-1">].</span><span class="hl-5">point</span><span class="hl-1">);</span><br/><span class="hl-1">  }</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>

package/docs/documents/features_state.html CHANGED Viewed

@@ -10,7 +10,7 @@
 <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>
+<pre><code class="ts"><span class="hl-11">import</span><span class="hl-1"> </span><span class="hl-8">*</span><span class="hl-1"> </span><span class="hl-11">as</span><span class="hl-1"> </span><span class="hl-5">THREE</span><span class="hl-1"> </span><span class="hl-11">from</span><span class="hl-1"> </span><span class="hl-10">&quot;three&quot;</span><span class="hl-1">;</span><br/><span class="hl-11">import</span><span class="hl-1"> { </span><span class="hl-5">Mode</span><span class="hl-1"> } </span><span class="hl-11">from</span><span class="hl-1"> </span><span class="hl-10">&quot;@realsee/five&quot;</span><span class="hl-1">;</span><br/><br/><span class="hl-8">interface</span><span class="hl-1"> </span><span class="hl-9">Pose</span><span class="hl-1"> {</span><br/><span class="hl-1">  </span><span class="hl-7">/** 相机偏航角 (水平方向)，单位：弧度 */</span><br/><span class="hl-1">  </span><span class="hl-5">longitude</span><span class="hl-1">: </span><span class="hl-9">number</span><span class="hl-1">;</span><br/><span class="hl-1">  </span><span class="hl-7">/** 相机俯仰角 (垂直方向)，单位：弧度 */</span><br/><span class="hl-1">  </span><span class="hl-5">latitude</span><span class="hl-1">: </span><span class="hl-9">number</span><span class="hl-1">;</span><br/><span class="hl-1">  </span><span class="hl-7">/** 相机垂直视场角，单位：度 */</span><br/><span class="hl-1">  </span><span class="hl-5">fov</span><span class="hl-1">: </span><span class="hl-9">number</span><span class="hl-1">;</span><br/><span class="hl-1">  </span><span class="hl-7">/** 相机看向的目标中心点坐标 */</span><br/><span class="hl-1">  </span><span class="hl-5">offset</span><span class="hl-1">: </span><span class="hl-9">THREE</span><span class="hl-1">.</span><span class="hl-9">Vector3</span><span class="hl-1">;</span><br/><span class="hl-1">  </span><span class="hl-7">/** 相机距离目标中心点的距离 */</span><br/><span class="hl-1">  </span><span class="hl-5">distance</span><span class="hl-1">: </span><span class="hl-9">number</span><span class="hl-1">;</span><br/><span class="hl-1">}</span><br/><br/><span class="hl-8">interface</span><span class="hl-1"> </span><span class="hl-9">State</span><span class="hl-1"> </span><span class="hl-8">extends</span><span class="hl-1"> </span><span class="hl-9">Pose</span><span class="hl-1"> {</span><br/><span class="hl-1">  </span><span class="hl-7">/** 显示模式 */</span><br/><span class="hl-1">  </span><span class="hl-5">mode</span><span class="hl-1">: </span><span class="hl-9">Mode</span><span class="hl-1">;</span><br/><span class="hl-1">  </span><span class="hl-7">/** 当前点位的唯一标识 (workCode) */</span><br/><span class="hl-1">  </span><span class="hl-5">workCode</span><span class="hl-1">: </span><span class="hl-9">string</span><span class="hl-1">;</span><br/><span class="hl-1">  </span><span class="hl-7">/** 当前点位在列表中的索引 */</span><br/><span class="hl-1">  </span><span class="hl-5">panoIndex</span><span class="hl-1">: </span><span class="hl-9">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>
@@ -46,12 +46,12 @@
 <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>
+<pre><code class="ts"><span class="hl-7">// 切换到户型图模式，并旋转相机到 45 度</span><br/><span class="hl-5">five</span><span class="hl-1">.</span><span class="hl-4">setState</span><span class="hl-1">({</span><br/><span class="hl-1">  </span><span class="hl-5">mode:</span><span class="hl-1"> </span><span class="hl-10">&#39;Floorplan&#39;</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-5">longitude:</span><span class="hl-1"> </span><span class="hl-5">Math</span><span class="hl-1">.</span><span class="hl-6">PI</span><span class="hl-1"> / </span><span class="hl-3">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>
+<pre><code class="ts"><span class="hl-8">const</span><span class="hl-1"> </span><span class="hl-6">state</span><span class="hl-1"> = </span><span class="hl-5">five</span><span class="hl-1">.</span><span class="hl-5">state</span><span class="hl-1">;</span><br/><br/><span class="hl-7">// 在当前状态基础上，向右旋转 90 度，并略微拉远距离</span><br/><span class="hl-5">five</span><span class="hl-1">.</span><span class="hl-4">setState</span><span class="hl-1">({</span><br/><span class="hl-1">  </span><span class="hl-5">longitude:</span><span class="hl-1"> </span><span class="hl-5">state</span><span class="hl-1">.</span><span class="hl-5">longitude</span><span class="hl-1"> + </span><span class="hl-5">Math</span><span class="hl-1">.</span><span class="hl-6">PI</span><span class="hl-1"> / </span><span class="hl-3">2</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-5">distance:</span><span class="hl-1"> </span><span class="hl-5">state</span><span class="hl-1">.</span><span class="hl-5">distance</span><span class="hl-1"> + </span><span class="hl-3">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>
@@ -61,7 +61,7 @@
 <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>
+<pre><code class="typescript"><span class="hl-7">// 保存</span><br/><span class="hl-8">const</span><span class="hl-1"> </span><span class="hl-6">snapshot</span><span class="hl-1"> = {</span><br/><span class="hl-1">  ...</span><span class="hl-5">five</span><span class="hl-1">.</span><span class="hl-5">state</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-5">offset:</span><span class="hl-1"> { </span><span class="hl-5">x:</span><span class="hl-1"> </span><span class="hl-5">five</span><span class="hl-1">.</span><span class="hl-5">state</span><span class="hl-1">.</span><span class="hl-5">offset</span><span class="hl-1">.</span><span class="hl-5">x</span><span class="hl-1">, </span><span class="hl-5">y:</span><span class="hl-1"> </span><span class="hl-5">five</span><span class="hl-1">.</span><span class="hl-5">state</span><span class="hl-1">.</span><span class="hl-5">offset</span><span class="hl-1">.</span><span class="hl-5">y</span><span class="hl-1">, </span><span class="hl-5">z:</span><span class="hl-1"> </span><span class="hl-5">five</span><span class="hl-1">.</span><span class="hl-5">state</span><span class="hl-1">.</span><span class="hl-5">offset</span><span class="hl-1">.</span><span class="hl-5">z</span><span class="hl-1"> }</span><br/><span class="hl-1">};</span><br/><span class="hl-5">localStorage</span><span class="hl-1">.</span><span class="hl-4">setItem</span><span class="hl-1">(</span><span class="hl-10">&#39;fiveState&#39;</span><span class="hl-1">, </span><span class="hl-6">JSON</span><span class="hl-1">.</span><span class="hl-4">stringify</span><span class="hl-1">(</span><span class="hl-5">snapshot</span><span class="hl-1">));</span><br/><br/><span class="hl-7">// 恢复</span><br/><span class="hl-8">const</span><span class="hl-1"> </span><span class="hl-6">saved</span><span class="hl-1"> = </span><span class="hl-6">JSON</span><span class="hl-1">.</span><span class="hl-4">parse</span><span class="hl-1">(</span><span class="hl-5">localStorage</span><span class="hl-1">.</span><span class="hl-4">getItem</span><span class="hl-1">(</span><span class="hl-10">&#39;fiveState&#39;</span><span class="hl-1">)!);</span><br/><span class="hl-5">five</span><span class="hl-1">.</span><span class="hl-4">setState</span><span class="hl-1">({</span><br/><span class="hl-1">  ...</span><span class="hl-5">saved</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-5">offset:</span><span class="hl-1"> </span><span class="hl-8">new</span><span class="hl-1"> </span><span class="hl-6">THREE</span><span class="hl-1">.</span><span class="hl-4">Vector3</span><span class="hl-1">(</span><span class="hl-5">saved</span><span class="hl-1">.</span><span class="hl-5">offset</span><span class="hl-1">.</span><span class="hl-5">x</span><span class="hl-1">, </span><span class="hl-5">saved</span><span class="hl-1">.</span><span class="hl-5">offset</span><span class="hl-1">.</span><span class="hl-5">y</span><span class="hl-1">, </span><span class="hl-5">saved</span><span class="hl-1">.</span><span class="hl-5">offset</span><span class="hl-1">.</span><span class="hl-5">z</span><span class="hl-1">)</span><br/><span class="hl-1">}, </span><span class="hl-8">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>

package/docs/documents/features_view-layer.html CHANGED Viewed

@@ -10,7 +10,7 @@
 <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>
+<pre><code class="typescript"><span class="hl-7">// 简化定义</span><br/><span class="hl-8">interface</span><span class="hl-1"> </span><span class="hl-9">ViewLayer</span><span class="hl-1"> </span><span class="hl-8">extends</span><span class="hl-1"> </span><span class="hl-9">Tile3D</span><span class="hl-1"> {</span><br/><span class="hl-1">  </span><span class="hl-7">/** 图层名称 (如 &#39;mesh&#39;, &#39;point_cloud&#39;) */</span><br/><span class="hl-1">  </span><span class="hl-5">name</span><span class="hl-1">: </span><span class="hl-9">string</span><span class="hl-1">;</span><br/><span class="hl-1">  </span><span class="hl-7">/** 图层类型 */</span><br/><span class="hl-1">  </span><span class="hl-5">type</span><span class="hl-1">: </span><span class="hl-10">&quot;point_cloud&quot;</span><span class="hl-1"> | </span><span class="hl-10">&quot;mesh&quot;</span><span class="hl-1"> | </span><span class="hl-10">&quot;gaussian_splatting&quot;</span><span class="hl-1">;</span><br/><span class="hl-1">  </span><span class="hl-7">/** 独立的参数配置对象 */</span><br/><span class="hl-1">  </span><span class="hl-5">parameter</span><span class="hl-1">: </span><span class="hl-9">Parameter</span><span class="hl-1">;</span><br/><span class="hl-1">  </span><span class="hl-7">/** 是否可见 */</span><br/><span class="hl-1">  </span><span class="hl-5">visible</span><span class="hl-1">: </span><span class="hl-9">boolean</span><span class="hl-1">;</span><br/><span class="hl-1">  </span><span class="hl-7">/** 对应的 Tileset URL */</span><br/><span class="hl-1">  </span><span class="hl-5">tilesetUrl</span><span class="hl-1">: </span><span class="hl-9">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>
@@ -133,15 +133,15 @@ Five 会遍历这个数组，为每一项创建一个 <code>ViewLayer</code> 实
 </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>
+<pre><code class="typescript"><span class="hl-7">// 获取当前模型</span><br/><span class="hl-8">const</span><span class="hl-1"> </span><span class="hl-6">model</span><span class="hl-1"> = </span><span class="hl-5">five</span><span class="hl-1">.</span><span class="hl-5">model</span><span class="hl-1">;</span><br/><br/><span class="hl-7">// 遍历所有图层</span><br/><span class="hl-5">model</span><span class="hl-1">.</span><span class="hl-5">viewLayers</span><span class="hl-1">.</span><span class="hl-4">forEach</span><span class="hl-1">(</span><span class="hl-5">layer</span><span class="hl-1"> </span><span class="hl-8">=&gt;</span><span class="hl-1"> {</span><br/><span class="hl-1">  </span><span class="hl-5">console</span><span class="hl-1">.</span><span class="hl-4">log</span><span class="hl-1">(</span><span class="hl-10">`Layer Name: </span><span class="hl-8">${</span><span class="hl-5">layer</span><span class="hl-12">.</span><span class="hl-5">name</span><span class="hl-8">}</span><span class="hl-10">, Type: </span><span class="hl-8">${</span><span class="hl-5">layer</span><span class="hl-12">.</span><span class="hl-5">type</span><span class="hl-8">}</span><span class="hl-10">`</span><span class="hl-1">);</span><br/><span class="hl-1">});</span><br/><br/><span class="hl-7">// 查找特定的图层 (例如点云层)</span><br/><span class="hl-8">const</span><span class="hl-1"> </span><span class="hl-6">pointCloudLayer</span><span class="hl-1"> = </span><span class="hl-5">model</span><span class="hl-1">.</span><span class="hl-5">viewLayers</span><span class="hl-1">.</span><span class="hl-4">find</span><span class="hl-1">(</span><span class="hl-5">layer</span><span class="hl-1"> </span><span class="hl-8">=&gt;</span><span class="hl-1"> </span><span class="hl-5">layer</span><span class="hl-1">.</span><span class="hl-5">type</span><span class="hl-1"> === </span><span class="hl-10">&#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>
+<pre><code class="typescript"><span class="hl-7">// 方式 A: 运行时控制</span><br/><span class="hl-8">const</span><span class="hl-1"> </span><span class="hl-6">meshLayer</span><span class="hl-1"> = </span><span class="hl-5">five</span><span class="hl-1">.</span><span class="hl-5">model</span><span class="hl-1">.</span><span class="hl-5">viewLayers</span><span class="hl-1">.</span><span class="hl-4">find</span><span class="hl-1">(</span><span class="hl-5">layer</span><span class="hl-1"> </span><span class="hl-8">=&gt;</span><span class="hl-1"> </span><span class="hl-5">layer</span><span class="hl-1">.</span><span class="hl-5">type</span><span class="hl-1"> === </span><span class="hl-10">&#39;mesh&#39;</span><span class="hl-1">);</span><br/><br/><span class="hl-11">if</span><span class="hl-1"> (</span><span class="hl-5">meshLayer</span><span class="hl-1">) {</span><br/><span class="hl-1">  </span><span class="hl-7">// 隐藏模型层，只看点云</span><br/><span class="hl-1">  </span><span class="hl-5">meshLayer</span><span class="hl-1">.</span><span class="hl-5">visible</span><span class="hl-1"> = </span><span class="hl-8">false</span><span class="hl-1">;</span><br/><span class="hl-1">  </span><span class="hl-7">// 或者通过 parameter 设置</span><br/><span class="hl-1">  </span><span class="hl-7">// meshLayer.parameter.set(&#39;visible&#39;, false);</span><br/><span class="hl-1">}</span><br/><br/><span class="hl-7">// 方式 B: 加载时控制 (初始化时仅显示 mesh)</span><br/><span class="hl-5">five</span><span class="hl-1">.</span><span class="hl-4">load</span><span class="hl-1">(</span><span class="hl-5">work</span><span class="hl-1">, {</span><br/><span class="hl-1">  </span><span class="hl-5">model:</span><span class="hl-1"> {</span><br/><span class="hl-1">    </span><span class="hl-10">&quot;3d-tiles&quot;</span><span class="hl-5">:</span><span class="hl-1"> {</span><br/><span class="hl-1">      </span><span class="hl-5">showLayers:</span><span class="hl-1"> [</span><span class="hl-10">&#39;mesh&#39;</span><span class="hl-1">] </span><span class="hl-7">// 仅显示 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>
+<pre><code class="typescript"><span class="hl-8">const</span><span class="hl-1"> </span><span class="hl-6">pointCloudLayer</span><span class="hl-1"> = </span><span class="hl-5">five</span><span class="hl-1">.</span><span class="hl-5">model</span><span class="hl-1">.</span><span class="hl-5">viewLayers</span><span class="hl-1">.</span><span class="hl-4">find</span><span class="hl-1">(</span><span class="hl-5">layer</span><span class="hl-1"> </span><span class="hl-8">=&gt;</span><span class="hl-1"> </span><span class="hl-5">layer</span><span class="hl-1">.</span><span class="hl-5">type</span><span class="hl-1"> === </span><span class="hl-10">&#39;point_cloud&#39;</span><span class="hl-1">);</span><br/><br/><span class="hl-11">if</span><span class="hl-1"> (</span><span class="hl-5">pointCloudLayer</span><span class="hl-1">) {</span><br/><span class="hl-1">  </span><span class="hl-7">// 仅修改点云层的点大小，不影响其他模型</span><br/><span class="hl-1">  </span><span class="hl-5">pointCloudLayer</span><span class="hl-1">.</span><span class="hl-5">parameter</span><span class="hl-1">.</span><span class="hl-4">set</span><span class="hl-1">(</span><span class="hl-10">&#39;pointSize&#39;</span><span class="hl-1">, </span><span class="hl-3">2.0</span><span class="hl-1">);</span><br/><br/><span class="hl-1">  </span><span class="hl-7">// 仅修改点云层的最大显存占用</span><br/><span class="hl-1">  </span><span class="hl-5">pointCloudLayer</span><span class="hl-1">.</span><span class="hl-5">parameter</span><span class="hl-1">.</span><span class="hl-4">set</span><span class="hl-1">(</span><span class="hl-10">&#39;maxMemoryUsage&#39;</span><span class="hl-1">, </span><span class="hl-3">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>