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_camera-animation.html CHANGED Viewed

@@ -12,18 +12,18 @@
 <p><strong>Definition</strong>: <a href="../../five/types/movePanoOptions.d.ts">MovePanoOptions</a></p>
 </blockquote>
 <p>点位移动参数配置。</p>
-<pre><code class="typescript"><span class="hl-3">interface</span><span class="hl-1"> </span><span class="hl-7">MovePanoOptions</span><span class="hl-1"> </span><span class="hl-3">extends</span><span class="hl-1"> </span><span class="hl-7">Partial</span><span class="hl-1">&lt;</span><span class="hl-7">Omit</span><span class="hl-1">&lt;</span><span class="hl-7">State</span><span class="hl-1">, </span><span class="hl-9">&quot;offset&quot;</span><span class="hl-1"> | </span><span class="hl-9">&#39;distance&#39;</span><span class="hl-1"> | </span><span class="hl-9">&#39;mode&#39;</span><span class="hl-1">&gt;&gt; {</span><br/><span class="hl-1">  </span><span class="hl-8">/** 动画效果: &#39;fly&#39; | &#39;fade&#39; | &#39;instant&#39; ... */</span><br/><span class="hl-1">  </span><span class="hl-6">effect</span><span class="hl-1">?: </span><span class="hl-7">MovePanoEffect</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-5">effectEasing</span><span class="hl-1">?: (</span><span class="hl-6">progress</span><span class="hl-1">: </span><span class="hl-7">number</span><span class="hl-1">) </span><span class="hl-3">=&gt;</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-8">   * 运动耗时 (ms)</span><br/><span class="hl-8">   * - number: 固定时长</span><br/><span class="hl-8">   * - function: (distance, speed) =&gt; number 根据距离动态计算</span><br/><span class="hl-8">   */</span><br/><span class="hl-1">  </span><span class="hl-6">duration</span><span class="hl-1">?: </span><span class="hl-7">number</span><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><span class="hl-6">speed</span><span class="hl-1">: </span><span class="hl-7">number</span><span class="hl-1">) </span><span class="hl-3">=&gt;</span><span class="hl-1"> </span><span class="hl-7">number</span><span class="hl-1">) | </span><span class="hl-7">string</span><span class="hl-1"> | </span><span class="hl-7">null</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-5">moveStartCallback</span><span class="hl-1">?: (</span><span class="hl-6">toState</span><span class="hl-1">: </span><span class="hl-7">State</span><span class="hl-1">) </span><span class="hl-3">=&gt;</span><span class="hl-1"> </span><span class="hl-7">void</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-5">moveEndCallback</span><span class="hl-1">?: (</span><span class="hl-6">state</span><span class="hl-1">: </span><span class="hl-7">State</span><span class="hl-1">) </span><span class="hl-3">=&gt;</span><span class="hl-1"> </span><span class="hl-7">void</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-5">moveCancelCallback</span><span class="hl-1">?: () </span><span class="hl-3">=&gt;</span><span class="hl-1"> </span><span class="hl-7">void</span><span class="hl-1">;</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">MovePanoOptions</span><span class="hl-1"> </span><span class="hl-8">extends</span><span class="hl-1"> </span><span class="hl-9">Partial</span><span class="hl-1">&lt;</span><span class="hl-9">Omit</span><span class="hl-1">&lt;</span><span class="hl-9">State</span><span class="hl-1">, </span><span class="hl-10">&quot;offset&quot;</span><span class="hl-1"> | </span><span class="hl-10">&#39;distance&#39;</span><span class="hl-1"> | </span><span class="hl-10">&#39;mode&#39;</span><span class="hl-1">&gt;&gt; {</span><br/><span class="hl-1">  </span><span class="hl-7">/** 动画效果: &#39;fly&#39; | &#39;fade&#39; | &#39;instant&#39; ... */</span><br/><span class="hl-1">  </span><span class="hl-5">effect</span><span class="hl-1">?: </span><span class="hl-9">MovePanoEffect</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-4">effectEasing</span><span class="hl-1">?: (</span><span class="hl-5">progress</span><span class="hl-1">: </span><span class="hl-9">number</span><span class="hl-1">) </span><span class="hl-8">=&gt;</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-7">   * 运动耗时 (ms)</span><br/><span class="hl-7">   * - number: 固定时长</span><br/><span class="hl-7">   * - function: (distance, speed) =&gt; number 根据距离动态计算</span><br/><span class="hl-7">   */</span><br/><span class="hl-1">  </span><span class="hl-5">duration</span><span class="hl-1">?: </span><span class="hl-9">number</span><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><span class="hl-5">speed</span><span class="hl-1">: </span><span class="hl-9">number</span><span class="hl-1">) </span><span class="hl-8">=&gt;</span><span class="hl-1"> </span><span class="hl-9">number</span><span class="hl-1">) | </span><span class="hl-9">string</span><span class="hl-1"> | </span><span class="hl-9">null</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-4">moveStartCallback</span><span class="hl-1">?: (</span><span class="hl-5">toState</span><span class="hl-1">: </span><span class="hl-9">State</span><span class="hl-1">) </span><span class="hl-8">=&gt;</span><span class="hl-1"> </span><span class="hl-9">void</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-4">moveEndCallback</span><span class="hl-1">?: (</span><span class="hl-5">state</span><span class="hl-1">: </span><span class="hl-9">State</span><span class="hl-1">) </span><span class="hl-8">=&gt;</span><span class="hl-1"> </span><span class="hl-9">void</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-4">moveCancelCallback</span><span class="hl-1">?: () </span><span class="hl-8">=&gt;</span><span class="hl-1"> </span><span class="hl-9">void</span><span class="hl-1">;</span><br/><span class="hl-1">}</span>
 </code><button type="button">Copy</button></pre>
 <h3 id="movepanoeffect" class="tsd-anchor-link">MovePanoEffect<a href="#movepanoeffect" 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">type</span><span class="hl-1"> </span><span class="hl-7">MovePanoEffect</span><span class="hl-1"> =</span><br/><span class="hl-1">  | </span><span class="hl-9">&quot;fly&quot;</span><span class="hl-1">     </span><span class="hl-8">// 通过相机移动方式变化 (默认)</span><br/><span class="hl-1">  | </span><span class="hl-9">&quot;instant&quot;</span><span class="hl-1"> </span><span class="hl-8">// 直接变化 (无动画)</span><br/><span class="hl-1">  | </span><span class="hl-9">&quot;fade&quot;</span><span class="hl-1">    </span><span class="hl-8">// 通过渐变方式变化</span><br/><span class="hl-1">  | </span><span class="hl-9">&quot;model&quot;</span><span class="hl-1">;  </span><span class="hl-8">// 通过过度到模型</span>
+<pre><code class="typescript"><span class="hl-8">type</span><span class="hl-1"> </span><span class="hl-9">MovePanoEffect</span><span class="hl-1"> =</span><br/><span class="hl-1">  | </span><span class="hl-10">&quot;fly&quot;</span><span class="hl-1">     </span><span class="hl-7">// 通过相机移动方式变化 (默认)</span><br/><span class="hl-1">  | </span><span class="hl-10">&quot;instant&quot;</span><span class="hl-1"> </span><span class="hl-7">// 直接变化 (无动画)</span><br/><span class="hl-1">  | </span><span class="hl-10">&quot;fade&quot;</span><span class="hl-1">    </span><span class="hl-7">// 通过渐变方式变化</span><br/><span class="hl-1">  | </span><span class="hl-10">&quot;model&quot;</span><span class="hl-1">;  </span><span class="hl-7">// 通过过度到模型</span>
 </code><button type="button">Copy</button></pre>
 <h2 id="core-methods-核心方法" class="tsd-anchor-link">Core Methods (核心方法)<a href="#core-methods-核心方法" 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>Five 提供了多种层级的 API 来控制相机动画。</p>
 <h3 id="1-setstate" class="tsd-anchor-link">1. setState<a href="#1-setstate" 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>longitude</code> / <code>latitude</code> (旋转) 或 <code>fov</code> (缩放) 来产生动画。</p>
-<pre><code class="typescript"><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-5">setState</span><span class="hl-1">(</span><span class="hl-6">state</span><span class="hl-1">: </span><span class="hl-6">Partial</span><span class="hl-1">&lt;</span><span class="hl-6">State</span><span class="hl-1">&gt;, </span><span class="hl-6">immediately</span><span class="hl-1">?: </span><span class="hl-6">boolean</span><span class="hl-1">): </span><span class="hl-3">void</span>
+<pre><code class="typescript"><span class="hl-5">five</span><span class="hl-1">.</span><span class="hl-4">setState</span><span class="hl-1">(</span><span class="hl-5">state</span><span class="hl-1">: </span><span class="hl-5">Partial</span><span class="hl-1">&lt;</span><span class="hl-5">State</span><span class="hl-1">&gt;, </span><span class="hl-5">immediately</span><span class="hl-1">?: </span><span class="hl-5">boolean</span><span class="hl-1">): </span><span class="hl-8">void</span>
 </code><button type="button">Copy</button></pre>
 <ul>
@@ -32,7 +32,7 @@
 </ul>
 <h3 id="2-movetopano" class="tsd-anchor-link">2. moveToPano<a href="#2-movetopano" 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>专用于全景点位之间的切换。支持 &quot;飞行&quot; (Fly) 和 &quot;渐变&quot; (Fade) 两种效果。</p>
-<pre><code class="typescript"><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-5">moveToPano</span><span class="hl-1">(</span><span class="hl-6">panoIndex</span><span class="hl-1">: </span><span class="hl-6">number</span><span class="hl-1">, </span><span class="hl-6">options</span><span class="hl-1">?: </span><span class="hl-6">MovePanoOptions</span><span class="hl-1">): </span><span class="hl-7">Promise</span><span class="hl-1">&lt;</span><span class="hl-3">void</span><span class="hl-1">&gt;</span>
+<pre><code class="typescript"><span class="hl-5">five</span><span class="hl-1">.</span><span class="hl-4">moveToPano</span><span class="hl-1">(</span><span class="hl-5">panoIndex</span><span class="hl-1">: </span><span class="hl-5">number</span><span class="hl-1">, </span><span class="hl-5">options</span><span class="hl-1">?: </span><span class="hl-5">MovePanoOptions</span><span class="hl-1">): </span><span class="hl-9">Promise</span><span class="hl-1">&lt;</span><span class="hl-8">void</span><span class="hl-1">&gt;</span>
 </code><button type="button">Copy</button></pre>
 <ul>
@@ -42,12 +42,12 @@
 </ul>
 <h3 id="3-changemode" class="tsd-anchor-link">3. changeMode<a href="#3-changemode" 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-6">five</span><span class="hl-1">.</span><span class="hl-5">changeMode</span><span class="hl-1">(</span><span class="hl-6">mode</span><span class="hl-1">: </span><span class="hl-6">Mode</span><span class="hl-1">, </span><span class="hl-6">options</span><span class="hl-1">?, </span><span class="hl-6">animationOptions</span><span class="hl-1">?): </span><span class="hl-7">Promise</span><span class="hl-1">&lt;</span><span class="hl-3">void</span><span class="hl-1">&gt;</span>
+<pre><code class="typescript"><span class="hl-5">five</span><span class="hl-1">.</span><span class="hl-4">changeMode</span><span class="hl-1">(</span><span class="hl-5">mode</span><span class="hl-1">: </span><span class="hl-5">Mode</span><span class="hl-1">, </span><span class="hl-5">options</span><span class="hl-1">?, </span><span class="hl-5">animationOptions</span><span class="hl-1">?): </span><span class="hl-9">Promise</span><span class="hl-1">&lt;</span><span class="hl-8">void</span><span class="hl-1">&gt;</span>
 </code><button type="button">Copy</button></pre>
 <h3 id="4-updatecamera" class="tsd-anchor-link">4. updateCamera<a href="#4-updatecamera" 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>在不切换全景点位的情况下，将相机平滑动画到目标位姿。适用于&quot;定点环顾&quot;或&quot;聚焦某个方向&quot;等场景。</p>
-<pre><code class="typescript"><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-5">updateCamera</span><span class="hl-1">(</span><span class="hl-6">pose</span><span class="hl-1">: </span><span class="hl-6">Partial</span><span class="hl-1">&lt;</span><span class="hl-6">Pose</span><span class="hl-1">&gt;, </span><span class="hl-6">duration</span><span class="hl-1">: </span><span class="hl-6">number</span><span class="hl-1">, </span><span class="hl-6">userAction</span><span class="hl-1">?: </span><span class="hl-6">boolean</span><span class="hl-1">): </span><span class="hl-7">Promise</span><span class="hl-1">&lt;</span><span class="hl-3">void</span><span class="hl-1">&gt;</span>
+<pre><code class="typescript"><span class="hl-5">five</span><span class="hl-1">.</span><span class="hl-4">updateCamera</span><span class="hl-1">(</span><span class="hl-5">pose</span><span class="hl-1">: </span><span class="hl-5">Partial</span><span class="hl-1">&lt;</span><span class="hl-5">Pose</span><span class="hl-1">&gt;, </span><span class="hl-5">duration</span><span class="hl-1">: </span><span class="hl-5">number</span><span class="hl-1">, </span><span class="hl-5">userAction</span><span class="hl-1">?: </span><span class="hl-5">boolean</span><span class="hl-1">): </span><span class="hl-9">Promise</span><span class="hl-1">&lt;</span><span class="hl-8">void</span><span class="hl-1">&gt;</span>
 </code><button type="button">Copy</button></pre>
 <ul>
@@ -135,22 +135,22 @@
 <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-旋转视角-rotate-camera" class="tsd-anchor-link">1. 旋转视角 (Rotate Camera)<a href="#1-旋转视角-rotate-camera" 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-8">// 旋转到水平 0 度，垂直 0 度</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-11">0</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-6">latitude:</span><span class="hl-1"> </span><span class="hl-11">0</span><br/><span class="hl-1">});</span><br/><br/><span class="hl-8">// 立即跳转 (无动画)</span><br/><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-5">setState</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-3">true</span><span class="hl-1">);</span>
+<pre><code class="typescript"><span class="hl-7">// 旋转到水平 0 度，垂直 0 度</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-3">0</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-5">latitude:</span><span class="hl-1"> </span><span class="hl-3">0</span><br/><span class="hl-1">});</span><br/><br/><span class="hl-7">// 立即跳转 (无动画)</span><br/><span class="hl-5">five</span><span class="hl-1">.</span><span class="hl-4">setState</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-8">true</span><span class="hl-1">);</span>
 </code><button type="button">Copy</button></pre>
 <h3 id="2-切换全景点-change-pano" class="tsd-anchor-link">2. 切换全景点 (Change Pano)<a href="#2-切换全景点-change-pano" 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-8">// 飞向索引为 2 的全景点</span><br/><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-5">moveToPano</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">effect:</span><span class="hl-1"> </span><span class="hl-9">&#39;fly&#39;</span><span class="hl-1">, </span><span class="hl-8">// 飞行效果</span><br/><span class="hl-1">  </span><span class="hl-6">duration:</span><span class="hl-1"> </span><span class="hl-11">1500</span><span class="hl-1">, </span><span class="hl-8">// 1.5秒</span><br/><span class="hl-1">  </span><span class="hl-5">moveEndCallback</span><span class="hl-6">:</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">&quot;到达目的地&quot;</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-7">// 飞向索引为 2 的全景点</span><br/><span class="hl-5">five</span><span class="hl-1">.</span><span class="hl-4">moveToPano</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">effect:</span><span class="hl-1"> </span><span class="hl-10">&#39;fly&#39;</span><span class="hl-1">, </span><span class="hl-7">// 飞行效果</span><br/><span class="hl-1">  </span><span class="hl-5">duration:</span><span class="hl-1"> </span><span class="hl-3">1500</span><span class="hl-1">, </span><span class="hl-7">// 1.5秒</span><br/><span class="hl-1">  </span><span class="hl-4">moveEndCallback</span><span class="hl-5">:</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">&quot;到达目的地&quot;</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-模态切换-change-mode" class="tsd-anchor-link">3. 模态切换 (Change Mode)<a href="#3-模态切换-change-mode" 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-8">// 切换到 Floorplan 模式</span><br/><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-5">changeMode</span><span class="hl-1">(</span><span class="hl-9">&#39;Floorplan&#39;</span><span class="hl-1">);</span><br/><br/><span class="hl-8">// 切换回 Panorama 模式，并指定进入时的视角</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;Panorama&#39;</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-6">panoIndex:</span><span class="hl-1"> </span><span class="hl-11">0</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">2</span><br/><span class="hl-1">});</span>
+<pre><code class="typescript"><span class="hl-7">// 切换到 Floorplan 模式</span><br/><span class="hl-5">five</span><span class="hl-1">.</span><span class="hl-4">changeMode</span><span class="hl-1">(</span><span class="hl-10">&#39;Floorplan&#39;</span><span class="hl-1">);</span><br/><br/><span class="hl-7">// 切换回 Panorama 模式，并指定进入时的视角</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;Panorama&#39;</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-5">panoIndex:</span><span class="hl-1"> </span><span class="hl-3">0</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">2</span><br/><span class="hl-1">});</span>
 </code><button type="button">Copy</button></pre>
 <h3 id="4-自动巡更-auto-tour" class="tsd-anchor-link">4. 自动巡更 (Auto Tour)<a href="#4-自动巡更-auto-tour" 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> 或 <code>moveToPano</code> 实现简单的自动导览。</p>
-<pre><code class="typescript"><span class="hl-3">async</span><span class="hl-1"> </span><span class="hl-3">function</span><span class="hl-1"> </span><span class="hl-5">startTour</span><span class="hl-1">() {</span><br/><span class="hl-1">  </span><span class="hl-8">// 1. 先看天花板</span><br/><span class="hl-1">  </span><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-5">setState</span><span class="hl-1">({ </span><span class="hl-6">latitude:</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">3</span><span class="hl-1"> });</span><br/><span class="hl-1">  </span><span class="hl-10">await</span><span class="hl-1"> </span><span class="hl-5">wait</span><span class="hl-1">(</span><span class="hl-11">2000</span><span class="hl-1">); </span><span class="hl-8">// 等待动画完成</span><br/><br/><span class="hl-1">  </span><span class="hl-8">// 2. 移动到下一个点</span><br/><span class="hl-1">  </span><span class="hl-10">await</span><span class="hl-1"> </span><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-5">moveToPano</span><span class="hl-1">(</span><span class="hl-11">1</span><span class="hl-1">, { </span><span class="hl-6">effect:</span><span class="hl-1"> </span><span class="hl-9">&#39;fly&#39;</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-10">await</span><span class="hl-1"> </span><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-5">changeMode</span><span class="hl-1">(</span><span class="hl-9">&#39;Mapview&#39;</span><span class="hl-1">);</span><br/><span class="hl-1">}</span><br/><br/><span class="hl-3">function</span><span class="hl-1"> </span><span class="hl-5">wait</span><span class="hl-1">(</span><span class="hl-6">ms</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-10">return</span><span class="hl-1"> </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-7">Promise</span><span class="hl-1">(</span><span class="hl-6">resolve</span><span class="hl-1"> </span><span class="hl-3">=&gt;</span><span class="hl-1"> </span><span class="hl-5">setTimeout</span><span class="hl-1">(</span><span class="hl-6">resolve</span><span class="hl-1">, </span><span class="hl-6">ms</span><span class="hl-1">));</span><br/><span class="hl-1">}</span>
+<pre><code class="typescript"><span class="hl-8">async</span><span class="hl-1"> </span><span class="hl-8">function</span><span class="hl-1"> </span><span class="hl-4">startTour</span><span class="hl-1">() {</span><br/><span class="hl-1">  </span><span class="hl-7">// 1. 先看天花板</span><br/><span class="hl-1">  </span><span class="hl-5">five</span><span class="hl-1">.</span><span class="hl-4">setState</span><span class="hl-1">({ </span><span class="hl-5">latitude:</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">3</span><span class="hl-1"> });</span><br/><span class="hl-1">  </span><span class="hl-11">await</span><span class="hl-1"> </span><span class="hl-4">wait</span><span class="hl-1">(</span><span class="hl-3">2000</span><span class="hl-1">); </span><span class="hl-7">// 等待动画完成</span><br/><br/><span class="hl-1">  </span><span class="hl-7">// 2. 移动到下一个点</span><br/><span class="hl-1">  </span><span class="hl-11">await</span><span class="hl-1"> </span><span class="hl-5">five</span><span class="hl-1">.</span><span class="hl-4">moveToPano</span><span class="hl-1">(</span><span class="hl-3">1</span><span class="hl-1">, { </span><span class="hl-5">effect:</span><span class="hl-1"> </span><span class="hl-10">&#39;fly&#39;</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-11">await</span><span class="hl-1"> </span><span class="hl-5">five</span><span class="hl-1">.</span><span class="hl-4">changeMode</span><span class="hl-1">(</span><span class="hl-10">&#39;Mapview&#39;</span><span class="hl-1">);</span><br/><span class="hl-1">}</span><br/><br/><span class="hl-8">function</span><span class="hl-1"> </span><span class="hl-4">wait</span><span class="hl-1">(</span><span class="hl-5">ms</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-11">return</span><span class="hl-1"> </span><span class="hl-8">new</span><span class="hl-1"> </span><span class="hl-9">Promise</span><span class="hl-1">(</span><span class="hl-5">resolve</span><span class="hl-1"> </span><span class="hl-8">=&gt;</span><span class="hl-1"> </span><span class="hl-4">setTimeout</span><span class="hl-1">(</span><span class="hl-5">resolve</span><span class="hl-1">, </span><span class="hl-5">ms</span><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_clipper.html CHANGED Viewed

@@ -10,7 +10,7 @@
 <blockquote>
 <p><strong>Definition</strong>: <a href="../../five/model/materials/pbmMaterial.d.ts">PBMClipperParameter</a></p>
 </blockquote>
-<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">PBMClipperParameter</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><br/><span class="hl-8">   * 定义了一个变换后的立方体空间。</span><br/><span class="hl-8">   * 基础形状为边长为 1 的立方体，中心在 (0,0,0)，范围 [-0.5, 0.5]。</span><br/><span class="hl-8">   * 凡是落在这个变换后立方体内部的模型点，都会被丢弃 (discard)。</span><br/><span class="hl-8">   */</span><br/><span class="hl-1">  </span><span class="hl-6">clippingBoxMatrix</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-8">   * (可选) 楼层索引。</span><br/><span class="hl-8">   * </span><span class="hl-3">@description</span><br/><span class="hl-8">   * 如果指定，则裁切仅对该楼层的点云生效。</span><br/><span class="hl-8">   * 如果未指定 (undefined)，则对所有楼层生效。</span><br/><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/><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">PBMClipperParameter</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><br/><span class="hl-7">   * 定义了一个变换后的立方体空间。</span><br/><span class="hl-7">   * 基础形状为边长为 1 的立方体，中心在 (0,0,0)，范围 [-0.5, 0.5]。</span><br/><span class="hl-7">   * 凡是落在这个变换后立方体内部的模型点，都会被丢弃 (discard)。</span><br/><span class="hl-7">   */</span><br/><span class="hl-1">  </span><span class="hl-5">clippingBoxMatrix</span><span class="hl-1">: </span><span class="hl-9">THREE</span><span class="hl-1">.</span><span class="hl-9">Matrix4</span><span class="hl-1">;</span><br/><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><br/><span class="hl-7">   * 如果指定，则裁切仅对该楼层的点云生效。</span><br/><span class="hl-7">   * 如果未指定 (undefined)，则对所有楼层生效。</span><br/><span class="hl-7">   */</span><br/><span class="hl-1">  </span><span class="hl-5">floorIndex</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>
@@ -49,12 +49,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="基础用法-basic-usage" class="tsd-anchor-link">基础用法 (Basic Usage)<a href="#基础用法-basic-usage" 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>创建一个不可见的 Box，将其位置和大小作为裁切区域。</p>
-<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">&#39;three&#39;</span><span class="hl-1">;</span><br/><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-10">from</span><span class="hl-1"> </span><span class="hl-9">&#39;@realsee/five&#39;</span><span class="hl-1">;</span><br/><br/><span class="hl-8">// 1. 创建一个辅助 Mesh 来定义裁切区域</span><br/><span class="hl-8">// 注意：必须使用 1x1x1 的 BoxGeometry，因为 Shader 是基于单位立方体判断的</span><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">clipperMesh</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">Mesh</span><span class="hl-1">(</span><br/><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">BoxGeometry</span><span class="hl-1">(</span><span class="hl-11">1</span><span class="hl-1">, </span><span class="hl-11">1</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-3">new</span><span class="hl-1"> </span><span class="hl-4">THREE</span><span class="hl-1">.</span><span class="hl-5">MeshBasicMaterial</span><span class="hl-1">({ </span><span class="hl-6">color:</span><span class="hl-1"> </span><span class="hl-11">0xff0000</span><span class="hl-1">, </span><span class="hl-6">wireframe:</span><span class="hl-1"> </span><span class="hl-3">true</span><span class="hl-1"> })</span><br/><span class="hl-1">);</span><br/><br/><span class="hl-8">// 2. 设置裁切盒的位置、旋转和缩放</span><br/><span class="hl-6">clipperMesh</span><span class="hl-1">.</span><span class="hl-6">position</span><span class="hl-1">.</span><span class="hl-5">set</span><span class="hl-1">(</span><span class="hl-11">0</span><span class="hl-1">, </span><span class="hl-11">1.5</span><span class="hl-1">, </span><span class="hl-11">0</span><span class="hl-1">); </span><span class="hl-8">// 抬高位置</span><br/><span class="hl-6">clipperMesh</span><span class="hl-1">.</span><span class="hl-6">scale</span><span class="hl-1">.</span><span class="hl-5">set</span><span class="hl-1">(</span><span class="hl-11">2</span><span class="hl-1">, </span><span class="hl-11">3</span><span class="hl-1">, </span><span class="hl-11">2</span><span class="hl-1">);      </span><span class="hl-8">// 设定大小为 2x3x2</span><br/><span class="hl-6">clipperMesh</span><span class="hl-1">.</span><span class="hl-6">rotation</span><span class="hl-1">.</span><span class="hl-6">y</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><span class="hl-1">; </span><span class="hl-8">// 旋转 45 度</span><br/><br/><span class="hl-8">// 更新矩阵，确保 .matrix 属性是最新的</span><br/><span class="hl-6">clipperMesh</span><span class="hl-1">.</span><span class="hl-5">updateMatrix</span><span class="hl-1">();</span><br/><br/><span class="hl-8">// (可选) 将辅助 Mesh 加入场景以便调试看到范围</span><br/><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-6">scene</span><span class="hl-1">.</span><span class="hl-5">add</span><span class="hl-1">(</span><span class="hl-6">clipperMesh</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-6">model</span><span class="hl-1">.</span><span class="hl-6">clippers</span><span class="hl-1"> = [</span><br/><span class="hl-1">  {</span><br/><span class="hl-1">    </span><span class="hl-6">clippingBoxMatrix:</span><span class="hl-1"> </span><span class="hl-6">clipperMesh</span><span class="hl-1">.</span><span class="hl-6">matrix</span><span class="hl-1">,</span><br/><span class="hl-1">    </span><span class="hl-8">// floorIndex: 0 // 可选：仅裁切第 0 层</span><br/><span class="hl-1">  }</span><br/><span class="hl-1">];</span><br/><br/><span class="hl-8">// 4. 触发重绘</span><br/><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-6">needsRender</span><span class="hl-1"> = </span><span class="hl-3">true</span><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">&#39;three&#39;</span><span class="hl-1">;</span><br/><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-11">from</span><span class="hl-1"> </span><span class="hl-10">&#39;@realsee/five&#39;</span><span class="hl-1">;</span><br/><br/><span class="hl-7">// 1. 创建一个辅助 Mesh 来定义裁切区域</span><br/><span class="hl-7">// 注意：必须使用 1x1x1 的 BoxGeometry，因为 Shader 是基于单位立方体判断的</span><br/><span class="hl-8">const</span><span class="hl-1"> </span><span class="hl-6">clipperMesh</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">Mesh</span><span class="hl-1">(</span><br/><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">BoxGeometry</span><span class="hl-1">(</span><span class="hl-3">1</span><span class="hl-1">, </span><span class="hl-3">1</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-8">new</span><span class="hl-1"> </span><span class="hl-6">THREE</span><span class="hl-1">.</span><span class="hl-4">MeshBasicMaterial</span><span class="hl-1">({ </span><span class="hl-5">color:</span><span class="hl-1"> </span><span class="hl-3">0xff0000</span><span class="hl-1">, </span><span class="hl-5">wireframe:</span><span class="hl-1"> </span><span class="hl-8">true</span><span class="hl-1"> })</span><br/><span class="hl-1">);</span><br/><br/><span class="hl-7">// 2. 设置裁切盒的位置、旋转和缩放</span><br/><span class="hl-5">clipperMesh</span><span class="hl-1">.</span><span class="hl-5">position</span><span class="hl-1">.</span><span class="hl-4">set</span><span class="hl-1">(</span><span class="hl-3">0</span><span class="hl-1">, </span><span class="hl-3">1.5</span><span class="hl-1">, </span><span class="hl-3">0</span><span class="hl-1">); </span><span class="hl-7">// 抬高位置</span><br/><span class="hl-5">clipperMesh</span><span class="hl-1">.</span><span class="hl-5">scale</span><span class="hl-1">.</span><span class="hl-4">set</span><span class="hl-1">(</span><span class="hl-3">2</span><span class="hl-1">, </span><span class="hl-3">3</span><span class="hl-1">, </span><span class="hl-3">2</span><span class="hl-1">);      </span><span class="hl-7">// 设定大小为 2x3x2</span><br/><span class="hl-5">clipperMesh</span><span class="hl-1">.</span><span class="hl-5">rotation</span><span class="hl-1">.</span><span class="hl-5">y</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><span class="hl-1">; </span><span class="hl-7">// 旋转 45 度</span><br/><br/><span class="hl-7">// 更新矩阵，确保 .matrix 属性是最新的</span><br/><span class="hl-5">clipperMesh</span><span class="hl-1">.</span><span class="hl-4">updateMatrix</span><span class="hl-1">();</span><br/><br/><span class="hl-7">// (可选) 将辅助 Mesh 加入场景以便调试看到范围</span><br/><span class="hl-5">five</span><span class="hl-1">.</span><span class="hl-5">scene</span><span class="hl-1">.</span><span class="hl-4">add</span><span class="hl-1">(</span><span class="hl-5">clipperMesh</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-5">model</span><span class="hl-1">.</span><span class="hl-5">clippers</span><span class="hl-1"> = [</span><br/><span class="hl-1">  {</span><br/><span class="hl-1">    </span><span class="hl-5">clippingBoxMatrix:</span><span class="hl-1"> </span><span class="hl-5">clipperMesh</span><span class="hl-1">.</span><span class="hl-5">matrix</span><span class="hl-1">,</span><br/><span class="hl-1">    </span><span class="hl-7">// floorIndex: 0 // 可选：仅裁切第 0 层</span><br/><span class="hl-1">  }</span><br/><span class="hl-1">];</span><br/><br/><span class="hl-7">// 4. 触发重绘</span><br/><span class="hl-5">five</span><span class="hl-1">.</span><span class="hl-5">needsRender</span><span class="hl-1"> = </span><span class="hl-8">true</span><span class="hl-1">;</span>
 </code><button type="button">Copy</button></pre>
 <h3 id="动态更新-dynamic-update" class="tsd-anchor-link">动态更新 (Dynamic Update)<a href="#动态更新-dynamic-update" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3>
 <p>如果需要动态移动裁切盒，需要重新赋值 <code>five.model.clippers</code> 或手动触发更新机制（虽然 setter 会自动触发更新，但如果只修改数组内部对象可能需要重新赋值）。</p>
-<pre><code class="typescript"><span class="hl-3">function</span><span class="hl-1"> </span><span class="hl-5">updateClipper</span><span class="hl-1">(</span><span class="hl-6">mesh</span><span class="hl-1">: </span><span class="hl-7">THREE</span><span class="hl-1">.</span><span class="hl-7">Mesh</span><span class="hl-1">) {</span><br/><span class="hl-1">  </span><span class="hl-6">mesh</span><span class="hl-1">.</span><span class="hl-5">updateMatrix</span><span class="hl-1">();</span><br/><br/><span class="hl-1">  </span><span class="hl-8">// 重新赋值以触发 Five 内部的 setter 和 uniform 更新</span><br/><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">clippers</span><span class="hl-1"> = [{</span><br/><span class="hl-1">    </span><span class="hl-6">clippingBoxMatrix:</span><span class="hl-1"> </span><span class="hl-6">mesh</span><span class="hl-1">.</span><span class="hl-6">matrix</span><br/><span class="hl-1">  }];</span><br/><span class="hl-1">}</span><br/><br/><span class="hl-8">// 在动画循环或交互事件中调用</span><br/><span class="hl-8">// ...</span>
+<pre><code class="typescript"><span class="hl-8">function</span><span class="hl-1"> </span><span class="hl-4">updateClipper</span><span class="hl-1">(</span><span class="hl-5">mesh</span><span class="hl-1">: </span><span class="hl-9">THREE</span><span class="hl-1">.</span><span class="hl-9">Mesh</span><span class="hl-1">) {</span><br/><span class="hl-1">  </span><span class="hl-5">mesh</span><span class="hl-1">.</span><span class="hl-4">updateMatrix</span><span class="hl-1">();</span><br/><br/><span class="hl-1">  </span><span class="hl-7">// 重新赋值以触发 Five 内部的 setter 和 uniform 更新</span><br/><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">clippers</span><span class="hl-1"> = [{</span><br/><span class="hl-1">    </span><span class="hl-5">clippingBoxMatrix:</span><span class="hl-1"> </span><span class="hl-5">mesh</span><span class="hl-1">.</span><span class="hl-5">matrix</span><br/><span class="hl-1">  }];</span><br/><span class="hl-1">}</span><br/><br/><span class="hl-7">// 在动画循环或交互事件中调用</span><br/><span class="hl-7">// ...</span>
 </code><button type="button">Copy</button></pre>
 <h2 id="debugging" class="tsd-anchor-link">Debugging<a href="#debugging" 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_coordinate-system.html CHANGED Viewed

@@ -11,12 +11,12 @@
 </blockquote>
 <h3 id="rootmeta" class="tsd-anchor-link">RootMeta<a href="#rootmeta" 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 Tiles <code>rootMeta</code> 字段中定义的坐标系元数据。</p>
-<pre><code class="typescript"><span class="hl-3">interface</span><span class="hl-1"> </span><span class="hl-7">RootMeta</span><span class="hl-1"> {</span><br/><span class="hl-1">  </span><span class="hl-8">/** 模型垂直轴向 (如 &quot;Z&quot;, &quot;-Y&quot;) */</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">/** 坐标系转换矩阵信息 */</span><br/><span class="hl-1">  </span><span class="hl-6">coordinate</span><span class="hl-1">?: </span><span class="hl-7">Coordinate</span><span class="hl-1">;</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">RootMeta</span><span class="hl-1"> {</span><br/><span class="hl-1">  </span><span class="hl-7">/** 模型垂直轴向 (如 &quot;Z&quot;, &quot;-Y&quot;) */</span><br/><span class="hl-1">  </span><span class="hl-5">upAxis</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">coordinate</span><span class="hl-1">?: </span><span class="hl-9">Coordinate</span><span class="hl-1">;</span><br/><span class="hl-1">}</span>
 </code><button type="button">Copy</button></pre>
 <h3 id="coordinate" class="tsd-anchor-link">Coordinate<a href="#coordinate" 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>描述 ECEF 与 ENU 之间的转换关系。</p>
-<pre><code class="typescript"><span class="hl-3">interface</span><span class="hl-1"> </span><span class="hl-7">Coordinate</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">ground_height</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">/** ECEF 到 ENU 的转换矩阵 (4x4 数组) */</span><br/><span class="hl-1">  </span><span class="hl-6">pose_ecef_to_enu</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">/** ENU 到 ECEF 的转换矩阵 (4x4 数组) */</span><br/><span class="hl-1">  </span><span class="hl-6">pose_enu_to_ecef</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="typescript"><span class="hl-8">interface</span><span class="hl-1"> </span><span class="hl-9">Coordinate</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">ground_height</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">/** ECEF 到 ENU 的转换矩阵 (4x4 数组) */</span><br/><span class="hl-1">  </span><span class="hl-5">pose_ecef_to_enu</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">/** ENU 到 ECEF 的转换矩阵 (4x4 数组) */</span><br/><span class="hl-1">  </span><span class="hl-5">pose_enu_to_ecef</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>
@@ -162,7 +162,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="坐标转换-coordinate-transformation" class="tsd-anchor-link">坐标转换 (Coordinate Transformation)<a href="#坐标转换-coordinate-transformation" 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>推荐在与后端或算法交互时，将 Local 坐标转换为 ENU 坐标。</p>
-<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">&#39;three&#39;</span><span class="hl-1">;</span><br/><span class="hl-10">import</span><span class="hl-1"> { </span><span class="hl-6">ViewLayer</span><span class="hl-1"> } </span><span class="hl-10">from</span><span class="hl-1"> </span><span class="hl-9">&#39;@realsee/five&#39;</span><span class="hl-1">;</span><br/><br/><span class="hl-8">// 假设已加载 ViewLayer</span><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">viewLayer</span><span class="hl-1">: </span><span class="hl-7">ViewLayer</span><span class="hl-1"> = ...;</span><br/><br/><span class="hl-8">// 1. 获取场景中某点的坐标 (Local Y-up)</span><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">localPosition</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">10</span><span class="hl-1">, </span><span class="hl-11">20</span><span class="hl-1">, </span><span class="hl-11">30</span><span class="hl-1">);</span><br/><br/><span class="hl-8">// 2. 转换为 ENU 坐标 (Z-up) 用于传输给后端/算法</span><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">enuPosition</span><span class="hl-1"> = </span><span class="hl-6">viewLayer</span><span class="hl-1">.</span><span class="hl-5">localToEnu</span><span class="hl-1">(</span><span class="hl-6">localPosition</span><span class="hl-1">.</span><span class="hl-5">clone</span><span class="hl-1">());</span><br/><br/><span class="hl-6">console</span><span class="hl-1">.</span><span class="hl-5">log</span><span class="hl-1">(</span><span class="hl-9">`Local: </span><span class="hl-3">${</span><span class="hl-6">localPosition</span><span class="hl-12">.</span><span class="hl-5">toArray</span><span class="hl-12">()</span><span class="hl-3">}</span><span class="hl-9">`</span><span class="hl-1">); </span><span class="hl-8">// [x, y, z] (y-up)</span><br/><span class="hl-6">console</span><span class="hl-1">.</span><span class="hl-5">log</span><span class="hl-1">(</span><span class="hl-9">`ENU: </span><span class="hl-3">${</span><span class="hl-6">enuPosition</span><span class="hl-12">.</span><span class="hl-5">toArray</span><span class="hl-12">()</span><span class="hl-3">}</span><span class="hl-9">`</span><span class="hl-1">);     </span><span class="hl-8">// [x, y, z] (z-up)</span><br/><br/><span class="hl-8">// 3. 将 ECEF 坐标转换为 Local 坐标用于显示</span><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">ecefPosition</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><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">displayPosition</span><span class="hl-1"> = </span><span class="hl-6">viewLayer</span><span class="hl-1">.</span><span class="hl-5">ecefToLocal</span><span class="hl-1">(</span><span class="hl-6">ecefPosition</span><span class="hl-1">.</span><span class="hl-5">clone</span><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">&#39;three&#39;</span><span class="hl-1">;</span><br/><span class="hl-11">import</span><span class="hl-1"> { </span><span class="hl-5">ViewLayer</span><span class="hl-1"> } </span><span class="hl-11">from</span><span class="hl-1"> </span><span class="hl-10">&#39;@realsee/five&#39;</span><span class="hl-1">;</span><br/><br/><span class="hl-7">// 假设已加载 ViewLayer</span><br/><span class="hl-8">const</span><span class="hl-1"> </span><span class="hl-6">viewLayer</span><span class="hl-1">: </span><span class="hl-9">ViewLayer</span><span class="hl-1"> = ...;</span><br/><br/><span class="hl-7">// 1. 获取场景中某点的坐标 (Local Y-up)</span><br/><span class="hl-8">const</span><span class="hl-1"> </span><span class="hl-6">localPosition</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">10</span><span class="hl-1">, </span><span class="hl-3">20</span><span class="hl-1">, </span><span class="hl-3">30</span><span class="hl-1">);</span><br/><br/><span class="hl-7">// 2. 转换为 ENU 坐标 (Z-up) 用于传输给后端/算法</span><br/><span class="hl-8">const</span><span class="hl-1"> </span><span class="hl-6">enuPosition</span><span class="hl-1"> = </span><span class="hl-5">viewLayer</span><span class="hl-1">.</span><span class="hl-4">localToEnu</span><span class="hl-1">(</span><span class="hl-5">localPosition</span><span class="hl-1">.</span><span class="hl-4">clone</span><span class="hl-1">());</span><br/><br/><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">`Local: </span><span class="hl-8">${</span><span class="hl-5">localPosition</span><span class="hl-12">.</span><span class="hl-4">toArray</span><span class="hl-12">()</span><span class="hl-8">}</span><span class="hl-10">`</span><span class="hl-1">); </span><span class="hl-7">// [x, y, z] (y-up)</span><br/><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">`ENU: </span><span class="hl-8">${</span><span class="hl-5">enuPosition</span><span class="hl-12">.</span><span class="hl-4">toArray</span><span class="hl-12">()</span><span class="hl-8">}</span><span class="hl-10">`</span><span class="hl-1">);     </span><span class="hl-7">// [x, y, z] (z-up)</span><br/><br/><span class="hl-7">// 3. 将 ECEF 坐标转换为 Local 坐标用于显示</span><br/><span class="hl-8">const</span><span class="hl-1"> </span><span class="hl-6">ecefPosition</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><br/><span class="hl-8">const</span><span class="hl-1"> </span><span class="hl-6">displayPosition</span><span class="hl-1"> = </span><span class="hl-5">viewLayer</span><span class="hl-1">.</span><span class="hl-4">ecefToLocal</span><span class="hl-1">(</span><span class="hl-5">ecefPosition</span><span class="hl-1">.</span><span class="hl-4">clone</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>