@realsee/five 6.8.9 → 6.9.0-alpha.1

package/docs/documents/features_gaussian-blur-pass.html

@@ -11,7 +11,7 @@
 <p><strong>Definition</strong>: <a href="../../five/renderer/postprocessing/passes/gaussian-blur-pass.d.ts">GaussianBlurPass</a></p>
 </blockquote>
 <p><code>GaussianBlurPass</code> 是 <code>FivePass</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">&#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">FivePass</span><span class="hl-1"> } </span><span class="hl-10">from</span><span class="hl-1"> </span><span class="hl-9">&#39;./pass&#39;</span><span class="hl-1">;</span><br/><span class="hl-10">import</span><span class="hl-1"> { </span><span class="hl-10">type</span><span class="hl-1"> </span><span class="hl-6">Camera</span><span class="hl-1"> } </span><span class="hl-10">from</span><span class="hl-1"> </span><span class="hl-9">&#39;../../../core/camera&#39;</span><span class="hl-1">;</span><br/><br/><span class="hl-10">export</span><span class="hl-1"> </span><span class="hl-3">class</span><span class="hl-1"> </span><span class="hl-7">GaussianBlurPass</span><span class="hl-1"> </span><span class="hl-3">extends</span><span class="hl-1"> </span><span class="hl-7">FivePass</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-3">constructor</span><span class="hl-1">(</span><span class="hl-6">camera</span><span class="hl-1">: </span><span class="hl-7">Camera</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-3">public</span><span class="hl-1"> </span><span class="hl-5">setRadius</span><span class="hl-1">(</span><span class="hl-6">radius</span><span class="hl-1">: </span><span class="hl-7">number</span><span class="hl-1">): </span><span class="hl-7">void</span><span class="hl-1">;</span><br/><br/><span class="hl-1">  </span><span class="hl-8">// 渲染方法（由 EffectComposer 调用）</span><br/><span class="hl-1">  </span><span class="hl-3">public</span><span class="hl-1"> </span><span class="hl-5">render</span><span class="hl-1">(</span><br/><span class="hl-1">    </span><span class="hl-6">renderer</span><span class="hl-1">: </span><span class="hl-7">THREE</span><span class="hl-1">.</span><span class="hl-7">WebGLRenderer</span><span class="hl-1">,</span><br/><span class="hl-1">    </span><span class="hl-6">writeBuffer</span><span class="hl-1">: </span><span class="hl-7">THREE</span><span class="hl-1">.</span><span class="hl-7">WebGLRenderTarget</span><span class="hl-1">,</span><br/><span class="hl-1">    </span><span class="hl-6">readBuffer</span><span class="hl-1">: </span><span class="hl-7">THREE</span><span class="hl-1">.</span><span class="hl-7">WebGLRenderTarget</span><span class="hl-1">,</span><br/><span class="hl-1">    </span><span class="hl-6">deltaTime</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-6">maskActive</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-7">void</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-3">public</span><span class="hl-1"> </span><span class="hl-5">dispose</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="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">&#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">FivePass</span><span class="hl-1"> } </span><span class="hl-11">from</span><span class="hl-1"> </span><span class="hl-10">&#39;./pass&#39;</span><span class="hl-1">;</span><br/><span class="hl-11">import</span><span class="hl-1"> { </span><span class="hl-11">type</span><span class="hl-1"> </span><span class="hl-5">Camera</span><span class="hl-1"> } </span><span class="hl-11">from</span><span class="hl-1"> </span><span class="hl-10">&#39;../../../core/camera&#39;</span><span class="hl-1">;</span><br/><br/><span class="hl-11">export</span><span class="hl-1"> </span><span class="hl-8">class</span><span class="hl-1"> </span><span class="hl-9">GaussianBlurPass</span><span class="hl-1"> </span><span class="hl-8">extends</span><span class="hl-1"> </span><span class="hl-9">FivePass</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-8">constructor</span><span class="hl-1">(</span><span class="hl-5">camera</span><span class="hl-1">: </span><span class="hl-9">Camera</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-8">public</span><span class="hl-1"> </span><span class="hl-4">setRadius</span><span class="hl-1">(</span><span class="hl-5">radius</span><span class="hl-1">: </span><span class="hl-9">number</span><span class="hl-1">): </span><span class="hl-9">void</span><span class="hl-1">;</span><br/><br/><span class="hl-1">  </span><span class="hl-7">// 渲染方法（由 EffectComposer 调用）</span><br/><span class="hl-1">  </span><span class="hl-8">public</span><span class="hl-1"> </span><span class="hl-4">render</span><span class="hl-1">(</span><br/><span class="hl-1">    </span><span class="hl-5">renderer</span><span class="hl-1">: </span><span class="hl-9">THREE</span><span class="hl-1">.</span><span class="hl-9">WebGLRenderer</span><span class="hl-1">,</span><br/><span class="hl-1">    </span><span class="hl-5">writeBuffer</span><span class="hl-1">: </span><span class="hl-9">THREE</span><span class="hl-1">.</span><span class="hl-9">WebGLRenderTarget</span><span class="hl-1">,</span><br/><span class="hl-1">    </span><span class="hl-5">readBuffer</span><span class="hl-1">: </span><span class="hl-9">THREE</span><span class="hl-1">.</span><span class="hl-9">WebGLRenderTarget</span><span class="hl-1">,</span><br/><span class="hl-1">    </span><span class="hl-5">deltaTime</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-5">maskActive</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-9">void</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-8">public</span><span class="hl-1"> </span><span class="hl-4">dispose</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="shader-uniforms-内部-shader-参数" class="tsd-anchor-link">Shader Uniforms (内部 Shader 参数)<a href="#shader-uniforms-内部-shader-参数" 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>
@@ -113,20 +113,20 @@
 <p>释放 Shader Material 和 FullScreenQuad 资源。在销毁 Pass 时必须调用，以防内存泄漏。</p>
 <h2 id="examples" class="tsd-anchor-link">Examples<a href="#examples" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h2>
 <h3 id="快速上手-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>
-<pre><code class="ts"><span class="hl-10">import</span><span class="hl-1"> { </span><span class="hl-6">Five</span><span class="hl-1"> } </span><span class="hl-10">from</span><span class="hl-1"> </span><span class="hl-9">&#39;@realsee/five&#39;</span><span class="hl-1">;</span><br/><span class="hl-10">import</span><span class="hl-1"> { </span><span class="hl-6">GaussianBlurPass</span><span class="hl-1"> } </span><span class="hl-10">from</span><span class="hl-1"> </span><span class="hl-9">&#39;../../lib/five/renderer/postprocessing&#39;</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/><br/><span class="hl-8">// 使用 Five 的 addPass() 方法添加后处理通道</span><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">blurPass</span><span class="hl-1"> = </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-5">GaussianBlurPass</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/><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-5">addPass</span><span class="hl-1">(</span><span class="hl-6">blurPass</span><span class="hl-1">);</span><br/><br/><span class="hl-8">// 动画循环由 Five 内部管理</span><br/><span class="hl-3">function</span><span class="hl-1"> </span><span class="hl-5">animate</span><span class="hl-1">() {</span><br/><span class="hl-1">  </span><span class="hl-5">requestAnimationFrame</span><span class="hl-1">(</span><span class="hl-6">animate</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-5">render</span><span class="hl-1">();</span><br/><span class="hl-1">}</span><br/><span class="hl-5">animate</span><span class="hl-1">();</span>
+<pre><code class="ts"><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/><span class="hl-11">import</span><span class="hl-1"> { </span><span class="hl-5">GaussianBlurPass</span><span class="hl-1"> } </span><span class="hl-11">from</span><span class="hl-1"> </span><span class="hl-10">&#39;../../lib/five/renderer/postprocessing&#39;</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/><br/><span class="hl-7">// 使用 Five 的 addPass() 方法添加后处理通道</span><br/><span class="hl-8">const</span><span class="hl-1"> </span><span class="hl-6">blurPass</span><span class="hl-1"> = </span><span class="hl-8">new</span><span class="hl-1"> </span><span class="hl-4">GaussianBlurPass</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/><span class="hl-5">five</span><span class="hl-1">.</span><span class="hl-4">addPass</span><span class="hl-1">(</span><span class="hl-5">blurPass</span><span class="hl-1">);</span><br/><br/><span class="hl-7">// 动画循环由 Five 内部管理</span><br/><span class="hl-8">function</span><span class="hl-1"> </span><span class="hl-4">animate</span><span class="hl-1">() {</span><br/><span class="hl-1">  </span><span class="hl-4">requestAnimationFrame</span><span class="hl-1">(</span><span class="hl-5">animate</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-4">render</span><span class="hl-1">();</span><br/><span class="hl-1">}</span><br/><span class="hl-4">animate</span><span class="hl-1">();</span>
 </code><button type="button">Copy</button></pre>
 
 <h3 id="进阶用法-advanced-usage" class="tsd-anchor-link">进阶用法 (Advanced Usage)<a href="#进阶用法-advanced-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>
 <h4 id="动态调整模糊强度" class="tsd-anchor-link">动态调整模糊强度<a href="#动态调整模糊强度" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h4>
-<pre><code class="ts"><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">blurPass</span><span class="hl-1"> = </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-5">GaussianBlurPass</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/><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-5">addPass</span><span class="hl-1">(</span><span class="hl-6">blurPass</span><span class="hl-1">);</span><br/><br/><span class="hl-8">// 响应用户输入调整模糊半径</span><br/><span class="hl-6">document</span><span class="hl-1">.</span><span class="hl-5">addEventListener</span><span class="hl-1">(</span><span class="hl-9">&#39;keydown&#39;</span><span class="hl-1">, (</span><span class="hl-6">e</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-10">if</span><span class="hl-1"> (</span><span class="hl-6">e</span><span class="hl-1">.</span><span class="hl-6">key</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-3">const</span><span class="hl-1"> </span><span class="hl-4">current</span><span class="hl-1"> = </span><span class="hl-6">blurPass</span><span class="hl-1">[</span><span class="hl-9">&#39;material&#39;</span><span class="hl-1">].</span><span class="hl-6">uniforms</span><span class="hl-1">.</span><span class="hl-6">radius</span><span class="hl-1">.</span><span class="hl-6">value</span><span class="hl-1">;</span><br/><span class="hl-1">    </span><span class="hl-6">blurPass</span><span class="hl-1">.</span><span class="hl-5">setRadius</span><span class="hl-1">(</span><span class="hl-6">Math</span><span class="hl-1">.</span><span class="hl-5">min</span><span class="hl-1">(</span><span class="hl-11">8</span><span class="hl-1">, </span><span class="hl-6">current</span><span class="hl-1"> + </span><span class="hl-11">0.5</span><span class="hl-1">));</span><br/><span class="hl-1">  }</span><br/><span class="hl-1">  </span><span class="hl-10">if</span><span class="hl-1"> (</span><span class="hl-6">e</span><span class="hl-1">.</span><span class="hl-6">key</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-3">const</span><span class="hl-1"> </span><span class="hl-4">current</span><span class="hl-1"> = </span><span class="hl-6">blurPass</span><span class="hl-1">[</span><span class="hl-9">&#39;material&#39;</span><span class="hl-1">].</span><span class="hl-6">uniforms</span><span class="hl-1">.</span><span class="hl-6">radius</span><span class="hl-1">.</span><span class="hl-6">value</span><span class="hl-1">;</span><br/><span class="hl-1">    </span><span class="hl-6">blurPass</span><span class="hl-1">.</span><span class="hl-5">setRadius</span><span class="hl-1">(</span><span class="hl-6">Math</span><span class="hl-1">.</span><span class="hl-5">max</span><span class="hl-1">(</span><span class="hl-11">0</span><span class="hl-1">, </span><span class="hl-6">current</span><span class="hl-1"> - </span><span class="hl-11">0.5</span><span class="hl-1">));</span><br/><span class="hl-1">  }</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">blurPass</span><span class="hl-1"> = </span><span class="hl-8">new</span><span class="hl-1"> </span><span class="hl-4">GaussianBlurPass</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/><span class="hl-5">five</span><span class="hl-1">.</span><span class="hl-4">addPass</span><span class="hl-1">(</span><span class="hl-5">blurPass</span><span class="hl-1">);</span><br/><br/><span class="hl-7">// 响应用户输入调整模糊半径</span><br/><span class="hl-5">document</span><span class="hl-1">.</span><span class="hl-4">addEventListener</span><span class="hl-1">(</span><span class="hl-10">&#39;keydown&#39;</span><span class="hl-1">, (</span><span class="hl-5">e</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-11">if</span><span class="hl-1"> (</span><span class="hl-5">e</span><span class="hl-1">.</span><span class="hl-5">key</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-8">const</span><span class="hl-1"> </span><span class="hl-6">current</span><span class="hl-1"> = </span><span class="hl-5">blurPass</span><span class="hl-1">[</span><span class="hl-10">&#39;material&#39;</span><span class="hl-1">].</span><span class="hl-5">uniforms</span><span class="hl-1">.</span><span class="hl-5">radius</span><span class="hl-1">.</span><span class="hl-5">value</span><span class="hl-1">;</span><br/><span class="hl-1">    </span><span class="hl-5">blurPass</span><span class="hl-1">.</span><span class="hl-4">setRadius</span><span class="hl-1">(</span><span class="hl-5">Math</span><span class="hl-1">.</span><span class="hl-4">min</span><span class="hl-1">(</span><span class="hl-3">8</span><span class="hl-1">, </span><span class="hl-5">current</span><span class="hl-1"> + </span><span class="hl-3">0.5</span><span class="hl-1">));</span><br/><span class="hl-1">  }</span><br/><span class="hl-1">  </span><span class="hl-11">if</span><span class="hl-1"> (</span><span class="hl-5">e</span><span class="hl-1">.</span><span class="hl-5">key</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-8">const</span><span class="hl-1"> </span><span class="hl-6">current</span><span class="hl-1"> = </span><span class="hl-5">blurPass</span><span class="hl-1">[</span><span class="hl-10">&#39;material&#39;</span><span class="hl-1">].</span><span class="hl-5">uniforms</span><span class="hl-1">.</span><span class="hl-5">radius</span><span class="hl-1">.</span><span class="hl-5">value</span><span class="hl-1">;</span><br/><span class="hl-1">    </span><span class="hl-5">blurPass</span><span class="hl-1">.</span><span class="hl-4">setRadius</span><span class="hl-1">(</span><span class="hl-5">Math</span><span class="hl-1">.</span><span class="hl-4">max</span><span class="hl-1">(</span><span class="hl-3">0</span><span class="hl-1">, </span><span class="hl-5">current</span><span class="hl-1"> - </span><span class="hl-3">0.5</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>
 
 <h4 id="多通道组合（模糊-其他效果）" class="tsd-anchor-link">多通道组合（模糊 + 其他效果）<a href="#多通道组合（模糊-其他效果）" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h4>
-<pre><code class="ts"><span class="hl-8">// Five 的 addPass() 会自动管理后处理链</span><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">blurPass</span><span class="hl-1"> = </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-5">GaussianBlurPass</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/><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-5">addPass</span><span class="hl-1">(</span><span class="hl-6">blurPass</span><span class="hl-1">);</span><br/><br/><span class="hl-8">// 可添加其他后处理通道</span><br/><span class="hl-8">// five.addPass(otherPass);</span>
+<pre><code class="ts"><span class="hl-7">// Five 的 addPass() 会自动管理后处理链</span><br/><span class="hl-8">const</span><span class="hl-1"> </span><span class="hl-6">blurPass</span><span class="hl-1"> = </span><span class="hl-8">new</span><span class="hl-1"> </span><span class="hl-4">GaussianBlurPass</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/><span class="hl-5">five</span><span class="hl-1">.</span><span class="hl-4">addPass</span><span class="hl-1">(</span><span class="hl-5">blurPass</span><span class="hl-1">);</span><br/><br/><span class="hl-7">// 可添加其他后处理通道</span><br/><span class="hl-7">// five.addPass(otherPass);</span>
 </code><button type="button">Copy</button></pre>
 
 <h4 id="修改高斯标准差-advanced" class="tsd-anchor-link">修改高斯标准差 (Advanced)<a href="#修改高斯标准差-advanced" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h4>
-<pre><code class="ts"><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">blurPass</span><span class="hl-1"> = </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-5">GaussianBlurPass</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/><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-5">addPass</span><span class="hl-1">(</span><span class="hl-6">blurPass</span><span class="hl-1">);</span><br/><br/><span class="hl-8">// 获取 Material 并直接修改 sigma</span><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">sigmaMaterial</span><span class="hl-1"> = </span><span class="hl-6">blurPass</span><span class="hl-1">[</span><span class="hl-9">&#39;material&#39;</span><span class="hl-1">] </span><span class="hl-10">as</span><span class="hl-1"> </span><span class="hl-7">THREE</span><span class="hl-1">.</span><span class="hl-7">ShaderMaterial</span><span class="hl-1">;</span><br/><span class="hl-6">sigmaMaterial</span><span class="hl-1">.</span><span class="hl-6">uniforms</span><span class="hl-1">.</span><span class="hl-6">sigma</span><span class="hl-1">.</span><span class="hl-6">value</span><span class="hl-1"> = </span><span class="hl-11">2.0</span><span class="hl-1">;  </span><span class="hl-8">// 调整标准差（更强锐利）</span>
+<pre><code class="ts"><span class="hl-8">const</span><span class="hl-1"> </span><span class="hl-6">blurPass</span><span class="hl-1"> = </span><span class="hl-8">new</span><span class="hl-1"> </span><span class="hl-4">GaussianBlurPass</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/><span class="hl-5">five</span><span class="hl-1">.</span><span class="hl-4">addPass</span><span class="hl-1">(</span><span class="hl-5">blurPass</span><span class="hl-1">);</span><br/><br/><span class="hl-7">// 获取 Material 并直接修改 sigma</span><br/><span class="hl-8">const</span><span class="hl-1"> </span><span class="hl-6">sigmaMaterial</span><span class="hl-1"> = </span><span class="hl-5">blurPass</span><span class="hl-1">[</span><span class="hl-10">&#39;material&#39;</span><span class="hl-1">] </span><span class="hl-11">as</span><span class="hl-1"> </span><span class="hl-9">THREE</span><span class="hl-1">.</span><span class="hl-9">ShaderMaterial</span><span class="hl-1">;</span><br/><span class="hl-5">sigmaMaterial</span><span class="hl-1">.</span><span class="hl-5">uniforms</span><span class="hl-1">.</span><span class="hl-5">sigma</span><span class="hl-1">.</span><span class="hl-5">value</span><span class="hl-1"> = </span><span class="hl-3">2.0</span><span class="hl-1">;  </span><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>
@@ -141,7 +141,7 @@
 <li>考虑在低端设备上禁用该通道（设置 <code>blurPass.enabled = false</code>）。</li>
 </ul>
 <h3 id="可视化调试" class="tsd-anchor-link">可视化调试<a href="#可视化调试" 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="ts"><span class="hl-8">// 监控当前模糊参数</span><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">blurPass</span><span class="hl-1"> = </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-5">GaussianBlurPass</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/><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">&#39;Blur Radius:&#39;</span><span class="hl-1">, </span><span class="hl-6">blurPass</span><span class="hl-1">[</span><span class="hl-9">&#39;material&#39;</span><span class="hl-1">].</span><span class="hl-6">uniforms</span><span class="hl-1">.</span><span class="hl-6">radius</span><span class="hl-1">.</span><span class="hl-6">value</span><span class="hl-1">);</span><br/><span class="hl-6">console</span><span class="hl-1">.</span><span class="hl-5">log</span><span class="hl-1">(</span><span class="hl-9">&#39;Blur Sigma:&#39;</span><span class="hl-1">, </span><span class="hl-6">blurPass</span><span class="hl-1">[</span><span class="hl-9">&#39;material&#39;</span><span class="hl-1">].</span><span class="hl-6">uniforms</span><span class="hl-1">.</span><span class="hl-6">sigma</span><span class="hl-1">.</span><span class="hl-6">value</span><span class="hl-1">);</span><br/><span class="hl-6">console</span><span class="hl-1">.</span><span class="hl-5">log</span><span class="hl-1">(</span><span class="hl-9">&#39;Resolution:&#39;</span><span class="hl-1">, </span><span class="hl-6">blurPass</span><span class="hl-1">[</span><span class="hl-9">&#39;material&#39;</span><span class="hl-1">].</span><span class="hl-6">uniforms</span><span class="hl-1">.</span><span class="hl-6">resolution</span><span class="hl-1">.</span><span class="hl-6">value</span><span class="hl-1">);</span>
+<pre><code class="ts"><span class="hl-7">// 监控当前模糊参数</span><br/><span class="hl-8">const</span><span class="hl-1"> </span><span class="hl-6">blurPass</span><span class="hl-1"> = </span><span class="hl-8">new</span><span class="hl-1"> </span><span class="hl-4">GaussianBlurPass</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/><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">&#39;Blur Radius:&#39;</span><span class="hl-1">, </span><span class="hl-5">blurPass</span><span class="hl-1">[</span><span class="hl-10">&#39;material&#39;</span><span class="hl-1">].</span><span class="hl-5">uniforms</span><span class="hl-1">.</span><span class="hl-5">radius</span><span class="hl-1">.</span><span class="hl-5">value</span><span class="hl-1">);</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">&#39;Blur Sigma:&#39;</span><span class="hl-1">, </span><span class="hl-5">blurPass</span><span class="hl-1">[</span><span class="hl-10">&#39;material&#39;</span><span class="hl-1">].</span><span class="hl-5">uniforms</span><span class="hl-1">.</span><span class="hl-5">sigma</span><span class="hl-1">.</span><span class="hl-5">value</span><span class="hl-1">);</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">&#39;Resolution:&#39;</span><span class="hl-1">, </span><span class="hl-5">blurPass</span><span class="hl-1">[</span><span class="hl-10">&#39;material&#39;</span><span class="hl-1">].</span><span class="hl-5">uniforms</span><span class="hl-1">.</span><span class="hl-5">resolution</span><span class="hl-1">.</span><span class="hl-5">value</span><span class="hl-1">);</span>
 </code><button type="button">Copy</button></pre>
 
 <h2 id="common-pitfalls" class="tsd-anchor-link">Common Pitfalls<a href="#common-pitfalls" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h2>

package/docs/documents/features_gesture.html

@@ -10,7 +10,7 @@
 <p><strong>Definition</strong>: <a href="../../five/utils/event.d.ts">GestureEvent</a></p>
 </blockquote>
 <p>所有手势事件的回调参数均为 <code>GestureEvent</code> 类型：</p>
-<pre><code class="typescript"><span class="hl-10">import</span><span class="hl-1"> { </span><span class="hl-6">State</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">interface</span><span class="hl-1"> </span><span class="hl-7">GestureEvent</span><span class="hl-1"> {</span><br/><span class="hl-1">  </span><span class="hl-6">type</span><span class="hl-1">: </span><span class="hl-7">string</span><span class="hl-1">;             </span><span class="hl-8">// 事件类型，如 &quot;gesture.tap&quot;</span><br/><span class="hl-1">  </span><span class="hl-6">timeStamp</span><span class="hl-1">: </span><span class="hl-7">number</span><span class="hl-1">;        </span><span class="hl-8">// 时间戳</span><br/><span class="hl-1">  </span><span class="hl-6">target</span><span class="hl-1">: </span><span class="hl-7">EventTarget</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-6">pointerType</span><span class="hl-1">: </span><span class="hl-9">&#39;touch&#39;</span><span class="hl-1"> | </span><span class="hl-9">&#39;pen&#39;</span><span class="hl-1"> | </span><span class="hl-9">&#39;mouse&#39;</span><span class="hl-1"> | </span><span class="hl-9">&#39;kinect&#39;</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">center</span><span class="hl-1">: {</span><br/><span class="hl-1">    </span><span class="hl-6">x</span><span class="hl-1">: </span><span class="hl-7">number</span><span class="hl-1">;              </span><span class="hl-8">// 屏幕 X 坐标</span><br/><span class="hl-1">    </span><span class="hl-6">y</span><span class="hl-1">: </span><span class="hl-7">number</span><span class="hl-1">;              </span><span class="hl-8">// 屏幕 Y 坐标</span><br/><span class="hl-1">    </span><span class="hl-6">raycaster</span><span class="hl-1">: </span><span class="hl-7">THREE</span><span class="hl-1">.</span><span class="hl-7">Raycaster</span><span class="hl-1">; </span><span class="hl-8">// 从相机发出的射线（已包含坐标变换）</span><br/><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">state</span><span class="hl-1">: </span><span class="hl-7">State</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">userAction</span><span class="hl-1">: </span><span class="hl-7">boolean</span><span class="hl-1">;</span><br/><br/><span class="hl-1">  </span><span class="hl-8">// 阻止默认行为</span><br/><span class="hl-1">  </span><span class="hl-5">preventDefault</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-6">defaultPrevented</span><span class="hl-1">: </span><span class="hl-7">boolean</span><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">State</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">interface</span><span class="hl-1"> </span><span class="hl-9">GestureEvent</span><span class="hl-1"> {</span><br/><span class="hl-1">  </span><span class="hl-5">type</span><span class="hl-1">: </span><span class="hl-9">string</span><span class="hl-1">;             </span><span class="hl-7">// 事件类型，如 &quot;gesture.tap&quot;</span><br/><span class="hl-1">  </span><span class="hl-5">timeStamp</span><span class="hl-1">: </span><span class="hl-9">number</span><span class="hl-1">;        </span><span class="hl-7">// 时间戳</span><br/><span class="hl-1">  </span><span class="hl-5">target</span><span class="hl-1">: </span><span class="hl-9">EventTarget</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-5">pointerType</span><span class="hl-1">: </span><span class="hl-10">&#39;touch&#39;</span><span class="hl-1"> | </span><span class="hl-10">&#39;pen&#39;</span><span class="hl-1"> | </span><span class="hl-10">&#39;mouse&#39;</span><span class="hl-1"> | </span><span class="hl-10">&#39;kinect&#39;</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">center</span><span class="hl-1">: {</span><br/><span class="hl-1">    </span><span class="hl-5">x</span><span class="hl-1">: </span><span class="hl-9">number</span><span class="hl-1">;              </span><span class="hl-7">// 屏幕 X 坐标</span><br/><span class="hl-1">    </span><span class="hl-5">y</span><span class="hl-1">: </span><span class="hl-9">number</span><span class="hl-1">;              </span><span class="hl-7">// 屏幕 Y 坐标</span><br/><span class="hl-1">    </span><span class="hl-5">raycaster</span><span class="hl-1">: </span><span class="hl-9">THREE</span><span class="hl-1">.</span><span class="hl-9">Raycaster</span><span class="hl-1">; </span><span class="hl-7">// 从相机发出的射线（已包含坐标变换）</span><br/><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">state</span><span class="hl-1">: </span><span class="hl-9">State</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">userAction</span><span class="hl-1">: </span><span class="hl-9">boolean</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-4">preventDefault</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-5">defaultPrevented</span><span class="hl-1">: </span><span class="hl-9">boolean</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>
@@ -79,25 +79,25 @@
 <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>监听点击事件并打印日志：</p>
-<pre><code class="typescript"><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;gesture.tap&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-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><span class="hl-6">event</span><span class="hl-1">.</span><span class="hl-6">center</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">center</span><span class="hl-1">.</span><span class="hl-6">y</span><span class="hl-1">);</span><br/><span class="hl-1">  </span><span class="hl-8">// event.center.raycaster 可以用来做射线检测</span><br/><span class="hl-1">});</span>
+<pre><code class="typescript"><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;gesture.tap&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-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><span class="hl-5">event</span><span class="hl-1">.</span><span class="hl-5">center</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">center</span><span class="hl-1">.</span><span class="hl-5">y</span><span class="hl-1">);</span><br/><span class="hl-1">  </span><span class="hl-7">// event.center.raycaster 可以用来做射线检测</span><br/><span class="hl-1">});</span>
 </code><button type="button">Copy</button></pre>
 
 <h3 id="场景交互：点击添加标签球-add-label-on-click" class="tsd-anchor-link">场景交互：点击添加标签球 (Add Label on Click)<a href="#场景交互：点击添加标签球-add-label-on-click" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3>
 <p>这个示例展示了如何通过点击事件在场景中添加一个红色的球体，并阻止 Five 默认的点位移动行为。</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">&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">Five</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">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/><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;gesture.tap&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-8">// 1. 阻止默认行为（防止点击地面时 Five 自动走点或切换模式）</span><br/><span class="hl-1">  </span><span class="hl-6">event</span><span class="hl-1">.</span><span class="hl-5">preventDefault</span><span class="hl-1">();</span><br/><br/><span class="hl-1">  </span><span class="hl-8">// 2. 获取射线</span><br/><span class="hl-1">  </span><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">raycaster</span><span class="hl-1"> = </span><span class="hl-6">event</span><span class="hl-1">.</span><span class="hl-6">center</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-8">// 3. 检测与模型的碰撞</span><br/><span class="hl-1">  </span><span class="hl-8">// five.model.intersectRaycaster 是 Five 提供的便捷方法，会自动检测所有可见模型</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-3">const</span><span class="hl-1"> </span><span class="hl-4">intersect</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><br/><span class="hl-1">    </span><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">point</span><span class="hl-1"> = </span><span class="hl-6">intersect</span><span class="hl-1">.</span><span class="hl-6">point</span><span class="hl-1">; </span><span class="hl-8">// 碰撞点世界坐标</span><br/><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><span class="hl-6">point</span><span class="hl-1">);</span><br/><br/><span class="hl-1">    </span><span class="hl-8">// 4. 创建一个小球</span><br/><span class="hl-1">    </span><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">geometry</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">SphereGeometry</span><span class="hl-1">(</span><span class="hl-11">0.1</span><span class="hl-1">, </span><span class="hl-11">32</span><span class="hl-1">, </span><span class="hl-11">32</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">material</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">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><br/><span class="hl-1">    </span><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">sphere</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><span class="hl-6">geometry</span><span class="hl-1">, </span><span class="hl-6">material</span><span class="hl-1">);</span><br/><br/><span class="hl-1">    </span><span class="hl-8">// 5. 设置位置并添加到场景</span><br/><span class="hl-1">    </span><span class="hl-6">sphere</span><span class="hl-1">.</span><span class="hl-6">position</span><span class="hl-1">.</span><span class="hl-5">copy</span><span class="hl-1">(</span><span class="hl-6">point</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">scene</span><span class="hl-1">.</span><span class="hl-5">add</span><span class="hl-1">(</span><span class="hl-6">sphere</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">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><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">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-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">Five</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">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/><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;gesture.tap&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-7">// 1. 阻止默认行为（防止点击地面时 Five 自动走点或切换模式）</span><br/><span class="hl-1">  </span><span class="hl-5">event</span><span class="hl-1">.</span><span class="hl-4">preventDefault</span><span class="hl-1">();</span><br/><br/><span class="hl-1">  </span><span class="hl-7">// 2. 获取射线</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-5">event</span><span class="hl-1">.</span><span class="hl-5">center</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-7">// 3. 检测与模型的碰撞</span><br/><span class="hl-1">  </span><span class="hl-7">// five.model.intersectRaycaster 是 Five 提供的便捷方法，会自动检测所有可见模型</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-8">const</span><span class="hl-1"> </span><span class="hl-6">intersect</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><br/><span class="hl-1">    </span><span class="hl-8">const</span><span class="hl-1"> </span><span class="hl-6">point</span><span class="hl-1"> = </span><span class="hl-5">intersect</span><span class="hl-1">.</span><span class="hl-5">point</span><span class="hl-1">; </span><span class="hl-7">// 碰撞点世界坐标</span><br/><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><span class="hl-5">point</span><span class="hl-1">);</span><br/><br/><span class="hl-1">    </span><span class="hl-7">// 4. 创建一个小球</span><br/><span class="hl-1">    </span><span class="hl-8">const</span><span class="hl-1"> </span><span class="hl-6">geometry</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">SphereGeometry</span><span class="hl-1">(</span><span class="hl-3">0.1</span><span class="hl-1">, </span><span class="hl-3">32</span><span class="hl-1">, </span><span class="hl-3">32</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">material</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">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><br/><span class="hl-1">    </span><span class="hl-8">const</span><span class="hl-1"> </span><span class="hl-6">sphere</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><span class="hl-5">geometry</span><span class="hl-1">, </span><span class="hl-5">material</span><span class="hl-1">);</span><br/><br/><span class="hl-1">    </span><span class="hl-7">// 5. 设置位置并添加到场景</span><br/><span class="hl-1">    </span><span class="hl-5">sphere</span><span class="hl-1">.</span><span class="hl-5">position</span><span class="hl-1">.</span><span class="hl-4">copy</span><span class="hl-1">(</span><span class="hl-5">point</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">scene</span><span class="hl-1">.</span><span class="hl-4">add</span><span class="hl-1">(</span><span class="hl-5">sphere</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">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><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">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="进阶用法：自定义双指缩放范围" class="tsd-anchor-link">进阶用法：自定义双指缩放范围<a href="#进阶用法：自定义双指缩放范围" 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-6">five</span><span class="hl-1">.</span><span class="hl-5">on</span><span class="hl-1">(</span><span class="hl-9">&quot;gesture.pinch&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-8">// 获取当前 FOV</span><br/><span class="hl-1">  </span><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">currentFov</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">fov</span><span class="hl-1">;</span><br/><br/><span class="hl-1">  </span><span class="hl-8">// 假设我们限制 FOV 在 80 到 100 之间</span><br/><span class="hl-1">  </span><span class="hl-8">// 注意：这只是逻辑演示，Five 内部有自己的 minFov/maxFov 配置，</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">currentFov</span><span class="hl-1"> &lt; </span><span class="hl-11">80</span><span class="hl-1"> || </span><span class="hl-6">currentFov</span><span class="hl-1"> &gt; </span><span class="hl-11">100</span><span class="hl-1">) {</span><br/><span class="hl-1">    </span><span class="hl-8">// 阻止 Five 的默认缩放</span><br/><span class="hl-1">    </span><span class="hl-6">event</span><span class="hl-1">.</span><span class="hl-5">preventDefault</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-5">five</span><span class="hl-1">.</span><span class="hl-4">on</span><span class="hl-1">(</span><span class="hl-10">&quot;gesture.pinch&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-7">// 获取当前 FOV</span><br/><span class="hl-1">  </span><span class="hl-8">const</span><span class="hl-1"> </span><span class="hl-6">currentFov</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">fov</span><span class="hl-1">;</span><br/><br/><span class="hl-1">  </span><span class="hl-7">// 假设我们限制 FOV 在 80 到 100 之间</span><br/><span class="hl-1">  </span><span class="hl-7">// 注意：这只是逻辑演示，Five 内部有自己的 minFov/maxFov 配置，</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">currentFov</span><span class="hl-1"> &lt; </span><span class="hl-3">80</span><span class="hl-1"> || </span><span class="hl-5">currentFov</span><span class="hl-1"> &gt; </span><span class="hl-3">100</span><span class="hl-1">) {</span><br/><span class="hl-1">    </span><span class="hl-7">// 阻止 Five 的默认缩放</span><br/><span class="hl-1">    </span><span class="hl-5">event</span><span class="hl-1">.</span><span class="hl-4">preventDefault</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>
 
 <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>
 <ul>
-<li><strong>查看事件触发</strong>: 在控制台监听所有手势。<pre><code class="typescript"><span class="hl-1">[</span><span class="hl-9">&quot;pan&quot;</span><span class="hl-1">, </span><span class="hl-9">&quot;tap&quot;</span><span class="hl-1">, </span><span class="hl-9">&quot;pinch&quot;</span><span class="hl-1">, </span><span class="hl-9">&quot;press&quot;</span><span class="hl-1">].</span><span class="hl-5">forEach</span><span class="hl-1">(</span><span class="hl-6">type</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">five</span><span class="hl-1">.</span><span class="hl-5">on</span><span class="hl-1">(</span><span class="hl-9">`gesture.</span><span class="hl-3">${</span><span class="hl-6">type</span><span class="hl-3">}</span><span class="hl-9">`</span><span class="hl-1"> </span><span class="hl-10">as</span><span class="hl-1"> </span><span class="hl-7">any</span><span class="hl-1">, (</span><span class="hl-6">e</span><span class="hl-1">) </span><span class="hl-3">=&gt;</span><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-6">type</span><span class="hl-1">, </span><span class="hl-6">e</span><span class="hl-1">));</span><br/><span class="hl-1">});</span>
+<li><strong>查看事件触发</strong>: 在控制台监听所有手势。<pre><code class="typescript"><span class="hl-1">[</span><span class="hl-10">&quot;pan&quot;</span><span class="hl-1">, </span><span class="hl-10">&quot;tap&quot;</span><span class="hl-1">, </span><span class="hl-10">&quot;pinch&quot;</span><span class="hl-1">, </span><span class="hl-10">&quot;press&quot;</span><span class="hl-1">].</span><span class="hl-4">forEach</span><span class="hl-1">(</span><span class="hl-5">type</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">five</span><span class="hl-1">.</span><span class="hl-4">on</span><span class="hl-1">(</span><span class="hl-10">`gesture.</span><span class="hl-8">${</span><span class="hl-5">type</span><span class="hl-8">}</span><span class="hl-10">`</span><span class="hl-1"> </span><span class="hl-11">as</span><span class="hl-1"> </span><span class="hl-9">any</span><span class="hl-1">, (</span><span class="hl-5">e</span><span class="hl-1">) </span><span class="hl-8">=&gt;</span><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-5">type</span><span class="hl-1">, </span><span class="hl-5">e</span><span class="hl-1">));</span><br/><span class="hl-1">});</span>
 </code><button type="button">Copy</button></pre>
 
 </li>
-<li><strong>Helper Line</strong>: 如果射线检测不准，可以画出射线辅助线。<pre><code class="typescript"><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-3">new</span><span class="hl-1"> </span><span class="hl-4">THREE</span><span class="hl-1">.</span><span class="hl-5">ArrowHelper</span><span class="hl-1">(</span><span class="hl-6">raycaster</span><span class="hl-1">.</span><span class="hl-6">ray</span><span class="hl-1">.</span><span class="hl-6">direction</span><span class="hl-1">, </span><span class="hl-6">raycaster</span><span class="hl-1">.</span><span class="hl-6">ray</span><span class="hl-1">.</span><span class="hl-6">origin</span><span class="hl-1">, </span><span class="hl-11">10</span><span class="hl-1">, </span><span class="hl-11">0xff0000</span><span class="hl-1">));</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>
+<li><strong>Helper Line</strong>: 如果射线检测不准，可以画出射线辅助线。<pre><code class="typescript"><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-8">new</span><span class="hl-1"> </span><span class="hl-6">THREE</span><span class="hl-1">.</span><span class="hl-4">ArrowHelper</span><span class="hl-1">(</span><span class="hl-5">raycaster</span><span class="hl-1">.</span><span class="hl-5">ray</span><span class="hl-1">.</span><span class="hl-5">direction</span><span class="hl-1">, </span><span class="hl-5">raycaster</span><span class="hl-1">.</span><span class="hl-5">ray</span><span class="hl-1">.</span><span class="hl-5">origin</span><span class="hl-1">, </span><span class="hl-3">10</span><span class="hl-1">, </span><span class="hl-3">0xff0000</span><span class="hl-1">));</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>
 
 </li>

package/docs/documents/features_get-screen-pixels.html

@@ -11,11 +11,11 @@
 </blockquote>
 <p><code>five.getPixels</code> 支持两种调用方式：参数列表（旧版）和对象参数（推荐）。</p>
 <h3 id="推荐调用方式" class="tsd-anchor-link">推荐调用方式<a href="#推荐调用方式" 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-6">five</span><span class="hl-1">.</span><span class="hl-5">getPixels</span><span class="hl-1">(</span><span class="hl-6">options</span><span class="hl-1">: </span><span class="hl-6">GetPixelsOptions</span><span class="hl-1">): </span><span class="hl-6">Uint8Array</span><span class="hl-1"> | </span><span class="hl-6">Uint8ClampedArray</span><span class="hl-1">;</span><br/><br/><span class="hl-3">interface</span><span class="hl-1"> </span><span class="hl-7">GetPixelsOptions</span><span class="hl-1"> {</span><br/><span class="hl-1">  </span><span class="hl-8">/** 获取像素区域的起始坐标 x (基于 Canvas 左下角，除非 flipY 为 true) */</span><br/><span class="hl-1">  </span><span class="hl-6">x</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">/** 获取像素区域的起始坐标 y */</span><br/><span class="hl-1">  </span><span class="hl-6">y</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">width</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">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">/** 获取区域的像素比 (默认 1) */</span><br/><span class="hl-1">  </span><span class="hl-6">pixelRatio</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">/** 是否显示辅助元素 (默认 false) */</span><br/><span class="hl-1">  </span><span class="hl-6">helperVisible</span><span class="hl-1">?: </span><span class="hl-7">boolean</span><span class="hl-1">;</span><br/><span class="hl-1">  </span><span class="hl-8">/** 是否跳过全景图渲染 (仅渲染模型) */</span><br/><span class="hl-1">  </span><span class="hl-6">skipPanorama</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">/** 是否 Y 轴翻转 (通常设为 true 以匹配 Canvas 2D 坐标系) */</span><br/><span class="hl-1">  </span><span class="hl-6">flipY</span><span class="hl-1">?: </span><span class="hl-7">boolean</span><span class="hl-1">;</span><br/><span class="hl-1">  </span><span class="hl-8">/** 存储数组 (可选，复用数组以提升性能) */</span><br/><span class="hl-1">  </span><span class="hl-6">buffer</span><span class="hl-1">?: </span><span class="hl-7">Uint8Array</span><span class="hl-1"> | </span><span class="hl-7">Uint8ClampedArray</span><span class="hl-1">;</span><br/><span class="hl-1">}</span>
+<pre><code class="typescript"><span class="hl-5">five</span><span class="hl-1">.</span><span class="hl-4">getPixels</span><span class="hl-1">(</span><span class="hl-5">options</span><span class="hl-1">: </span><span class="hl-5">GetPixelsOptions</span><span class="hl-1">): </span><span class="hl-5">Uint8Array</span><span class="hl-1"> | </span><span class="hl-5">Uint8ClampedArray</span><span class="hl-1">;</span><br/><br/><span class="hl-8">interface</span><span class="hl-1"> </span><span class="hl-9">GetPixelsOptions</span><span class="hl-1"> {</span><br/><span class="hl-1">  </span><span class="hl-7">/** 获取像素区域的起始坐标 x (基于 Canvas 左下角，除非 flipY 为 true) */</span><br/><span class="hl-1">  </span><span class="hl-5">x</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">/** 获取像素区域的起始坐标 y */</span><br/><span class="hl-1">  </span><span class="hl-5">y</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">width</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">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">/** 获取区域的像素比 (默认 1) */</span><br/><span class="hl-1">  </span><span class="hl-5">pixelRatio</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">/** 是否显示辅助元素 (默认 false) */</span><br/><span class="hl-1">  </span><span class="hl-5">helperVisible</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">/** 是否跳过全景图渲染 (仅渲染模型) */</span><br/><span class="hl-1">  </span><span class="hl-5">skipPanorama</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">/** 是否 Y 轴翻转 (通常设为 true 以匹配 Canvas 2D 坐标系) */</span><br/><span class="hl-1">  </span><span class="hl-5">flipY</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">/** 存储数组 (可选，复用数组以提升性能) */</span><br/><span class="hl-1">  </span><span class="hl-5">buffer</span><span class="hl-1">?: </span><span class="hl-9">Uint8Array</span><span class="hl-1"> | </span><span class="hl-9">Uint8ClampedArray</span><span class="hl-1">;</span><br/><span class="hl-1">}</span>
 </code><button type="button">Copy</button></pre>
 
 <h3 id="简写调用方式-不推荐" class="tsd-anchor-link">简写调用方式 (不推荐)<a href="#简写调用方式-不推荐" 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-6">five</span><span class="hl-1">.</span><span class="hl-5">getPixels</span><span class="hl-1">(</span><br/><span class="hl-1">  </span><span class="hl-6">x</span><span class="hl-1">: </span><span class="hl-6">number</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-6">y</span><span class="hl-1">: </span><span class="hl-6">number</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-6">width</span><span class="hl-1">: </span><span class="hl-6">number</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-6">height</span><span class="hl-1">: </span><span class="hl-6">number</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-6">pixelRatio</span><span class="hl-1">?: </span><span class="hl-6">number</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-6">flipY</span><span class="hl-1">?: </span><span class="hl-6">boolean</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-6">buffer</span><span class="hl-1">?: </span><span class="hl-6">Uint8Array</span><span class="hl-1"> | </span><span class="hl-6">Uint8ClampedArray</span><br/><span class="hl-1">): </span><span class="hl-6">Uint8Array</span><span class="hl-1"> | </span><span class="hl-6">Uint8ClampedArray</span><span class="hl-1">;</span>
+<pre><code class="typescript"><span class="hl-5">five</span><span class="hl-1">.</span><span class="hl-4">getPixels</span><span class="hl-1">(</span><br/><span class="hl-1">  </span><span class="hl-5">x</span><span class="hl-1">: </span><span class="hl-5">number</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-5">y</span><span class="hl-1">: </span><span class="hl-5">number</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-5">width</span><span class="hl-1">: </span><span class="hl-5">number</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-5">height</span><span class="hl-1">: </span><span class="hl-5">number</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-5">pixelRatio</span><span class="hl-1">?: </span><span class="hl-5">number</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-5">flipY</span><span class="hl-1">?: </span><span class="hl-5">boolean</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-5">buffer</span><span class="hl-1">?: </span><span class="hl-5">Uint8Array</span><span class="hl-1"> | </span><span class="hl-5">Uint8ClampedArray</span><br/><span class="hl-1">): </span><span class="hl-5">Uint8Array</span><span class="hl-1"> | </span><span class="hl-5">Uint8ClampedArray</span><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>
@@ -39,12 +39,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="放大镜-magnifier" class="tsd-anchor-link">放大镜 (Magnifier)<a href="#放大镜-magnifier" 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>pixelRatio</code> 重新渲染，从而获得清晰的放大效果。</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">// 假设有一个用于显示的 canvas</span><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">magnifierCanvas</span><span class="hl-1"> = </span><span class="hl-6">document</span><span class="hl-1">.</span><span class="hl-5">getElementById</span><span class="hl-1">(</span><span class="hl-9">&#39;magnifier-canvas&#39;</span><span class="hl-1">) </span><span class="hl-10">as</span><span class="hl-1"> </span><span class="hl-7">HTMLCanvasElement</span><span class="hl-1">;</span><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">ctx</span><span class="hl-1"> = </span><span class="hl-6">magnifierCanvas</span><span class="hl-1">.</span><span class="hl-5">getContext</span><span class="hl-1">(</span><span class="hl-9">&#39;2d&#39;</span><span class="hl-1">)!;</span><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">magnifierSize</span><span class="hl-1"> = </span><span class="hl-11">200</span><span class="hl-1">; </span><span class="hl-8">// 放大镜尺寸 200px</span><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">scale</span><span class="hl-1"> = </span><span class="hl-11">2</span><span class="hl-1">; </span><span class="hl-8">// 放大倍数</span><br/><br/><span class="hl-8">// 预先创建 Buffer 以提升性能</span><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">pixelWidth</span><span class="hl-1"> = </span><span class="hl-6">magnifierSize</span><span class="hl-1"> * </span><span class="hl-6">scale</span><span class="hl-1">;</span><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">pixelHeight</span><span class="hl-1"> = </span><span class="hl-6">magnifierSize</span><span class="hl-1"> * </span><span class="hl-6">scale</span><span class="hl-1">;</span><br/><span class="hl-3">let</span><span class="hl-1"> </span><span class="hl-6">magnifierImageData</span><span class="hl-1"> = </span><span class="hl-6">ctx</span><span class="hl-1">.</span><span class="hl-5">createImageData</span><span class="hl-1">(</span><span class="hl-6">pixelWidth</span><span class="hl-1">, </span><span class="hl-6">pixelHeight</span><span class="hl-1">);</span><br/><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">&#39;gesture.mousemove&#39;</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-8">// 1. 获取鼠标在 Canvas 上的坐标</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-6">event</span><span class="hl-1">.</span><span class="hl-6">pointers</span><span class="hl-1">[</span><span class="hl-11">0</span><span class="hl-1">]?.</span><span class="hl-6">coords</span><span class="hl-1">;</span><br/><span class="hl-1">  </span><span class="hl-10">if</span><span class="hl-1"> (!</span><span class="hl-6">mouse</span><span class="hl-1">) </span><span class="hl-10">return</span><span class="hl-1">;</span><br/><br/><span class="hl-1">  </span><span class="hl-8">// 转换归一化坐标 (-1 到 1) 到 像素坐标</span><br/><span class="hl-1">  </span><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">renderSize</span><span class="hl-1"> = </span><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-5">getSize</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/><span class="hl-1">  </span><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">x</span><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-11">1</span><span class="hl-1">) / </span><span class="hl-11">2</span><span class="hl-1"> * </span><span class="hl-6">renderSize</span><span class="hl-1">.</span><span class="hl-6">x</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">y</span><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-11">1</span><span class="hl-1">) / </span><span class="hl-11">2</span><span class="hl-1"> * </span><span class="hl-6">renderSize</span><span class="hl-1">.</span><span class="hl-6">y</span><span class="hl-1">;</span><br/><br/><span class="hl-1">  </span><span class="hl-8">// 2. 获取像素数据</span><br/><span class="hl-1">  </span><span class="hl-8">// 注意：我们以更高的分辨率 (pixelRatio * scale) 渲染小区域，从而获得“无损”放大效果</span><br/><span class="hl-1">  </span><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">pixelRatio</span><span class="hl-1"> = </span><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-6">renderer</span><span class="hl-1">?.</span><span class="hl-5">getPixelRatio</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">const</span><span class="hl-1"> </span><span class="hl-4">targetPixelRatio</span><span class="hl-1"> = </span><span class="hl-6">Math</span><span class="hl-1">.</span><span class="hl-5">ceil</span><span class="hl-1">(</span><span class="hl-6">pixelRatio</span><span class="hl-1"> * </span><span class="hl-6">scale</span><span class="hl-1">);</span><br/><br/><span class="hl-1">  </span><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-5">getPixels</span><span class="hl-1">({</span><br/><span class="hl-1">    </span><span class="hl-6">x:</span><span class="hl-1"> </span><span class="hl-6">x</span><span class="hl-1"> - </span><span class="hl-6">magnifierSize</span><span class="hl-1"> / </span><span class="hl-11">2</span><span class="hl-1">, </span><span class="hl-8">// 居中</span><br/><span class="hl-1">    </span><span class="hl-6">y:</span><span class="hl-1"> </span><span class="hl-6">y</span><span class="hl-1"> - </span><span class="hl-6">magnifierSize</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">width:</span><span class="hl-1"> </span><span class="hl-6">magnifierSize</span><span class="hl-1">,</span><br/><span class="hl-1">    </span><span class="hl-6">height:</span><span class="hl-1"> </span><span class="hl-6">magnifierSize</span><span class="hl-1">,</span><br/><span class="hl-1">    </span><span class="hl-6">pixelRatio:</span><span class="hl-1"> </span><span class="hl-6">targetPixelRatio</span><span class="hl-1">,</span><br/><span class="hl-1">    </span><span class="hl-6">flipY:</span><span class="hl-1"> </span><span class="hl-3">true</span><span class="hl-1">, </span><span class="hl-8">// 翻转以适配 Canvas 2D</span><br/><span class="hl-1">    </span><span class="hl-6">buffer:</span><span class="hl-1"> </span><span class="hl-6">magnifierImageData</span><span class="hl-1">.</span><span class="hl-6">data</span><span class="hl-1">, </span><span class="hl-8">// 复用 buffer</span><br/><span class="hl-1">    </span><span class="hl-6">helperVisible:</span><span class="hl-1"> </span><span class="hl-3">false</span><span class="hl-1">, </span><span class="hl-8">// 隐藏辅助线等干扰元素</span><br/><span class="hl-1">  });</span><br/><br/><span class="hl-1">  </span><span class="hl-8">// 3. 将数据绘制到放大镜 Canvas 上</span><br/><span class="hl-1">  </span><span class="hl-8">// 需要调整 Canvas 尺寸以匹配数据</span><br/><span class="hl-1">  </span><span class="hl-6">magnifierCanvas</span><span class="hl-1">.</span><span class="hl-6">width</span><span class="hl-1"> = </span><span class="hl-6">pixelWidth</span><span class="hl-1">;</span><br/><span class="hl-1">  </span><span class="hl-6">magnifierCanvas</span><span class="hl-1">.</span><span class="hl-6">height</span><span class="hl-1"> = </span><span class="hl-6">pixelHeight</span><span class="hl-1">;</span><br/><span class="hl-1">  </span><span class="hl-6">ctx</span><span class="hl-1">.</span><span class="hl-5">putImageData</span><span class="hl-1">(</span><span class="hl-6">magnifierImageData</span><span class="hl-1">, </span><span class="hl-11">0</span><span class="hl-1">, </span><span class="hl-11">0</span><span class="hl-1">);</span><br/><br/><span class="hl-1">  </span><span class="hl-8">// 4. 更新放大镜位置 (CSS)</span><br/><span class="hl-1">  </span><span class="hl-6">magnifierCanvas</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">x</span><span class="hl-12"> </span><span class="hl-1">-</span><span class="hl-12"> </span><span class="hl-6">magnifierSize</span><span class="hl-12"> </span><span class="hl-1">/</span><span class="hl-12"> </span><span class="hl-11">2</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">magnifierCanvas</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">renderSize</span><span class="hl-12">.</span><span class="hl-6">y</span><span class="hl-12"> </span><span class="hl-1">-</span><span class="hl-12"> </span><span class="hl-6">y</span><span class="hl-12"> </span><span class="hl-1">-</span><span class="hl-12"> </span><span class="hl-6">magnifierSize</span><span class="hl-12"> </span><span class="hl-1">/</span><span class="hl-12"> </span><span class="hl-11">2</span><span class="hl-3">}</span><span class="hl-9">px`</span><span class="hl-1">; </span><span class="hl-8">// 注意 Y 轴方向</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">&#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">// 假设有一个用于显示的 canvas</span><br/><span class="hl-8">const</span><span class="hl-1"> </span><span class="hl-6">magnifierCanvas</span><span class="hl-1"> = </span><span class="hl-5">document</span><span class="hl-1">.</span><span class="hl-4">getElementById</span><span class="hl-1">(</span><span class="hl-10">&#39;magnifier-canvas&#39;</span><span class="hl-1">) </span><span class="hl-11">as</span><span class="hl-1"> </span><span class="hl-9">HTMLCanvasElement</span><span class="hl-1">;</span><br/><span class="hl-8">const</span><span class="hl-1"> </span><span class="hl-6">ctx</span><span class="hl-1"> = </span><span class="hl-5">magnifierCanvas</span><span class="hl-1">.</span><span class="hl-4">getContext</span><span class="hl-1">(</span><span class="hl-10">&#39;2d&#39;</span><span class="hl-1">)!;</span><br/><span class="hl-8">const</span><span class="hl-1"> </span><span class="hl-6">magnifierSize</span><span class="hl-1"> = </span><span class="hl-3">200</span><span class="hl-1">; </span><span class="hl-7">// 放大镜尺寸 200px</span><br/><span class="hl-8">const</span><span class="hl-1"> </span><span class="hl-6">scale</span><span class="hl-1"> = </span><span class="hl-3">2</span><span class="hl-1">; </span><span class="hl-7">// 放大倍数</span><br/><br/><span class="hl-7">// 预先创建 Buffer 以提升性能</span><br/><span class="hl-8">const</span><span class="hl-1"> </span><span class="hl-6">pixelWidth</span><span class="hl-1"> = </span><span class="hl-5">magnifierSize</span><span class="hl-1"> * </span><span class="hl-5">scale</span><span class="hl-1">;</span><br/><span class="hl-8">const</span><span class="hl-1"> </span><span class="hl-6">pixelHeight</span><span class="hl-1"> = </span><span class="hl-5">magnifierSize</span><span class="hl-1"> * </span><span class="hl-5">scale</span><span class="hl-1">;</span><br/><span class="hl-8">let</span><span class="hl-1"> </span><span class="hl-5">magnifierImageData</span><span class="hl-1"> = </span><span class="hl-5">ctx</span><span class="hl-1">.</span><span class="hl-4">createImageData</span><span class="hl-1">(</span><span class="hl-5">pixelWidth</span><span class="hl-1">, </span><span class="hl-5">pixelHeight</span><span class="hl-1">);</span><br/><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">&#39;gesture.mousemove&#39;</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-7">// 1. 获取鼠标在 Canvas 上的坐标</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-5">event</span><span class="hl-1">.</span><span class="hl-5">pointers</span><span class="hl-1">[</span><span class="hl-3">0</span><span class="hl-1">]?.</span><span class="hl-5">coords</span><span class="hl-1">;</span><br/><span class="hl-1">  </span><span class="hl-11">if</span><span class="hl-1"> (!</span><span class="hl-5">mouse</span><span class="hl-1">) </span><span class="hl-11">return</span><span class="hl-1">;</span><br/><br/><span class="hl-1">  </span><span class="hl-7">// 转换归一化坐标 (-1 到 1) 到 像素坐标</span><br/><span class="hl-1">  </span><span class="hl-8">const</span><span class="hl-1"> </span><span class="hl-6">renderSize</span><span class="hl-1"> = </span><span class="hl-5">five</span><span class="hl-1">.</span><span class="hl-4">getSize</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/><span class="hl-1">  </span><span class="hl-8">const</span><span class="hl-1"> </span><span class="hl-6">x</span><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-3">1</span><span class="hl-1">) / </span><span class="hl-3">2</span><span class="hl-1"> * </span><span class="hl-5">renderSize</span><span class="hl-1">.</span><span class="hl-5">x</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">y</span><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-3">1</span><span class="hl-1">) / </span><span class="hl-3">2</span><span class="hl-1"> * </span><span class="hl-5">renderSize</span><span class="hl-1">.</span><span class="hl-5">y</span><span class="hl-1">;</span><br/><br/><span class="hl-1">  </span><span class="hl-7">// 2. 获取像素数据</span><br/><span class="hl-1">  </span><span class="hl-7">// 注意：我们以更高的分辨率 (pixelRatio * scale) 渲染小区域，从而获得“无损”放大效果</span><br/><span class="hl-1">  </span><span class="hl-8">const</span><span class="hl-1"> </span><span class="hl-6">pixelRatio</span><span class="hl-1"> = </span><span class="hl-5">five</span><span class="hl-1">.</span><span class="hl-5">renderer</span><span class="hl-1">?.</span><span class="hl-4">getPixelRatio</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">const</span><span class="hl-1"> </span><span class="hl-6">targetPixelRatio</span><span class="hl-1"> = </span><span class="hl-5">Math</span><span class="hl-1">.</span><span class="hl-4">ceil</span><span class="hl-1">(</span><span class="hl-5">pixelRatio</span><span class="hl-1"> * </span><span class="hl-5">scale</span><span class="hl-1">);</span><br/><br/><span class="hl-1">  </span><span class="hl-5">five</span><span class="hl-1">.</span><span class="hl-4">getPixels</span><span class="hl-1">({</span><br/><span class="hl-1">    </span><span class="hl-5">x:</span><span class="hl-1"> </span><span class="hl-5">x</span><span class="hl-1"> - </span><span class="hl-5">magnifierSize</span><span class="hl-1"> / </span><span class="hl-3">2</span><span class="hl-1">, </span><span class="hl-7">// 居中</span><br/><span class="hl-1">    </span><span class="hl-5">y:</span><span class="hl-1"> </span><span class="hl-5">y</span><span class="hl-1"> - </span><span class="hl-5">magnifierSize</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">width:</span><span class="hl-1"> </span><span class="hl-5">magnifierSize</span><span class="hl-1">,</span><br/><span class="hl-1">    </span><span class="hl-5">height:</span><span class="hl-1"> </span><span class="hl-5">magnifierSize</span><span class="hl-1">,</span><br/><span class="hl-1">    </span><span class="hl-5">pixelRatio:</span><span class="hl-1"> </span><span class="hl-5">targetPixelRatio</span><span class="hl-1">,</span><br/><span class="hl-1">    </span><span class="hl-5">flipY:</span><span class="hl-1"> </span><span class="hl-8">true</span><span class="hl-1">, </span><span class="hl-7">// 翻转以适配 Canvas 2D</span><br/><span class="hl-1">    </span><span class="hl-5">buffer:</span><span class="hl-1"> </span><span class="hl-5">magnifierImageData</span><span class="hl-1">.</span><span class="hl-5">data</span><span class="hl-1">, </span><span class="hl-7">// 复用 buffer</span><br/><span class="hl-1">    </span><span class="hl-5">helperVisible:</span><span class="hl-1"> </span><span class="hl-8">false</span><span class="hl-1">, </span><span class="hl-7">// 隐藏辅助线等干扰元素</span><br/><span class="hl-1">  });</span><br/><br/><span class="hl-1">  </span><span class="hl-7">// 3. 将数据绘制到放大镜 Canvas 上</span><br/><span class="hl-1">  </span><span class="hl-7">// 需要调整 Canvas 尺寸以匹配数据</span><br/><span class="hl-1">  </span><span class="hl-5">magnifierCanvas</span><span class="hl-1">.</span><span class="hl-5">width</span><span class="hl-1"> = </span><span class="hl-5">pixelWidth</span><span class="hl-1">;</span><br/><span class="hl-1">  </span><span class="hl-5">magnifierCanvas</span><span class="hl-1">.</span><span class="hl-5">height</span><span class="hl-1"> = </span><span class="hl-5">pixelHeight</span><span class="hl-1">;</span><br/><span class="hl-1">  </span><span class="hl-5">ctx</span><span class="hl-1">.</span><span class="hl-4">putImageData</span><span class="hl-1">(</span><span class="hl-5">magnifierImageData</span><span class="hl-1">, </span><span class="hl-3">0</span><span class="hl-1">, </span><span class="hl-3">0</span><span class="hl-1">);</span><br/><br/><span class="hl-1">  </span><span class="hl-7">// 4. 更新放大镜位置 (CSS)</span><br/><span class="hl-1">  </span><span class="hl-5">magnifierCanvas</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">x</span><span class="hl-12"> </span><span class="hl-1">-</span><span class="hl-12"> </span><span class="hl-5">magnifierSize</span><span class="hl-12"> </span><span class="hl-1">/</span><span class="hl-12"> </span><span class="hl-3">2</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">magnifierCanvas</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">renderSize</span><span class="hl-12">.</span><span class="hl-5">y</span><span class="hl-12"> </span><span class="hl-1">-</span><span class="hl-12"> </span><span class="hl-5">y</span><span class="hl-12"> </span><span class="hl-1">-</span><span class="hl-12"> </span><span class="hl-5">magnifierSize</span><span class="hl-12"> </span><span class="hl-1">/</span><span class="hl-12"> </span><span class="hl-3">2</span><span class="hl-8">}</span><span class="hl-10">px`</span><span class="hl-1">; </span><span class="hl-7">// 注意 Y 轴方向</span><br/><span class="hl-1">});</span>
 </code><button type="button">Copy</button></pre>
 
 <h3 id="获取中心点颜色-color-picker" class="tsd-anchor-link">获取中心点颜色 (Color Picker)<a href="#获取中心点颜色-color-picker" 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">function</span><span class="hl-1"> </span><span class="hl-5">getCenterColor</span><span class="hl-1">(</span><span class="hl-6">five</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-3">const</span><span class="hl-1"> </span><span class="hl-4">size</span><span class="hl-1"> = </span><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-5">getSize</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/><span class="hl-1">  </span><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">x</span><span class="hl-1"> = </span><span class="hl-6">size</span><span class="hl-1">.</span><span class="hl-6">x</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-3">const</span><span class="hl-1"> </span><span class="hl-4">y</span><span class="hl-1"> = </span><span class="hl-6">size</span><span class="hl-1">.</span><span class="hl-6">y</span><span class="hl-1"> / </span><span class="hl-11">2</span><span class="hl-1">;</span><br/><br/><span class="hl-1">  </span><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">pixels</span><span class="hl-1"> = </span><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-5">getPixels</span><span class="hl-1">({</span><br/><span class="hl-1">    </span><span class="hl-6">x:</span><span class="hl-1"> </span><span class="hl-6">x</span><span class="hl-1">,</span><br/><span class="hl-1">    </span><span class="hl-6">y:</span><span class="hl-1"> </span><span class="hl-6">y</span><span class="hl-1">,</span><br/><span class="hl-1">    </span><span class="hl-6">width:</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">height:</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">flipY:</span><span class="hl-1"> </span><span class="hl-3">true</span><br/><span class="hl-1">  });</span><br/><br/><span class="hl-1">  </span><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">r</span><span class="hl-1"> = </span><span class="hl-6">pixels</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-3">const</span><span class="hl-1"> </span><span class="hl-4">g</span><span class="hl-1"> = </span><span class="hl-6">pixels</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">const</span><span class="hl-1"> </span><span class="hl-4">b</span><span class="hl-1"> = </span><span class="hl-6">pixels</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-3">const</span><span class="hl-1"> </span><span class="hl-4">a</span><span class="hl-1"> = </span><span class="hl-6">pixels</span><span class="hl-1">[</span><span class="hl-11">3</span><span class="hl-1">];</span><br/><br/><span class="hl-1">  </span><span class="hl-10">return</span><span class="hl-1"> </span><span class="hl-9">`rgba(</span><span class="hl-3">${</span><span class="hl-6">r</span><span class="hl-3">}</span><span class="hl-9">, </span><span class="hl-3">${</span><span class="hl-6">g</span><span class="hl-3">}</span><span class="hl-9">, </span><span class="hl-3">${</span><span class="hl-6">b</span><span class="hl-3">}</span><span class="hl-9">, </span><span class="hl-3">${</span><span class="hl-6">a</span><span class="hl-12"> </span><span class="hl-1">/</span><span class="hl-12"> </span><span class="hl-11">255</span><span class="hl-3">}</span><span class="hl-9">)`</span><span class="hl-1">;</span><br/><span class="hl-1">}</span>
+<pre><code class="typescript"><span class="hl-8">function</span><span class="hl-1"> </span><span class="hl-4">getCenterColor</span><span class="hl-1">(</span><span class="hl-5">five</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-8">const</span><span class="hl-1"> </span><span class="hl-6">size</span><span class="hl-1"> = </span><span class="hl-5">five</span><span class="hl-1">.</span><span class="hl-4">getSize</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/><span class="hl-1">  </span><span class="hl-8">const</span><span class="hl-1"> </span><span class="hl-6">x</span><span class="hl-1"> = </span><span class="hl-5">size</span><span class="hl-1">.</span><span class="hl-5">x</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-8">const</span><span class="hl-1"> </span><span class="hl-6">y</span><span class="hl-1"> = </span><span class="hl-5">size</span><span class="hl-1">.</span><span class="hl-5">y</span><span class="hl-1"> / </span><span class="hl-3">2</span><span class="hl-1">;</span><br/><br/><span class="hl-1">  </span><span class="hl-8">const</span><span class="hl-1"> </span><span class="hl-6">pixels</span><span class="hl-1"> = </span><span class="hl-5">five</span><span class="hl-1">.</span><span class="hl-4">getPixels</span><span class="hl-1">({</span><br/><span class="hl-1">    </span><span class="hl-5">x:</span><span class="hl-1"> </span><span class="hl-5">x</span><span class="hl-1">,</span><br/><span class="hl-1">    </span><span class="hl-5">y:</span><span class="hl-1"> </span><span class="hl-5">y</span><span class="hl-1">,</span><br/><span class="hl-1">    </span><span class="hl-5">width:</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">height:</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">flipY:</span><span class="hl-1"> </span><span class="hl-8">true</span><br/><span class="hl-1">  });</span><br/><br/><span class="hl-1">  </span><span class="hl-8">const</span><span class="hl-1"> </span><span class="hl-6">r</span><span class="hl-1"> = </span><span class="hl-5">pixels</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-8">const</span><span class="hl-1"> </span><span class="hl-6">g</span><span class="hl-1"> = </span><span class="hl-5">pixels</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">const</span><span class="hl-1"> </span><span class="hl-6">b</span><span class="hl-1"> = </span><span class="hl-5">pixels</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-8">const</span><span class="hl-1"> </span><span class="hl-6">a</span><span class="hl-1"> = </span><span class="hl-5">pixels</span><span class="hl-1">[</span><span class="hl-3">3</span><span class="hl-1">];</span><br/><br/><span class="hl-1">  </span><span class="hl-11">return</span><span class="hl-1"> </span><span class="hl-10">`rgba(</span><span class="hl-8">${</span><span class="hl-5">r</span><span class="hl-8">}</span><span class="hl-10">, </span><span class="hl-8">${</span><span class="hl-5">g</span><span class="hl-8">}</span><span class="hl-10">, </span><span class="hl-8">${</span><span class="hl-5">b</span><span class="hl-8">}</span><span class="hl-10">, </span><span class="hl-8">${</span><span class="hl-5">a</span><span class="hl-12"> </span><span class="hl-1">/</span><span class="hl-12"> </span><span class="hl-3">255</span><span class="hl-8">}</span><span class="hl-10">)`</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>