@realsee/five-webgpu 1.0.0-alpha.1 → 1.0.0-alpha.10

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

@@ -39,7 +39,7 @@
 <h2 id="examples" class="tsd-anchor-link">Examples<a href="#examples" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h2>
 <h3 id="放大镜-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-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-webgpu&#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>
 </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>

package/docs/documents/features_image-options.html

@@ -84,17 +84,17 @@
 <h2 id="examples" class="tsd-anchor-link">Examples<a href="#examples" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h2>
 <h3 id="基础优化配置-推荐" 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>
 <p>启用 AVIF 格式并设置初始尺寸为 <code>512</code>，适用于大多数场景。</p>
-<pre><code class="typescript"><span class="hl-10">import</span><span class="hl-1"> { </span><span class="hl-6">Five</span><span class="hl-1"> } </span><span class="hl-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/><span class="hl-1">  </span><span class="hl-6">imageOptions:</span><span class="hl-1"> {</span><br/><span class="hl-1">    </span><span class="hl-6">format:</span><span class="hl-1"> </span><span class="hl-9">&quot;avif&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">    </span><span class="hl-6">size:</span><span class="hl-1"> </span><span class="hl-11">512</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-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-webgpu&quot;</span><span class="hl-1">;</span><br/><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">five</span><span class="hl-1"> = </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-5">Five</span><span class="hl-1">({</span><br/><span class="hl-1">  </span><span class="hl-6">imageOptions:</span><span class="hl-1"> {</span><br/><span class="hl-1">    </span><span class="hl-6">format:</span><span class="hl-1"> </span><span class="hl-9">&quot;avif&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">    </span><span class="hl-6">size:</span><span class="hl-1"> </span><span class="hl-11">512</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>
 <p>将数据中的 <code>custom-oss-public.ljcdn.com</code> 域名映射到对应的资源专用 OSS 域名。</p>
-<pre><code class="typescript"><span class="hl-10">import</span><span class="hl-1"> { </span><span class="hl-6">Five</span><span class="hl-1"> } </span><span class="hl-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/><span class="hl-1">  </span><span class="hl-6">imageOptions:</span><span class="hl-1"> {</span><br/><span class="hl-1">    </span><span class="hl-6">mappings:</span><span class="hl-1"> {</span><br/><span class="hl-1">      </span><span class="hl-9">&quot;custom-oss-public.ljcdn.com&quot;</span><span class="hl-6">:</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-9">&quot;tencentCloud&quot;</span><span class="hl-1">, </span><span class="hl-8">// 指定使用腾讯云图片处理协议</span><br/><span class="hl-1">        </span><span class="hl-6">pano:</span><span class="hl-1"> [</span><span class="hl-9">&quot;custom-oss-image-1.com&quot;</span><span class="hl-1">, </span><span class="hl-9">&quot;custom-oss-image-2.com&quot;</span><span class="hl-1">], </span><span class="hl-8">// 双域名负载均衡</span><br/><span class="hl-1">        </span><span class="hl-6">tile:</span><span class="hl-1"> [</span><span class="hl-9">&quot;custom-oss-tile-1.com&quot;</span><span class="hl-1">, </span><span class="hl-9">&quot;custom-oss-tile-2.com&quot;</span><span class="hl-1">],</span><br/><span class="hl-1">        </span><span class="hl-6">model:</span><span class="hl-1"> [</span><span class="hl-9">&quot;custom-oss-model-1.com&quot;</span><span class="hl-1">, </span><span class="hl-9">&quot;custom-oss-model-2.com&quot;</span><span class="hl-1">],</span><br/><span class="hl-1">        </span><span class="hl-6">texture:</span><span class="hl-1"> [</span><span class="hl-9">&quot;custom-oss-image-3.com&quot;</span><span class="hl-1">],</span><br/><span class="hl-1">        </span><span class="hl-6">default:</span><span class="hl-1"> [</span><span class="hl-9">&quot;custom-oss-image-4.com&quot;</span><span class="hl-1">]</span><br/><span class="hl-1">      }</span><br/><span class="hl-1">    }</span><br/><span class="hl-1">  }</span><br/><span class="hl-1">});</span>
+<pre><code class="typescript"><span class="hl-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-webgpu&quot;</span><span class="hl-1">;</span><br/><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">five</span><span class="hl-1"> = </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-5">Five</span><span class="hl-1">({</span><br/><span class="hl-1">  </span><span class="hl-6">imageOptions:</span><span class="hl-1"> {</span><br/><span class="hl-1">    </span><span class="hl-6">mappings:</span><span class="hl-1"> {</span><br/><span class="hl-1">      </span><span class="hl-9">&quot;custom-oss-public.ljcdn.com&quot;</span><span class="hl-6">:</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-9">&quot;tencentCloud&quot;</span><span class="hl-1">, </span><span class="hl-8">// 指定使用腾讯云图片处理协议</span><br/><span class="hl-1">        </span><span class="hl-6">pano:</span><span class="hl-1"> [</span><span class="hl-9">&quot;custom-oss-image-1.com&quot;</span><span class="hl-1">, </span><span class="hl-9">&quot;custom-oss-image-2.com&quot;</span><span class="hl-1">], </span><span class="hl-8">// 双域名负载均衡</span><br/><span class="hl-1">        </span><span class="hl-6">tile:</span><span class="hl-1"> [</span><span class="hl-9">&quot;custom-oss-tile-1.com&quot;</span><span class="hl-1">, </span><span class="hl-9">&quot;custom-oss-tile-2.com&quot;</span><span class="hl-1">],</span><br/><span class="hl-1">        </span><span class="hl-6">model:</span><span class="hl-1"> [</span><span class="hl-9">&quot;custom-oss-model-1.com&quot;</span><span class="hl-1">, </span><span class="hl-9">&quot;custom-oss-model-2.com&quot;</span><span class="hl-1">],</span><br/><span class="hl-1">        </span><span class="hl-6">texture:</span><span class="hl-1"> [</span><span class="hl-9">&quot;custom-oss-image-3.com&quot;</span><span class="hl-1">],</span><br/><span class="hl-1">        </span><span class="hl-6">default:</span><span class="hl-1"> [</span><span class="hl-9">&quot;custom-oss-image-4.com&quot;</span><span class="hl-1">]</span><br/><span class="hl-1">      }</span><br/><span class="hl-1">    }</span><br/><span class="hl-1">  }</span><br/><span class="hl-1">});</span>
 </code><button type="button">Copy</button></pre>
 
 <h3 id="内部调用：获取全景图局部裁剪" 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>
 <p>使用 SDK 提供的 <code>defaultImageURLTransform</code> 工具函数（通常导出为 <code>defaultImageURLTransform</code>，可重命名为 <code>imageURL</code>），结合 <code>cut</code> 参数获取全景图特定区域（例如获取前方图片的中心 512x512 区域）。</p>
-<pre><code class="typescript"><span class="hl-10">import</span><span class="hl-1"> { </span><span class="hl-6">defaultImageURLTransform</span><span class="hl-1"> </span><span class="hl-10">as</span><span class="hl-1"> </span><span class="hl-6">imageURL</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">originalUrl</span><span class="hl-1"> = </span><span class="hl-9">&quot;https://vr-public.realsee-cdn.com/.../pano_f.jpg&quot;</span><span class="hl-1">;</span><br/><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">cutUrl</span><span class="hl-1"> = </span><span class="hl-5">imageURL</span><span class="hl-1">(</span><span class="hl-6">originalUrl</span><span class="hl-1">, {</span><br/><span class="hl-1">  </span><span class="hl-6">cut:</span><span class="hl-1"> [</span><span class="hl-11">256</span><span class="hl-1">, </span><span class="hl-11">256</span><span class="hl-1">, </span><span class="hl-11">512</span><span class="hl-1">, </span><span class="hl-11">512</span><span class="hl-1">], </span><span class="hl-8">// x, y, width, height</span><br/><span class="hl-1">  </span><span class="hl-6">format:</span><span class="hl-1"> </span><span class="hl-9">&quot;webp&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-6">quality:</span><span class="hl-1"> </span><span class="hl-11">80</span><span class="hl-1">,</span><br/><span class="hl-1">});</span><br/><br/><span class="hl-6">console</span><span class="hl-1">.</span><span class="hl-5">log</span><span class="hl-1">(</span><span class="hl-6">cutUrl</span><span class="hl-1">);</span><br/><span class="hl-8">// 输出示例: https://vr-image-4.realsee-cdn.com/.../pano_f.jpg?imageMogr2/format/webp/cut/512x512x256x256/quality/80</span>
+<pre><code class="typescript"><span class="hl-10">import</span><span class="hl-1"> { </span><span class="hl-6">defaultImageURLTransform</span><span class="hl-1"> </span><span class="hl-10">as</span><span class="hl-1"> </span><span class="hl-6">imageURL</span><span class="hl-1"> } </span><span class="hl-10">from</span><span class="hl-1"> </span><span class="hl-9">&quot;@realsee/five-webgpu&quot;</span><span class="hl-1">;</span><br/><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">originalUrl</span><span class="hl-1"> = </span><span class="hl-9">&quot;https://vr-public.realsee-cdn.com/.../pano_f.jpg&quot;</span><span class="hl-1">;</span><br/><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">cutUrl</span><span class="hl-1"> = </span><span class="hl-5">imageURL</span><span class="hl-1">(</span><span class="hl-6">originalUrl</span><span class="hl-1">, {</span><br/><span class="hl-1">  </span><span class="hl-6">cut:</span><span class="hl-1"> [</span><span class="hl-11">256</span><span class="hl-1">, </span><span class="hl-11">256</span><span class="hl-1">, </span><span class="hl-11">512</span><span class="hl-1">, </span><span class="hl-11">512</span><span class="hl-1">], </span><span class="hl-8">// x, y, width, height</span><br/><span class="hl-1">  </span><span class="hl-6">format:</span><span class="hl-1"> </span><span class="hl-9">&quot;webp&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-6">quality:</span><span class="hl-1"> </span><span class="hl-11">80</span><span class="hl-1">,</span><br/><span class="hl-1">});</span><br/><br/><span class="hl-6">console</span><span class="hl-1">.</span><span class="hl-5">log</span><span class="hl-1">(</span><span class="hl-6">cutUrl</span><span class="hl-1">);</span><br/><span class="hl-8">// 输出示例: https://vr-image-4.realsee-cdn.com/.../pano_f.jpg?imageMogr2/format/webp/cut/512x512x256x256/quality/80</span>
 </code><button type="button">Copy</button></pre>
 
 <h2 id="related" class="tsd-anchor-link">Related<a href="#related" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h2>

package/docs/documents/features_load-external-model.html

@@ -11,23 +11,23 @@
 <p><strong>Definition</strong>: <a href="../../five/model/loaders/shared.d.ts">LoadResultType</a></p>
 </blockquote>
 <p>所有加载函数均返回 <code>Promise&lt;LoadResultType&gt;</code>。</p>
-<pre><code class="typescript"><span class="hl-8">// 通用返回类型</span><br/><span class="hl-10">export</span><span class="hl-1"> </span><span class="hl-3">type</span><span class="hl-1"> </span><span class="hl-7">LoadResultType</span><span class="hl-1">&lt;</span><span class="hl-7">Scene</span><span class="hl-1"> = </span><span class="hl-7">THREE</span><span class="hl-1">.</span><span class="hl-7">Object3D</span><span class="hl-1">&gt; = {</span><br/><span class="hl-1">  </span><span class="hl-6">type</span><span class="hl-1">: </span><span class="hl-9">&#39;gltf&#39;</span><span class="hl-1"> | </span><span class="hl-9">&#39;obj&#39;</span><span class="hl-1"> | </span><span class="hl-9">&#39;ply&#39;</span><span class="hl-1"> | </span><span class="hl-9">&#39;fbx&#39;</span><span class="hl-1"> | </span><span class="hl-9">&#39;pbm&#39;</span><span class="hl-1"> | </span><span class="hl-9">&#39;splat&#39;</span><span class="hl-1"> | </span><span class="hl-9">&#39;spz&#39;</span><span class="hl-1"> | </span><span class="hl-9">&#39;b3dm&#39;</span><span class="hl-1"> | </span><span class="hl-9">&#39;pnts&#39;</span><span class="hl-1"> | </span><span class="hl-9">&#39;at3d&#39;</span><span class="hl-1"> | </span><span class="hl-9">&#39;dome&#39;</span><span class="hl-1"> | </span><span class="hl-9">&#39;domez&#39;</span><span class="hl-1"> | </span><span class="hl-9">&#39;x3p&#39;</span><span class="hl-1">; </span><span class="hl-8">// 模型类型</span><br/><span class="hl-1">  </span><span class="hl-6">modelUpAxis</span><span class="hl-1">: </span><span class="hl-9">&#39;Y&#39;</span><span class="hl-1"> | </span><span class="hl-9">&#39;Z&#39;</span><span class="hl-1">;     </span><span class="hl-8">// 原始模型的上轴</span><br/><span class="hl-1">  </span><span class="hl-6">upAxis</span><span class="hl-1">: </span><span class="hl-9">&#39;Y&#39;</span><span class="hl-1"> | </span><span class="hl-9">&#39;Z&#39;</span><span class="hl-1">;          </span><span class="hl-8">// 输出模型的上轴 (通常为 Z)</span><br/><span class="hl-1">  </span><span class="hl-6">byteLength</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">memoryUsage</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">uri</span><span class="hl-1">: </span><span class="hl-7">string</span><span class="hl-1">;                </span><span class="hl-8">// 模型地址</span><br/><span class="hl-1">  </span><span class="hl-6">scene</span><span class="hl-1">: </span><span class="hl-7">Scene</span><span class="hl-1">;               </span><span class="hl-8">// Three.js 对象 (Group 或 Object3D)，可直接添加到场景</span><br/><span class="hl-1">  </span><span class="hl-6">textures</span><span class="hl-1">: </span><span class="hl-7">THREE</span><span class="hl-1">.</span><span class="hl-7">Texture</span><span class="hl-1">[];  </span><span class="hl-8">// 加载的纹理列表</span><br/><span class="hl-1">  </span><span class="hl-6">animations</span><span class="hl-1">: </span><span class="hl-7">THREE</span><span class="hl-1">.</span><span class="hl-7">AnimationClip</span><span class="hl-1">[]; </span><span class="hl-8">// 动画剪辑列表</span><br/><span class="hl-1">  </span><span class="hl-6">rtcCenter</span><span class="hl-1">?: </span><span class="hl-7">THREE</span><span class="hl-1">.</span><span class="hl-7">Vector3</span><span class="hl-1">;  </span><span class="hl-8">// 若存在 RTC (Relative To Center) 坐标偏移</span><br/><span class="hl-1">  </span><span class="hl-5">dispose</span><span class="hl-1">: () </span><span class="hl-3">=&gt;</span><span class="hl-1"> </span><span class="hl-7">void</span><span class="hl-1">;        </span><span class="hl-8">// 销毁资源函数</span><br/><span class="hl-1">}</span><br/><br/><span class="hl-8">// 通用配置项接口</span><br/><span class="hl-3">interface</span><span class="hl-1"> </span><span class="hl-7">BaseLoaderOptions</span><span class="hl-1"> {</span><br/><span class="hl-1">  </span><span class="hl-6">upAxis</span><span class="hl-1">?: </span><span class="hl-9">&#39;Y&#39;</span><span class="hl-1"> | </span><span class="hl-9">&#39;Z&#39;</span><span class="hl-1">;         </span><span class="hl-8">// 期望输出的上轴，默认为 &#39;Z&#39; (Five 坐标系)</span><br/><span class="hl-1">  </span><span class="hl-6">modelUpAxis</span><span class="hl-1">?: </span><span class="hl-9">&#39;Y&#39;</span><span class="hl-1"> | </span><span class="hl-9">&#39;Z&#39;</span><span class="hl-1">;    </span><span class="hl-8">// (部分加载器支持) 原始模型的上轴，用于自动旋转修正</span><br/><span class="hl-1">  </span><span class="hl-6">fetcher</span><span class="hl-1">?: </span><span class="hl-7">Fetcher</span><span class="hl-1">;          </span><span class="hl-8">// 自定义网络请求 Fetcher</span><br/><span class="hl-1">  </span><span class="hl-6">light</span><span class="hl-1">?: </span><span class="hl-7">boolean</span><span class="hl-1">;            </span><span class="hl-8">// 是否使用简化/无光照材质 (取决于加载器实现)</span><br/><span class="hl-1">  </span><span class="hl-5">onDownloadProgress</span><span class="hl-1">?: (</span><span class="hl-6">progress</span><span class="hl-1">: { </span><span class="hl-6">loaded</span><span class="hl-1">: </span><span class="hl-7">number</span><span class="hl-1">, </span><span class="hl-6">total</span><span class="hl-1">: </span><span class="hl-7">number</span><span class="hl-1"> }) </span><span class="hl-3">=&gt;</span><span class="hl-1"> </span><span class="hl-7">void</span><span class="hl-1">; </span><span class="hl-8">// 下载进度回调</span><br/><span class="hl-1">}</span>
+<pre><code class="typescript"><span class="hl-8">// 通用返回类型</span><br/><span class="hl-10">export</span><span class="hl-1"> </span><span class="hl-3">type</span><span class="hl-1"> </span><span class="hl-7">LoadResultType</span><span class="hl-1">&lt;</span><span class="hl-7">Scene</span><span class="hl-1"> = </span><span class="hl-7">THREE</span><span class="hl-1">.</span><span class="hl-7">Object3D</span><span class="hl-1">&gt; = {</span><br/><span class="hl-1">  </span><span class="hl-6">type</span><span class="hl-1">: </span><span class="hl-9">&#39;gltf&#39;</span><span class="hl-1"> | </span><span class="hl-9">&#39;obj&#39;</span><span class="hl-1"> | </span><span class="hl-9">&#39;ply&#39;</span><span class="hl-1"> | </span><span class="hl-9">&#39;fbx&#39;</span><span class="hl-1"> | </span><span class="hl-9">&#39;pbm&#39;</span><span class="hl-1"> | </span><span class="hl-9">&#39;splat&#39;</span><span class="hl-1"> | </span><span class="hl-9">&#39;spz&#39;</span><span class="hl-1"> | </span><span class="hl-9">&#39;b3dm&#39;</span><span class="hl-1"> | </span><span class="hl-9">&#39;pnts&#39;</span><span class="hl-1"> | </span><span class="hl-9">&#39;at3d&#39;</span><span class="hl-1"> | </span><span class="hl-9">&#39;dome&#39;</span><span class="hl-1"> | </span><span class="hl-9">&#39;domez&#39;</span><span class="hl-1"> | </span><span class="hl-9">&#39;x3p&#39;</span><span class="hl-1">; </span><span class="hl-8">// 模型类型</span><br/><span class="hl-1">  </span><span class="hl-6">modelUpAxis</span><span class="hl-1">: </span><span class="hl-9">&#39;Y&#39;</span><span class="hl-1"> | </span><span class="hl-9">&#39;Z&#39;</span><span class="hl-1">;     </span><span class="hl-8">// 原始模型的上轴</span><br/><span class="hl-1">  </span><span class="hl-6">upAxis</span><span class="hl-1">: </span><span class="hl-9">&#39;Y&#39;</span><span class="hl-1"> | </span><span class="hl-9">&#39;Z&#39;</span><span class="hl-1">;          </span><span class="hl-8">// 输出模型的上轴 (通常为 Z)</span><br/><span class="hl-1">  </span><span class="hl-6">byteLength</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">memoryUsage</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">uri</span><span class="hl-1">: </span><span class="hl-7">string</span><span class="hl-1">;                </span><span class="hl-8">// 模型地址</span><br/><span class="hl-1">  </span><span class="hl-6">scene</span><span class="hl-1">: </span><span class="hl-7">Scene</span><span class="hl-1">;               </span><span class="hl-8">// Three.js 对象 (Group 或 Object3D)，可直接添加到场景</span><br/><span class="hl-1">  </span><span class="hl-6">textures</span><span class="hl-1">: </span><span class="hl-7">THREE</span><span class="hl-1">.</span><span class="hl-7">Texture</span><span class="hl-1">[];  </span><span class="hl-8">// 加载的纹理列表</span><br/><span class="hl-1">  </span><span class="hl-6">animations</span><span class="hl-1">: </span><span class="hl-7">THREE</span><span class="hl-1">.</span><span class="hl-7">AnimationClip</span><span class="hl-1">[]; </span><span class="hl-8">// 动画剪辑列表</span><br/><span class="hl-1">  </span><span class="hl-6">rtcCenter</span><span class="hl-1">?: </span><span class="hl-7">THREE</span><span class="hl-1">.</span><span class="hl-7">Vector3</span><span class="hl-1">;  </span><span class="hl-8">// 若存在 RTC (Relative To Center) 坐标偏移</span><br/><span class="hl-1">  </span><span class="hl-5">dispose</span><span class="hl-1">: () </span><span class="hl-3">=&gt;</span><span class="hl-1"> </span><span class="hl-7">void</span><span class="hl-1">;        </span><span class="hl-8">// 销毁资源函数</span><br/><span class="hl-1">}</span><br/><br/><span class="hl-8">// 通用配置项接口</span><br/><span class="hl-3">interface</span><span class="hl-1"> </span><span class="hl-7">BaseLoaderOptions</span><span class="hl-1"> {</span><br/><span class="hl-1">  </span><span class="hl-6">upAxis</span><span class="hl-1">?: </span><span class="hl-9">&#39;Y&#39;</span><span class="hl-1"> | </span><span class="hl-9">&#39;Z&#39;</span><span class="hl-1">;         </span><span class="hl-8">// 期望输出的上轴，默认为 &#39;Z&#39;（加载器输出坐标系）</span><br/><span class="hl-1">  </span><span class="hl-6">modelUpAxis</span><span class="hl-1">?: </span><span class="hl-9">&#39;Y&#39;</span><span class="hl-1"> | </span><span class="hl-9">&#39;Z&#39;</span><span class="hl-1">;    </span><span class="hl-8">// (部分加载器支持) 原始模型的上轴，用于自动旋转修正</span><br/><span class="hl-1">  </span><span class="hl-6">fetcher</span><span class="hl-1">?: </span><span class="hl-7">Fetcher</span><span class="hl-1">;          </span><span class="hl-8">// 自定义网络请求 Fetcher</span><br/><span class="hl-1">  </span><span class="hl-6">light</span><span class="hl-1">?: </span><span class="hl-7">boolean</span><span class="hl-1">;            </span><span class="hl-8">// 是否使用简化/无光照材质 (取决于加载器实现)</span><br/><span class="hl-1">  </span><span class="hl-5">onDownloadProgress</span><span class="hl-1">?: (</span><span class="hl-6">progress</span><span class="hl-1">: { </span><span class="hl-6">loaded</span><span class="hl-1">: </span><span class="hl-7">number</span><span class="hl-1">, </span><span class="hl-6">total</span><span class="hl-1">: </span><span class="hl-7">number</span><span class="hl-1"> }) </span><span class="hl-3">=&gt;</span><span class="hl-1"> </span><span class="hl-7">void</span><span class="hl-1">; </span><span class="hl-8">// 下载进度回调</span><br/><span class="hl-1">}</span>
 </code><button type="button">Copy</button></pre>
 
 <h2 id="concepts" class="tsd-anchor-link">Concepts<a href="#concepts" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h2>
 <h3 id="独立加载函数-standalone-functions" class="tsd-anchor-link">独立加载函数 (Standalone Functions)<a href="#独立加载函数-standalone-functions" 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>loadGltf</code>, <code>loadPly</code>）是 <code>@realsee/five</code> 包导出的<strong>独立函数</strong>，而非 <code>Five</code> 实例的方法。你需要单独引入它们使用。</p>
+<p>这些加载函数（如 <code>loadGltf</code>, <code>loadPly</code>）是 <code>@realsee/five-webgpu</code> 包导出的<strong>独立函数</strong>，而非 <code>Five</code> 实例的方法。你需要单独引入它们使用。</p>
 <h3 id="坐标系转换-up-axis-conversion" class="tsd-anchor-link">坐标系转换 (Up-Axis Conversion)<a href="#坐标系转换-up-axis-conversion" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3>
-<p>Five 使用 <strong>Z-up</strong> (Z 轴向上) 的右手坐标系。
+<p>Five 运行时场景使用 <strong>Y-up</strong> (Y 轴向上) 的右手坐标系；加载器默认输出通常为 <strong>Z-up</strong>。
 许多外部模型（如 standard GLTF, FBX）通常是 <strong>Y-up</strong> 的。
 加载器提供了 <code>upAxis</code> 和 <code>modelUpAxis</code> 选项来自动处理旋转：</p>
 <ul>
-<li><code>upAxis</code>: 你期望得到的结果坐标系上轴（通常保持默认 'Z'）。</li>
+<li><code>upAxis</code>: 你期望得到的加载器输出坐标系上轴（通常保持默认 'Z'）。</li>
 <li><code>modelUpAxis</code>: 原始文件的上轴（如 GLTF 默认为 'Y'，PLY 默认为 'Z'）。
-如果不指定，加载器会尝试使用合理的默认值将模型旋转到 Z 轴向上。</li>
+如果不指定，加载器会使用各自的默认值；将结果直接添加到 <code>five.scene</code> 时，应按需设置 <code>upAxis: 'Y'</code> 与 Five 的运行时坐标系对齐。</li>
 </ul>
 <h3 id="资源销毁-disposal" class="tsd-anchor-link">资源销毁 (Disposal)<a href="#资源销毁-disposal" 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>加载的模型包含 Geometry、Material 和 Texture 等 WebGL 资源。当你不再需要该模型时（例如切换场景或移除物体），<strong>必须</strong>调用返回结果中的 <code>dispose()</code> 方法来释放内存，否则会导致内存泄漏。</p>
+<p>加载的模型包含 Geometry、Material 和 Texture 等 GPU 资源。当你不再需要该模型时（例如切换场景或移除物体），<strong>必须</strong>调用返回结果中的 <code>dispose()</code> 方法来释放资源，否则会导致内存泄漏。</p>
 <h3 id="fetcher" class="tsd-anchor-link">Fetcher<a href="#fetcher" 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>fetcher</code>。这在需要鉴权、自定义 Header 或处理特定 CDN 逻辑时非常有用。如果不传，默认使用内部的 <code>internalFetcher</code>。</p>
 <h2 id="configuration" class="tsd-anchor-link">Configuration<a href="#configuration" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h2>
@@ -533,31 +533,31 @@
 </table>
 <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="基础用法：加载-gltf-模型-basic-usage" class="tsd-anchor-link">基础用法：加载 GLTF 模型 (Basic Usage)<a href="#基础用法：加载-gltf-模型-basic-usage" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3>
-<pre><code class="typescript"><span class="hl-10">import</span><span class="hl-1"> { </span><span class="hl-6">Five</span><span class="hl-1">, </span><span class="hl-6">FivePlugin</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">loadGltf</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-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/><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><span class="hl-8">/*...*/</span><span class="hl-1">});</span><br/><br/><span class="hl-8">// 加载 GLB 模型</span><br/><span class="hl-5">loadGltf</span><span class="hl-1">(</span><span class="hl-9">&#39;https://example.com/model.glb&#39;</span><span class="hl-1">).</span><span class="hl-5">then</span><span class="hl-1">((</span><span class="hl-6">result</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. 获取模型对象</span><br/><span class="hl-1">  </span><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">model</span><span class="hl-1"> = </span><span class="hl-6">result</span><span class="hl-1">.</span><span class="hl-6">scene</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-6">model</span><span class="hl-1">.</span><span class="hl-6">position</span><span class="hl-1">.</span><span class="hl-5">set</span><span class="hl-1">(</span><span class="hl-11">0</span><span class="hl-1">, </span><span class="hl-11">0</span><span class="hl-1">, </span><span class="hl-11">0</span><span class="hl-1">);</span><br/><span class="hl-1">  </span><span class="hl-6">model</span><span class="hl-1">.</span><span class="hl-6">scale</span><span class="hl-1">.</span><span class="hl-5">set</span><span class="hl-1">(</span><span class="hl-11">1</span><span class="hl-1">, </span><span class="hl-11">1</span><span class="hl-1">, </span><span class="hl-11">1</span><span class="hl-1">);</span><br/><br/><span class="hl-1">  </span><span class="hl-8">// 3. 添加到 Five 场景</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">model</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-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/><br/><span class="hl-1">  </span><span class="hl-8">// 保存 result 用于后续销毁</span><br/><span class="hl-1">  </span><span class="hl-8">// result.dispose();</span><br/><span class="hl-1">}).</span><span class="hl-5">catch</span><span class="hl-1">(</span><span class="hl-6">err</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">error</span><span class="hl-1">(</span><span class="hl-9">&#39;加载失败&#39;</span><span class="hl-1">, </span><span class="hl-6">err</span><span class="hl-1">);</span><br/><span class="hl-1">});</span>
+<pre><code class="typescript"><span class="hl-10">import</span><span class="hl-1"> { </span><span class="hl-6">Five</span><span class="hl-1">, </span><span class="hl-6">FivePlugin</span><span class="hl-1"> } </span><span class="hl-10">from</span><span class="hl-1"> </span><span class="hl-9">&#39;@realsee/five-webgpu&#39;</span><span class="hl-1">;</span><br/><span class="hl-10">import</span><span class="hl-1"> { </span><span class="hl-6">loadGltf</span><span class="hl-1"> } </span><span class="hl-10">from</span><span class="hl-1"> </span><span class="hl-9">&#39;@realsee/five-webgpu&#39;</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">&#39;three&#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><span class="hl-8">/*...*/</span><span class="hl-1">});</span><br/><br/><span class="hl-8">// 加载 GLB 模型</span><br/><span class="hl-5">loadGltf</span><span class="hl-1">(</span><span class="hl-9">&#39;https://example.com/model.glb&#39;</span><span class="hl-1">).</span><span class="hl-5">then</span><span class="hl-1">((</span><span class="hl-6">result</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. 获取模型对象</span><br/><span class="hl-1">  </span><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">model</span><span class="hl-1"> = </span><span class="hl-6">result</span><span class="hl-1">.</span><span class="hl-6">scene</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-6">model</span><span class="hl-1">.</span><span class="hl-6">position</span><span class="hl-1">.</span><span class="hl-5">set</span><span class="hl-1">(</span><span class="hl-11">0</span><span class="hl-1">, </span><span class="hl-11">0</span><span class="hl-1">, </span><span class="hl-11">0</span><span class="hl-1">);</span><br/><span class="hl-1">  </span><span class="hl-6">model</span><span class="hl-1">.</span><span class="hl-6">scale</span><span class="hl-1">.</span><span class="hl-5">set</span><span class="hl-1">(</span><span class="hl-11">1</span><span class="hl-1">, </span><span class="hl-11">1</span><span class="hl-1">, </span><span class="hl-11">1</span><span class="hl-1">);</span><br/><br/><span class="hl-1">  </span><span class="hl-8">// 3. 添加到 Five 场景</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">model</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-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/><br/><span class="hl-1">  </span><span class="hl-8">// 保存 result 用于后续销毁</span><br/><span class="hl-1">  </span><span class="hl-8">// result.dispose();</span><br/><span class="hl-1">}).</span><span class="hl-5">catch</span><span class="hl-1">(</span><span class="hl-6">err</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">error</span><span class="hl-1">(</span><span class="hl-9">&#39;加载失败&#39;</span><span class="hl-1">, </span><span class="hl-6">err</span><span class="hl-1">);</span><br/><span class="hl-1">});</span>
 </code><button type="button">Copy</button></pre>
 
 <h3 id="进阶用法：加载高斯泼溅-gaussian-splat" class="tsd-anchor-link">进阶用法：加载高斯泼溅 (Gaussian Splat)<a href="#进阶用法：加载高斯泼溅-gaussian-splat" 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-10">import</span><span class="hl-1"> { </span><span class="hl-6">loadSplat</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-5">loadSplat</span><span class="hl-1">(</span><span class="hl-9">&#39;https://example.com/scene.splat&#39;</span><span class="hl-1">, {</span><br/><span class="hl-1">  </span><span class="hl-6">modelUpAxis:</span><span class="hl-1"> </span><span class="hl-9">&#39;Y&#39;</span><span class="hl-1">, </span><span class="hl-8">// 假设原始数据是 Y-up</span><br/><span class="hl-1">  </span><span class="hl-6">upAxis:</span><span class="hl-1"> </span><span class="hl-9">&#39;Z&#39;</span><span class="hl-1">,      </span><span class="hl-8">// 转换到 Five 的 Z-up</span><br/><span class="hl-1">}).</span><span class="hl-5">then</span><span class="hl-1">((</span><span class="hl-6">result</span><span class="hl-1">) </span><span class="hl-3">=&gt;</span><span class="hl-1"> {</span><br/><span class="hl-1">  </span><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">splatMesh</span><span class="hl-1"> = </span><span class="hl-6">result</span><span class="hl-1">.</span><span class="hl-6">scene</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">splatMesh</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">needsRender</span><span class="hl-1"> = </span><span class="hl-3">true</span><span class="hl-1">;</span><br/><span class="hl-1">});</span>
+<pre><code class="typescript"><span class="hl-10">import</span><span class="hl-1"> { </span><span class="hl-6">loadSplat</span><span class="hl-1"> } </span><span class="hl-10">from</span><span class="hl-1"> </span><span class="hl-9">&#39;@realsee/five-webgpu&#39;</span><span class="hl-1">;</span><br/><br/><span class="hl-5">loadSplat</span><span class="hl-1">(</span><span class="hl-9">&#39;https://example.com/scene.splat&#39;</span><span class="hl-1">, {</span><br/><span class="hl-1">  </span><span class="hl-6">modelUpAxis:</span><span class="hl-1"> </span><span class="hl-9">&#39;Y&#39;</span><span class="hl-1">, </span><span class="hl-8">// 假设原始数据是 Y-up</span><br/><span class="hl-1">  </span><span class="hl-6">upAxis:</span><span class="hl-1"> </span><span class="hl-9">&#39;Y&#39;</span><span class="hl-1">,      </span><span class="hl-8">// 转换到 Five 的 Y-up 运行时坐标系</span><br/><span class="hl-1">}).</span><span class="hl-5">then</span><span class="hl-1">((</span><span class="hl-6">result</span><span class="hl-1">) </span><span class="hl-3">=&gt;</span><span class="hl-1"> {</span><br/><span class="hl-1">  </span><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">splatMesh</span><span class="hl-1"> = </span><span class="hl-6">result</span><span class="hl-1">.</span><span class="hl-6">scene</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">splatMesh</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">needsRender</span><span class="hl-1"> = </span><span class="hl-3">true</span><span class="hl-1">;</span><br/><span class="hl-1">});</span>
 </code><button type="button">Copy</button></pre>
 
 <h3 id="进阶用法：自定义-ply-属性映射-custom-ply-properties" class="tsd-anchor-link">进阶用法：自定义 PLY 属性映射 (Custom PLY Properties)<a href="#进阶用法：自定义-ply-属性映射-custom-ply-properties" 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-10">import</span><span class="hl-1"> { </span><span class="hl-6">loadPly</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-5">loadPly</span><span class="hl-1">(</span><span class="hl-9">&#39;https://example.com/data.ply&#39;</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-9">&#39;pbmPointCloud&#39;</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-6">customPropertyMapping:</span><span class="hl-1"> {</span><br/><span class="hl-1">    </span><span class="hl-6">intensity:</span><span class="hl-1"> {</span><br/><span class="hl-1">      </span><span class="hl-6">itemType:</span><span class="hl-1"> </span><span class="hl-9">&#39;float32&#39;</span><span class="hl-1">,</span><br/><span class="hl-1">      </span><span class="hl-6">itemNames:</span><span class="hl-1"> [</span><span class="hl-9">&#39;intensity&#39;</span><span class="hl-1">],</span><br/><span class="hl-1">      </span><span class="hl-6">normalized:</span><span class="hl-1"> </span><span class="hl-3">true</span><br/><span class="hl-1">    }</span><br/><span class="hl-1">  }</span><br/><span class="hl-1">}).</span><span class="hl-5">then</span><span class="hl-1">((</span><span class="hl-6">result</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">// result.scene 是一个 PBMPointCloud 对象</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">result</span><span class="hl-1">.</span><span class="hl-6">scene</span><span class="hl-1">);</span><br/><span class="hl-1">});</span>
+<pre><code class="typescript"><span class="hl-10">import</span><span class="hl-1"> { </span><span class="hl-6">loadPly</span><span class="hl-1"> } </span><span class="hl-10">from</span><span class="hl-1"> </span><span class="hl-9">&#39;@realsee/five-webgpu&#39;</span><span class="hl-1">;</span><br/><br/><span class="hl-5">loadPly</span><span class="hl-1">(</span><span class="hl-9">&#39;https://example.com/data.ply&#39;</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-9">&#39;pbmPointCloud&#39;</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-6">customPropertyMapping:</span><span class="hl-1"> {</span><br/><span class="hl-1">    </span><span class="hl-6">intensity:</span><span class="hl-1"> {</span><br/><span class="hl-1">      </span><span class="hl-6">itemType:</span><span class="hl-1"> </span><span class="hl-9">&#39;float32&#39;</span><span class="hl-1">,</span><br/><span class="hl-1">      </span><span class="hl-6">itemNames:</span><span class="hl-1"> [</span><span class="hl-9">&#39;intensity&#39;</span><span class="hl-1">],</span><br/><span class="hl-1">      </span><span class="hl-6">normalized:</span><span class="hl-1"> </span><span class="hl-3">true</span><br/><span class="hl-1">    }</span><br/><span class="hl-1">  }</span><br/><span class="hl-1">}).</span><span class="hl-5">then</span><span class="hl-1">((</span><span class="hl-6">result</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">// result.scene 是一个 PBMPointCloud 对象</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">result</span><span class="hl-1">.</span><span class="hl-6">scene</span><span class="hl-1">);</span><br/><span class="hl-1">});</span>
 </code><button type="button">Copy</button></pre>
 
 <h3 id="基础用法：加载-obj-模型-basic-usage-obj" class="tsd-anchor-link">基础用法：加载 OBJ 模型 (Basic Usage - OBJ)<a href="#基础用法：加载-obj-模型-basic-usage-obj" 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-10">import</span><span class="hl-1"> { </span><span class="hl-6">loadObj</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-5">loadObj</span><span class="hl-1">(</span><span class="hl-9">&#39;https://example.com/model.obj&#39;</span><span class="hl-1">, {</span><br/><span class="hl-1">  </span><span class="hl-6">modelUpAxis:</span><span class="hl-1"> </span><span class="hl-9">&#39;Z&#39;</span><span class="hl-1">, </span><span class="hl-8">// OBJ 默认通常是 Z-up (或根据实际情况调整)</span><br/><span class="hl-1">}).</span><span class="hl-5">then</span><span class="hl-1">((</span><span class="hl-6">result</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-6">scene</span><span class="hl-1">.</span><span class="hl-5">add</span><span class="hl-1">(</span><span class="hl-6">result</span><span class="hl-1">.</span><span class="hl-6">scene</span><span class="hl-1">);</span><br/><span class="hl-1">  </span><span class="hl-8">// OBJ 文件中定义的 .mtl 材质会自动加载</span><br/><span class="hl-1">});</span>
+<pre><code class="typescript"><span class="hl-10">import</span><span class="hl-1"> { </span><span class="hl-6">loadObj</span><span class="hl-1"> } </span><span class="hl-10">from</span><span class="hl-1"> </span><span class="hl-9">&#39;@realsee/five-webgpu&#39;</span><span class="hl-1">;</span><br/><br/><span class="hl-5">loadObj</span><span class="hl-1">(</span><span class="hl-9">&#39;https://example.com/model.obj&#39;</span><span class="hl-1">, {</span><br/><span class="hl-1">  </span><span class="hl-6">modelUpAxis:</span><span class="hl-1"> </span><span class="hl-9">&#39;Z&#39;</span><span class="hl-1">, </span><span class="hl-8">// OBJ 默认通常是 Z-up (或根据实际情况调整)</span><br/><span class="hl-1">}).</span><span class="hl-5">then</span><span class="hl-1">((</span><span class="hl-6">result</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-6">scene</span><span class="hl-1">.</span><span class="hl-5">add</span><span class="hl-1">(</span><span class="hl-6">result</span><span class="hl-1">.</span><span class="hl-6">scene</span><span class="hl-1">);</span><br/><span class="hl-1">  </span><span class="hl-8">// OBJ 文件中定义的 .mtl 材质会自动加载</span><br/><span class="hl-1">});</span>
 </code><button type="button">Copy</button></pre>
 
 <h3 id="基础用法：加载-fbx-模型" class="tsd-anchor-link">基础用法：加载 FBX 模型<a href="#基础用法：加载-fbx-模型" 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-10">import</span><span class="hl-1"> { </span><span class="hl-6">loadFbx</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-5">loadFbx</span><span class="hl-1">(</span><span class="hl-9">&#39;https://example.com/model.fbx&#39;</span><span class="hl-1">).</span><span class="hl-5">then</span><span class="hl-1">((</span><span class="hl-6">result</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-6">scene</span><span class="hl-1">.</span><span class="hl-5">add</span><span class="hl-1">(</span><span class="hl-6">result</span><span class="hl-1">.</span><span class="hl-6">scene</span><span class="hl-1">);</span><br/><span class="hl-1">  </span><span class="hl-8">// 动画会自动解析到 result.animations</span><br/><span class="hl-1">});</span>
+<pre><code class="typescript"><span class="hl-10">import</span><span class="hl-1"> { </span><span class="hl-6">loadFbx</span><span class="hl-1"> } </span><span class="hl-10">from</span><span class="hl-1"> </span><span class="hl-9">&#39;@realsee/five-webgpu&#39;</span><span class="hl-1">;</span><br/><br/><span class="hl-5">loadFbx</span><span class="hl-1">(</span><span class="hl-9">&#39;https://example.com/model.fbx&#39;</span><span class="hl-1">).</span><span class="hl-5">then</span><span class="hl-1">((</span><span class="hl-6">result</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-6">scene</span><span class="hl-1">.</span><span class="hl-5">add</span><span class="hl-1">(</span><span class="hl-6">result</span><span class="hl-1">.</span><span class="hl-6">scene</span><span class="hl-1">);</span><br/><span class="hl-1">  </span><span class="hl-8">// 动画会自动解析到 result.animations</span><br/><span class="hl-1">});</span>
 </code><button type="button">Copy</button></pre>
 
 <h3 id="进阶用法：加载-dome-全景-panorama" class="tsd-anchor-link">进阶用法：加载 Dome 全景 (Panorama)<a href="#进阶用法：加载-dome-全景-panorama" 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-10">import</span><span class="hl-1"> { </span><span class="hl-6">loadDome</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">// 加载 .dome 或 .domez 格式</span><br/><span class="hl-5">loadDome</span><span class="hl-1">(</span><span class="hl-9">&#39;https://example.com/panorama.domez&#39;</span><span class="hl-1">, {</span><br/><span class="hl-1">  </span><span class="hl-6">light:</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><span class="hl-6">textureOptions:</span><span class="hl-1"> {</span><br/><span class="hl-1">    </span><span class="hl-6">size:</span><span class="hl-1"> </span><span class="hl-11">4096</span><span class="hl-1">, </span><span class="hl-8">// 限制最大纹理尺寸</span><br/><span class="hl-1">  }</span><br/><span class="hl-1">}).</span><span class="hl-5">then</span><span class="hl-1">((</span><span class="hl-6">result</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">result</span><span class="hl-1">.</span><span class="hl-6">scene</span><span class="hl-1">.</span><span class="hl-6">position</span><span class="hl-1">.</span><span class="hl-5">set</span><span class="hl-1">(</span><span class="hl-11">0</span><span class="hl-1">, </span><span class="hl-11">0</span><span class="hl-1">, </span><span class="hl-11">0</span><span class="hl-1">);</span><br/><span class="hl-1">  </span><span class="hl-6">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">result</span><span class="hl-1">.</span><span class="hl-6">scene</span><span class="hl-1">);</span><br/><span class="hl-1">});</span>
+<pre><code class="typescript"><span class="hl-10">import</span><span class="hl-1"> { </span><span class="hl-6">loadDome</span><span class="hl-1"> } </span><span class="hl-10">from</span><span class="hl-1"> </span><span class="hl-9">&#39;@realsee/five-webgpu&#39;</span><span class="hl-1">;</span><br/><br/><span class="hl-8">// 加载 .dome 或 .domez 格式</span><br/><span class="hl-5">loadDome</span><span class="hl-1">(</span><span class="hl-9">&#39;https://example.com/panorama.domez&#39;</span><span class="hl-1">, {</span><br/><span class="hl-1">  </span><span class="hl-6">light:</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><span class="hl-6">textureOptions:</span><span class="hl-1"> {</span><br/><span class="hl-1">    </span><span class="hl-6">size:</span><span class="hl-1"> </span><span class="hl-11">4096</span><span class="hl-1">, </span><span class="hl-8">// 限制最大纹理尺寸</span><br/><span class="hl-1">  }</span><br/><span class="hl-1">}).</span><span class="hl-5">then</span><span class="hl-1">((</span><span class="hl-6">result</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">result</span><span class="hl-1">.</span><span class="hl-6">scene</span><span class="hl-1">.</span><span class="hl-6">position</span><span class="hl-1">.</span><span class="hl-5">set</span><span class="hl-1">(</span><span class="hl-11">0</span><span class="hl-1">, </span><span class="hl-11">0</span><span class="hl-1">, </span><span class="hl-11">0</span><span class="hl-1">);</span><br/><span class="hl-1">  </span><span class="hl-6">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">result</span><span class="hl-1">.</span><span class="hl-6">scene</span><span class="hl-1">);</span><br/><span class="hl-1">});</span>
 </code><button type="button">Copy</button></pre>
 
 <h3 id="进阶用法：加载压缩模型-at3d" class="tsd-anchor-link">进阶用法：加载压缩模型 (AT3D)<a href="#进阶用法：加载压缩模型-at3d" 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-10">import</span><span class="hl-1"> { </span><span class="hl-6">loadAt3d</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-5">loadAt3d</span><span class="hl-1">(</span><span class="hl-9">&#39;https://example.com/model.at3d&#39;</span><span class="hl-1">, {</span><br/><span class="hl-1">  </span><span class="hl-6">light:</span><span class="hl-1"> </span><span class="hl-3">false</span><span class="hl-1">,</span><br/><span class="hl-1">}).</span><span class="hl-5">then</span><span class="hl-1">((</span><span class="hl-6">result</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-6">scene</span><span class="hl-1">.</span><span class="hl-5">add</span><span class="hl-1">(</span><span class="hl-6">result</span><span class="hl-1">.</span><span class="hl-6">scene</span><span class="hl-1">);</span><br/><span class="hl-1">});</span>
+<pre><code class="typescript"><span class="hl-10">import</span><span class="hl-1"> { </span><span class="hl-6">loadAt3d</span><span class="hl-1"> } </span><span class="hl-10">from</span><span class="hl-1"> </span><span class="hl-9">&#39;@realsee/five-webgpu&#39;</span><span class="hl-1">;</span><br/><br/><span class="hl-5">loadAt3d</span><span class="hl-1">(</span><span class="hl-9">&#39;https://example.com/model.at3d&#39;</span><span class="hl-1">, {</span><br/><span class="hl-1">  </span><span class="hl-6">light:</span><span class="hl-1"> </span><span class="hl-3">false</span><span class="hl-1">,</span><br/><span class="hl-1">}).</span><span class="hl-5">then</span><span class="hl-1">((</span><span class="hl-6">result</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-6">scene</span><span class="hl-1">.</span><span class="hl-5">add</span><span class="hl-1">(</span><span class="hl-6">result</span><span class="hl-1">.</span><span class="hl-6">scene</span><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>

package/docs/documents/features_load-progress.html

@@ -80,7 +80,7 @@
 
 <h4 id="tile-lifecycle-monitoring-tile-生命周期监控" class="tsd-anchor-link">Tile Lifecycle Monitoring (Tile 生命周期监控)<a href="#tile-lifecycle-monitoring-tile-生命周期监控" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h4>
 <p>监控单个 Tile 的加载与卸载事件，用于更精细的调试或资源统计。</p>
-<pre><code class="ts"><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;model.tileLoad&quot;</span><span class="hl-1">, (</span><span class="hl-6">tile</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">`Tile loaded: </span><span class="hl-3">${</span><span class="hl-6">tile</span><span class="hl-12">.</span><span class="hl-6">debugLabel</span><span class="hl-3">}</span><span class="hl-9">, Size: </span><span class="hl-3">${</span><span class="hl-6">tile</span><span class="hl-12">.</span><span class="hl-6">content</span><span class="hl-12">.</span><span class="hl-6">byteLength</span><span class="hl-3">}</span><span class="hl-9">`</span><span class="hl-1">);</span><br/><span class="hl-1">});</span><br/><br/><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-5">on</span><span class="hl-1">(</span><span class="hl-9">&quot;model.tileUnload&quot;</span><span class="hl-1">, (</span><span class="hl-6">tile</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">`Tile unloaded: </span><span class="hl-3">${</span><span class="hl-6">tile</span><span class="hl-12">.</span><span class="hl-6">debugLabel</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="ts"><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;models.tileLoad&quot;</span><span class="hl-1">, ({ </span><span class="hl-6">tile</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">`Tile loaded: </span><span class="hl-3">${</span><span class="hl-6">tile</span><span class="hl-12">.</span><span class="hl-6">debugLabel</span><span class="hl-3">}</span><span class="hl-9">, Size: </span><span class="hl-3">${</span><span class="hl-6">tile</span><span class="hl-12">.</span><span class="hl-6">content</span><span class="hl-12">.</span><span class="hl-6">byteLength</span><span class="hl-3">}</span><span class="hl-9">`</span><span class="hl-1">);</span><br/><span class="hl-1">});</span><br/><br/><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-5">on</span><span class="hl-1">(</span><span class="hl-9">&quot;models.tileUnload&quot;</span><span class="hl-1">, ({ </span><span class="hl-6">tile</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">`Tile unloaded: </span><span class="hl-3">${</span><span class="hl-6">tile</span><span class="hl-12">.</span><span class="hl-6">debugLabel</span><span class="hl-3">}</span><span class="hl-9">`</span><span class="hl-1">);</span><br/><span class="hl-1">});</span>
 </code><button type="button">Copy</button></pre>
 
 <h3 id="2-panorama-loading-全景图加载" class="tsd-anchor-link">2. Panorama Loading (全景图加载)<a href="#2-panorama-loading-全景图加载" 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>

package/docs/documents/features_material.html

@@ -40,15 +40,22 @@
 <li><strong>Shown Floor (<code>shownFloorIndex</code>)</strong>: 指定当前高亮显示的楼层索引。</li>
 </ul>
 <h3 id="4-vertex-marks-semantic-filtering-顶点标记与语义过滤" class="tsd-anchor-link">4. Vertex Marks &amp; Semantic Filtering (顶点标记与语义过滤)<a href="#4-vertex-marks-semantic-filtering-顶点标记与语义过滤" 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>vertexMarks</code> 是一个<strong>全局开关</strong>，用于控制是否启用模型顶点上的语义标记（<code>_feature_id_rsmask</code>）逻辑。</p>
+<p><code>vertexMarks</code> 用于控制模型顶点上的语义标记（<code>_feature_id_rsmask</code>）逻辑。它是一个<strong>按位掩码（bit flag）</strong>，可以独立开关多类标注，而不再是单一的全局 <code>boolean</code> 开关。</p>
 <ul>
-<li><strong>机制</strong>: 模型顶点预置了 <code>_feature_id_rsmask</code> 属性，不同的值代表不同的语义部分。</li>
-<li><strong>当前支持</strong>: 目前主要支持 <code>_feature_id_rsmask=1</code>（通常标记为天花板/房顶）。
+<li><strong>机制</strong>: 模型顶点预置了 <code>_feature_id_rsmask</code> 属性，不同的值代表不同的语义部分；每一类标注对应掩码中的一位，可按位独立启用。</li>
+<li><strong>标志位 (<code>PBMVertexMarkFlag</code>)</strong>:
 <ul>
-<li>当 <code>vertexMarks</code> 开启时，标记为 <code>1</code> 的顶点部分会在特定视角（如俯视）下自动隐藏，实现“开盖”效果，优化室内布局观测体验。</li>
+<li><code>PBMVertexMarkFlag.roof</code> (<code>0b00000010</code>): 开盖标注（<code>_feature_id_rsmask=1</code>）。开启后，命中屋顶标记的顶点会按 <code>roofStyle</code> 裁切：<code>AUTO</code> 随相机俯仰角渐进隐藏，<code>HIDE</code> 始终隐藏。</li>
+<li><code>PBMVertexMarkFlag.hidden</code> (<code>0b00000100</code>): 隐藏标注（<code>_feature_id_rsmask=2</code>）。开启后，命中隐藏标记且超过高度阈值的顶点会被裁掉。</li>
+<li><code>PBMVertexMarkFlag.none</code> (<code>0b00000000</code>): 不启用任何标注。</li>
+<li><code>PBMVertexMarkFlag.all</code> (<code>0b11111111</code>): 启用全部标注（默认全开，且包含未来新增的标注档位）。</li>
 </ul>
 </li>
-<li><strong>未来扩展</strong>: 该机制设计支持更多标记值，未来可能用于控制其他特定模型部件的显示效果。</li>
+<li><strong>按位组合</strong>: 使用按位或组合多个标志，例如同时开启开盖与隐藏：
+<code>PBMVertexMarkFlag.roof | PBMVertexMarkFlag.hidden</code>。</li>
+<li><strong>向后兼容</strong>: <code>vertexMarks</code> 仍接受 <code>boolean</code>。传入 <code>true</code> 等价于 <code>PBMVertexMarkFlag.all</code>（全开），<code>false</code> 等价于 <code>PBMVertexMarkFlag.none</code>（全关）。</li>
+<li><strong>与自定义节点的关系</strong>: 节点上下文中的 <code>isRoof</code> / <code>isHidden</code> 等标记判定<strong>始终可用</strong>，不受本开关影响；<code>vertexMarks</code> 只门控管线内置的自动裁切。</li>
+<li><strong>未来扩展</strong>: 新增标注档位时，只需在 <code>PBMVertexMarkFlag</code> 中追加一个新的位，不影响现有标志。</li>
 </ul>
 <h2 id="configuration" class="tsd-anchor-link">Configuration<a href="#configuration" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h2>
 <p>以下表格列出了控制材质与外观的可用参数，按使用频率和场景分类。</p>
@@ -113,9 +120,9 @@
 </tr>
 <tr>
 <td style="text-align:left"><code>vertexMarks</code></td>
-<td style="text-align:left"><code>boolean</code></td>
+<td style="text-align:left"><code>boolean | number</code></td>
 <td style="text-align:left"><code>true</code></td>
-<td style="text-align:left">是否显示/生效标注。</td>
+<td style="text-align:left">顶点标注开关，按位控制（见 Concepts）。<code>PBMVertexMarkFlag</code> 位掩码；传入 <code>boolean</code> 时 <code>true</code>=全开、<code>false</code>=全关。</td>
 </tr>
 <tr>
 <td style="text-align:left"><code>brightness</code></td>
@@ -328,6 +335,10 @@
 <pre><code class="typescript"><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">set</span><span class="hl-1">({</span><br/><span class="hl-1">  </span><span class="hl-6">pointSize:</span><span class="hl-1"> </span><span class="hl-9">&#39;ATTENUATION&#39;</span><span class="hl-1">, </span><span class="hl-8">// 大小随距离衰减</span><br/><span class="hl-1">  </span><span class="hl-6">pointScale:</span><span class="hl-1"> </span><span class="hl-11">0.05</span><span class="hl-1">,         </span><span class="hl-8">// 基础大小</span><br/><span class="hl-1">  </span><span class="hl-6">pointMaxPixel:</span><span class="hl-1"> </span><span class="hl-11">20</span><span class="hl-1">         </span><span class="hl-8">// 最大像素限制</span><br/><span class="hl-1">});</span>
 </code><button type="button">Copy</button></pre>
 
+<h3 id="3-toggling-vertex-marks-控制顶点标注" class="tsd-anchor-link">3. Toggling Vertex Marks (控制顶点标注)<a href="#3-toggling-vertex-marks-控制顶点标注" 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-10">import</span><span class="hl-1"> { </span><span class="hl-6">PBMVertexMarkFlag</span><span class="hl-1"> } </span><span class="hl-10">from</span><span class="hl-1"> </span><span class="hl-9">&#39;@realsee/five-webgpu&#39;</span><span class="hl-1">;</span><br/><br/><span class="hl-8">// 仅开启“开盖”标注</span><br/><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-6">model</span><span class="hl-1">.</span><span class="hl-5">set</span><span class="hl-1">({ </span><span class="hl-6">vertexMarks:</span><span class="hl-1"> </span><span class="hl-6">PBMVertexMarkFlag</span><span class="hl-1">.</span><span class="hl-6">roof</span><span class="hl-1"> });</span><br/><br/><span class="hl-8">// 同时开启“开盖”与“隐藏”标注</span><br/><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-6">model</span><span class="hl-1">.</span><span class="hl-5">set</span><span class="hl-1">({</span><br/><span class="hl-1">  </span><span class="hl-6">vertexMarks:</span><span class="hl-1"> </span><span class="hl-6">PBMVertexMarkFlag</span><span class="hl-1">.</span><span class="hl-6">roof</span><span class="hl-1"> | </span><span class="hl-6">PBMVertexMarkFlag</span><span class="hl-1">.</span><span class="hl-6">hidden</span><span class="hl-1">,</span><br/><span class="hl-1">});</span><br/><br/><span class="hl-8">// 关闭全部标注</span><br/><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-6">model</span><span class="hl-1">.</span><span class="hl-5">set</span><span class="hl-1">({ </span><span class="hl-6">vertexMarks:</span><span class="hl-1"> </span><span class="hl-6">PBMVertexMarkFlag</span><span class="hl-1">.</span><span class="hl-6">none</span><span class="hl-1"> });</span><br/><br/><span class="hl-8">// 向后兼容：true 等价于全开，false 等价于全关</span><br/><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-6">model</span><span class="hl-1">.</span><span class="hl-5">set</span><span class="hl-1">({ </span><span class="hl-6">vertexMarks:</span><span class="hl-1"> </span><span class="hl-3">true</span><span class="hl-1"> });</span>
+</code><button type="button">Copy</button></pre>
+
 <h2 id="related" class="tsd-anchor-link">Related<a href="#related" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h2>
 <ul>
 <li><a href="features_parameter.html">Parameter</a>: 配置系统入口与继承逻辑。</li>
@@ -335,7 +346,7 @@
 <li><a href="features_3dtile.html">3DTile Params</a>: 性能与加载相关参数。</li>
 </ul>
 <hr>
-<pre><code class="yaml"><span class="hl-0">tags</span><span class="hl-1">: [</span><span class="hl-2">material</span><span class="hl-1">, </span><span class="hl-2">appearance</span><span class="hl-1">, </span><span class="hl-2">pointcloud</span><span class="hl-1">, </span><span class="hl-2">parameter</span><span class="hl-1">, </span><span class="hl-2">roof</span><span class="hl-1">, </span><span class="hl-2">ceiling</span><span class="hl-1">, </span><span class="hl-2">config</span><span class="hl-1">]</span>
+<pre><code class="yaml"><span class="hl-0">tags</span><span class="hl-1">: [</span><span class="hl-2">material</span><span class="hl-1">, </span><span class="hl-2">appearance</span><span class="hl-1">, </span><span class="hl-2">pointcloud</span><span class="hl-1">, </span><span class="hl-2">parameter</span><span class="hl-1">, </span><span class="hl-2">roof</span><span class="hl-1">, </span><span class="hl-2">hidden</span><span class="hl-1">, </span><span class="hl-2">ceiling</span><span class="hl-1">, </span><span class="hl-2">开盖</span><span class="hl-1">, </span><span class="hl-2">隐藏</span><span class="hl-1">, </span><span class="hl-2">顶点标记</span><span class="hl-1">, </span><span class="hl-2">位掩码</span><span class="hl-1">, </span><span class="hl-2">bitmask</span><span class="hl-1">, </span><span class="hl-2">vertex-mark</span><span class="hl-1">, </span><span class="hl-2">config</span><span class="hl-1">]</span>
 </code><button type="button">Copy</button></pre>
 
-</div></div><div class="col-sidebar"><div class="page-menu"><div class="tsd-navigation settings"><details class="tsd-accordion"><summary class="tsd-accordion-summary"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-chevronDown"></use></svg><h3>Settings</h3></summary><div class="tsd-accordion-details"><div class="tsd-filter-visibility"><span class="settings-label">Member Visibility</span><ul id="tsd-filter-options"><li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-inherited" name="inherited" checked/><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></svg><span>Inherited</span></label></li></ul></div><div class="tsd-theme-toggle"><label class="settings-label" for="tsd-theme">Theme</label><select id="tsd-theme"><option value="os">OS</option><option value="light">Light</option><option value="dark">Dark</option></select></div></div></details></div><details open class="tsd-accordion tsd-page-navigation"><summary class="tsd-accordion-summary"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-chevronDown"></use></svg><h3>On This Page</h3></summary><div class="tsd-accordion-details"><a href="#material-parameters-材质参数"><span>Material <wbr/>Parameters (材质参数)</span></a><ul><li><a href="#schema"><span>Schema</span></a></li><li><a href="#concepts"><span>Concepts</span></a></li><li><ul><li><a href="#1-transparency-blending-透明度与混合"><span>1. <wbr/>Transparency &amp; <wbr/>Blending (透明度与混合)</span></a></li><li><a href="#2-point-cloud-rendering-点云渲染"><span>2. <wbr/>Point <wbr/>Cloud <wbr/>Rendering (点云渲染)</span></a></li><li><a href="#3-floor-management-楼层管理"><span>3. <wbr/>Floor <wbr/>Management (楼层管理)</span></a></li><li><a href="#4-vertex-marks-semantic-filtering-顶点标记与语义过滤"><span>4. <wbr/>Vertex <wbr/>Marks &amp; <wbr/>Semantic <wbr/>Filtering (顶点标记与语义过滤)</span></a></li></ul></li><li><a href="#configuration"><span>Configuration</span></a></li><li><ul><li><a href="#common-configuration-常用配置"><span>Common <wbr/>Configuration (常用配置)</span></a></li><li><a href="#advanced-appearance-进阶外观配置"><span>Advanced <wbr/>Appearance (进阶外观配置)</span></a></li><li><a href="#internal-low-level-内部与底层配置"><span>Internal &amp; <wbr/>Low-<wbr/>Level (内部与底层配置)</span></a></li></ul></li><li><a href="#examples"><span>Examples</span></a></li><li><ul><li><a href="#1-adjusting-model-transparency-and-style-调整模型透明度与样式"><span>1. <wbr/>Adjusting <wbr/>Model <wbr/>Transparency and <wbr/>Style (调整模型透明度与样式)</span></a></li><li><a href="#2-configuring-point-cloud-appearance-配置点云外观"><span>2. <wbr/>Configuring <wbr/>Point <wbr/>Cloud <wbr/>Appearance (配置点云外观)</span></a></li></ul></li><li><a href="#related"><span>Related</span></a></li></ul></div></details></div><div class="site-menu"><nav class="tsd-navigation"><a href="../modules.html">如视 Five SDK</a><ul class="tsd-small-nested-navigation" id="tsd-nav-container"><li>Loading...</li></ul></nav></div></div></div><footer><p class="tsd-generator">Generated using <a href="https://typedoc.org/" target="_blank">TypeDoc</a></p></footer><div class="overlay"></div></body></html>
+</div></div><div class="col-sidebar"><div class="page-menu"><div class="tsd-navigation settings"><details class="tsd-accordion"><summary class="tsd-accordion-summary"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-chevronDown"></use></svg><h3>Settings</h3></summary><div class="tsd-accordion-details"><div class="tsd-filter-visibility"><span class="settings-label">Member Visibility</span><ul id="tsd-filter-options"><li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-inherited" name="inherited" checked/><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></svg><span>Inherited</span></label></li></ul></div><div class="tsd-theme-toggle"><label class="settings-label" for="tsd-theme">Theme</label><select id="tsd-theme"><option value="os">OS</option><option value="light">Light</option><option value="dark">Dark</option></select></div></div></details></div><details open class="tsd-accordion tsd-page-navigation"><summary class="tsd-accordion-summary"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-chevronDown"></use></svg><h3>On This Page</h3></summary><div class="tsd-accordion-details"><a href="#material-parameters-材质参数"><span>Material <wbr/>Parameters (材质参数)</span></a><ul><li><a href="#schema"><span>Schema</span></a></li><li><a href="#concepts"><span>Concepts</span></a></li><li><ul><li><a href="#1-transparency-blending-透明度与混合"><span>1. <wbr/>Transparency &amp; <wbr/>Blending (透明度与混合)</span></a></li><li><a href="#2-point-cloud-rendering-点云渲染"><span>2. <wbr/>Point <wbr/>Cloud <wbr/>Rendering (点云渲染)</span></a></li><li><a href="#3-floor-management-楼层管理"><span>3. <wbr/>Floor <wbr/>Management (楼层管理)</span></a></li><li><a href="#4-vertex-marks-semantic-filtering-顶点标记与语义过滤"><span>4. <wbr/>Vertex <wbr/>Marks &amp; <wbr/>Semantic <wbr/>Filtering (顶点标记与语义过滤)</span></a></li></ul></li><li><a href="#configuration"><span>Configuration</span></a></li><li><ul><li><a href="#common-configuration-常用配置"><span>Common <wbr/>Configuration (常用配置)</span></a></li><li><a href="#advanced-appearance-进阶外观配置"><span>Advanced <wbr/>Appearance (进阶外观配置)</span></a></li><li><a href="#internal-low-level-内部与底层配置"><span>Internal &amp; <wbr/>Low-<wbr/>Level (内部与底层配置)</span></a></li></ul></li><li><a href="#examples"><span>Examples</span></a></li><li><ul><li><a href="#1-adjusting-model-transparency-and-style-调整模型透明度与样式"><span>1. <wbr/>Adjusting <wbr/>Model <wbr/>Transparency and <wbr/>Style (调整模型透明度与样式)</span></a></li><li><a href="#2-configuring-point-cloud-appearance-配置点云外观"><span>2. <wbr/>Configuring <wbr/>Point <wbr/>Cloud <wbr/>Appearance (配置点云外观)</span></a></li><li><a href="#3-toggling-vertex-marks-控制顶点标注"><span>3. <wbr/>Toggling <wbr/>Vertex <wbr/>Marks (控制顶点标注)</span></a></li></ul></li><li><a href="#related"><span>Related</span></a></li></ul></div></details></div><div class="site-menu"><nav class="tsd-navigation"><a href="../modules.html">如视 Five SDK</a><ul class="tsd-small-nested-navigation" id="tsd-nav-container"><li>Loading...</li></ul></nav></div></div></div><footer><p class="tsd-generator">Generated using <a href="https://typedoc.org/" target="_blank">TypeDoc</a></p></footer><div class="overlay"></div></body></html>