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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (71) hide show
  1. package/README.md +6 -6
  2. package/ai_guides/README.md +2 -2
  3. package/ai_guides/features/clipper.md +1 -1
  4. package/ai_guides/features/coordinate-system.md +1 -1
  5. package/ai_guides/features/event.md +1 -1
  6. package/ai_guides/features/five.md +3 -3
  7. package/ai_guides/features/gesture.md +2 -2
  8. package/ai_guides/features/get-screen-pixels.md +1 -1
  9. package/ai_guides/features/image-options.md +3 -3
  10. package/ai_guides/features/load-external-model.md +9 -9
  11. package/ai_guides/features/mode.md +2 -2
  12. package/ai_guides/features/pano-filter.md +3 -3
  13. package/ai_guides/features/pano-tile.md +2 -2
  14. package/ai_guides/features/raycast.md +1 -1
  15. package/ai_guides/features/screen-project.md +1 -1
  16. package/ai_guides/features/state.md +1 -1
  17. package/ai_guides/features/work.md +2 -2
  18. package/ai_guides/quick-start.md +3 -3
  19. package/ai_guides/release_notes/6.6.md +2 -2
  20. package/ai_guides/release_notes/6.7.md +1 -1
  21. package/ai_guides/release_notes/6.8.md +1 -1
  22. package/docs/documents/README.html +2 -2
  23. package/docs/documents/features_clipper.html +1 -1
  24. package/docs/documents/features_coordinate-system.html +1 -1
  25. package/docs/documents/features_event.html +1 -1
  26. package/docs/documents/features_five.html +3 -3
  27. package/docs/documents/features_gesture.html +2 -2
  28. package/docs/documents/features_get-screen-pixels.html +1 -1
  29. package/docs/documents/features_image-options.html +3 -3
  30. package/docs/documents/features_load-external-model.html +8 -8
  31. package/docs/documents/features_mode.html +2 -2
  32. package/docs/documents/features_pano-filter.html +3 -3
  33. package/docs/documents/features_pano-tile.html +2 -2
  34. package/docs/documents/features_raycast.html +1 -1
  35. package/docs/documents/features_screen-project.html +1 -1
  36. package/docs/documents/features_state.html +1 -1
  37. package/docs/documents/features_work.html +2 -2
  38. package/docs/documents/quick-start.html +2 -2
  39. package/docs/documents/release_notes_6.6.html +2 -2
  40. package/docs/documents/release_notes_6.7.html +1 -1
  41. package/docs/documents/release_notes_6.8.html +1 -1
  42. package/docs/index.html +2 -2
  43. package/five/index.js +3 -3
  44. package/five/index.mjs +3 -3
  45. package/llms.txt +1 -1
  46. package/package.json +1 -1
  47. package/plugins/BasePlugin/index.d.ts +1 -1
  48. package/plugins/GaussianSplattingEntranceAnimationPlugin/Controller.d.ts +1 -1
  49. package/plugins/GaussianSplattingEntranceAnimationPlugin/index.d.ts +1 -1
  50. package/plugins/index.js +3 -3
  51. package/plugins/index.mjs +3 -3
  52. package/react/context.d.ts +1 -1
  53. package/react/createProvider.d.ts +1 -1
  54. package/react/fiveApp.d.ts +1 -1
  55. package/react/hooks/unsafe__useFiveInstance.d.ts +1 -1
  56. package/react/hooks/useFiveAction.d.ts +1 -1
  57. package/react/hooks/useFiveCurrentObserver.d.ts +1 -1
  58. package/react/hooks/useFiveCurrentState.d.ts +1 -1
  59. package/react/hooks/useFiveEventCallback.d.ts +1 -1
  60. package/react/hooks/useFiveModelEffect.d.ts +1 -1
  61. package/react/hooks/useFiveModelIntersectRaycaster.d.ts +1 -1
  62. package/react/hooks/useFivePlugin.d.ts +1 -1
  63. package/react/hooks/useFiveSceneEffect.d.ts +1 -1
  64. package/react/hooks/useFiveState.d.ts +1 -1
  65. package/react/hooks/useFiveWork.d.ts +1 -1
  66. package/react/index.js +3 -3
  67. package/react/index.mjs +3 -3
  68. package/react/withFive.d.ts +1 -1
  69. package/umd/five-plugins.js +3 -3
  70. package/umd/five-react.js +3 -3
  71. package/umd/five.js +3 -3
package/docs/documents/features_five.html CHANGED
@@ -1,6 +1,6 @@
1
1
  <!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/five | 如视 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/five</a></li></ul></div><div class="tsd-panel tsd-typography"><h1 id="five-five-核心类" class="tsd-anchor-link">Five (Five 核心类)<a href="#five-five-核心类" 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>
2
2
  <ul>
3
- <li><strong>Summary</strong>: Five 是 @realsee/five 的核心类，负责 3D 场景的渲染、资源加载、用户交互和状态管理。</li>
3
+ <li><strong>Summary</strong>: Five 是 @realsee/five-webgpu 的核心类，负责 3D 场景的渲染、资源加载、用户交互和状态管理。</li>
4
4
  <li><strong>Schema</strong>: FiveInitArgs 初始化参数接口。</li>
5
5
  <li><strong>Concepts</strong>: Instance Management, Rendering Loop, Resource Loading, State Sync.</li>
6
6
  <li><strong>Configuration</strong>: Five 初始化参数详解。</li>
@@ -86,12 +86,12 @@
86
86
  <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>
87
87
  <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>
88
88
  <p>创建一个全屏的 Five 实例并加载数据。</p>
89
- <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">parseWork</span><span class="hl-1"> } </span><span class="hl-10">from</span><span class="hl-1"> </span><span class="hl-9">&quot;@realsee/five&quot;</span><span class="hl-1">;</span><br/><br/><span class="hl-8">// 1. 初始化实例</span><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">five</span><span class="hl-1"> = </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-5">Five</span><span class="hl-1">({</span><br/><span class="hl-1"> </span><span class="hl-6">imageOptions:</span><span class="hl-1"> { </span><span class="hl-6">size:</span><span class="hl-1"> </span><span class="hl-11">512</span><span class="hl-1"> }, </span><span class="hl-8">// 初始加载小图</span><br/><span class="hl-1"> </span><span class="hl-6">onlyRenderIfNeeds:</span><span class="hl-1"> </span><span class="hl-3">true</span><br/><span class="hl-1">});</span><br/><br/><span class="hl-8">// 2. 挂载到 DOM</span><br/><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-5">appendTo</span><span class="hl-1">(</span><span class="hl-6">document</span><span class="hl-1">.</span><span class="hl-5">getElementById</span><span class="hl-1">(</span><span class="hl-9">&quot;app&quot;</span><span class="hl-1">));</span><br/><br/><span class="hl-8">// 3. 加载数据</span><br/><span class="hl-8">// workData 通常来自服务端 API</span><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>
89
+ <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">parseWork</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">// 1. 初始化实例</span><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">five</span><span class="hl-1"> = </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-5">Five</span><span class="hl-1">({</span><br/><span class="hl-1"> </span><span class="hl-6">imageOptions:</span><span class="hl-1"> { </span><span class="hl-6">size:</span><span class="hl-1"> </span><span class="hl-11">512</span><span class="hl-1"> }, </span><span class="hl-8">// 初始加载小图</span><br/><span class="hl-1"> </span><span class="hl-6">onlyRenderIfNeeds:</span><span class="hl-1"> </span><span class="hl-3">true</span><br/><span class="hl-1">});</span><br/><br/><span class="hl-8">// 2. 挂载到 DOM</span><br/><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-5">appendTo</span><span class="hl-1">(</span><span class="hl-6">document</span><span class="hl-1">.</span><span class="hl-5">getElementById</span><span class="hl-1">(</span><span class="hl-9">&quot;app&quot;</span><span class="hl-1">));</span><br/><br/><span class="hl-8">// 3. 加载数据</span><br/><span class="hl-8">// workData 通常来自服务端 API</span><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>
90
90
  </code><button type="button">Copy</button></pre>
91
91
 
92
92
  <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>
93
93
  <p>使用外部渲染器并指定视口区域（例如用于分屏渲染）。</p>
94
- <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&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>
94
+ <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>
95
95
  </code><button type="button">Copy</button></pre>
96
96
 
97
97
  <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>
package/docs/documents/features_gesture.html CHANGED
@@ -10,7 +10,7 @@
10
10
  <p><strong>Definition</strong>: <a href="../../five/utils/event.d.ts">GestureEvent</a></p>
11
11
  </blockquote>
12
12
  <p>所有手势事件的回调参数均为 <code>GestureEvent</code> 类型：</p>
13
- <pre><code class="typescript"><span class="hl-10">import</span><span class="hl-1"> { </span><span class="hl-6">State</span><span class="hl-1"> } </span><span class="hl-10">from</span><span class="hl-1"> </span><span class="hl-9">&quot;@realsee/five&quot;</span><span class="hl-1">;</span><br/><span class="hl-10">import</span><span class="hl-1"> </span><span class="hl-3">*</span><span class="hl-1"> </span><span class="hl-10">as</span><span class="hl-1"> </span><span class="hl-6">THREE</span><span class="hl-1"> </span><span class="hl-10">from</span><span class="hl-1"> </span><span class="hl-9">&quot;three/webgpu&quot;</span><span class="hl-1">;</span><br/><br/><span class="hl-3">interface</span><span class="hl-1"> </span><span class="hl-7">GestureEvent</span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-6">type</span><span class="hl-1">: </span><span class="hl-7">string</span><span class="hl-1">; </span><span class="hl-8">// 事件类型，如 &quot;gesture.tap&quot;</span><br/><span class="hl-1"> </span><span class="hl-6">timeStamp</span><span class="hl-1">: </span><span class="hl-7">number</span><span class="hl-1">; </span><span class="hl-8">// 时间戳</span><br/><span class="hl-1"> </span><span class="hl-6">target</span><span class="hl-1">: </span><span class="hl-7">EventTarget</span><span class="hl-1"> | </span><span class="hl-7">null</span><span class="hl-1">;</span><br/><span class="hl-1"> </span><span class="hl-6">pointerType</span><span class="hl-1">: </span><span class="hl-9">&#39;touch&#39;</span><span class="hl-1"> | </span><span class="hl-9">&#39;pen&#39;</span><span class="hl-1"> | </span><span class="hl-9">&#39;mouse&#39;</span><span class="hl-1"> | </span><span class="hl-9">&#39;kinect&#39;</span><span class="hl-1">;</span><br/><br/><span class="hl-1"> </span><span class="hl-8">// 手势中心点信息</span><br/><span class="hl-1"> </span><span class="hl-6">center</span><span class="hl-1">: {</span><br/><span class="hl-1"> </span><span class="hl-6">x</span><span class="hl-1">: </span><span class="hl-7">number</span><span class="hl-1">; </span><span class="hl-8">// 屏幕 X 坐标</span><br/><span class="hl-1"> </span><span class="hl-6">y</span><span class="hl-1">: </span><span class="hl-7">number</span><span class="hl-1">; </span><span class="hl-8">// 屏幕 Y 坐标</span><br/><span class="hl-1"> </span><span class="hl-6">raycaster</span><span class="hl-1">: </span><span class="hl-7">THREE</span><span class="hl-1">.</span><span class="hl-7">Raycaster</span><span class="hl-1">; </span><span class="hl-8">// 从相机发出的射线（已包含坐标变换）</span><br/><span class="hl-1"> };</span><br/><br/><span class="hl-1"> </span><span class="hl-8">// 当前相机状态</span><br/><span class="hl-1"> </span><span class="hl-6">state</span><span class="hl-1">: </span><span class="hl-7">State</span><span class="hl-1">;</span><br/><br/><span class="hl-1"> </span><span class="hl-8">// 是否是用户触发（区别于代码调用）</span><br/><span class="hl-1"> </span><span class="hl-6">userAction</span><span class="hl-1">: </span><span class="hl-7">boolean</span><span class="hl-1">;</span><br/><br/><span class="hl-1"> </span><span class="hl-8">// 阻止默认行为</span><br/><span class="hl-1"> </span><span class="hl-5">preventDefault</span><span class="hl-1">(): </span><span class="hl-7">void</span><span class="hl-1">;</span><br/><span class="hl-1"> </span><span class="hl-6">defaultPrevented</span><span class="hl-1">: </span><span class="hl-7">boolean</span><span class="hl-1">;</span><br/><span class="hl-1">}</span>
13
+ <pre><code class="typescript"><span class="hl-10">import</span><span class="hl-1"> { </span><span class="hl-6">State</span><span class="hl-1"> } </span><span class="hl-10">from</span><span class="hl-1"> </span><span class="hl-9">&quot;@realsee/five-webgpu&quot;</span><span class="hl-1">;</span><br/><span class="hl-10">import</span><span class="hl-1"> </span><span class="hl-3">*</span><span class="hl-1"> </span><span class="hl-10">as</span><span class="hl-1"> </span><span class="hl-6">THREE</span><span class="hl-1"> </span><span class="hl-10">from</span><span class="hl-1"> </span><span class="hl-9">&quot;three/webgpu&quot;</span><span class="hl-1">;</span><br/><br/><span class="hl-3">interface</span><span class="hl-1"> </span><span class="hl-7">GestureEvent</span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-6">type</span><span class="hl-1">: </span><span class="hl-7">string</span><span class="hl-1">; </span><span class="hl-8">// 事件类型，如 &quot;gesture.tap&quot;</span><br/><span class="hl-1"> </span><span class="hl-6">timeStamp</span><span class="hl-1">: </span><span class="hl-7">number</span><span class="hl-1">; </span><span class="hl-8">// 时间戳</span><br/><span class="hl-1"> </span><span class="hl-6">target</span><span class="hl-1">: </span><span class="hl-7">EventTarget</span><span class="hl-1"> | </span><span class="hl-7">null</span><span class="hl-1">;</span><br/><span class="hl-1"> </span><span class="hl-6">pointerType</span><span class="hl-1">: </span><span class="hl-9">&#39;touch&#39;</span><span class="hl-1"> | </span><span class="hl-9">&#39;pen&#39;</span><span class="hl-1"> | </span><span class="hl-9">&#39;mouse&#39;</span><span class="hl-1"> | </span><span class="hl-9">&#39;kinect&#39;</span><span class="hl-1">;</span><br/><br/><span class="hl-1"> </span><span class="hl-8">// 手势中心点信息</span><br/><span class="hl-1"> </span><span class="hl-6">center</span><span class="hl-1">: {</span><br/><span class="hl-1"> </span><span class="hl-6">x</span><span class="hl-1">: </span><span class="hl-7">number</span><span class="hl-1">; </span><span class="hl-8">// 屏幕 X 坐标</span><br/><span class="hl-1"> </span><span class="hl-6">y</span><span class="hl-1">: </span><span class="hl-7">number</span><span class="hl-1">; </span><span class="hl-8">// 屏幕 Y 坐标</span><br/><span class="hl-1"> </span><span class="hl-6">raycaster</span><span class="hl-1">: </span><span class="hl-7">THREE</span><span class="hl-1">.</span><span class="hl-7">Raycaster</span><span class="hl-1">; </span><span class="hl-8">// 从相机发出的射线（已包含坐标变换）</span><br/><span class="hl-1"> };</span><br/><br/><span class="hl-1"> </span><span class="hl-8">// 当前相机状态</span><br/><span class="hl-1"> </span><span class="hl-6">state</span><span class="hl-1">: </span><span class="hl-7">State</span><span class="hl-1">;</span><br/><br/><span class="hl-1"> </span><span class="hl-8">// 是否是用户触发（区别于代码调用）</span><br/><span class="hl-1"> </span><span class="hl-6">userAction</span><span class="hl-1">: </span><span class="hl-7">boolean</span><span class="hl-1">;</span><br/><br/><span class="hl-1"> </span><span class="hl-8">// 阻止默认行为</span><br/><span class="hl-1"> </span><span class="hl-5">preventDefault</span><span class="hl-1">(): </span><span class="hl-7">void</span><span class="hl-1">;</span><br/><span class="hl-1"> </span><span class="hl-6">defaultPrevented</span><span class="hl-1">: </span><span class="hl-7">boolean</span><span class="hl-1">;</span><br/><span class="hl-1">}</span>
14
14
  </code><button type="button">Copy</button></pre>
15
15
 
16
16
  <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>
@@ -84,7 +84,7 @@
84
84
 
85
85
  <h3 id="场景交互：点击添加标签球-add-label-on-click" class="tsd-anchor-link">场景交互：点击添加标签球 (Add Label on Click)<a href="#场景交互：点击添加标签球-add-label-on-click" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3>
86
86
  <p>这个示例展示了如何通过点击事件在场景中添加一个红色的球体，并阻止 Five 默认的点位移动行为。</p>
87
- <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&quot;</span><span class="hl-1">;</span><br/><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">five</span><span class="hl-1"> = </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-5">Five</span><span class="hl-1">();</span><br/><br/><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-5">on</span><span class="hl-1">(</span><span class="hl-9">&quot;gesture.tap&quot;</span><span class="hl-1">, (</span><span class="hl-6">event</span><span class="hl-1">) </span><span class="hl-3">=&gt;</span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-8">// 1. 阻止默认行为（防止点击地面时 Five 自动走点或切换模式）</span><br/><span class="hl-1"> </span><span class="hl-6">event</span><span class="hl-1">.</span><span class="hl-5">preventDefault</span><span class="hl-1">();</span><br/><br/><span class="hl-1"> </span><span class="hl-8">// 2. 获取射线</span><br/><span class="hl-1"> </span><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">raycaster</span><span class="hl-1"> = </span><span class="hl-6">event</span><span class="hl-1">.</span><span class="hl-6">center</span><span class="hl-1">.</span><span class="hl-6">raycaster</span><span class="hl-1">;</span><br/><br/><span class="hl-1"> </span><span class="hl-8">// 3. 检测与模型的碰撞</span><br/><span class="hl-1"> </span><span class="hl-8">// five.model.intersectRaycaster 是 Five 提供的便捷方法，会自动检测所有可见模型</span><br/><span class="hl-1"> </span><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">intersects</span><span class="hl-1"> = </span><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-6">model</span><span class="hl-1">.</span><span class="hl-5">intersectRaycaster</span><span class="hl-1">(</span><span class="hl-6">raycaster</span><span class="hl-1">);</span><br/><br/><span class="hl-1"> </span><span class="hl-10">if</span><span class="hl-1"> (</span><span class="hl-6">intersects</span><span class="hl-1">.</span><span class="hl-6">length</span><span class="hl-1"> &gt; </span><span class="hl-11">0</span><span class="hl-1">) {</span><br/><span class="hl-1"> </span><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">intersect</span><span class="hl-1"> = </span><span class="hl-6">intersects</span><span class="hl-1">[</span><span class="hl-11">0</span><span class="hl-1">];</span><br/><span class="hl-1"> </span><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">point</span><span class="hl-1"> = </span><span class="hl-6">intersect</span><span class="hl-1">.</span><span class="hl-6">point</span><span class="hl-1">; </span><span class="hl-8">// 碰撞点世界坐标</span><br/><br/><span class="hl-1"> </span><span class="hl-6">console</span><span class="hl-1">.</span><span class="hl-5">log</span><span class="hl-1">(</span><span class="hl-9">&quot;点击到了模型，坐标:&quot;</span><span class="hl-1">, </span><span class="hl-6">point</span><span class="hl-1">);</span><br/><br/><span class="hl-1"> </span><span class="hl-8">// 4. 创建一个小球</span><br/><span class="hl-1"> </span><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">geometry</span><span class="hl-1"> = </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-4">THREE</span><span class="hl-1">.</span><span class="hl-5">SphereGeometry</span><span class="hl-1">(</span><span class="hl-11">0.1</span><span class="hl-1">, </span><span class="hl-11">32</span><span class="hl-1">, </span><span class="hl-11">32</span><span class="hl-1">);</span><br/><span class="hl-1"> </span><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">material</span><span class="hl-1"> = </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-4">THREE</span><span class="hl-1">.</span><span class="hl-5">MeshBasicMaterial</span><span class="hl-1">({ </span><span class="hl-6">color:</span><span class="hl-1"> </span><span class="hl-11">0xff0000</span><span class="hl-1"> });</span><br/><span class="hl-1"> </span><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">sphere</span><span class="hl-1"> = </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-4">THREE</span><span class="hl-1">.</span><span class="hl-5">Mesh</span><span class="hl-1">(</span><span class="hl-6">geometry</span><span class="hl-1">, </span><span class="hl-6">material</span><span class="hl-1">);</span><br/><br/><span class="hl-1"> </span><span class="hl-8">// 5. 设置位置并添加到场景</span><br/><span class="hl-1"> </span><span class="hl-6">sphere</span><span class="hl-1">.</span><span class="hl-6">position</span><span class="hl-1">.</span><span class="hl-5">copy</span><span class="hl-1">(</span><span class="hl-6">point</span><span class="hl-1">);</span><br/><span class="hl-1"> </span><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-6">scene</span><span class="hl-1">.</span><span class="hl-5">add</span><span class="hl-1">(</span><span class="hl-6">sphere</span><span class="hl-1">);</span><br/><br/><span class="hl-1"> </span><span class="hl-8">// 强制刷新渲染，确保小球立即出现</span><br/><span class="hl-1"> </span><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-6">needsRender</span><span class="hl-1"> = </span><span class="hl-3">true</span><span class="hl-1">;</span><br/><span class="hl-1"> } </span><span class="hl-10">else</span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-6">console</span><span class="hl-1">.</span><span class="hl-5">log</span><span class="hl-1">(</span><span class="hl-9">&quot;未点击到任何模型&quot;</span><span class="hl-1">);</span><br/><span class="hl-1"> }</span><br/><span class="hl-1">});</span>
87
+ <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">five</span><span class="hl-1"> = </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-5">Five</span><span class="hl-1">();</span><br/><br/><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-5">on</span><span class="hl-1">(</span><span class="hl-9">&quot;gesture.tap&quot;</span><span class="hl-1">, (</span><span class="hl-6">event</span><span class="hl-1">) </span><span class="hl-3">=&gt;</span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-8">// 1. 阻止默认行为（防止点击地面时 Five 自动走点或切换模式）</span><br/><span class="hl-1"> </span><span class="hl-6">event</span><span class="hl-1">.</span><span class="hl-5">preventDefault</span><span class="hl-1">();</span><br/><br/><span class="hl-1"> </span><span class="hl-8">// 2. 获取射线</span><br/><span class="hl-1"> </span><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">raycaster</span><span class="hl-1"> = </span><span class="hl-6">event</span><span class="hl-1">.</span><span class="hl-6">center</span><span class="hl-1">.</span><span class="hl-6">raycaster</span><span class="hl-1">;</span><br/><br/><span class="hl-1"> </span><span class="hl-8">// 3. 检测与模型的碰撞</span><br/><span class="hl-1"> </span><span class="hl-8">// five.model.intersectRaycaster 是 Five 提供的便捷方法，会自动检测所有可见模型</span><br/><span class="hl-1"> </span><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">intersects</span><span class="hl-1"> = </span><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-6">model</span><span class="hl-1">.</span><span class="hl-5">intersectRaycaster</span><span class="hl-1">(</span><span class="hl-6">raycaster</span><span class="hl-1">);</span><br/><br/><span class="hl-1"> </span><span class="hl-10">if</span><span class="hl-1"> (</span><span class="hl-6">intersects</span><span class="hl-1">.</span><span class="hl-6">length</span><span class="hl-1"> &gt; </span><span class="hl-11">0</span><span class="hl-1">) {</span><br/><span class="hl-1"> </span><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">intersect</span><span class="hl-1"> = </span><span class="hl-6">intersects</span><span class="hl-1">[</span><span class="hl-11">0</span><span class="hl-1">];</span><br/><span class="hl-1"> </span><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">point</span><span class="hl-1"> = </span><span class="hl-6">intersect</span><span class="hl-1">.</span><span class="hl-6">point</span><span class="hl-1">; </span><span class="hl-8">// 碰撞点世界坐标</span><br/><br/><span class="hl-1"> </span><span class="hl-6">console</span><span class="hl-1">.</span><span class="hl-5">log</span><span class="hl-1">(</span><span class="hl-9">&quot;点击到了模型，坐标:&quot;</span><span class="hl-1">, </span><span class="hl-6">point</span><span class="hl-1">);</span><br/><br/><span class="hl-1"> </span><span class="hl-8">// 4. 创建一个小球</span><br/><span class="hl-1"> </span><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">geometry</span><span class="hl-1"> = </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-4">THREE</span><span class="hl-1">.</span><span class="hl-5">SphereGeometry</span><span class="hl-1">(</span><span class="hl-11">0.1</span><span class="hl-1">, </span><span class="hl-11">32</span><span class="hl-1">, </span><span class="hl-11">32</span><span class="hl-1">);</span><br/><span class="hl-1"> </span><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">material</span><span class="hl-1"> = </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-4">THREE</span><span class="hl-1">.</span><span class="hl-5">MeshBasicMaterial</span><span class="hl-1">({ </span><span class="hl-6">color:</span><span class="hl-1"> </span><span class="hl-11">0xff0000</span><span class="hl-1"> });</span><br/><span class="hl-1"> </span><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">sphere</span><span class="hl-1"> = </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-4">THREE</span><span class="hl-1">.</span><span class="hl-5">Mesh</span><span class="hl-1">(</span><span class="hl-6">geometry</span><span class="hl-1">, </span><span class="hl-6">material</span><span class="hl-1">);</span><br/><br/><span class="hl-1"> </span><span class="hl-8">// 5. 设置位置并添加到场景</span><br/><span class="hl-1"> </span><span class="hl-6">sphere</span><span class="hl-1">.</span><span class="hl-6">position</span><span class="hl-1">.</span><span class="hl-5">copy</span><span class="hl-1">(</span><span class="hl-6">point</span><span class="hl-1">);</span><br/><span class="hl-1"> </span><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-6">scene</span><span class="hl-1">.</span><span class="hl-5">add</span><span class="hl-1">(</span><span class="hl-6">sphere</span><span class="hl-1">);</span><br/><br/><span class="hl-1"> </span><span class="hl-8">// 强制刷新渲染，确保小球立即出现</span><br/><span class="hl-1"> </span><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-6">needsRender</span><span class="hl-1"> = </span><span class="hl-3">true</span><span class="hl-1">;</span><br/><span class="hl-1"> } </span><span class="hl-10">else</span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-6">console</span><span class="hl-1">.</span><span class="hl-5">log</span><span class="hl-1">(</span><span class="hl-9">&quot;未点击到任何模型&quot;</span><span class="hl-1">);</span><br/><span class="hl-1"> }</span><br/><span class="hl-1">});</span>
88
88
  </code><button type="button">Copy</button></pre>
89
89
 
90
90
  <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>
package/docs/documents/features_get-screen-pixels.html CHANGED
@@ -39,7 +39,7 @@
39
39
  <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>
40
40
  <h3 id="放大镜-magnifier" class="tsd-anchor-link">放大镜 (Magnifier)<a href="#放大镜-magnifier" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3>
41
41
  <p>这是一个经典的放大镜实现示例。通过获取鼠标周围的像素，并以更高的 <code>pixelRatio</code> 重新渲染，从而获得清晰的放大效果。</p>
42
- <pre><code class="typescript"><span class="hl-10">import</span><span class="hl-1"> </span><span class="hl-3">*</span><span class="hl-1"> </span><span class="hl-10">as</span><span class="hl-1"> </span><span class="hl-6">THREE</span><span class="hl-1"> </span><span class="hl-10">from</span><span class="hl-1"> </span><span class="hl-9">&#39;three&#39;</span><span class="hl-1">;</span><br/><span class="hl-10">import</span><span class="hl-1"> { </span><span class="hl-6">Five</span><span class="hl-1"> } </span><span class="hl-10">from</span><span class="hl-1"> </span><span class="hl-9">&#39;@realsee/five&#39;</span><span class="hl-1">;</span><br/><br/><span class="hl-8">// 假设有一个用于显示的 canvas</span><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">magnifierCanvas</span><span class="hl-1"> = </span><span class="hl-6">document</span><span class="hl-1">.</span><span class="hl-5">getElementById</span><span class="hl-1">(</span><span class="hl-9">&#39;magnifier-canvas&#39;</span><span class="hl-1">) </span><span class="hl-10">as</span><span class="hl-1"> </span><span class="hl-7">HTMLCanvasElement</span><span class="hl-1">;</span><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">ctx</span><span class="hl-1"> = </span><span class="hl-6">magnifierCanvas</span><span class="hl-1">.</span><span class="hl-5">getContext</span><span class="hl-1">(</span><span class="hl-9">&#39;2d&#39;</span><span class="hl-1">)!;</span><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">magnifierSize</span><span class="hl-1"> = </span><span class="hl-11">200</span><span class="hl-1">; </span><span class="hl-8">// 放大镜尺寸 200px</span><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">scale</span><span class="hl-1"> = </span><span class="hl-11">2</span><span class="hl-1">; </span><span class="hl-8">// 放大倍数</span><br/><br/><span class="hl-8">// 预先创建 Buffer 以提升性能</span><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">pixelWidth</span><span class="hl-1"> = </span><span class="hl-6">magnifierSize</span><span class="hl-1"> * </span><span class="hl-6">scale</span><span class="hl-1">;</span><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">pixelHeight</span><span class="hl-1"> = </span><span class="hl-6">magnifierSize</span><span class="hl-1"> * </span><span class="hl-6">scale</span><span class="hl-1">;</span><br/><span class="hl-3">let</span><span class="hl-1"> </span><span class="hl-6">magnifierImageData</span><span class="hl-1"> = </span><span class="hl-6">ctx</span><span class="hl-1">.</span><span class="hl-5">createImageData</span><span class="hl-1">(</span><span class="hl-6">pixelWidth</span><span class="hl-1">, </span><span class="hl-6">pixelHeight</span><span class="hl-1">);</span><br/><br/><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-5">on</span><span class="hl-1">(</span><span class="hl-9">&#39;gesture.mousemove&#39;</span><span class="hl-1">, (</span><span class="hl-6">event</span><span class="hl-1">) </span><span class="hl-3">=&gt;</span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-8">// 1. 获取鼠标在 Canvas 上的坐标</span><br/><span class="hl-1"> </span><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">mouse</span><span class="hl-1"> = </span><span class="hl-6">event</span><span class="hl-1">.</span><span class="hl-6">pointers</span><span class="hl-1">[</span><span class="hl-11">0</span><span class="hl-1">]?.</span><span class="hl-6">coords</span><span class="hl-1">;</span><br/><span class="hl-1"> </span><span class="hl-10">if</span><span class="hl-1"> (!</span><span class="hl-6">mouse</span><span class="hl-1">) </span><span class="hl-10">return</span><span class="hl-1">;</span><br/><br/><span class="hl-1"> </span><span class="hl-8">// 转换归一化坐标 (-1 到 1) 到 像素坐标</span><br/><span class="hl-1"> </span><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">renderSize</span><span class="hl-1"> = </span><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-5">getSize</span><span class="hl-1">(</span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-4">THREE</span><span class="hl-1">.</span><span class="hl-5">Vector2</span><span class="hl-1">());</span><br/><span class="hl-1"> </span><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">x</span><span class="hl-1"> = (</span><span class="hl-6">mouse</span><span class="hl-1">.</span><span class="hl-6">x</span><span class="hl-1"> + </span><span class="hl-11">1</span><span class="hl-1">) / </span><span class="hl-11">2</span><span class="hl-1"> * </span><span class="hl-6">renderSize</span><span class="hl-1">.</span><span class="hl-6">x</span><span class="hl-1">;</span><br/><span class="hl-1"> </span><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">y</span><span class="hl-1"> = (</span><span class="hl-6">mouse</span><span class="hl-1">.</span><span class="hl-6">y</span><span class="hl-1"> + </span><span class="hl-11">1</span><span class="hl-1">) / </span><span class="hl-11">2</span><span class="hl-1"> * </span><span class="hl-6">renderSize</span><span class="hl-1">.</span><span class="hl-6">y</span><span class="hl-1">;</span><br/><br/><span class="hl-1"> </span><span class="hl-8">// 2. 获取像素数据</span><br/><span class="hl-1"> </span><span class="hl-8">// 注意：我们以更高的分辨率 (pixelRatio * scale) 渲染小区域，从而获得“无损”放大效果</span><br/><span class="hl-1"> </span><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">pixelRatio</span><span class="hl-1"> = </span><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-6">renderer</span><span class="hl-1">?.</span><span class="hl-5">getPixelRatio</span><span class="hl-1">() ?? </span><span class="hl-11">1</span><span class="hl-1">;</span><br/><span class="hl-1"> </span><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">targetPixelRatio</span><span class="hl-1"> = </span><span class="hl-6">Math</span><span class="hl-1">.</span><span class="hl-5">ceil</span><span class="hl-1">(</span><span class="hl-6">pixelRatio</span><span class="hl-1"> * </span><span class="hl-6">scale</span><span class="hl-1">);</span><br/><br/><span class="hl-1"> </span><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-5">getPixels</span><span class="hl-1">({</span><br/><span class="hl-1"> </span><span class="hl-6">x:</span><span class="hl-1"> </span><span class="hl-6">x</span><span class="hl-1"> - </span><span class="hl-6">magnifierSize</span><span class="hl-1"> / </span><span class="hl-11">2</span><span class="hl-1">, </span><span class="hl-8">// 居中</span><br/><span class="hl-1"> </span><span class="hl-6">y:</span><span class="hl-1"> </span><span class="hl-6">y</span><span class="hl-1"> - </span><span class="hl-6">magnifierSize</span><span class="hl-1"> / </span><span class="hl-11">2</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-6">width:</span><span class="hl-1"> </span><span class="hl-6">magnifierSize</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-6">height:</span><span class="hl-1"> </span><span class="hl-6">magnifierSize</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-6">pixelRatio:</span><span class="hl-1"> </span><span class="hl-6">targetPixelRatio</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-6">flipY:</span><span class="hl-1"> </span><span class="hl-3">true</span><span class="hl-1">, </span><span class="hl-8">// 翻转以适配 Canvas 2D</span><br/><span class="hl-1"> </span><span class="hl-6">buffer:</span><span class="hl-1"> </span><span class="hl-6">magnifierImageData</span><span class="hl-1">.</span><span class="hl-6">data</span><span class="hl-1">, </span><span class="hl-8">// 复用 buffer</span><br/><span class="hl-1"> </span><span class="hl-6">helperVisible:</span><span class="hl-1"> </span><span class="hl-3">false</span><span class="hl-1">, </span><span class="hl-8">// 隐藏辅助线等干扰元素</span><br/><span class="hl-1"> });</span><br/><br/><span class="hl-1"> </span><span class="hl-8">// 3. 将数据绘制到放大镜 Canvas 上</span><br/><span class="hl-1"> </span><span class="hl-8">// 需要调整 Canvas 尺寸以匹配数据</span><br/><span class="hl-1"> </span><span class="hl-6">magnifierCanvas</span><span class="hl-1">.</span><span class="hl-6">width</span><span class="hl-1"> = </span><span class="hl-6">pixelWidth</span><span class="hl-1">;</span><br/><span class="hl-1"> </span><span class="hl-6">magnifierCanvas</span><span class="hl-1">.</span><span class="hl-6">height</span><span class="hl-1"> = </span><span class="hl-6">pixelHeight</span><span class="hl-1">;</span><br/><span class="hl-1"> </span><span class="hl-6">ctx</span><span class="hl-1">.</span><span class="hl-5">putImageData</span><span class="hl-1">(</span><span class="hl-6">magnifierImageData</span><span class="hl-1">, </span><span class="hl-11">0</span><span class="hl-1">, </span><span class="hl-11">0</span><span class="hl-1">);</span><br/><br/><span class="hl-1"> </span><span class="hl-8">// 4. 更新放大镜位置 (CSS)</span><br/><span class="hl-1"> </span><span class="hl-6">magnifierCanvas</span><span class="hl-1">.</span><span class="hl-6">style</span><span class="hl-1">.</span><span class="hl-6">left</span><span class="hl-1"> = </span><span class="hl-9">`</span><span class="hl-3">${</span><span class="hl-6">x</span><span class="hl-12"> </span><span class="hl-1">-</span><span class="hl-12"> </span><span class="hl-6">magnifierSize</span><span class="hl-12"> </span><span class="hl-1">/</span><span class="hl-12"> </span><span class="hl-11">2</span><span class="hl-3">}</span><span class="hl-9">px`</span><span class="hl-1">;</span><br/><span class="hl-1"> </span><span class="hl-6">magnifierCanvas</span><span class="hl-1">.</span><span class="hl-6">style</span><span class="hl-1">.</span><span class="hl-6">top</span><span class="hl-1"> = </span><span class="hl-9">`</span><span class="hl-3">${</span><span class="hl-6">renderSize</span><span class="hl-12">.</span><span class="hl-6">y</span><span class="hl-12"> </span><span class="hl-1">-</span><span class="hl-12"> </span><span class="hl-6">y</span><span class="hl-12"> </span><span class="hl-1">-</span><span class="hl-12"> </span><span class="hl-6">magnifierSize</span><span class="hl-12"> </span><span class="hl-1">/</span><span class="hl-12"> </span><span class="hl-11">2</span><span class="hl-3">}</span><span class="hl-9">px`</span><span class="hl-1">; </span><span class="hl-8">// 注意 Y 轴方向</span><br/><span class="hl-1">});</span>
42
+ <pre><code class="typescript"><span class="hl-10">import</span><span class="hl-1"> </span><span class="hl-3">*</span><span class="hl-1"> </span><span class="hl-10">as</span><span class="hl-1"> </span><span class="hl-6">THREE</span><span class="hl-1"> </span><span class="hl-10">from</span><span class="hl-1"> </span><span class="hl-9">&#39;three&#39;</span><span class="hl-1">;</span><br/><span class="hl-10">import</span><span class="hl-1"> { </span><span class="hl-6">Five</span><span class="hl-1"> } </span><span class="hl-10">from</span><span class="hl-1"> </span><span class="hl-9">&#39;@realsee/five-webgpu&#39;</span><span class="hl-1">;</span><br/><br/><span class="hl-8">// 假设有一个用于显示的 canvas</span><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">magnifierCanvas</span><span class="hl-1"> = </span><span class="hl-6">document</span><span class="hl-1">.</span><span class="hl-5">getElementById</span><span class="hl-1">(</span><span class="hl-9">&#39;magnifier-canvas&#39;</span><span class="hl-1">) </span><span class="hl-10">as</span><span class="hl-1"> </span><span class="hl-7">HTMLCanvasElement</span><span class="hl-1">;</span><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">ctx</span><span class="hl-1"> = </span><span class="hl-6">magnifierCanvas</span><span class="hl-1">.</span><span class="hl-5">getContext</span><span class="hl-1">(</span><span class="hl-9">&#39;2d&#39;</span><span class="hl-1">)!;</span><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">magnifierSize</span><span class="hl-1"> = </span><span class="hl-11">200</span><span class="hl-1">; </span><span class="hl-8">// 放大镜尺寸 200px</span><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">scale</span><span class="hl-1"> = </span><span class="hl-11">2</span><span class="hl-1">; </span><span class="hl-8">// 放大倍数</span><br/><br/><span class="hl-8">// 预先创建 Buffer 以提升性能</span><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">pixelWidth</span><span class="hl-1"> = </span><span class="hl-6">magnifierSize</span><span class="hl-1"> * </span><span class="hl-6">scale</span><span class="hl-1">;</span><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">pixelHeight</span><span class="hl-1"> = </span><span class="hl-6">magnifierSize</span><span class="hl-1"> * </span><span class="hl-6">scale</span><span class="hl-1">;</span><br/><span class="hl-3">let</span><span class="hl-1"> </span><span class="hl-6">magnifierImageData</span><span class="hl-1"> = </span><span class="hl-6">ctx</span><span class="hl-1">.</span><span class="hl-5">createImageData</span><span class="hl-1">(</span><span class="hl-6">pixelWidth</span><span class="hl-1">, </span><span class="hl-6">pixelHeight</span><span class="hl-1">);</span><br/><br/><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-5">on</span><span class="hl-1">(</span><span class="hl-9">&#39;gesture.mousemove&#39;</span><span class="hl-1">, (</span><span class="hl-6">event</span><span class="hl-1">) </span><span class="hl-3">=&gt;</span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-8">// 1. 获取鼠标在 Canvas 上的坐标</span><br/><span class="hl-1"> </span><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">mouse</span><span class="hl-1"> = </span><span class="hl-6">event</span><span class="hl-1">.</span><span class="hl-6">pointers</span><span class="hl-1">[</span><span class="hl-11">0</span><span class="hl-1">]?.</span><span class="hl-6">coords</span><span class="hl-1">;</span><br/><span class="hl-1"> </span><span class="hl-10">if</span><span class="hl-1"> (!</span><span class="hl-6">mouse</span><span class="hl-1">) </span><span class="hl-10">return</span><span class="hl-1">;</span><br/><br/><span class="hl-1"> </span><span class="hl-8">// 转换归一化坐标 (-1 到 1) 到 像素坐标</span><br/><span class="hl-1"> </span><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">renderSize</span><span class="hl-1"> = </span><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-5">getSize</span><span class="hl-1">(</span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-4">THREE</span><span class="hl-1">.</span><span class="hl-5">Vector2</span><span class="hl-1">());</span><br/><span class="hl-1"> </span><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">x</span><span class="hl-1"> = (</span><span class="hl-6">mouse</span><span class="hl-1">.</span><span class="hl-6">x</span><span class="hl-1"> + </span><span class="hl-11">1</span><span class="hl-1">) / </span><span class="hl-11">2</span><span class="hl-1"> * </span><span class="hl-6">renderSize</span><span class="hl-1">.</span><span class="hl-6">x</span><span class="hl-1">;</span><br/><span class="hl-1"> </span><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">y</span><span class="hl-1"> = (</span><span class="hl-6">mouse</span><span class="hl-1">.</span><span class="hl-6">y</span><span class="hl-1"> + </span><span class="hl-11">1</span><span class="hl-1">) / </span><span class="hl-11">2</span><span class="hl-1"> * </span><span class="hl-6">renderSize</span><span class="hl-1">.</span><span class="hl-6">y</span><span class="hl-1">;</span><br/><br/><span class="hl-1"> </span><span class="hl-8">// 2. 获取像素数据</span><br/><span class="hl-1"> </span><span class="hl-8">// 注意：我们以更高的分辨率 (pixelRatio * scale) 渲染小区域，从而获得“无损”放大效果</span><br/><span class="hl-1"> </span><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">pixelRatio</span><span class="hl-1"> = </span><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-6">renderer</span><span class="hl-1">?.</span><span class="hl-5">getPixelRatio</span><span class="hl-1">() ?? </span><span class="hl-11">1</span><span class="hl-1">;</span><br/><span class="hl-1"> </span><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">targetPixelRatio</span><span class="hl-1"> = </span><span class="hl-6">Math</span><span class="hl-1">.</span><span class="hl-5">ceil</span><span class="hl-1">(</span><span class="hl-6">pixelRatio</span><span class="hl-1"> * </span><span class="hl-6">scale</span><span class="hl-1">);</span><br/><br/><span class="hl-1"> </span><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-5">getPixels</span><span class="hl-1">({</span><br/><span class="hl-1"> </span><span class="hl-6">x:</span><span class="hl-1"> </span><span class="hl-6">x</span><span class="hl-1"> - </span><span class="hl-6">magnifierSize</span><span class="hl-1"> / </span><span class="hl-11">2</span><span class="hl-1">, </span><span class="hl-8">// 居中</span><br/><span class="hl-1"> </span><span class="hl-6">y:</span><span class="hl-1"> </span><span class="hl-6">y</span><span class="hl-1"> - </span><span class="hl-6">magnifierSize</span><span class="hl-1"> / </span><span class="hl-11">2</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-6">width:</span><span class="hl-1"> </span><span class="hl-6">magnifierSize</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-6">height:</span><span class="hl-1"> </span><span class="hl-6">magnifierSize</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-6">pixelRatio:</span><span class="hl-1"> </span><span class="hl-6">targetPixelRatio</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-6">flipY:</span><span class="hl-1"> </span><span class="hl-3">true</span><span class="hl-1">, </span><span class="hl-8">// 翻转以适配 Canvas 2D</span><br/><span class="hl-1"> </span><span class="hl-6">buffer:</span><span class="hl-1"> </span><span class="hl-6">magnifierImageData</span><span class="hl-1">.</span><span class="hl-6">data</span><span class="hl-1">, </span><span class="hl-8">// 复用 buffer</span><br/><span class="hl-1"> </span><span class="hl-6">helperVisible:</span><span class="hl-1"> </span><span class="hl-3">false</span><span class="hl-1">, </span><span class="hl-8">// 隐藏辅助线等干扰元素</span><br/><span class="hl-1"> });</span><br/><br/><span class="hl-1"> </span><span class="hl-8">// 3. 将数据绘制到放大镜 Canvas 上</span><br/><span class="hl-1"> </span><span class="hl-8">// 需要调整 Canvas 尺寸以匹配数据</span><br/><span class="hl-1"> </span><span class="hl-6">magnifierCanvas</span><span class="hl-1">.</span><span class="hl-6">width</span><span class="hl-1"> = </span><span class="hl-6">pixelWidth</span><span class="hl-1">;</span><br/><span class="hl-1"> </span><span class="hl-6">magnifierCanvas</span><span class="hl-1">.</span><span class="hl-6">height</span><span class="hl-1"> = </span><span class="hl-6">pixelHeight</span><span class="hl-1">;</span><br/><span class="hl-1"> </span><span class="hl-6">ctx</span><span class="hl-1">.</span><span class="hl-5">putImageData</span><span class="hl-1">(</span><span class="hl-6">magnifierImageData</span><span class="hl-1">, </span><span class="hl-11">0</span><span class="hl-1">, </span><span class="hl-11">0</span><span class="hl-1">);</span><br/><br/><span class="hl-1"> </span><span class="hl-8">// 4. 更新放大镜位置 (CSS)</span><br/><span class="hl-1"> </span><span class="hl-6">magnifierCanvas</span><span class="hl-1">.</span><span class="hl-6">style</span><span class="hl-1">.</span><span class="hl-6">left</span><span class="hl-1"> = </span><span class="hl-9">`</span><span class="hl-3">${</span><span class="hl-6">x</span><span class="hl-12"> </span><span class="hl-1">-</span><span class="hl-12"> </span><span class="hl-6">magnifierSize</span><span class="hl-12"> </span><span class="hl-1">/</span><span class="hl-12"> </span><span class="hl-11">2</span><span class="hl-3">}</span><span class="hl-9">px`</span><span class="hl-1">;</span><br/><span class="hl-1"> </span><span class="hl-6">magnifierCanvas</span><span class="hl-1">.</span><span class="hl-6">style</span><span class="hl-1">.</span><span class="hl-6">top</span><span class="hl-1"> = </span><span class="hl-9">`</span><span class="hl-3">${</span><span class="hl-6">renderSize</span><span class="hl-12">.</span><span class="hl-6">y</span><span class="hl-12"> </span><span class="hl-1">-</span><span class="hl-12"> </span><span class="hl-6">y</span><span class="hl-12"> </span><span class="hl-1">-</span><span class="hl-12"> </span><span class="hl-6">magnifierSize</span><span class="hl-12"> </span><span class="hl-1">/</span><span class="hl-12"> </span><span class="hl-11">2</span><span class="hl-3">}</span><span class="hl-9">px`</span><span class="hl-1">; </span><span class="hl-8">// 注意 Y 轴方向</span><br/><span class="hl-1">});</span>
43
43
  </code><button type="button">Copy</button></pre>
44
44
 
45
45
  <h3 id="获取中心点颜色-color-picker" class="tsd-anchor-link">获取中心点颜色 (Color Picker)<a href="#获取中心点颜色-color-picker" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3>
package/docs/documents/features_image-options.html CHANGED
@@ -84,17 +84,17 @@
84
84
  <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>
85
85
  <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>
86
86
  <p>启用 AVIF 格式并设置初始尺寸为 <code>512</code>，适用于大多数场景。</p>
87
- <pre><code class="typescript"><span class="hl-10">import</span><span class="hl-1"> { </span><span class="hl-6">Five</span><span class="hl-1"> } </span><span class="hl-10">from</span><span class="hl-1"> </span><span class="hl-9">&quot;@realsee/five&quot;</span><span class="hl-1">;</span><br/><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">five</span><span class="hl-1"> = </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-5">Five</span><span class="hl-1">({</span><br/><span class="hl-1"> </span><span class="hl-6">imageOptions:</span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-6">format:</span><span class="hl-1"> </span><span class="hl-9">&quot;avif&quot;</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-6">size:</span><span class="hl-1"> </span><span class="hl-11">512</span><span class="hl-1">,</span><br/><span class="hl-1"> }</span><br/><span class="hl-1">});</span>
87
+ <pre><code class="typescript"><span class="hl-10">import</span><span class="hl-1"> { </span><span class="hl-6">Five</span><span class="hl-1"> } </span><span class="hl-10">from</span><span class="hl-1"> </span><span class="hl-9">&quot;@realsee/five-webgpu&quot;</span><span class="hl-1">;</span><br/><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">five</span><span class="hl-1"> = </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-5">Five</span><span class="hl-1">({</span><br/><span class="hl-1"> </span><span class="hl-6">imageOptions:</span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-6">format:</span><span class="hl-1"> </span><span class="hl-9">&quot;avif&quot;</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-6">size:</span><span class="hl-1"> </span><span class="hl-11">512</span><span class="hl-1">,</span><br/><span class="hl-1"> }</span><br/><span class="hl-1">});</span>
88
88
  </code><button type="button">Copy</button></pre>
89
89
 
90
90
  <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>
91
91
  <p>将数据中的 <code>custom-oss-public.ljcdn.com</code> 域名映射到对应的资源专用 OSS 域名。</p>
92
- <pre><code class="typescript"><span class="hl-10">import</span><span class="hl-1"> { </span><span class="hl-6">Five</span><span class="hl-1"> } </span><span class="hl-10">from</span><span class="hl-1"> </span><span class="hl-9">&quot;@realsee/five&quot;</span><span class="hl-1">;</span><br/><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">five</span><span class="hl-1"> = </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-5">Five</span><span class="hl-1">({</span><br/><span class="hl-1"> </span><span class="hl-6">imageOptions:</span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-6">mappings:</span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-9">&quot;custom-oss-public.ljcdn.com&quot;</span><span class="hl-6">:</span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-6">type:</span><span class="hl-1"> </span><span class="hl-9">&quot;tencentCloud&quot;</span><span class="hl-1">, </span><span class="hl-8">// 指定使用腾讯云图片处理协议</span><br/><span class="hl-1"> </span><span class="hl-6">pano:</span><span class="hl-1"> [</span><span class="hl-9">&quot;custom-oss-image-1.com&quot;</span><span class="hl-1">, </span><span class="hl-9">&quot;custom-oss-image-2.com&quot;</span><span class="hl-1">], </span><span class="hl-8">// 双域名负载均衡</span><br/><span class="hl-1"> </span><span class="hl-6">tile:</span><span class="hl-1"> [</span><span class="hl-9">&quot;custom-oss-tile-1.com&quot;</span><span class="hl-1">, </span><span class="hl-9">&quot;custom-oss-tile-2.com&quot;</span><span class="hl-1">],</span><br/><span class="hl-1"> </span><span class="hl-6">model:</span><span class="hl-1"> [</span><span class="hl-9">&quot;custom-oss-model-1.com&quot;</span><span class="hl-1">, </span><span class="hl-9">&quot;custom-oss-model-2.com&quot;</span><span class="hl-1">],</span><br/><span class="hl-1"> </span><span class="hl-6">texture:</span><span class="hl-1"> [</span><span class="hl-9">&quot;custom-oss-image-3.com&quot;</span><span class="hl-1">],</span><br/><span class="hl-1"> </span><span class="hl-6">default:</span><span class="hl-1"> [</span><span class="hl-9">&quot;custom-oss-image-4.com&quot;</span><span class="hl-1">]</span><br/><span class="hl-1"> }</span><br/><span class="hl-1"> }</span><br/><span class="hl-1"> }</span><br/><span class="hl-1">});</span>
92
+ <pre><code class="typescript"><span class="hl-10">import</span><span class="hl-1"> { </span><span class="hl-6">Five</span><span class="hl-1"> } </span><span class="hl-10">from</span><span class="hl-1"> </span><span class="hl-9">&quot;@realsee/five-webgpu&quot;</span><span class="hl-1">;</span><br/><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">five</span><span class="hl-1"> = </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-5">Five</span><span class="hl-1">({</span><br/><span class="hl-1"> </span><span class="hl-6">imageOptions:</span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-6">mappings:</span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-9">&quot;custom-oss-public.ljcdn.com&quot;</span><span class="hl-6">:</span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-6">type:</span><span class="hl-1"> </span><span class="hl-9">&quot;tencentCloud&quot;</span><span class="hl-1">, </span><span class="hl-8">// 指定使用腾讯云图片处理协议</span><br/><span class="hl-1"> </span><span class="hl-6">pano:</span><span class="hl-1"> [</span><span class="hl-9">&quot;custom-oss-image-1.com&quot;</span><span class="hl-1">, </span><span class="hl-9">&quot;custom-oss-image-2.com&quot;</span><span class="hl-1">], </span><span class="hl-8">// 双域名负载均衡</span><br/><span class="hl-1"> </span><span class="hl-6">tile:</span><span class="hl-1"> [</span><span class="hl-9">&quot;custom-oss-tile-1.com&quot;</span><span class="hl-1">, </span><span class="hl-9">&quot;custom-oss-tile-2.com&quot;</span><span class="hl-1">],</span><br/><span class="hl-1"> </span><span class="hl-6">model:</span><span class="hl-1"> [</span><span class="hl-9">&quot;custom-oss-model-1.com&quot;</span><span class="hl-1">, </span><span class="hl-9">&quot;custom-oss-model-2.com&quot;</span><span class="hl-1">],</span><br/><span class="hl-1"> </span><span class="hl-6">texture:</span><span class="hl-1"> [</span><span class="hl-9">&quot;custom-oss-image-3.com&quot;</span><span class="hl-1">],</span><br/><span class="hl-1"> </span><span class="hl-6">default:</span><span class="hl-1"> [</span><span class="hl-9">&quot;custom-oss-image-4.com&quot;</span><span class="hl-1">]</span><br/><span class="hl-1"> }</span><br/><span class="hl-1"> }</span><br/><span class="hl-1"> }</span><br/><span class="hl-1">});</span>
93
93
  </code><button type="button">Copy</button></pre>
94
94
 
95
95
  <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>
96
96
  <p>使用 SDK 提供的 <code>defaultImageURLTransform</code> 工具函数（通常导出为 <code>defaultImageURLTransform</code>，可重命名为 <code>imageURL</code>），结合 <code>cut</code> 参数获取全景图特定区域（例如获取前方图片的中心 512x512 区域）。</p>
97
- <pre><code class="typescript"><span class="hl-10">import</span><span class="hl-1"> { </span><span class="hl-6">defaultImageURLTransform</span><span class="hl-1"> </span><span class="hl-10">as</span><span class="hl-1"> </span><span class="hl-6">imageURL</span><span class="hl-1"> } </span><span class="hl-10">from</span><span class="hl-1"> </span><span class="hl-9">&quot;@realsee/five&quot;</span><span class="hl-1">;</span><br/><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">originalUrl</span><span class="hl-1"> = </span><span class="hl-9">&quot;https://vr-public.realsee-cdn.com/.../pano_f.jpg&quot;</span><span class="hl-1">;</span><br/><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">cutUrl</span><span class="hl-1"> = </span><span class="hl-5">imageURL</span><span class="hl-1">(</span><span class="hl-6">originalUrl</span><span class="hl-1">, {</span><br/><span class="hl-1"> </span><span class="hl-6">cut:</span><span class="hl-1"> [</span><span class="hl-11">256</span><span class="hl-1">, </span><span class="hl-11">256</span><span class="hl-1">, </span><span class="hl-11">512</span><span class="hl-1">, </span><span class="hl-11">512</span><span class="hl-1">], </span><span class="hl-8">// x, y, width, height</span><br/><span class="hl-1"> </span><span class="hl-6">format:</span><span class="hl-1"> </span><span class="hl-9">&quot;webp&quot;</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-6">quality:</span><span class="hl-1"> </span><span class="hl-11">80</span><span class="hl-1">,</span><br/><span class="hl-1">});</span><br/><br/><span class="hl-6">console</span><span class="hl-1">.</span><span class="hl-5">log</span><span class="hl-1">(</span><span class="hl-6">cutUrl</span><span class="hl-1">);</span><br/><span class="hl-8">// 输出示例: https://vr-image-4.realsee-cdn.com/.../pano_f.jpg?imageMogr2/format/webp/cut/512x512x256x256/quality/80</span>
97
+ <pre><code class="typescript"><span class="hl-10">import</span><span class="hl-1"> { </span><span class="hl-6">defaultImageURLTransform</span><span class="hl-1"> </span><span class="hl-10">as</span><span class="hl-1"> </span><span class="hl-6">imageURL</span><span class="hl-1"> } </span><span class="hl-10">from</span><span class="hl-1"> </span><span class="hl-9">&quot;@realsee/five-webgpu&quot;</span><span class="hl-1">;</span><br/><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">originalUrl</span><span class="hl-1"> = </span><span class="hl-9">&quot;https://vr-public.realsee-cdn.com/.../pano_f.jpg&quot;</span><span class="hl-1">;</span><br/><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">cutUrl</span><span class="hl-1"> = </span><span class="hl-5">imageURL</span><span class="hl-1">(</span><span class="hl-6">originalUrl</span><span class="hl-1">, {</span><br/><span class="hl-1"> </span><span class="hl-6">cut:</span><span class="hl-1"> [</span><span class="hl-11">256</span><span class="hl-1">, </span><span class="hl-11">256</span><span class="hl-1">, </span><span class="hl-11">512</span><span class="hl-1">, </span><span class="hl-11">512</span><span class="hl-1">], </span><span class="hl-8">// x, y, width, height</span><br/><span class="hl-1"> </span><span class="hl-6">format:</span><span class="hl-1"> </span><span class="hl-9">&quot;webp&quot;</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-6">quality:</span><span class="hl-1"> </span><span class="hl-11">80</span><span class="hl-1">,</span><br/><span class="hl-1">});</span><br/><br/><span class="hl-6">console</span><span class="hl-1">.</span><span class="hl-5">log</span><span class="hl-1">(</span><span class="hl-6">cutUrl</span><span class="hl-1">);</span><br/><span class="hl-8">// 输出示例: https://vr-image-4.realsee-cdn.com/.../pano_f.jpg?imageMogr2/format/webp/cut/512x512x256x256/quality/80</span>
98
98
  </code><button type="button">Copy</button></pre>
99
99
 
100
100
  <h2 id="related" class="tsd-anchor-link">Related<a href="#related" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h2>
package/docs/documents/features_load-external-model.html CHANGED
@@ -16,7 +16,7 @@
16
16
 
17
17
  <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>
18
18
  <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>
19
- <p>这些加载函数（如 <code>loadGltf</code>, <code>loadPly</code>）是 <code>@realsee/five</code> 包导出的<strong>独立函数</strong>，而非 <code>Five</code> 实例的方法。你需要单独引入它们使用。</p>
19
+ <p>这些加载函数（如 <code>loadGltf</code>, <code>loadPly</code>）是 <code>@realsee/five-webgpu</code> 包导出的<strong>独立函数</strong>，而非 <code>Five</code> 实例的方法。你需要单独引入它们使用。</p>
20
20
  <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>
21
21
  <p>Five 使用 <strong>Z-up</strong> (Z 轴向上) 的右手坐标系。
22
22
  许多外部模型（如 standard GLTF, FBX）通常是 <strong>Y-up</strong> 的。
@@ -533,31 +533,31 @@
533
533
  </table>
534
534
  <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>
535
535
  <h3 id="基础用法：加载-gltf-模型-basic-usage" class="tsd-anchor-link">基础用法：加载 GLTF 模型 (Basic Usage)<a href="#基础用法：加载-gltf-模型-basic-usage" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3>
536
- <pre><code class="typescript"><span class="hl-10">import</span><span class="hl-1"> { </span><span class="hl-6">Five</span><span class="hl-1">, </span><span class="hl-6">FivePlugin</span><span class="hl-1"> } </span><span class="hl-10">from</span><span class="hl-1"> </span><span class="hl-9">&#39;@realsee/five&#39;</span><span class="hl-1">;</span><br/><span class="hl-10">import</span><span class="hl-1"> { </span><span class="hl-6">loadGltf</span><span class="hl-1"> } </span><span class="hl-10">from</span><span class="hl-1"> </span><span class="hl-9">&#39;@realsee/five&#39;</span><span class="hl-1">;</span><br/><span class="hl-10">import</span><span class="hl-1"> </span><span class="hl-3">*</span><span class="hl-1"> </span><span class="hl-10">as</span><span class="hl-1"> </span><span class="hl-6">THREE</span><span class="hl-1"> </span><span class="hl-10">from</span><span class="hl-1"> </span><span class="hl-9">&#39;three&#39;</span><span class="hl-1">;</span><br/><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">five</span><span class="hl-1"> = </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-5">Five</span><span class="hl-1">({</span><span class="hl-8">/*...*/</span><span class="hl-1">});</span><br/><br/><span class="hl-8">// 加载 GLB 模型</span><br/><span class="hl-5">loadGltf</span><span class="hl-1">(</span><span class="hl-9">&#39;https://example.com/model.glb&#39;</span><span class="hl-1">).</span><span class="hl-5">then</span><span class="hl-1">((</span><span class="hl-6">result</span><span class="hl-1">) </span><span class="hl-3">=&gt;</span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-8">// 1. 获取模型对象</span><br/><span class="hl-1"> </span><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">model</span><span class="hl-1"> = </span><span class="hl-6">result</span><span class="hl-1">.</span><span class="hl-6">scene</span><span class="hl-1">;</span><br/><br/><span class="hl-1"> </span><span class="hl-8">// 2. 设置位置和大小</span><br/><span class="hl-1"> </span><span class="hl-6">model</span><span class="hl-1">.</span><span class="hl-6">position</span><span class="hl-1">.</span><span class="hl-5">set</span><span class="hl-1">(</span><span class="hl-11">0</span><span class="hl-1">, </span><span class="hl-11">0</span><span class="hl-1">, </span><span class="hl-11">0</span><span class="hl-1">);</span><br/><span class="hl-1"> </span><span class="hl-6">model</span><span class="hl-1">.</span><span class="hl-6">scale</span><span class="hl-1">.</span><span class="hl-5">set</span><span class="hl-1">(</span><span class="hl-11">1</span><span class="hl-1">, </span><span class="hl-11">1</span><span class="hl-1">, </span><span class="hl-11">1</span><span class="hl-1">);</span><br/><br/><span class="hl-1"> </span><span class="hl-8">// 3. 添加到 Five 场景</span><br/><span class="hl-1"> </span><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-6">scene</span><span class="hl-1">.</span><span class="hl-5">add</span><span class="hl-1">(</span><span class="hl-6">model</span><span class="hl-1">);</span><br/><br/><span class="hl-1"> </span><span class="hl-8">// 4. (可选) 渲染一帧以确保显示</span><br/><span class="hl-1"> </span><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-6">needsRender</span><span class="hl-1"> = </span><span class="hl-3">true</span><span class="hl-1">;</span><br/><br/><span class="hl-1"> </span><span class="hl-8">// 保存 result 用于后续销毁</span><br/><span class="hl-1"> </span><span class="hl-8">// result.dispose();</span><br/><span class="hl-1">}).</span><span class="hl-5">catch</span><span class="hl-1">(</span><span class="hl-6">err</span><span class="hl-1"> </span><span class="hl-3">=&gt;</span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-6">console</span><span class="hl-1">.</span><span class="hl-5">error</span><span class="hl-1">(</span><span class="hl-9">&#39;加载失败&#39;</span><span class="hl-1">, </span><span class="hl-6">err</span><span class="hl-1">);</span><br/><span class="hl-1">});</span>
536
+ <pre><code class="typescript"><span class="hl-10">import</span><span class="hl-1"> { </span><span class="hl-6">Five</span><span class="hl-1">, </span><span class="hl-6">FivePlugin</span><span class="hl-1"> } </span><span class="hl-10">from</span><span class="hl-1"> </span><span class="hl-9">&#39;@realsee/five-webgpu&#39;</span><span class="hl-1">;</span><br/><span class="hl-10">import</span><span class="hl-1"> { </span><span class="hl-6">loadGltf</span><span class="hl-1"> } </span><span class="hl-10">from</span><span class="hl-1"> </span><span class="hl-9">&#39;@realsee/five-webgpu&#39;</span><span class="hl-1">;</span><br/><span class="hl-10">import</span><span class="hl-1"> </span><span class="hl-3">*</span><span class="hl-1"> </span><span class="hl-10">as</span><span class="hl-1"> </span><span class="hl-6">THREE</span><span class="hl-1"> </span><span class="hl-10">from</span><span class="hl-1"> </span><span class="hl-9">&#39;three&#39;</span><span class="hl-1">;</span><br/><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">five</span><span class="hl-1"> = </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-5">Five</span><span class="hl-1">({</span><span class="hl-8">/*...*/</span><span class="hl-1">});</span><br/><br/><span class="hl-8">// 加载 GLB 模型</span><br/><span class="hl-5">loadGltf</span><span class="hl-1">(</span><span class="hl-9">&#39;https://example.com/model.glb&#39;</span><span class="hl-1">).</span><span class="hl-5">then</span><span class="hl-1">((</span><span class="hl-6">result</span><span class="hl-1">) </span><span class="hl-3">=&gt;</span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-8">// 1. 获取模型对象</span><br/><span class="hl-1"> </span><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">model</span><span class="hl-1"> = </span><span class="hl-6">result</span><span class="hl-1">.</span><span class="hl-6">scene</span><span class="hl-1">;</span><br/><br/><span class="hl-1"> </span><span class="hl-8">// 2. 设置位置和大小</span><br/><span class="hl-1"> </span><span class="hl-6">model</span><span class="hl-1">.</span><span class="hl-6">position</span><span class="hl-1">.</span><span class="hl-5">set</span><span class="hl-1">(</span><span class="hl-11">0</span><span class="hl-1">, </span><span class="hl-11">0</span><span class="hl-1">, </span><span class="hl-11">0</span><span class="hl-1">);</span><br/><span class="hl-1"> </span><span class="hl-6">model</span><span class="hl-1">.</span><span class="hl-6">scale</span><span class="hl-1">.</span><span class="hl-5">set</span><span class="hl-1">(</span><span class="hl-11">1</span><span class="hl-1">, </span><span class="hl-11">1</span><span class="hl-1">, </span><span class="hl-11">1</span><span class="hl-1">);</span><br/><br/><span class="hl-1"> </span><span class="hl-8">// 3. 添加到 Five 场景</span><br/><span class="hl-1"> </span><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-6">scene</span><span class="hl-1">.</span><span class="hl-5">add</span><span class="hl-1">(</span><span class="hl-6">model</span><span class="hl-1">);</span><br/><br/><span class="hl-1"> </span><span class="hl-8">// 4. (可选) 渲染一帧以确保显示</span><br/><span class="hl-1"> </span><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-6">needsRender</span><span class="hl-1"> = </span><span class="hl-3">true</span><span class="hl-1">;</span><br/><br/><span class="hl-1"> </span><span class="hl-8">// 保存 result 用于后续销毁</span><br/><span class="hl-1"> </span><span class="hl-8">// result.dispose();</span><br/><span class="hl-1">}).</span><span class="hl-5">catch</span><span class="hl-1">(</span><span class="hl-6">err</span><span class="hl-1"> </span><span class="hl-3">=&gt;</span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-6">console</span><span class="hl-1">.</span><span class="hl-5">error</span><span class="hl-1">(</span><span class="hl-9">&#39;加载失败&#39;</span><span class="hl-1">, </span><span class="hl-6">err</span><span class="hl-1">);</span><br/><span class="hl-1">});</span>
537
537
  </code><button type="button">Copy</button></pre>
538
538
 
539
539
  <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>
540
- <pre><code class="typescript"><span class="hl-10">import</span><span class="hl-1"> { </span><span class="hl-6">loadSplat</span><span class="hl-1"> } </span><span class="hl-10">from</span><span class="hl-1"> </span><span class="hl-9">&#39;@realsee/five&#39;</span><span class="hl-1">;</span><br/><br/><span class="hl-5">loadSplat</span><span class="hl-1">(</span><span class="hl-9">&#39;https://example.com/scene.splat&#39;</span><span class="hl-1">, {</span><br/><span class="hl-1"> </span><span class="hl-6">modelUpAxis:</span><span class="hl-1"> </span><span class="hl-9">&#39;Y&#39;</span><span class="hl-1">, </span><span class="hl-8">// 假设原始数据是 Y-up</span><br/><span class="hl-1"> </span><span class="hl-6">upAxis:</span><span class="hl-1"> </span><span class="hl-9">&#39;Z&#39;</span><span class="hl-1">, </span><span class="hl-8">// 转换到 Five 的 Z-up</span><br/><span class="hl-1">}).</span><span class="hl-5">then</span><span class="hl-1">((</span><span class="hl-6">result</span><span class="hl-1">) </span><span class="hl-3">=&gt;</span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">splatMesh</span><span class="hl-1"> = </span><span class="hl-6">result</span><span class="hl-1">.</span><span class="hl-6">scene</span><span class="hl-1">;</span><br/><span class="hl-1"> </span><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-6">scene</span><span class="hl-1">.</span><span class="hl-5">add</span><span class="hl-1">(</span><span class="hl-6">splatMesh</span><span class="hl-1">);</span><br/><span class="hl-1"> </span><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-6">needsRender</span><span class="hl-1"> = </span><span class="hl-3">true</span><span class="hl-1">;</span><br/><span class="hl-1">});</span>
540
+ <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>
541
541
  </code><button type="button">Copy</button></pre>
542
542
 
543
543
  <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>
544
- <pre><code class="typescript"><span class="hl-10">import</span><span class="hl-1"> { </span><span class="hl-6">loadPly</span><span class="hl-1"> } </span><span class="hl-10">from</span><span class="hl-1"> </span><span class="hl-9">&#39;@realsee/five&#39;</span><span class="hl-1">;</span><br/><br/><span class="hl-5">loadPly</span><span class="hl-1">(</span><span class="hl-9">&#39;https://example.com/data.ply&#39;</span><span class="hl-1">, {</span><br/><span class="hl-1"> </span><span class="hl-6">type:</span><span class="hl-1"> </span><span class="hl-9">&#39;pbmPointCloud&#39;</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-6">customPropertyMapping:</span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-6">intensity:</span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-6">itemType:</span><span class="hl-1"> </span><span class="hl-9">&#39;float32&#39;</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-6">itemNames:</span><span class="hl-1"> [</span><span class="hl-9">&#39;intensity&#39;</span><span class="hl-1">],</span><br/><span class="hl-1"> </span><span class="hl-6">normalized:</span><span class="hl-1"> </span><span class="hl-3">true</span><br/><span class="hl-1"> }</span><br/><span class="hl-1"> }</span><br/><span class="hl-1">}).</span><span class="hl-5">then</span><span class="hl-1">((</span><span class="hl-6">result</span><span class="hl-1">) </span><span class="hl-3">=&gt;</span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-8">// result.scene 是一个 PBMPointCloud 对象</span><br/><span class="hl-1"> </span><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-6">scene</span><span class="hl-1">.</span><span class="hl-5">add</span><span class="hl-1">(</span><span class="hl-6">result</span><span class="hl-1">.</span><span class="hl-6">scene</span><span class="hl-1">);</span><br/><span class="hl-1">});</span>
544
+ <pre><code class="typescript"><span class="hl-10">import</span><span class="hl-1"> { </span><span class="hl-6">loadPly</span><span class="hl-1"> } </span><span class="hl-10">from</span><span class="hl-1"> </span><span class="hl-9">&#39;@realsee/five-webgpu&#39;</span><span class="hl-1">;</span><br/><br/><span class="hl-5">loadPly</span><span class="hl-1">(</span><span class="hl-9">&#39;https://example.com/data.ply&#39;</span><span class="hl-1">, {</span><br/><span class="hl-1"> </span><span class="hl-6">type:</span><span class="hl-1"> </span><span class="hl-9">&#39;pbmPointCloud&#39;</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-6">customPropertyMapping:</span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-6">intensity:</span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-6">itemType:</span><span class="hl-1"> </span><span class="hl-9">&#39;float32&#39;</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-6">itemNames:</span><span class="hl-1"> [</span><span class="hl-9">&#39;intensity&#39;</span><span class="hl-1">],</span><br/><span class="hl-1"> </span><span class="hl-6">normalized:</span><span class="hl-1"> </span><span class="hl-3">true</span><br/><span class="hl-1"> }</span><br/><span class="hl-1"> }</span><br/><span class="hl-1">}).</span><span class="hl-5">then</span><span class="hl-1">((</span><span class="hl-6">result</span><span class="hl-1">) </span><span class="hl-3">=&gt;</span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-8">// result.scene 是一个 PBMPointCloud 对象</span><br/><span class="hl-1"> </span><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-6">scene</span><span class="hl-1">.</span><span class="hl-5">add</span><span class="hl-1">(</span><span class="hl-6">result</span><span class="hl-1">.</span><span class="hl-6">scene</span><span class="hl-1">);</span><br/><span class="hl-1">});</span>
545
545
  </code><button type="button">Copy</button></pre>
546
546
 
547
547
  <h3 id="基础用法：加载-obj-模型-basic-usage-obj" class="tsd-anchor-link">基础用法：加载 OBJ 模型 (Basic Usage - OBJ)<a href="#基础用法：加载-obj-模型-basic-usage-obj" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3>
548
- <pre><code class="typescript"><span class="hl-10">import</span><span class="hl-1"> { </span><span class="hl-6">loadObj</span><span class="hl-1"> } </span><span class="hl-10">from</span><span class="hl-1"> </span><span class="hl-9">&#39;@realsee/five&#39;</span><span class="hl-1">;</span><br/><br/><span class="hl-5">loadObj</span><span class="hl-1">(</span><span class="hl-9">&#39;https://example.com/model.obj&#39;</span><span class="hl-1">, {</span><br/><span class="hl-1"> </span><span class="hl-6">modelUpAxis:</span><span class="hl-1"> </span><span class="hl-9">&#39;Z&#39;</span><span class="hl-1">, </span><span class="hl-8">// OBJ 默认通常是 Z-up (或根据实际情况调整)</span><br/><span class="hl-1">}).</span><span class="hl-5">then</span><span class="hl-1">((</span><span class="hl-6">result</span><span class="hl-1">) </span><span class="hl-3">=&gt;</span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-6">scene</span><span class="hl-1">.</span><span class="hl-5">add</span><span class="hl-1">(</span><span class="hl-6">result</span><span class="hl-1">.</span><span class="hl-6">scene</span><span class="hl-1">);</span><br/><span class="hl-1"> </span><span class="hl-8">// OBJ 文件中定义的 .mtl 材质会自动加载</span><br/><span class="hl-1">});</span>
548
+ <pre><code class="typescript"><span class="hl-10">import</span><span class="hl-1"> { </span><span class="hl-6">loadObj</span><span class="hl-1"> } </span><span class="hl-10">from</span><span class="hl-1"> </span><span class="hl-9">&#39;@realsee/five-webgpu&#39;</span><span class="hl-1">;</span><br/><br/><span class="hl-5">loadObj</span><span class="hl-1">(</span><span class="hl-9">&#39;https://example.com/model.obj&#39;</span><span class="hl-1">, {</span><br/><span class="hl-1"> </span><span class="hl-6">modelUpAxis:</span><span class="hl-1"> </span><span class="hl-9">&#39;Z&#39;</span><span class="hl-1">, </span><span class="hl-8">// OBJ 默认通常是 Z-up (或根据实际情况调整)</span><br/><span class="hl-1">}).</span><span class="hl-5">then</span><span class="hl-1">((</span><span class="hl-6">result</span><span class="hl-1">) </span><span class="hl-3">=&gt;</span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-6">scene</span><span class="hl-1">.</span><span class="hl-5">add</span><span class="hl-1">(</span><span class="hl-6">result</span><span class="hl-1">.</span><span class="hl-6">scene</span><span class="hl-1">);</span><br/><span class="hl-1"> </span><span class="hl-8">// OBJ 文件中定义的 .mtl 材质会自动加载</span><br/><span class="hl-1">});</span>
549
549
  </code><button type="button">Copy</button></pre>
550
550
 
551
551
  <h3 id="基础用法：加载-fbx-模型" class="tsd-anchor-link">基础用法：加载 FBX 模型<a href="#基础用法：加载-fbx-模型" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3>
552
- <pre><code class="typescript"><span class="hl-10">import</span><span class="hl-1"> { </span><span class="hl-6">loadFbx</span><span class="hl-1"> } </span><span class="hl-10">from</span><span class="hl-1"> </span><span class="hl-9">&#39;@realsee/five&#39;</span><span class="hl-1">;</span><br/><br/><span class="hl-5">loadFbx</span><span class="hl-1">(</span><span class="hl-9">&#39;https://example.com/model.fbx&#39;</span><span class="hl-1">).</span><span class="hl-5">then</span><span class="hl-1">((</span><span class="hl-6">result</span><span class="hl-1">) </span><span class="hl-3">=&gt;</span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-6">scene</span><span class="hl-1">.</span><span class="hl-5">add</span><span class="hl-1">(</span><span class="hl-6">result</span><span class="hl-1">.</span><span class="hl-6">scene</span><span class="hl-1">);</span><br/><span class="hl-1"> </span><span class="hl-8">// 动画会自动解析到 result.animations</span><br/><span class="hl-1">});</span>
552
+ <pre><code class="typescript"><span class="hl-10">import</span><span class="hl-1"> { </span><span class="hl-6">loadFbx</span><span class="hl-1"> } </span><span class="hl-10">from</span><span class="hl-1"> </span><span class="hl-9">&#39;@realsee/five-webgpu&#39;</span><span class="hl-1">;</span><br/><br/><span class="hl-5">loadFbx</span><span class="hl-1">(</span><span class="hl-9">&#39;https://example.com/model.fbx&#39;</span><span class="hl-1">).</span><span class="hl-5">then</span><span class="hl-1">((</span><span class="hl-6">result</span><span class="hl-1">) </span><span class="hl-3">=&gt;</span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-6">scene</span><span class="hl-1">.</span><span class="hl-5">add</span><span class="hl-1">(</span><span class="hl-6">result</span><span class="hl-1">.</span><span class="hl-6">scene</span><span class="hl-1">);</span><br/><span class="hl-1"> </span><span class="hl-8">// 动画会自动解析到 result.animations</span><br/><span class="hl-1">});</span>
553
553
  </code><button type="button">Copy</button></pre>
554
554
 
555
555
  <h3 id="进阶用法：加载-dome-全景-panorama" class="tsd-anchor-link">进阶用法：加载 Dome 全景 (Panorama)<a href="#进阶用法：加载-dome-全景-panorama" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3>
556
- <pre><code class="typescript"><span class="hl-10">import</span><span class="hl-1"> { </span><span class="hl-6">loadDome</span><span class="hl-1"> } </span><span class="hl-10">from</span><span class="hl-1"> </span><span class="hl-9">&#39;@realsee/five&#39;</span><span class="hl-1">;</span><br/><br/><span class="hl-8">// 加载 .dome 或 .domez 格式</span><br/><span class="hl-5">loadDome</span><span class="hl-1">(</span><span class="hl-9">&#39;https://example.com/panorama.domez&#39;</span><span class="hl-1">, {</span><br/><span class="hl-1"> </span><span class="hl-6">light:</span><span class="hl-1"> </span><span class="hl-3">false</span><span class="hl-1">, </span><span class="hl-8">// 全景模型通常不需要光照计算</span><br/><span class="hl-1"> </span><span class="hl-6">textureOptions:</span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-6">size:</span><span class="hl-1"> </span><span class="hl-11">4096</span><span class="hl-1">, </span><span class="hl-8">// 限制最大纹理尺寸</span><br/><span class="hl-1"> }</span><br/><span class="hl-1">}).</span><span class="hl-5">then</span><span class="hl-1">((</span><span class="hl-6">result</span><span class="hl-1">) </span><span class="hl-3">=&gt;</span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-6">result</span><span class="hl-1">.</span><span class="hl-6">scene</span><span class="hl-1">.</span><span class="hl-6">position</span><span class="hl-1">.</span><span class="hl-5">set</span><span class="hl-1">(</span><span class="hl-11">0</span><span class="hl-1">, </span><span class="hl-11">0</span><span class="hl-1">, </span><span class="hl-11">0</span><span class="hl-1">);</span><br/><span class="hl-1"> </span><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-6">scene</span><span class="hl-1">.</span><span class="hl-5">add</span><span class="hl-1">(</span><span class="hl-6">result</span><span class="hl-1">.</span><span class="hl-6">scene</span><span class="hl-1">);</span><br/><span class="hl-1">});</span>
556
+ <pre><code class="typescript"><span class="hl-10">import</span><span class="hl-1"> { </span><span class="hl-6">loadDome</span><span class="hl-1"> } </span><span class="hl-10">from</span><span class="hl-1"> </span><span class="hl-9">&#39;@realsee/five-webgpu&#39;</span><span class="hl-1">;</span><br/><br/><span class="hl-8">// 加载 .dome 或 .domez 格式</span><br/><span class="hl-5">loadDome</span><span class="hl-1">(</span><span class="hl-9">&#39;https://example.com/panorama.domez&#39;</span><span class="hl-1">, {</span><br/><span class="hl-1"> </span><span class="hl-6">light:</span><span class="hl-1"> </span><span class="hl-3">false</span><span class="hl-1">, </span><span class="hl-8">// 全景模型通常不需要光照计算</span><br/><span class="hl-1"> </span><span class="hl-6">textureOptions:</span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-6">size:</span><span class="hl-1"> </span><span class="hl-11">4096</span><span class="hl-1">, </span><span class="hl-8">// 限制最大纹理尺寸</span><br/><span class="hl-1"> }</span><br/><span class="hl-1">}).</span><span class="hl-5">then</span><span class="hl-1">((</span><span class="hl-6">result</span><span class="hl-1">) </span><span class="hl-3">=&gt;</span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-6">result</span><span class="hl-1">.</span><span class="hl-6">scene</span><span class="hl-1">.</span><span class="hl-6">position</span><span class="hl-1">.</span><span class="hl-5">set</span><span class="hl-1">(</span><span class="hl-11">0</span><span class="hl-1">, </span><span class="hl-11">0</span><span class="hl-1">, </span><span class="hl-11">0</span><span class="hl-1">);</span><br/><span class="hl-1"> </span><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-6">scene</span><span class="hl-1">.</span><span class="hl-5">add</span><span class="hl-1">(</span><span class="hl-6">result</span><span class="hl-1">.</span><span class="hl-6">scene</span><span class="hl-1">);</span><br/><span class="hl-1">});</span>
557
557
  </code><button type="button">Copy</button></pre>
558
558
 
559
559
  <h3 id="进阶用法：加载压缩模型-at3d" class="tsd-anchor-link">进阶用法：加载压缩模型 (AT3D)<a href="#进阶用法：加载压缩模型-at3d" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3>
560
- <pre><code class="typescript"><span class="hl-10">import</span><span class="hl-1"> { </span><span class="hl-6">loadAt3d</span><span class="hl-1"> } </span><span class="hl-10">from</span><span class="hl-1"> </span><span class="hl-9">&#39;@realsee/five&#39;</span><span class="hl-1">;</span><br/><br/><span class="hl-5">loadAt3d</span><span class="hl-1">(</span><span class="hl-9">&#39;https://example.com/model.at3d&#39;</span><span class="hl-1">, {</span><br/><span class="hl-1"> </span><span class="hl-6">light:</span><span class="hl-1"> </span><span class="hl-3">false</span><span class="hl-1">,</span><br/><span class="hl-1">}).</span><span class="hl-5">then</span><span class="hl-1">((</span><span class="hl-6">result</span><span class="hl-1">) </span><span class="hl-3">=&gt;</span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-6">scene</span><span class="hl-1">.</span><span class="hl-5">add</span><span class="hl-1">(</span><span class="hl-6">result</span><span class="hl-1">.</span><span class="hl-6">scene</span><span class="hl-1">);</span><br/><span class="hl-1">});</span>
560
+ <pre><code class="typescript"><span class="hl-10">import</span><span class="hl-1"> { </span><span class="hl-6">loadAt3d</span><span class="hl-1"> } </span><span class="hl-10">from</span><span class="hl-1"> </span><span class="hl-9">&#39;@realsee/five-webgpu&#39;</span><span class="hl-1">;</span><br/><br/><span class="hl-5">loadAt3d</span><span class="hl-1">(</span><span class="hl-9">&#39;https://example.com/model.at3d&#39;</span><span class="hl-1">, {</span><br/><span class="hl-1"> </span><span class="hl-6">light:</span><span class="hl-1"> </span><span class="hl-3">false</span><span class="hl-1">,</span><br/><span class="hl-1">}).</span><span class="hl-5">then</span><span class="hl-1">((</span><span class="hl-6">result</span><span class="hl-1">) </span><span class="hl-3">=&gt;</span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-6">scene</span><span class="hl-1">.</span><span class="hl-5">add</span><span class="hl-1">(</span><span class="hl-6">result</span><span class="hl-1">.</span><span class="hl-6">scene</span><span class="hl-1">);</span><br/><span class="hl-1">});</span>
561
561
  </code><button type="button">Copy</button></pre>
562
562
 
563
563
  <h2 id="debugging" class="tsd-anchor-link">Debugging<a href="#debugging" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h2>