@realsee/five 6.8.0-alpha.5 → 6.8.0-alpha.7

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

@@ -11,7 +11,7 @@
 <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>
+<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>
 </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>
@@ -32,7 +32,24 @@
 <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>
 <h3 id="loadgltf" class="tsd-anchor-link">loadGltf<a href="#loadgltf" 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>.gltf</code> 或 <code>.glb</code> 文件。支持 Draco 压缩。</p>
+<p>加载 <code>.gltf</code> 或 <code>.glb</code> 文件。支持 Draco 压缩。
+支持扩展：</p>
+<ul>
+<li><code>KHR_binary_glTF</code></li>
+<li><code>KHR_draco_mesh_compression</code></li>
+<li><code>KHR_texture_basisu</code></li>
+<li><code>KHR_texture_transform</code></li>
+<li><code>KHR_mesh_quantization</code></li>
+<li><code>KHR_materials_unlit</code></li>
+<li><code>KHR_node_visibility</code></li>
+<li><code>KHR_animation_pointer</code></li>
+<li><code>EXT_meshopt_compression</code></li>
+<li><code>EXT_texture_webp</code></li>
+<li><code>CESIUM_RTC</code></li>
+<li><code>REALSEE_materials_lightmap</code></li>
+<li><code>PBM_mesh</code></li>
+<li><code>KHR_gaussian_splatting_compression_spz</code></li>
+</ul>
 <table>
 <thead>
 <tr>

package/docs/documents/features_load-progress.html

@@ -0,0 +1,110 @@
+<!DOCTYPE html><html class="default" lang="en" data-base="../"><head><meta charset="utf-8"/><meta http-equiv="x-ua-compatible" content="IE=edge"/><title>features/load-progress | 如视 Five SDK</title><meta name="description" content="Documentation for 如视 Five SDK"/><meta name="viewport" content="width=device-width, initial-scale=1"/><link rel="stylesheet" href="../assets/style.css"/><link rel="stylesheet" href="../assets/highlight.css"/><script defer src="../assets/main.js"></script><script async src="../assets/icons.js" id="tsd-icons-script"></script><script async src="../assets/search.js" id="tsd-search-script"></script><script async src="../assets/navigation.js" id="tsd-nav-script"></script><script async src="../assets/hierarchy.js" id="tsd-hierarchy-script"></script></head><body><script>document.documentElement.dataset.theme = localStorage.getItem("tsd-theme") || "os";document.body.style.display="none";setTimeout(() => window.app?app.showPage():document.body.style.removeProperty("display"),500)</script><header class="tsd-page-toolbar"><div class="tsd-toolbar-contents container"><a href="../index.html" class="title">如视 Five SDK</a><div id="tsd-toolbar-links"></div><button id="tsd-search-trigger" class="tsd-widget" aria-label="Search"><svg width="16" height="16" viewBox="0 0 16 16" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-search"></use></svg></button><dialog id="tsd-search" aria-label="Search"><input role="combobox" id="tsd-search-input" aria-controls="tsd-search-results" aria-autocomplete="list" aria-expanded="true" autocapitalize="off" autocomplete="off" placeholder="Search the docs" maxLength="100"/><ul role="listbox" id="tsd-search-results"></ul><div id="tsd-search-status" aria-live="polite" aria-atomic="true"><div>Preparing search index...</div></div></dialog><a href="#" class="tsd-widget menu" id="tsd-toolbar-menu-trigger" data-toggle="menu" aria-label="Menu"><svg width="16" height="16" viewBox="0 0 16 16" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-menu"></use></svg></a></div></header><div class="container container-main"><div class="col-content"><div class="tsd-page-title"><ul class="tsd-breadcrumb" aria-label="Breadcrumb"><li><a href="" aria-current="page">features/load-progress</a></li></ul></div><div class="tsd-panel tsd-typography"><h1 id="resource-loading-progress-资源加载进度" class="tsd-anchor-link">Resource Loading Progress (资源加载进度)<a href="#resource-loading-progress-资源加载进度" 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></h1>
+<ul>
+<li><strong>Summary</strong>: 监控 3D 模型与全景图的加载状态和实时进度。</li>
+<li><strong>Schema</strong>: <code>Model</code>, <code>Tile</code>, <code>PanoTextureEvent</code></li>
+<li><strong>Concepts</strong>: Loaded vs Refined, Level of Detail (LOD), Panorama Lifecycle</li>
+<li><strong>Configuration</strong>: <code>minLevelOfDetail</code>, <code>maxScreenSpaceError</code></li>
+<li><strong>Examples</strong>: 状态检查、进度监听、生命周期事件</li>
+</ul>
+<h2 id="schema" class="tsd-anchor-link">Schema<a href="#schema" 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>
+<blockquote>
+<p><strong>Definition</strong>: <a href="../../five/model/index.d.ts">Model</a>, <a href="../../five/model/tile3d/tile.d.ts">Tile</a>, <a href="../../five/controllers/events.d.ts">PanoTextureEvent</a></p>
+</blockquote>
+<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>在 3D Tiles 模型（如 Five 的 Work 模型）中，&quot;加载&quot; 分为两个阶段：</p>
+<ol>
+<li>
+<p><strong>Loaded (初步加载完成)</strong>:</p>
+<ul>
+<li>表示模型已经加载了足够用于显示的<strong>基础</strong>数据。</li>
+<li>受 <code>minLevelOfDetail</code> 参数影响。只有当满足最小 LOD 要求的 Tile 加载完毕后，<code>loaded</code> 才会变为 <code>true</code>。</li>
+<li>通常作为 &quot;首屏加载完成&quot; 的标志，此时模型可能还比较模糊。</li>
+</ul>
+</li>
+<li>
+<p><strong>Refined (细化完成)</strong>:</p>
+<ul>
+<li>表示模型在当前视角下，已经加载了所有必要的<strong>高清</strong>数据，达到了最佳渲染效果。</li>
+<li>受 <code>maxScreenSpaceError</code> 参数影响。该值越小，需要的 Tile 精度越高，细化完成所需的时间越长。</li>
+<li>这是一个动态状态。当相机移动时，可能会因为需要加载新的高清分块而从 <code>refined: true</code> 变为 <code>false</code>。</li>
+</ul>
+</li>
+</ol>
+<h2 id="instance-properties" class="tsd-anchor-link">Instance Properties<a href="#instance-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></h2>
+<h3 id="model-status" class="tsd-anchor-link">Model Status<a href="#model-status" 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>
+<table>
+<thead>
+<tr>
+<th style="text-align:left">Property</th>
+<th style="text-align:left">Type</th>
+<th style="text-align:left">Description</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td style="text-align:left"><code>five.model.loaded</code></td>
+<td style="text-align:left"><code>boolean</code></td>
+<td style="text-align:left">检查模型是否已完成初步加载 (Loaded)。</td>
+</tr>
+<tr>
+<td style="text-align:left"><code>five.model.refined</code></td>
+<td style="text-align:left"><code>boolean</code></td>
+<td style="text-align:left">检查模型是否已完成细化 (Refined)。</td>
+</tr>
+<tr>
+<td style="text-align:left"><code>five.model.refineProgress</code></td>
+<td style="text-align:left"><code>[number, number]</code></td>
+<td style="text-align:left">细化进度元组 <code>[current, total]</code> (已加载/总需加载)。</td>
+</tr>
+</tbody>
+</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="1-model-loading-模型加载" class="tsd-anchor-link">1. Model Loading (模型加载)<a href="#1-model-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>
+<h4 id="检查当前状态-state-checking" class="tsd-anchor-link">检查当前状态 (State Checking)<a href="#检查当前状态-state-checking" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h4>
+<pre><code class="ts"><span class="hl-10">if</span><span class="hl-1"> (</span><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-6">model</span><span class="hl-1">.</span><span class="hl-6">loaded</span><span class="hl-1">) {</span><br/><span class="hl-1">  </span><span class="hl-6">console</span><span class="hl-1">.</span><span class="hl-5">log</span><span class="hl-1">(</span><span class="hl-9">&quot;Model is ready (basic data loaded)!&quot;</span><span class="hl-1">);</span><br/><span class="hl-1">}</span><br/><br/><span class="hl-10">if</span><span class="hl-1"> (</span><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-6">model</span><span class="hl-1">.</span><span class="hl-6">refined</span><span class="hl-1">) {</span><br/><span class="hl-1">  </span><span class="hl-6">console</span><span class="hl-1">.</span><span class="hl-5">log</span><span class="hl-1">(</span><span class="hl-9">&quot;Model is fully refined (high-res data loaded)!&quot;</span><span class="hl-1">);</span><br/><span class="hl-1">}</span>
+</code><button type="button">Copy</button></pre>
+
+<h4 id="监控细化进度-refine-progress" class="tsd-anchor-link">监控细化进度 (Refine Progress)<a href="#监控细化进度-refine-progress" 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><code>five.model.refineProgress</code> 提供了当前视图下模型细化的整体进度。</p>
+<pre><code class="ts"><span class="hl-3">const</span><span class="hl-1"> [</span><span class="hl-4">current</span><span class="hl-1">, </span><span class="hl-4">total</span><span class="hl-1">] = </span><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-6">model</span><span class="hl-1">.</span><span class="hl-6">refineProgress</span><span class="hl-1">;</span><br/><span class="hl-6">console</span><span class="hl-1">.</span><span class="hl-5">log</span><span class="hl-1">(</span><span class="hl-9">`Model Refine Progress: </span><span class="hl-3">${</span><span class="hl-6">current</span><span class="hl-3">}</span><span class="hl-9"> / </span><span class="hl-3">${</span><span class="hl-6">total</span><span class="hl-3">}</span><span class="hl-9">`</span><span class="hl-1">);</span><br/><br/><span class="hl-10">if</span><span class="hl-1"> (</span><span class="hl-6">current</span><span class="hl-1"> === </span><span class="hl-6">total</span><span class="hl-1"> &amp;&amp; </span><span class="hl-6">total</span><span class="hl-1"> &gt; </span><span class="hl-11">0</span><span class="hl-1">) {</span><br/><span class="hl-1">  </span><span class="hl-6">console</span><span class="hl-1">.</span><span class="hl-5">log</span><span class="hl-1">(</span><span class="hl-9">&quot;Model is fully refined for current view.&quot;</span><span class="hl-1">);</span><br/><span class="hl-1">}</span>
+</code><button type="button">Copy</button></pre>
+
+<h4 id="监听加载完成事件" class="tsd-anchor-link">监听加载完成事件<a href="#监听加载完成事件" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h4>
+<pre><code class="ts"><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-5">on</span><span class="hl-1">(</span><span class="hl-9">&quot;modelLoaded&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">console</span><span class="hl-1">.</span><span class="hl-5">log</span><span class="hl-1">(</span><span class="hl-9">&quot;Model has been loaded.&quot;</span><span class="hl-1">);</span><br/><span class="hl-1">});</span>
+</code><button type="button">Copy</button></pre>
+
+<h4 id="advanced-tile-级别进度" class="tsd-anchor-link">(Advanced) Tile 级别进度<a href="#advanced-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>对于 <code>3dtiles</code> 类型的模型，你可以访问具体的 Tile 对象来查看进度。</p>
+<pre><code class="ts"><span class="hl-8">// 仅示例，通常在调试或特定渲染逻辑中使用</span><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">progress</span><span class="hl-1"> = </span><span class="hl-6">tile</span><span class="hl-1">.</span><span class="hl-6">content</span><span class="hl-1">.</span><span class="hl-6">loadProgress</span><span class="hl-1">; </span><span class="hl-8">// [0, 1]</span>
+</code><button type="button">Copy</button></pre>
+
+<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>
+</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>
+<p>全景图通常在用户移动到某个点位时按需加载。</p>
+<h4 id="监听加载进度" class="tsd-anchor-link">监听加载进度<a href="#监听加载进度" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h4>
+<p>使用 <code>pano.texture.progress</code> 事件获取当前全景图的加载进度。</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;pano.texture.progress&quot;</span><span class="hl-1">, (</span><span class="hl-6">event</span><span class="hl-1">) </span><span class="hl-3">=&gt;</span><span class="hl-1"> {</span><br/><span class="hl-1">  </span><span class="hl-3">const</span><span class="hl-1"> { </span><span class="hl-4">progress</span><span class="hl-1">, </span><span class="hl-4">pano</span><span class="hl-1"> } = </span><span class="hl-6">event</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">`Pano </span><span class="hl-3">${</span><span class="hl-6">pano</span><span class="hl-12">.</span><span class="hl-6">panoIndex</span><span class="hl-3">}</span><span class="hl-9"> loading: </span><span class="hl-3">${</span><span class="hl-12">(</span><span class="hl-6">progress</span><span class="hl-12"> </span><span class="hl-1">*</span><span class="hl-12"> </span><span class="hl-11">100</span><span class="hl-12">).</span><span class="hl-5">toFixed</span><span class="hl-12">(</span><span class="hl-11">1</span><span class="hl-12">)</span><span class="hl-3">}</span><span class="hl-9">%`</span><span class="hl-1">);</span><br/><span class="hl-1">});</span>
+</code><button type="button">Copy</button></pre>
+
+<h4 id="生命周期事件" class="tsd-anchor-link">生命周期事件<a href="#生命周期事件" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h4>
+<ul>
+<li><strong><code>pano.texture.load</code></strong>: 开始加载。</li>
+<li><strong><code>pano.texture.success</code></strong>: 加载完成。</li>
+<li><strong><code>pano.texture.error</code></strong>: 加载失败。</li>
+</ul>
+<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;pano.texture.load&quot;</span><span class="hl-1">, (</span><span class="hl-6">event</span><span class="hl-1">) </span><span class="hl-3">=&gt;</span><span class="hl-1"> {</span><br/><span class="hl-1">  </span><span class="hl-6">console</span><span class="hl-1">.</span><span class="hl-5">log</span><span class="hl-1">(</span><span class="hl-9">`Started loading pano </span><span class="hl-3">${</span><span class="hl-6">event</span><span class="hl-12">.</span><span class="hl-6">pano</span><span class="hl-12">.</span><span class="hl-6">panoIndex</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;pano.texture.success&quot;</span><span class="hl-1">, (</span><span class="hl-6">event</span><span class="hl-1">) </span><span class="hl-3">=&gt;</span><span class="hl-1"> {</span><br/><span class="hl-1">  </span><span class="hl-6">console</span><span class="hl-1">.</span><span class="hl-5">log</span><span class="hl-1">(</span><span class="hl-9">`Finished loading pano </span><span class="hl-3">${</span><span class="hl-6">event</span><span class="hl-12">.</span><span class="hl-6">pano</span><span class="hl-12">.</span><span class="hl-6">panoIndex</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;pano.texture.error&quot;</span><span class="hl-1">, (</span><span class="hl-6">event</span><span class="hl-1">) </span><span class="hl-3">=&gt;</span><span class="hl-1"> {</span><br/><span class="hl-1">  </span><span class="hl-6">console</span><span class="hl-1">.</span><span class="hl-5">error</span><span class="hl-1">(</span><span class="hl-9">`Failed to load pano </span><span class="hl-3">${</span><span class="hl-6">event</span><span class="hl-12">.</span><span class="hl-6">pano</span><span class="hl-12">.</span><span class="hl-6">panoIndex</span><span class="hl-3">}</span><span class="hl-9">`</span><span class="hl-1">, </span><span class="hl-6">event</span><span class="hl-1">.</span><span class="hl-6">error</span><span class="hl-1">);</span><br/><span class="hl-1">});</span>
+</code><button type="button">Copy</button></pre>
+
+<h2 id="related" class="tsd-anchor-link">Related<a href="#related" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h2>
+<ul>
+<li><a href="api.html">Five Class</a>: Five 核心类 API 索引。</li>
+</ul>
+<hr>
+<pre><code class="yaml"><span class="hl-0">tags</span><span class="hl-1">: [</span><span class="hl-2">loading</span><span class="hl-1">, </span><span class="hl-2">progress</span><span class="hl-1">, </span><span class="hl-2">refined</span><span class="hl-1">, </span><span class="hl-2">loaded</span><span class="hl-1">, </span><span class="hl-2">event</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="#resource-loading-progress-资源加载进度"><span>Resource <wbr/>Loading <wbr/>Progress (资源加载进度)</span></a><ul><li><a href="#schema"><span>Schema</span></a></li><li><a href="#concepts"><span>Concepts</span></a></li><li><a href="#instance-properties"><span>Instance <wbr/>Properties</span></a></li><li><ul><li><a href="#model-status"><span>Model <wbr/>Status</span></a></li></ul></li><li><a href="#examples"><span>Examples</span></a></li><li><ul><li><a href="#1-model-loading-模型加载"><span>1. <wbr/>Model <wbr/>Loading (模型加载)</span></a></li><li><ul><li><a href="#检查当前状态-state-checking"><span>检查当前状态 (<wbr/>State <wbr/>Checking)</span></a></li><li><a href="#监控细化进度-refine-progress"><span>监控细化进度 (<wbr/>Refine <wbr/>Progress)</span></a></li><li><a href="#监听加载完成事件"><span>监听加载完成事件</span></a></li><li><a href="#advanced-tile-级别进度"><span>(<wbr/>Advanced) <wbr/>Tile 级别进度</span></a></li><li><a href="#tile-lifecycle-monitoring-tile-生命周期监控"><span>Tile <wbr/>Lifecycle <wbr/>Monitoring (<wbr/>Tile 生命周期监控)</span></a></li></ul></li><li><a href="#2-panorama-loading-全景图加载"><span>2. <wbr/>Panorama <wbr/>Loading (全景图加载)</span></a></li><li><ul><li><a href="#监听加载进度"><span>监听加载进度</span></a></li><li><a href="#生命周期事件"><span>生命周期事件</span></a></li></ul></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_parameter.html

@@ -64,6 +64,13 @@
 <pre><code class="mermaid"><span class="hl-1">graph TD</span><br/><span class="hl-1">  Scene[ModelScene.parameter] --&gt;|Inherit| Model[Model.parameter]</span><br/><span class="hl-1">  Model --&gt;|Inherit| Layer1[ViewLayer.parameter]</span><br/><span class="hl-1">  Model --&gt;|Inherit| Layer2[ViewLayer.parameter]</span>
 </code><button type="button">Copy</button></pre>
 
+<blockquote>
+<p><strong>Global Configuration (全局设置)</strong>:
+若需修改所有模型的默认表现（如统一调暗亮度、统一设置显存上限），<strong>请直接配置 <code>five.modelScene.parameter</code></strong>。它是继承链的根节点，其设置会向下传递给所有 Model 和 ViewLayer。</p>
+<p><strong>Why modelScene? (生命周期优势)</strong>:
+<code>Model</code> 实例是跟随 Work 加载生命周期的（需 <code>five.load(work)</code> 后才能访问，且切换 Work 会销毁重建）。
+相比之下，<code>ModelScene</code> 是常驻对象。因此，<strong>使用 <code>modelScene</code> 进行配置更安全且持久</strong>，既无需等待 Work 加载完成，也无需担心切换 Work 导致配置丢失。</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="1-基础配置-basic-usage" class="tsd-anchor-link">1. 基础配置 (Basic Usage)<a href="#1-基础配置-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-8">// 1. 设置全局最大显存 (影响所有模型)</span><br/><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-6">modelScene</span><span class="hl-1">.</span><span class="hl-6">parameter</span><span class="hl-1">.</span><span class="hl-5">set</span><span class="hl-1">(</span><span class="hl-9">&#39;maxMemoryUsage&#39;</span><span class="hl-1">, </span><span class="hl-11">512</span><span class="hl-1">);</span><br/><br/><span class="hl-8">// 2. 设置全局半透明</span><br/><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-6">modelScene</span><span class="hl-1">.</span><span class="hl-6">parameter</span><span class="hl-1">.</span><span class="hl-5">set</span><span class="hl-1">(</span><span class="hl-9">&#39;opacity&#39;</span><span class="hl-1">, </span><span class="hl-11">0.5</span><span class="hl-1">);</span>

package/docs/documents/features_postprocessing.html

@@ -1,6 +1,6 @@
 <!DOCTYPE html><html class="default" lang="en" data-base="../"><head><meta charset="utf-8"/><meta http-equiv="x-ua-compatible" content="IE=edge"/><title>features/postprocessing | 如视 Five SDK</title><meta name="description" content="Documentation for 如视 Five SDK"/><meta name="viewport" content="width=device-width, initial-scale=1"/><link rel="stylesheet" href="../assets/style.css"/><link rel="stylesheet" href="../assets/highlight.css"/><script defer src="../assets/main.js"></script><script async src="../assets/icons.js" id="tsd-icons-script"></script><script async src="../assets/search.js" id="tsd-search-script"></script><script async src="../assets/navigation.js" id="tsd-nav-script"></script><script async src="../assets/hierarchy.js" id="tsd-hierarchy-script"></script></head><body><script>document.documentElement.dataset.theme = localStorage.getItem("tsd-theme") || "os";document.body.style.display="none";setTimeout(() => window.app?app.showPage():document.body.style.removeProperty("display"),500)</script><header class="tsd-page-toolbar"><div class="tsd-toolbar-contents container"><a href="../index.html" class="title">如视 Five SDK</a><div id="tsd-toolbar-links"></div><button id="tsd-search-trigger" class="tsd-widget" aria-label="Search"><svg width="16" height="16" viewBox="0 0 16 16" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-search"></use></svg></button><dialog id="tsd-search" aria-label="Search"><input role="combobox" id="tsd-search-input" aria-controls="tsd-search-results" aria-autocomplete="list" aria-expanded="true" autocapitalize="off" autocomplete="off" placeholder="Search the docs" maxLength="100"/><ul role="listbox" id="tsd-search-results"></ul><div id="tsd-search-status" aria-live="polite" aria-atomic="true"><div>Preparing search index...</div></div></dialog><a href="#" class="tsd-widget menu" id="tsd-toolbar-menu-trigger" data-toggle="menu" aria-label="Menu"><svg width="16" height="16" viewBox="0 0 16 16" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-menu"></use></svg></a></div></header><div class="container container-main"><div class="col-content"><div class="tsd-page-title"><ul class="tsd-breadcrumb" aria-label="Breadcrumb"><li><a href="" aria-current="page">features/postprocessing</a></li></ul></div><div class="tsd-panel tsd-typography"><h1 id="后处理-post-processing" class="tsd-anchor-link">后处理 (Post Processing)<a href="#后处理-post-processing" 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></h1>
 <ul>
-<li><strong>Summary</strong>: Five 提供了基于 EffectComposer 的后处理机制，内置了自适应亮度 (Auto Exposure) 和眼球穹顶光照 (EDL) 两种效果，并支持开发者编写自定义 Pass。</li>
+<li><strong>Summary</strong>: Five 提供了基于 EffectComposer 的后处理机制，默认挂载了自适应亮度 (Auto Exposure) 和眼球穹顶光照 (EDL) 两种效果，同时提供多种可选内置 Pass，并支持开发者编写自定义 Pass。</li>
 <li><strong>Schema</strong>: <code>FivePass</code> 类及 <code>Pass</code> 接口。</li>
 <li><strong>Concepts</strong>: EffectComposer, G-Buffer, Pass, AdaptiveLuminance, EyeDomeLighting。</li>
 <li><strong>Configuration</strong>: 开启内置 Pass 的开关及参数配置。</li>
@@ -21,7 +21,7 @@
 <li><strong>EyeDomeLightingPass (EDL)</strong>: 一种非真实感渲染技术，主要用于增强点云模型的深度感知。通过屏幕空间的深度差计算遮蔽效果，让点云看起来更有轮廓感。</li>
 </ul>
 <h2 id="built-in-passes-内置-pass" class="tsd-anchor-link">Built-in Passes (内置 Pass)<a href="#built-in-passes-内置-pass" 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 内置了两个 Pass 实例，挂载在 <code>five</code> 实例上，默认是关闭状态。</p>
+<p>Five 默认挂载了两个 Pass 实例，挂载在 <code>five</code> 实例上，默认是关闭状态。</p>
 <h3 id="1-adaptiveluminancepass" class="tsd-anchor-link">1. AdaptiveLuminancePass<a href="#1-adaptiveluminancepass" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3>
 <p>位于 <code>five.adaptiveLuminancePass</code>。</p>
 <ul>
@@ -47,6 +47,17 @@
 </li>
 <li><strong>注意</strong>: 这是一个基于屏幕空间深度的算法，依赖 Depth Buffer。</li>
 </ul>
+<h3 id="3-optional-built-in-passes-可选内置-pass" class="tsd-anchor-link">3. Optional Built-in Passes (可选内置 Pass)<a href="#3-optional-built-in-passes-可选内置-pass" 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 新增了三个可选使用的内置 Pass，这些 Pass 没有预先挂载在 <code>five</code> 实例上，需手动导入并添加到渲染链中：</p>
+<ul>
+<li><strong><a href="features_gaussian-blur-pass.html">GaussianBlurPass</a></strong>: 高斯模糊效果。</li>
+<li><strong><a href="features_flowing-light-2d-pass.html">FlowingLight2DPass</a></strong>: 2D 流光效果（通常用于平面路线流光）。</li>
+<li><strong><a href="features_flowing-light-3d-pass.html">FlowingLight3DPass</a></strong>: 3D 流光效果（通常用于空间路径流光）。</li>
+</ul>
+<h4 id="gaussianblurpass-使用示例" class="tsd-anchor-link">GaussianBlurPass 使用示例<a href="#gaussianblurpass-使用示例" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h4>
+<pre><code class="typescript"><span class="hl-10">import</span><span class="hl-1"> { </span><span class="hl-6">GaussianBlurPass</span><span class="hl-1"> } </span><span class="hl-10">from</span><span class="hl-1"> </span><span class="hl-9">&#39;@realsee/five&#39;</span><span class="hl-1">;</span><br/><br/><span class="hl-8">// 1. 创建 GaussianBlurPass 实例 (需要传入 camera)</span><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">gaussianBlurPass</span><span class="hl-1"> = </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-5">GaussianBlurPass</span><span class="hl-1">(</span><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-6">camera</span><span class="hl-1">);</span><br/><br/><span class="hl-8">// 2. 配置参数</span><br/><span class="hl-8">// 设置模糊半径 (默认 4.0)</span><br/><span class="hl-6">gaussianBlurPass</span><span class="hl-1">.</span><span class="hl-5">setRadius</span><span class="hl-1">(</span><span class="hl-11">6</span><span class="hl-1">);</span><br/><br/><span class="hl-8">// 3. 将 Pass 添加到渲染链</span><br/><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-5">addPass</span><span class="hl-1">(</span><span class="hl-6">gaussianBlurPass</span><span class="hl-1">);</span><br/><br/><span class="hl-8">// 4. (可选) 动态开关</span><br/><span class="hl-8">// gaussianBlurPass.enabled = false;</span><br/><br/><span class="hl-8">// 5. (可选) 移除 Pass</span><br/><span class="hl-8">// five.removePass(gaussianBlurPass);</span>
+</code><button type="button">Copy</button></pre>
+
 <h2 id="custom-pass-自定义-pass" class="tsd-anchor-link">Custom Pass (自定义 Pass)<a href="#custom-pass-自定义-pass" 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>如果需要实现自定义的后处理效果（如景深、色彩校正、描边等），建议继承 <code>FivePass</code>。</p>
 <h3 id="步骤" class="tsd-anchor-link">步骤<a href="#步骤" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3>
@@ -85,6 +96,9 @@
 </ol>
 <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_gaussian-blur-pass.html">Gaussian Blur Pass</a>: 高斯模糊 Pass 文档。</li>
+<li><a href="features_flowing-light-2d-pass.html">Flowing Light 2D Pass</a>: 2D 流光 Pass 文档。</li>
+<li><a href="features_flowing-light-3d-pass.html">Flowing Light 3D Pass</a>: 3D 流光 Pass 文档。</li>
 <li><a href="../../five/application/five.d.ts">five.ts</a>: 查看 <code>addPass</code> 方法的实现。</li>
 <li><a href="../../five/renderer/postprocessing/passes/pass.d.ts">pass.ts</a>: 查看 <code>FivePass</code> 基类定义。</li>
 </ul>
@@ -92,4 +106,4 @@
 <pre><code class="yaml"><span class="hl-0">tags</span><span class="hl-1">: [</span><span class="hl-2">postprocessing</span><span class="hl-1">, </span><span class="hl-2">shader</span><span class="hl-1">, </span><span class="hl-2">effect</span><span class="hl-1">, </span><span class="hl-2">adaptive-luminance</span><span class="hl-1">, </span><span class="hl-2">edl</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="#后处理-post-processing"><span>后处理 (<wbr/>Post <wbr/>Processing)</span></a><ul><li><a href="#schema"><span>Schema</span></a></li><li><a href="#concepts"><span>Concepts</span></a></li><li><a href="#built-in-passes-内置-pass"><span>Built-<wbr/>in <wbr/>Passes (内置 <wbr/>Pass)</span></a></li><li><ul><li><a href="#1-adaptiveluminancepass"><span>1. <wbr/>Adaptive<wbr/>Luminance<wbr/>Pass</span></a></li><li><a href="#2-eyedomelightingpass"><span>2. <wbr/>Eye<wbr/>Dome<wbr/>Lighting<wbr/>Pass</span></a></li></ul></li><li><a href="#custom-pass-自定义-pass"><span>Custom <wbr/>Pass (自定义 <wbr/>Pass)</span></a></li><li><ul><li><a href="#步骤"><span>步骤</span></a></li></ul></li><li><a href="#examples"><span>Examples</span></a></li><li><ul><li><a href="#开启内置-pass"><span>开启内置 <wbr/>Pass</span></a></li><li><a href="#自定义-pass-黑白滤镜"><span>自定义 <wbr/>Pass (黑白滤镜)</span></a></li><li><a href="#使用-g-buffer-深度图示例"><span>使用 <wbr/>G-<wbr/>Buffer (深度图示例)</span></a></li></ul></li><li><a href="#debugging"><span>Debugging</span></a></li><li><a href="#common-pitfalls"><span>Common <wbr/>Pitfalls</span></a></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="#后处理-post-processing"><span>后处理 (<wbr/>Post <wbr/>Processing)</span></a><ul><li><a href="#schema"><span>Schema</span></a></li><li><a href="#concepts"><span>Concepts</span></a></li><li><a href="#built-in-passes-内置-pass"><span>Built-<wbr/>in <wbr/>Passes (内置 <wbr/>Pass)</span></a></li><li><ul><li><a href="#1-adaptiveluminancepass"><span>1. <wbr/>Adaptive<wbr/>Luminance<wbr/>Pass</span></a></li><li><a href="#2-eyedomelightingpass"><span>2. <wbr/>Eye<wbr/>Dome<wbr/>Lighting<wbr/>Pass</span></a></li><li><a href="#3-optional-built-in-passes-可选内置-pass"><span>3. <wbr/>Optional <wbr/>Built-<wbr/>in <wbr/>Passes (可选内置 <wbr/>Pass)</span></a></li><li><ul><li><a href="#gaussianblurpass-使用示例"><span>Gaussian<wbr/>Blur<wbr/>Pass 使用示例</span></a></li></ul></li></ul></li><li><a href="#custom-pass-自定义-pass"><span>Custom <wbr/>Pass (自定义 <wbr/>Pass)</span></a></li><li><ul><li><a href="#步骤"><span>步骤</span></a></li></ul></li><li><a href="#examples"><span>Examples</span></a></li><li><ul><li><a href="#开启内置-pass"><span>开启内置 <wbr/>Pass</span></a></li><li><a href="#自定义-pass-黑白滤镜"><span>自定义 <wbr/>Pass (黑白滤镜)</span></a></li><li><a href="#使用-g-buffer-深度图示例"><span>使用 <wbr/>G-<wbr/>Buffer (深度图示例)</span></a></li></ul></li><li><a href="#debugging"><span>Debugging</span></a></li><li><a href="#common-pitfalls"><span>Common <wbr/>Pitfalls</span></a></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_raycast.html

@@ -10,7 +10,7 @@
 <p><strong>Definition</strong>: <a href="../../five/declare.d.ts">Raycaster</a></p>
 </blockquote>
 <p>Five 对 Three.js 的 <code>Raycaster</code> 进行了扩展，在 <code>declare module 'three'</code> 中增加了以下属性：</p>
-<pre><code class="typescript"><span class="hl-8">// defined in five/declare.d.ts</span><br/><span class="hl-3">declare</span><span class="hl-1"> </span><span class="hl-3">module</span><span class="hl-1"> </span><span class="hl-9">&#39;three&#39;</span><span class="hl-1"> {</span><br/><span class="hl-1">  </span><span class="hl-10">export</span><span class="hl-1"> </span><span class="hl-3">interface</span><span class="hl-1"> </span><span class="hl-7">Raycaster</span><span class="hl-1"> {</span><br/><span class="hl-1">    </span><span class="hl-8">/**</span><br/><span class="hl-8">     * 只捕获第一个焦点 (性能优化)</span><br/><span class="hl-8">     * - true: 找到第一个交点后立即停止检测，返回结果。</span><br/><span class="hl-8">     * - false (默认): 检测所有可能的交点。</span><br/><span class="hl-8">     */</span><br/><span class="hl-1">    </span><span class="hl-6">firstHitOnly</span><span class="hl-1">?: </span><span class="hl-7">boolean</span><span class="hl-1">;</span><br/><br/><span class="hl-1">    </span><span class="hl-8">/**</span><br/><span class="hl-8">     * 自定义交点过滤器</span><br/><span class="hl-8">     * - 回调函数，返回 boolean。</span><br/><span class="hl-8">     * - true: 保留该交点。</span><br/><span class="hl-8">     * - false: 丢弃该交点。</span><br/><span class="hl-8">     */</span><br/><span class="hl-1">    </span><span class="hl-5">hitFilter</span><span class="hl-1">?: (</span><span class="hl-6">intersect</span><span class="hl-1">: </span><span class="hl-7">THREE</span><span class="hl-1">.</span><span class="hl-7">Intersection</span><span class="hl-1">) </span><span class="hl-3">=&gt;</span><span class="hl-1"> </span><span class="hl-7">boolean</span><span class="hl-1">;</span><br/><br/><span class="hl-1">    </span><span class="hl-8">/**</span><br/><span class="hl-8">     * 是否由近及远排序</span><br/><span class="hl-8">     * - true (默认): 返回的结果数组按距离摄像机从近到远排序。</span><br/><span class="hl-8">     * - false: 结果顺序不确定（通常按遍历顺序）。</span><br/><span class="hl-8">     */</span><br/><span class="hl-1">    </span><span class="hl-6">sortByDistance</span><span class="hl-1">?: </span><span class="hl-7">boolean</span><span class="hl-1">;</span><br/><br/><span class="hl-1">    </span><span class="hl-8">/**</span><br/><span class="hl-8">     * 作用楼层 (Five 特有逻辑)</span><br/><span class="hl-8">     * - 用于多楼层场景过滤。</span><br/><span class="hl-8">     */</span><br/><span class="hl-1">    </span><span class="hl-6">floorIndex</span><span class="hl-1">?: </span><span class="hl-7">number</span><span class="hl-1">;</span><br/><span class="hl-1">  }</span><br/><span class="hl-1">}</span>
+<pre><code class="typescript"><span class="hl-8">// defined in five/declare.d.ts</span><br/><span class="hl-3">declare</span><span class="hl-1"> </span><span class="hl-3">module</span><span class="hl-1"> </span><span class="hl-9">&#39;three&#39;</span><span class="hl-1"> {</span><br/><span class="hl-1">  </span><span class="hl-10">export</span><span class="hl-1"> </span><span class="hl-3">interface</span><span class="hl-1"> </span><span class="hl-7">Raycaster</span><span class="hl-1"> {</span><br/><span class="hl-1">    </span><span class="hl-8">/**</span><br/><span class="hl-8">     * 只捕获第一个焦点 (性能优化)</span><br/><span class="hl-8">     * - true: 找到第一个交点后立即停止检测，返回结果。</span><br/><span class="hl-8">     * - false (默认): 检测所有可能的交点。</span><br/><span class="hl-8">     */</span><br/><span class="hl-1">    </span><span class="hl-6">firstHitOnly</span><span class="hl-1">?: </span><span class="hl-7">boolean</span><span class="hl-1">;</span><br/><br/><span class="hl-1">    </span><span class="hl-8">/**</span><br/><span class="hl-8">     * 自定义交点过滤器</span><br/><span class="hl-8">     * - 回调函数，返回 boolean。</span><br/><span class="hl-8">     * - true: 保留该交点。</span><br/><span class="hl-8">     * - false: 丢弃该交点。</span><br/><span class="hl-8">     */</span><br/><span class="hl-1">    </span><span class="hl-5">hitFilter</span><span class="hl-1">?: (</span><span class="hl-6">intersect</span><span class="hl-1">: </span><span class="hl-7">THREE</span><span class="hl-1">.</span><span class="hl-7">Intersection</span><span class="hl-1">) </span><span class="hl-3">=&gt;</span><span class="hl-1"> </span><span class="hl-7">boolean</span><span class="hl-1">;</span><br/><br/><span class="hl-1">    </span><span class="hl-8">/**</span><br/><span class="hl-8">     * 是否由近及远排序</span><br/><span class="hl-8">     * - true (默认): 返回的结果数组按距离摄像机从近到远排序。</span><br/><span class="hl-8">     * - false: 结果顺序不确定（通常按遍历顺序）。</span><br/><span class="hl-8">     */</span><br/><span class="hl-1">    </span><span class="hl-6">sortByDistance</span><span class="hl-1">?: </span><span class="hl-7">boolean</span><span class="hl-1">;</span><br/><br/><span class="hl-1">    </span><span class="hl-8">/**</span><br/><span class="hl-8">     * 作用楼层 (Five 特有逻辑)</span><br/><span class="hl-8">     * - 用于多楼层场景过滤。</span><br/><span class="hl-8">     */</span><br/><span class="hl-1">    </span><span class="hl-6">floorIndex</span><span class="hl-1">?: </span><span class="hl-7">number</span><span class="hl-1">;</span><br/><span class="hl-1">  }</span><br/><br/><span class="hl-1">  </span><span class="hl-10">export</span><span class="hl-1"> </span><span class="hl-3">interface</span><span class="hl-1"> </span><span class="hl-7">Intersection</span><span class="hl-1"> {</span><br/><span class="hl-1">    </span><span class="hl-8">/** 命中的具体 Tile 对象 (仅 3DTiles) */</span><br/><span class="hl-1">    </span><span class="hl-6">tile</span><span class="hl-1">?: </span><span class="hl-7">Tile</span><span class="hl-1">;</span><br/><span class="hl-1">    </span><span class="hl-8">/** 命中的 ViewLayer 对象 */</span><br/><span class="hl-1">    </span><span class="hl-6">viewLayer</span><span class="hl-1">?: </span><span class="hl-7">ViewLayer</span><span class="hl-1">;</span><br/><span class="hl-1">    </span><span class="hl-8">/** 命中的 Model 对象 */</span><br/><span class="hl-1">    </span><span class="hl-6">model</span><span class="hl-1">?: </span><span class="hl-7">Model</span><span class="hl-1">;</span><br/><span class="hl-1">  }</span><br/><span class="hl-1">}</span>
 </code><button type="button">Copy</button></pre>
 
 <h2 id="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>

package/docs/documents/features_view-layer.html

@@ -77,15 +77,21 @@ Five 会遍历这个数组，为每一项创建一个 <code>ViewLayer</code> 实
 <li>如果你只想让<strong>点云层</strong>变暗，保留模型层亮度，设置 <code>pointCloudLayer.parameter.set('opacity', 0.5)</code>。</li>
 </ul>
 <h3 id="4-visibility-control-可见性控制" class="tsd-anchor-link">4. Visibility Control (可见性控制)<a href="#4-visibility-control-可见性控制" 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>默认情况下，<strong>所有</strong>定义在 <code>work.model.layers</code> 中的图层都会被加载并显示。</p>
+<p>默认情况下，Five <strong>不会</strong>加载所有图层，而是根据优先级<strong>仅加载一个</strong>图层，以节省资源。
+优先级顺序：<code>mesh</code> &gt; <code>point_cloud</code> &gt; 其他类型。</p>
+<p><strong>可见性与内存管理 (Visibility &amp; Memory)</strong>:</p>
+<ul>
+<li><strong>显示 (Show)</strong>: 当图层设置为可见 (<code>visible = true</code>) 时，Five 会开始加载该图层的资源。</li>
+<li><strong>隐藏 (Hide)</strong>: 当图层设置为隐藏 (<code>visible = false</code>) 时，Five 会<strong>释放该图层占用的所有内存资源</strong> (Geometry, Texture 等)。这意味着“隐藏”等同于“卸载”。</li>
+</ul>
 <p>Five 提供了两种层级的可见性控制方式：</p>
 <ol>
 <li>
 <p><strong>初始化配置 (Load Options)</strong>:
 在 <code>five.load</code> 时，通过 <code>model[&quot;3d-tiles&quot;].showLayers</code> 参数指定初始显示的图层。</p>
 <ul>
-<li><code>true</code> (默认): 显示所有图层。</li>
-<li><code>string[]</code>: 仅显示名称在数组中的图层（例如 <code>['mesh']</code> 只显示模型，隐藏点云）。</li>
+<li><code>true</code> (默认): 使用上述的默认优先级策略（仅加载一个最佳图层）。</li>
+<li><code>string[]</code>: 仅显示名称在数组中的图层（例如 <code>['mesh', 'point_cloud']</code> 可以强制同时显示模型和点云）。</li>
 </ul>
 </li>
 <li>