@realsee/five-webgpu 1.0.0-alpha.5 → 1.0.0-alpha.7

package/docs/documents/features_five.html

@@ -12,7 +12,7 @@
 <p><strong>Definition</strong>: <a href="../../five/application/fiveInitArgs.d.ts">FiveInitArgs</a></p>
 </blockquote>
 <p><code>new Five(args)</code> 的初始化参数对象。</p>
-<pre><code class="typescript"><span class="hl-3">interface</span><span class="hl-1"> </span><span class="hl-7">FiveInitArgs</span><span class="hl-1"> {</span><br/><span class="hl-1">  </span><span class="hl-8">/** 外部传入的渲染器 (如果传入，部分渲染配置将失效) */</span><br/><span class="hl-1">  </span><span class="hl-6">renderer</span><span class="hl-1">?: </span><span class="hl-7">THREE</span><span class="hl-1">.</span><span class="hl-7">WebGLRenderer</span><span class="hl-1">;</span><br/><span class="hl-1">  </span><span class="hl-8">/**</span><br/><span class="hl-8">   * 屏幕渲染区域 { left, bottom, width, height }</span><br/><span class="hl-8">   * 必须配合外部 renderer 使用</span><br/><span class="hl-8">   */</span><br/><span class="hl-1">  </span><span class="hl-6">viewport</span><span class="hl-1">?: </span><span class="hl-7">Viewport</span><span class="hl-1">;</span><br/><span class="hl-1">  </span><span class="hl-8">/** 背景颜色 (默认 0x181A1C) */</span><br/><span class="hl-1">  </span><span class="hl-6">backgroundColor</span><span class="hl-1">?: </span><span class="hl-7">number</span><span class="hl-1"> | </span><span class="hl-7">THREE</span><span class="hl-1">.</span><span class="hl-7">Color</span><span class="hl-1">;</span><br/><span class="hl-1">  </span><span class="hl-8">/** 背景透明度 (0-1, 默认 1) */</span><br/><span class="hl-1">  </span><span class="hl-6">backgroundAlpha</span><span class="hl-1">?: </span><span class="hl-7">number</span><span class="hl-1">;</span><br/><span class="hl-1">  </span><span class="hl-8">/** 是否开启抗锯齿 (默认 false) */</span><br/><span class="hl-1">  </span><span class="hl-6">antialias</span><span class="hl-1">?: </span><span class="hl-7">boolean</span><span class="hl-1">;</span><br/><span class="hl-1">  </span><span class="hl-8">/** 全景图配置 (见 image-options.md) */</span><br/><span class="hl-1">  </span><span class="hl-6">imageOptions</span><span class="hl-1">?: </span><span class="hl-7">ImageOptions</span><span class="hl-1">;</span><br/><span class="hl-1">  </span><span class="hl-8">/** 贴图配置 (见 image-options.md) */</span><br/><span class="hl-1">  </span><span class="hl-6">textureOptions</span><span class="hl-1">?: </span><span class="hl-7">TextureOptions</span><span class="hl-1">;</span><br/><span class="hl-1">  </span><span class="hl-8">/** 是否按需渲染 (默认 true, 推荐开启以节省性能) */</span><br/><span class="hl-1">  </span><span class="hl-6">onlyRenderIfNeeds</span><span class="hl-1">?: </span><span class="hl-7">boolean</span><span class="hl-1">;</span><br/><span class="hl-1">  </span><span class="hl-8">/** 模式切换动画时长 (ms, 默认 1000) */</span><br/><span class="hl-1">  </span><span class="hl-6">modeChangeDuration</span><span class="hl-1">?: </span><span class="hl-7">number</span><span class="hl-1">;</span><br/><span class="hl-1">  </span><span class="hl-8">/** 是否支持滚轮缩放 (默认 true) */</span><br/><span class="hl-1">  </span><span class="hl-6">enableWheel</span><span class="hl-1">?: </span><span class="hl-7">boolean</span><span class="hl-1">;</span><br/><span class="hl-1">  </span><span class="hl-8">/** 插件列表 */</span><br/><span class="hl-1">  </span><span class="hl-6">plugins</span><span class="hl-1">?: </span><span class="hl-7">FivePlugin</span><span class="hl-1">[];</span><br/><span class="hl-1">  </span><span class="hl-8">/** 是否显示 Powered by Realsee */</span><br/><span class="hl-1">  </span><span class="hl-6">poweredByRealsee</span><span class="hl-1">?: </span><span class="hl-7">boolean</span><span class="hl-1">;</span><br/><span class="hl-1">}</span>
+<pre><code class="typescript"><span class="hl-3">interface</span><span class="hl-1"> </span><span class="hl-7">FiveInitArgs</span><span class="hl-1"> {</span><br/><span class="hl-1">  </span><span class="hl-8">/** 外部传入的渲染器 (如果传入，部分渲染配置将失效) */</span><br/><span class="hl-1">  </span><span class="hl-6">renderer</span><span class="hl-1">?: </span><span class="hl-7">THREE</span><span class="hl-1">.</span><span class="hl-7">WebGPURenderer</span><span class="hl-1">;</span><br/><span class="hl-1">  </span><span class="hl-8">/**</span><br/><span class="hl-8">   * 屏幕渲染区域 { left, bottom, width, height }</span><br/><span class="hl-8">   * 必须配合外部 renderer 使用</span><br/><span class="hl-8">   */</span><br/><span class="hl-1">  </span><span class="hl-6">viewport</span><span class="hl-1">?: </span><span class="hl-7">Viewport</span><span class="hl-1">;</span><br/><span class="hl-1">  </span><span class="hl-8">/** 背景颜色 (默认 0x181A1C) */</span><br/><span class="hl-1">  </span><span class="hl-6">backgroundColor</span><span class="hl-1">?: </span><span class="hl-7">number</span><span class="hl-1"> | </span><span class="hl-7">THREE</span><span class="hl-1">.</span><span class="hl-7">Color</span><span class="hl-1">;</span><br/><span class="hl-1">  </span><span class="hl-8">/** 背景透明度 (0-1, 默认 1) */</span><br/><span class="hl-1">  </span><span class="hl-6">backgroundAlpha</span><span class="hl-1">?: </span><span class="hl-7">number</span><span class="hl-1">;</span><br/><span class="hl-1">  </span><span class="hl-8">/** 是否开启抗锯齿 (默认 false) */</span><br/><span class="hl-1">  </span><span class="hl-6">antialias</span><span class="hl-1">?: </span><span class="hl-7">boolean</span><span class="hl-1">;</span><br/><span class="hl-1">  </span><span class="hl-8">/** 全景图配置 (见 image-options.md) */</span><br/><span class="hl-1">  </span><span class="hl-6">imageOptions</span><span class="hl-1">?: </span><span class="hl-7">ImageOptions</span><span class="hl-1">;</span><br/><span class="hl-1">  </span><span class="hl-8">/** 贴图配置 (见 image-options.md) */</span><br/><span class="hl-1">  </span><span class="hl-6">textureOptions</span><span class="hl-1">?: </span><span class="hl-7">TextureOptions</span><span class="hl-1">;</span><br/><span class="hl-1">  </span><span class="hl-8">/** 是否按需渲染 (默认 true, 推荐开启以节省性能) */</span><br/><span class="hl-1">  </span><span class="hl-6">onlyRenderIfNeeds</span><span class="hl-1">?: </span><span class="hl-7">boolean</span><span class="hl-1">;</span><br/><span class="hl-1">  </span><span class="hl-8">/** 模式切换动画时长 (ms, 默认 800) */</span><br/><span class="hl-1">  </span><span class="hl-6">modeChangeDuration</span><span class="hl-1">?: </span><span class="hl-7">number</span><span class="hl-1">;</span><br/><span class="hl-1">  </span><span class="hl-8">/** 是否支持滚轮缩放 (默认 true) */</span><br/><span class="hl-1">  </span><span class="hl-6">enableWheel</span><span class="hl-1">?: </span><span class="hl-7">boolean</span><span class="hl-1">;</span><br/><span class="hl-1">  </span><span class="hl-8">/** 插件列表 */</span><br/><span class="hl-1">  </span><span class="hl-6">plugins</span><span class="hl-1">?: </span><span class="hl-7">FivePlugin</span><span class="hl-1">[];</span><br/><span class="hl-1">  </span><span class="hl-8">/** 是否显示 Powered by Realsee */</span><br/><span class="hl-1">  </span><span class="hl-6">poweredByRealsee</span><span class="hl-1">?: </span><span class="hl-7">boolean</span><span class="hl-1">;</span><br/><span class="hl-1">  </span><span class="hl-8">/**</span><br/><span class="hl-8">   * 强制使用 WebGL2 回落后端（默认 false）</span><br/><span class="hl-8">   * 进入 XRPanorama（WebXR 头显全景）的前置条件。</span><br/><span class="hl-8">   * 只在构造期生效，后端无法在运行时切换，设备检测必须在 new Five() 之前完成。</span><br/><span class="hl-8">   * 详见下方《forceWebGL 与 XR 回落后端》。</span><br/><span class="hl-8">   */</span><br/><span class="hl-1">  </span><span class="hl-6">forceWebGL</span><span class="hl-1">?: </span><span class="hl-7">boolean</span><span class="hl-1">;</span><br/><span class="hl-1">  </span><span class="hl-8">/**</span><br/><span class="hl-8">   * </span><span class="hl-3">@deprecated</span><span class="hl-8"> 在 five-webgpu 中未接线、无效。需要 WebGL2 后端请使用 `forceWebGL`。</span><br/><span class="hl-8">   */</span><br/><span class="hl-1">  </span><span class="hl-6">webgl2</span><span class="hl-1">?: </span><span class="hl-7">boolean</span><span class="hl-1">;</span><br/><span class="hl-1">}</span>
 </code><button type="button">Copy</button></pre>
 
 <h2 id="concepts" class="tsd-anchor-link">Concepts<a href="#concepts" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h2>
@@ -25,7 +25,7 @@
 <h3 id="rendering-loop-渲染循环" class="tsd-anchor-link">Rendering Loop (渲染循环)<a href="#rendering-loop-渲染循环" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3>
 <p>Five 内部维护了一个 <code>requestAnimationFrame</code> 循环。</p>
 <ul>
-<li><strong>按需渲染</strong>: 默认开启 <code>onlyRenderIfNeeds</code>，仅在画面发生变化（如视角移动、数据加载）时才触发 WebGL 绘制，大幅降低能耗。</li>
+<li><strong>按需渲染</strong>: 默认开启 <code>onlyRenderIfNeeds</code>，仅在画面发生变化（如视角移动、数据加载）时才触发渲染，大幅降低能耗。</li>
 <li><strong>手动触发</strong>: 可以通过 <code>five.needsRender = true</code> 强制下一帧进行渲染。</li>
 </ul>
 <h3 id="resource-loading-资源加载" class="tsd-anchor-link">Resource Loading (资源加载)<a href="#resource-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>
@@ -72,7 +72,7 @@
 <tr>
 <td style="text-align:left"><code>modeChangeDuration</code></td>
 <td style="text-align:left"><code>number</code></td>
-<td style="text-align:left"><code>1000</code></td>
+<td style="text-align:left"><code>800</code></td>
 <td style="text-align:left">模式切换动画时长 (ms)</td>
 </tr>
 <tr>
@@ -81,8 +81,50 @@
 <td style="text-align:left"><code>true</code></td>
 <td style="text-align:left">是否支持滚轮缩放</td>
 </tr>
+<tr>
+<td style="text-align:left"><code>forceWebGL</code></td>
+<td style="text-align:left"><code>boolean</code></td>
+<td style="text-align:left"><code>false</code></td>
+<td style="text-align:left">强制使用 WebGL2 回落后端，进入 <code>XRPanorama</code> 的前置条件，详见下文</td>
+</tr>
+<tr>
+<td style="text-align:left"><code>webgl2</code></td>
+<td style="text-align:left"><code>boolean</code></td>
+<td style="text-align:left">—</td>
+<td style="text-align:left"><strong>已废弃</strong>，在 five-webgpu 中未接线。需要 WebGL2 请用 <code>forceWebGL</code></td>
+</tr>
 </tbody>
 </table>
+<h3 id="forcewebgl-与-xr-回落后端" class="tsd-anchor-link">forceWebGL 与 XR 回落后端<a href="#forcewebgl-与-xr-回落后端" 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>forceWebGL</code> 让 five-webgpu 强制走 WebGL2 回落后端，而不是默认的 WebGPU 后端。它存在的唯一原因是 <strong>进入 <code>XRPanorama</code>（WebXR 头显全景）模式</strong>：<code>three</code> 的 WebGPU 后端目前不支持 WebXR，而 WebGL2 后端下 <code>renderer.xr</code> 完整可用。</p>
+<p><strong>语义与使用约束</strong></p>
+<ul>
+<li><strong>语义</strong>：<code>forceWebGL: true</code> 时，内部 <code>WebGPURenderer</code> 以 <code>{ forceWebGL: true }</code> 构造，使用 <code>WebGLBackend</code> 而非 WebGPU。</li>
+<li><strong>必须在 <code>new Five()</code> 时决定</strong>：后端在 renderer 构造期定死，<strong>运行时无法切换</strong>。因此业务侧的「是否需要进入 XR」的设备检测必须发生在 <code>new Five()</code> 之前，不能等实例创建后再改。</li>
+<li><strong>与 <code>enableHDR</code> 互斥</strong>：当 <code>forceWebGL</code> 为 <code>true</code> 时 <code>enableHDR</code> 不生效（<code>five.enableHDR</code> 会被置为 <code>false</code>），因为 XR 的 projection layer 固定 <code>colorFormat: RGBA8</code>，HDR 没有落地路径。</li>
+<li><strong>传入外部 <code>renderer</code> 时不生效</strong>：如果通过 <code>renderer</code> 参数传入了外部渲染器，<code>forceWebGL</code> 不会对其生效，需由调用方自行在构造该 renderer 时设置 <code>forceWebGL</code>（与 <code>antialias</code> 等参数一致）。</li>
+<li><strong><code>webgl2</code> 已废弃</strong>：遗留的 <code>webgl2</code> 参数在 five-webgpu 中未接线、无任何效果；需要 WebGL2 后端请改用 <code>forceWebGL</code>。</li>
+</ul>
+<p><strong>能力降级限制</strong>（开启 <code>forceWebGL</code> 后不可规避）</p>
+<ol>
+<li><strong>XR 下没有后处理</strong>：<code>XRPanorama</code> 模式会整体旁路 <code>FiveRenderer</code> 的后处理链路（合成 / EffectComposer 全屏 pass 均不参与），滤镜、泛光等后处理在头显中不生效。</li>
+<li><strong>点云走 NodeMaterial 路径</strong>：<code>forceWebGL</code> 下点云不再走 WebGPU compute 光栅化，而是退回 NodeMaterial 渲染路径。</li>
+<li><strong>3DGS 走 CPU 排序，且 VR 中性能预期需放低</strong>：<code>forceWebGL</code> 下 3DGS 只能走 CPU 排序（<code>RASTER_CPU_SORT</code>）；在 XR 中还要叠加双眼渲染开销，务必对点数 / 显示做降级，不要期待与 WebGPU 后端相同的帧率。</li>
+</ol>
+<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-8">// 设备检测需在 new Five() 之前完成</span><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">needXR</span><span class="hl-1"> = </span><span class="hl-5">detectNeedXR</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">forceWebGL:</span><span class="hl-1"> </span><span class="hl-6">needXR</span><span class="hl-1">, </span><span class="hl-8">// 一旦创建就无法再切换后端</span><br/><span class="hl-1">});</span><br/><br/><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-5">load</span><span class="hl-1">(</span><span class="hl-6">workData</span><span class="hl-1">);</span><br/><br/><span class="hl-8">// 进入 XR（需在用户手势回调中调用，会触发 WebXR 权限请求）</span><br/><span class="hl-6">button</span><span class="hl-1">.</span><span class="hl-5">addEventListener</span><span class="hl-1">(</span><span class="hl-9">&quot;click&quot;</span><span class="hl-1">, () </span><span class="hl-3">=&gt;</span><span class="hl-1"> {</span><br/><span class="hl-1">  </span><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-5">changeMode</span><span class="hl-1">(</span><span class="hl-9">&quot;XRPanorama&quot;</span><span class="hl-1">).</span><span class="hl-5">catch</span><span class="hl-1">((</span><span class="hl-6">error</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">// 后端非 WebGL2 或浏览器不支持 WebXR 时，这里会收到含 forceWebGL 字样的中文错误</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-6">error</span><span class="hl-1">);</span><br/><span class="hl-1">  });</span><br/><span class="hl-1">});</span><br/><br/><span class="hl-8">// 用户摘下头显 / 退出 XR 时切回普通全景</span><br/><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-5">on</span><span class="hl-1">(</span><span class="hl-9">&quot;xr.session.end&quot;</span><span class="hl-1">, () </span><span class="hl-3">=&gt;</span><span class="hl-1"> </span><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-5">changeMode</span><span class="hl-1">(</span><span class="hl-9">&quot;Panorama&quot;</span><span class="hl-1">));</span>
+</code><button type="button">Copy</button></pre>
+
+<p>也可以直接使用内置的 <code>XRButton</code>，样式与 API 同原始 five 保持一致（<code>XRButton.createButton(onClickHook)</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-6">XRButton</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">button</span><span class="hl-1"> = </span><span class="hl-6">XRButton</span><span class="hl-1">.</span><span class="hl-5">createButton</span><span class="hl-1">(() </span><span class="hl-3">=&gt;</span><span class="hl-1"> </span><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-5">changeMode</span><span class="hl-1">(</span><span class="hl-9">&quot;XRPanorama&quot;</span><span class="hl-1">));</span><br/><span class="hl-6">document</span><span class="hl-1">.</span><span class="hl-6">body</span><span class="hl-1">.</span><span class="hl-5">appendChild</span><span class="hl-1">(</span><span class="hl-6">button</span><span class="hl-1">);</span>
+</code><button type="button">Copy</button></pre>
+
+<ul>
+<li>浏览器没有 <code>navigator.xr</code> 时显示 <code>WEBXR NOT AVAILABLE</code>（非 HTTPS 时显示 <code>WEBXR NEEDS HTTPS</code>），不支持 <code>immersive-vr</code> 时显示 <code>VR NOT SUPPORTED</code>。</li>
+<li>回调返回 Promise 时，<code>XRButton</code> 会接住 reject。若失败原因是没有开启 <code>forceWebGL</code>（后端是 WebGPU），按钮文案会临时变为「需降级到 WebGL2」，3 秒后恢复。其他失败原因不改变按钮，错误通过 <code>five.on(&quot;error&quot;)</code> 上报。</li>
+</ul>
+<blockquote>
+<p>更多模式说明（含 <code>XRPanorama</code> 与 <code>VRPanorama</code> 的区别）见 <a href="features_mode.html">mode.md</a>，可运行示例参见 <code>examples/xr</code>。</p>
+</blockquote>
 <h2 id="examples" class="tsd-anchor-link">Examples<a href="#examples" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h2>
 <h3 id="快速上手-quick-example" class="tsd-anchor-link">快速上手 (Quick Example)<a href="#快速上手-quick-example" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3>
 <p>创建一个全屏的 Five 实例并加载数据。</p>
@@ -91,7 +133,7 @@
 
 <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>使用外部渲染器并指定视口区域（例如用于分屏渲染）。</p>
-<pre><code class="typescript"><span class="hl-10">import</span><span class="hl-1"> </span><span class="hl-3">*</span><span class="hl-1"> </span><span class="hl-10">as</span><span class="hl-1"> </span><span class="hl-6">THREE</span><span class="hl-1"> </span><span class="hl-10">from</span><span class="hl-1"> </span><span class="hl-9">&quot;three/webgpu&quot;</span><span class="hl-1">;</span><br/><span class="hl-10">import</span><span class="hl-1"> { </span><span class="hl-6">Five</span><span class="hl-1"> } </span><span class="hl-10">from</span><span class="hl-1"> </span><span class="hl-9">&quot;@realsee/five-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">renderer</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">WebGLRenderer</span><span class="hl-1">();</span><br/><span class="hl-6">renderer</span><span class="hl-1">.</span><span class="hl-5">setSize</span><span class="hl-1">(</span><span class="hl-6">window</span><span class="hl-1">.</span><span class="hl-6">innerWidth</span><span class="hl-1">, </span><span class="hl-6">window</span><span class="hl-1">.</span><span class="hl-6">innerHeight</span><span class="hl-1">);</span><br/><span class="hl-6">document</span><span class="hl-1">.</span><span class="hl-6">body</span><span class="hl-1">.</span><span class="hl-5">appendChild</span><span class="hl-1">(</span><span class="hl-6">renderer</span><span class="hl-1">.</span><span class="hl-6">domElement</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">renderer:</span><span class="hl-1"> </span><span class="hl-6">renderer</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-6">viewport:</span><span class="hl-1"> { </span><span class="hl-6">left:</span><span class="hl-1"> </span><span class="hl-11">0</span><span class="hl-1">, </span><span class="hl-6">bottom:</span><span class="hl-1"> </span><span class="hl-11">0</span><span class="hl-1">, </span><span class="hl-6">width:</span><span class="hl-1"> </span><span class="hl-11">0.5</span><span class="hl-1">, </span><span class="hl-6">height:</span><span class="hl-1"> </span><span class="hl-11">1</span><span class="hl-1"> } </span><span class="hl-8">// 仅占用左半屏</span><br/><span class="hl-1">});</span><br/><br/><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-5">load</span><span class="hl-1">(</span><span class="hl-6">workData</span><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">&quot;three/webgpu&quot;</span><span class="hl-1">;</span><br/><span class="hl-10">import</span><span class="hl-1"> { </span><span class="hl-6">Five</span><span class="hl-1"> } </span><span class="hl-10">from</span><span class="hl-1"> </span><span class="hl-9">&quot;@realsee/five-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">renderer</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">WebGPURenderer</span><span class="hl-1">();</span><br/><span class="hl-6">renderer</span><span class="hl-1">.</span><span class="hl-5">setSize</span><span class="hl-1">(</span><span class="hl-6">window</span><span class="hl-1">.</span><span class="hl-6">innerWidth</span><span class="hl-1">, </span><span class="hl-6">window</span><span class="hl-1">.</span><span class="hl-6">innerHeight</span><span class="hl-1">);</span><br/><span class="hl-6">document</span><span class="hl-1">.</span><span class="hl-6">body</span><span class="hl-1">.</span><span class="hl-5">appendChild</span><span class="hl-1">(</span><span class="hl-6">renderer</span><span class="hl-1">.</span><span class="hl-6">domElement</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">renderer:</span><span class="hl-1"> </span><span class="hl-6">renderer</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-6">viewport:</span><span class="hl-1"> { </span><span class="hl-6">left:</span><span class="hl-1"> </span><span class="hl-11">0</span><span class="hl-1">, </span><span class="hl-6">bottom:</span><span class="hl-1"> </span><span class="hl-11">0</span><span class="hl-1">, </span><span class="hl-6">width:</span><span class="hl-1"> </span><span class="hl-11">0.5</span><span class="hl-1">, </span><span class="hl-6">height:</span><span class="hl-1"> </span><span class="hl-11">1</span><span class="hl-1"> } </span><span class="hl-8">// 仅占用左半屏</span><br/><span class="hl-1">});</span><br/><br/><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-5">load</span><span class="hl-1">(</span><span class="hl-6">workData</span><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>
@@ -109,8 +151,8 @@
 <h3 id="实例方法-instance-methods" class="tsd-anchor-link">实例方法 (Instance Methods)<a href="#实例方法-instance-methods" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3>
 <ul>
 <li><strong><code>appendTo(element: HTMLElement)</code></strong>: 将 canvas 挂载到指定 DOM 元素。</li>
-<li><strong><code>load(work: Work, state?: State, duration?: number)</code></strong>: 加载场景数据。详见 <a href="features_work.html">work.md</a>。</li>
-<li><strong><code>dispose()</code></strong>: 销毁实例，释放 WebGL 上下文与内存。</li>
+<li><strong><code>load(inputWork, state?: &quot;inherit&quot; | &quot;initial&quot; | Partial&lt;State&gt;, options?: number | FiveLoadOptions, userAction?: boolean)</code></strong>: 加载场景数据。详见 <a href="features_work.html">work.md</a>。</li>
+<li><strong><code>dispose()</code></strong>: 销毁实例并释放相关渲染资源。</li>
 <li><strong><code>updateCamera(pose: Partial&lt;Pose&gt;, duration: number, userAction?: boolean)</code></strong>: 移动相机（不触发点位移动）。移动相机的视角或位置，不会改变当前所在的 PanoIndex。如果动画中途被打断，Promise 会被 reject。</li>
 <li><strong><code>updateCameraWithKeyframes(keyframes: { progress: number; value: Pose; key?: string }[], duration: number, userAction?: boolean)</code></strong>: 通过关键帧动画移动相机。</li>
 <li><strong><code>refresh()</code></strong>: 强制刷新画布尺寸。通常在窗口 resize 时调用，Five 会自动监听 resize，但在某些布局变化场景下可能需要手动调用。</li>
@@ -127,7 +169,7 @@
 </li>
 </ul>
 </li>
-<li><strong><code>setState(state: Partial&lt;State&gt;, options?: ChangeStateOptions)</code></strong>: 变更当前状态（如点位、视角）。详见 <a href="features_state.html">state.md</a>。</li>
+<li><strong><code>setState(state: Partial&lt;State&gt;, immediately?: boolean, userAction?: boolean)</code></strong>: 变更当前状态（如点位、视角）。详见 <a href="features_state.html">state.md</a>。</li>
 <li><strong><code>on(event, callback)</code> / <code>off(event, callback)</code></strong>: 事件监听。详见 <a href="features_event.html">event.md</a>。</li>
 </ul>
 <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>
@@ -141,7 +183,7 @@
 <li><a href="features_parameter.html">parameter.md</a>: 其他核心参数。</li>
 </ul>
 <hr>
-<pre><code class="yaml"><span class="hl-0">tags</span><span class="hl-1">: [</span><span class="hl-2">five</span><span class="hl-1">, </span><span class="hl-2">initialization</span><span class="hl-1">, </span><span class="hl-2">core</span><span class="hl-1">, </span><span class="hl-2">instance</span><span class="hl-1">, </span><span class="hl-2">lifecycle</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">five</span><span class="hl-1">, </span><span class="hl-2">initialization</span><span class="hl-1">, </span><span class="hl-2">core</span><span class="hl-1">, </span><span class="hl-2">instance</span><span class="hl-1">, </span><span class="hl-2">lifecycle</span><span class="hl-1">, </span><span class="hl-2">forceWebGL</span><span class="hl-1">, </span><span class="hl-2">webgl2</span><span class="hl-1">, </span><span class="hl-2">xr</span><span class="hl-1">, </span><span class="hl-2">webxr</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="#five-five-核心类"><span>Five (<wbr/>Five 核心类)</span></a><ul><li><a href="#schema"><span>Schema</span></a></li><li><ul><li><a href="#fiveinitargs"><span>Five<wbr/>Init<wbr/>Args</span></a></li></ul></li><li><a href="#concepts"><span>Concepts</span></a></li><li><ul><li><a href="#instance-management-实例管理"><span>Instance <wbr/>Management (实例管理)</span></a></li><li><a href="#rendering-loop-渲染循环"><span>Rendering <wbr/>Loop (渲染循环)</span></a></li><li><a href="#resource-loading-资源加载"><span>Resource <wbr/>Loading (资源加载)</span></a></li></ul></li><li><a href="#configuration"><span>Configuration</span></a></li><li><a href="#examples"><span>Examples</span></a></li><li><ul><li><a href="#快速上手-quick-example"><span>快速上手 (<wbr/>Quick <wbr/>Example)</span></a></li><li><a href="#进阶用法：自定义渲染器与视口"><span>进阶用法：自定义渲染器与视口</span></a></li><li><a href="#进阶用法：自定义相机动画"><span>进阶用法：自定义相机动画</span></a></li><li><a href="#实例属性-instance-properties"><span>实例属性 (<wbr/>Instance <wbr/>Properties)</span></a></li><li><a href="#实例方法-instance-methods"><span>实例方法 (<wbr/>Instance <wbr/>Methods)</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="#five-five-核心类"><span>Five (<wbr/>Five 核心类)</span></a><ul><li><a href="#schema"><span>Schema</span></a></li><li><ul><li><a href="#fiveinitargs"><span>Five<wbr/>Init<wbr/>Args</span></a></li></ul></li><li><a href="#concepts"><span>Concepts</span></a></li><li><ul><li><a href="#instance-management-实例管理"><span>Instance <wbr/>Management (实例管理)</span></a></li><li><a href="#rendering-loop-渲染循环"><span>Rendering <wbr/>Loop (渲染循环)</span></a></li><li><a href="#resource-loading-资源加载"><span>Resource <wbr/>Loading (资源加载)</span></a></li></ul></li><li><a href="#configuration"><span>Configuration</span></a></li><li><ul><li><a href="#forcewebgl-与-xr-回落后端"><span>force<wbr/>Web<wbr/>GL 与 <wbr/>XR 回落后端</span></a></li></ul></li><li><a href="#examples"><span>Examples</span></a></li><li><ul><li><a href="#快速上手-quick-example"><span>快速上手 (<wbr/>Quick <wbr/>Example)</span></a></li><li><a href="#进阶用法：自定义渲染器与视口"><span>进阶用法：自定义渲染器与视口</span></a></li><li><a href="#进阶用法：自定义相机动画"><span>进阶用法：自定义相机动画</span></a></li><li><a href="#实例属性-instance-properties"><span>实例属性 (<wbr/>Instance <wbr/>Properties)</span></a></li><li><a href="#实例方法-instance-methods"><span>实例方法 (<wbr/>Instance <wbr/>Methods)</span></a></li></ul></li><li><a href="#related"><span>Related</span></a></li></ul></div></details></div><div class="site-menu"><nav class="tsd-navigation"><a href="../modules.html">如视 Five SDK</a><ul class="tsd-small-nested-navigation" id="tsd-nav-container"><li>Loading...</li></ul></nav></div></div></div><footer><p class="tsd-generator">Generated using <a href="https://typedoc.org/" target="_blank">TypeDoc</a></p></footer><div class="overlay"></div></body></html>

package/docs/documents/features_gesture.html

@@ -16,7 +16,7 @@
 <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>
 <p>Five 的手势系统基于 Hammer.js 封装，主要包含以下几种手势：</p>
 <ul>
-<li><strong>gesture.create</strong>: 所有事件创建时。</li>
+<li><strong>gesture.fire</strong>: 任意事件被触发。</li>
 <li><strong>gesture.pan</strong>: 拖拽/平移。</li>
 <li><strong>gesture.pinch</strong>: 双指缩放。</li>
 <li><strong>gesture.tap</strong>: 点击。</li>

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-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>
@@ -537,7 +537,7 @@
 </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-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;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>

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>