UNPKG

@realsee/five

Version:

Realsee Renderer SDK

605 lines (595 loc) • 50.5 kB
<!DOCTYPE html><html class="default" lang="en" data-base="../"><head><meta charset="utf-8"/><meta http-equiv="x-ua-compatible" content="IE=edge"/><title>features/load-external-model | 如视 Five SDK</title><meta name="description" content="Documentation for 如视 Five SDK"/><meta name="viewport" content="width=device-width, initial-scale=1"/><link rel="stylesheet" href="../assets/style.css"/><link rel="stylesheet" href="../assets/highlight.css"/><script defer src="../assets/main.js"></script><script async src="../assets/icons.js" id="tsd-icons-script"></script><script async src="../assets/search.js" id="tsd-search-script"></script><script async src="../assets/navigation.js" id="tsd-nav-script"></script><script async src="../assets/hierarchy.js" id="tsd-hierarchy-script"></script></head><body><script>document.documentElement.dataset.theme = localStorage.getItem("tsd-theme") || "os";document.body.style.display="none";setTimeout(() => window.app?app.showPage():document.body.style.removeProperty("display"),500)</script><header class="tsd-page-toolbar"><div class="tsd-toolbar-contents container"><a href="../index.html" class="title">如视 Five SDK</a><div id="tsd-toolbar-links"></div><button id="tsd-search-trigger" class="tsd-widget" aria-label="Search"><svg width="16" height="16" viewBox="0 0 16 16" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-search"></use></svg></button><dialog id="tsd-search" aria-label="Search"><input role="combobox" id="tsd-search-input" aria-controls="tsd-search-results" aria-autocomplete="list" aria-expanded="true" autocapitalize="off" autocomplete="off" placeholder="Search the docs" maxLength="100"/><ul role="listbox" id="tsd-search-results"></ul><div id="tsd-search-status" aria-live="polite" aria-atomic="true"><div>Preparing search index...</div></div></dialog><a href="#" class="tsd-widget menu" id="tsd-toolbar-menu-trigger" data-toggle="menu" aria-label="Menu"><svg width="16" height="16" viewBox="0 0 16 16" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-menu"></use></svg></a></div></header><div class="container container-main"><div class="col-content"><div class="tsd-page-title"><ul class="tsd-breadcrumb" aria-label="Breadcrumb"><li><a href="" aria-current="page">features/load-external-model</a></li></ul></div><div class="tsd-panel tsd-typography"><h1 id="加载外部模型-load-external-models" class="tsd-anchor-link">加载外部模型 (Load External Models)<a href="#加载外部模型-load-external-models" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h1> <ul> <li><strong>Summary</strong>: 提供了一系列独立的加载函数 (<code>loadGltf</code>, <code>loadPly</code>, <code>loadFbx</code> 等),用于加载各种格式的外部 3D 模型(如 .glb, .ply, .splat, .fbx),并将其转换为 Three.js 对象以便添加到 Five 场景中。</li> <li><strong>Schema</strong>: 涉及 <code>LoadResultType</code> 返回结构及各加载器的配置项 (<code>LoaderOptions</code>)。</li> <li><strong>Concepts</strong>: 独立加载函数、坐标系转换 (UpAxis)、资源销毁 (Dispose)、Fetcher。</li> <li><strong>Configuration</strong>: <code>modelUpAxis</code>, <code>upAxis</code>, <code>fetcher</code> 等通用及特定配置。</li> <li><strong>Examples</strong>: 加载 GLTF 模型、加载高斯泼溅 (Gaussian Splat)、加载点云。</li> </ul> <h2 id="schema" class="tsd-anchor-link">Schema<a href="#schema" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h2> <blockquote> <p><strong>Definition</strong>: <a href="../../five/model/loaders/shared.d.ts">LoadResultType</a></p> </blockquote> <p>所有加载函数均返回 <code>Promise&lt;LoadResultType&gt;</code>。</p> <pre><code class="typescript"><span class="hl-8">// 通用返回类型</span><br/><span class="hl-10">export</span><span class="hl-1"> </span><span class="hl-3">type</span><span class="hl-1"> </span><span class="hl-7">LoadResultType</span><span class="hl-1">&lt;</span><span class="hl-7">Scene</span><span class="hl-1"> = </span><span class="hl-7">THREE</span><span class="hl-1">.</span><span class="hl-7">Object3D</span><span class="hl-1">&gt; = {</span><br/><span class="hl-1"> </span><span class="hl-6">type</span><span class="hl-1">: </span><span class="hl-9">&#39;gltf&#39;</span><span class="hl-1"> | </span><span class="hl-9">&#39;obj&#39;</span><span class="hl-1"> | </span><span class="hl-9">&#39;ply&#39;</span><span class="hl-1"> | </span><span class="hl-9">&#39;fbx&#39;</span><span class="hl-1"> | </span><span class="hl-9">&#39;pbm&#39;</span><span class="hl-1"> | </span><span class="hl-9">&#39;splat&#39;</span><span class="hl-1"> | </span><span class="hl-9">&#39;spz&#39;</span><span class="hl-1"> | </span><span class="hl-9">&#39;b3dm&#39;</span><span class="hl-1"> | </span><span class="hl-9">&#39;pnts&#39;</span><span class="hl-1"> | </span><span class="hl-9">&#39;at3d&#39;</span><span class="hl-1"> | </span><span class="hl-9">&#39;dome&#39;</span><span class="hl-1"> | </span><span class="hl-9">&#39;domez&#39;</span><span class="hl-1"> | </span><span class="hl-9">&#39;x3p&#39;</span><span class="hl-1">; </span><span class="hl-8">// 模型类型</span><br/><span class="hl-1"> </span><span class="hl-6">modelUpAxis</span><span class="hl-1">: </span><span class="hl-9">&#39;Y&#39;</span><span class="hl-1"> | </span><span class="hl-9">&#39;Z&#39;</span><span class="hl-1">; </span><span class="hl-8">// 原始模型的上轴</span><br/><span class="hl-1"> </span><span class="hl-6">upAxis</span><span class="hl-1">: </span><span class="hl-9">&#39;Y&#39;</span><span class="hl-1"> | </span><span class="hl-9">&#39;Z&#39;</span><span class="hl-1">; </span><span class="hl-8">// 输出模型的上轴 (通常为 Z)</span><br/><span class="hl-1"> </span><span class="hl-6">byteLength</span><span class="hl-1">: </span><span class="hl-7">number</span><span class="hl-1">; </span><span class="hl-8">// 文件字节大小</span><br/><span class="hl-1"> </span><span class="hl-6">memoryUsage</span><span class="hl-1">: </span><span class="hl-7">number</span><span class="hl-1">; </span><span class="hl-8">// 显存/内存占用估算</span><br/><span class="hl-1"> </span><span class="hl-6">uri</span><span class="hl-1">: </span><span class="hl-7">string</span><span class="hl-1">; </span><span class="hl-8">// 模型地址</span><br/><span class="hl-1"> </span><span class="hl-6">scene</span><span class="hl-1">: </span><span class="hl-7">Scene</span><span class="hl-1">; </span><span class="hl-8">// Three.js 对象 (Group 或 Object3D),可直接添加到场景</span><br/><span class="hl-1"> </span><span class="hl-6">textures</span><span class="hl-1">: </span><span class="hl-7">THREE</span><span class="hl-1">.</span><span class="hl-7">Texture</span><span class="hl-1">[]; </span><span class="hl-8">// 加载的纹理列表</span><br/><span class="hl-1"> </span><span class="hl-6">animations</span><span class="hl-1">: </span><span class="hl-7">THREE</span><span class="hl-1">.</span><span class="hl-7">AnimationClip</span><span class="hl-1">[]; </span><span class="hl-8">// 动画剪辑列表</span><br/><span class="hl-1"> </span><span class="hl-6">rtcCenter</span><span class="hl-1">?: </span><span class="hl-7">THREE</span><span class="hl-1">.</span><span class="hl-7">Vector3</span><span class="hl-1">; </span><span class="hl-8">// 若存在 RTC (Relative To Center) 坐标偏移</span><br/><span class="hl-1"> </span><span class="hl-5">dispose</span><span class="hl-1">: () </span><span class="hl-3">=&gt;</span><span class="hl-1"> </span><span class="hl-7">void</span><span class="hl-1">; </span><span class="hl-8">// 销毁资源函数</span><br/><span class="hl-1">}</span><br/><br/><span class="hl-8">// 通用配置项接口</span><br/><span class="hl-3">interface</span><span class="hl-1"> </span><span class="hl-7">BaseLoaderOptions</span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-6">upAxis</span><span class="hl-1">?: </span><span class="hl-9">&#39;Y&#39;</span><span class="hl-1"> | </span><span class="hl-9">&#39;Z&#39;</span><span class="hl-1">; </span><span class="hl-8">// 期望输出的上轴,默认为 &#39;Z&#39; (Five 坐标系)</span><br/><span class="hl-1"> </span><span class="hl-6">modelUpAxis</span><span class="hl-1">?: </span><span class="hl-9">&#39;Y&#39;</span><span class="hl-1"> | </span><span class="hl-9">&#39;Z&#39;</span><span class="hl-1">; </span><span class="hl-8">// (部分加载器支持) 原始模型的上轴,用于自动旋转修正</span><br/><span class="hl-1"> </span><span class="hl-6">fetcher</span><span class="hl-1">?: </span><span class="hl-7">Fetcher</span><span class="hl-1">; </span><span class="hl-8">// 自定义网络请求 Fetcher</span><br/><span class="hl-1"> </span><span class="hl-6">light</span><span class="hl-1">?: </span><span class="hl-7">boolean</span><span class="hl-1">; </span><span class="hl-8">// 是否使用简化/无光照材质 (取决于加载器实现)</span><br/><span class="hl-1"> </span><span class="hl-5">onDownloadProgress</span><span class="hl-1">?: (</span><span class="hl-6">progress</span><span class="hl-1">: { </span><span class="hl-6">loaded</span><span class="hl-1">: </span><span class="hl-7">number</span><span class="hl-1">, </span><span class="hl-6">total</span><span class="hl-1">: </span><span class="hl-7">number</span><span class="hl-1"> }) </span><span class="hl-3">=&gt;</span><span class="hl-1"> </span><span class="hl-7">void</span><span class="hl-1">; </span><span class="hl-8">// 下载进度回调</span><br/><span class="hl-1">}</span> </code><button type="button">Copy</button></pre> <h2 id="concepts" class="tsd-anchor-link">Concepts<a href="#concepts" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h2> <h3 id="独立加载函数-standalone-functions" class="tsd-anchor-link">独立加载函数 (Standalone Functions)<a href="#独立加载函数-standalone-functions" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3> <p>这些加载函数(如 <code>loadGltf</code>, <code>loadPly</code>)是 <code>@realsee/five</code> 包导出的<strong>独立函数</strong>,而非 <code>Five</code> 实例的方法。你需要单独引入它们使用。</p> <h3 id="坐标系转换-up-axis-conversion" class="tsd-anchor-link">坐标系转换 (Up-Axis Conversion)<a href="#坐标系转换-up-axis-conversion" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3> <p>Five 使用 <strong>Z-up</strong> (Z 轴向上) 的右手坐标系。 许多外部模型(如 standard GLTF, FBX)通常是 <strong>Y-up</strong> 的。 加载器提供了 <code>upAxis</code> 和 <code>modelUpAxis</code> 选项来自动处理旋转:</p> <ul> <li><code>upAxis</code>: 你期望得到的结果坐标系上轴(通常保持默认 'Z')。</li> <li><code>modelUpAxis</code>: 原始文件的上轴(如 GLTF 默认为 'Y',PLY 默认为 'Z')。 如果不指定,加载器会尝试使用合理的默认值将模型旋转到 Z 轴向上。</li> </ul> <h3 id="资源销毁-disposal" class="tsd-anchor-link">资源销毁 (Disposal)<a href="#资源销毁-disposal" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3> <p>加载的模型包含 Geometry、Material 和 Texture 等 WebGL 资源。当你不再需要该模型时(例如切换场景或移除物体),<strong>必须</strong>调用返回结果中的 <code>dispose()</code> 方法来释放内存,否则会导致内存泄漏。</p> <h3 id="fetcher" class="tsd-anchor-link">Fetcher<a href="#fetcher" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3> <p>所有加载器支持传入自定义 <code>fetcher</code>。这在需要鉴权、自定义 Header 或处理特定 CDN 逻辑时非常有用。如果不传,默认使用内部的 <code>internalFetcher</code>。</p> <h2 id="configuration" class="tsd-anchor-link">Configuration<a href="#configuration" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h2> <h3 id="loadgltf" class="tsd-anchor-link">loadGltf<a href="#loadgltf" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3> <p>加载 <code>.gltf</code> 或 <code>.glb</code> 文件。支持 Draco 压缩。 支持扩展:</p> <ul> <li><code>KHR_binary_glTF</code></li> <li><code>KHR_draco_mesh_compression</code></li> <li><code>KHR_texture_basisu</code></li> <li><code>KHR_texture_transform</code></li> <li><code>KHR_mesh_quantization</code></li> <li><code>KHR_materials_unlit</code></li> <li><code>KHR_node_visibility</code></li> <li><code>KHR_animation_pointer</code></li> <li><code>EXT_meshopt_compression</code></li> <li><code>KHR_materials_clearcoat</code></li> <li><code>KHR_materials_sheen</code></li> <li><code>KHR_materials_transmission</code></li> <li><code>KHR_materials_emissive_strength</code></li> <li><code>EXT_texture_webp</code></li> <li><code>CESIUM_RTC</code></li> <li><code>REALSEE_materials_lightmap</code></li> <li><code>KHR_gaussian_splatting</code></li> <li><code>KHR_gaussian_splatting_compression_spz</code></li> <li><code>KHR_gaussian_splatting_compression_spz_2</code></li> </ul> <table> <thead> <tr> <th>参数</th> <th>类型</th> <th>默认值</th> <th>说明</th> </tr> </thead> <tbody> <tr> <td><code>modelUpAxis</code></td> <td>`'Y'</td> <td>'Z'`</td> <td><code>'Y'</code></td> </tr> <tr> <td><code>upAxis</code></td> <td>`'Y'</td> <td>'Z'`</td> <td><code>'Z'</code></td> </tr> <tr> <td><code>light</code></td> <td><code>boolean</code></td> <td><code>undefined</code></td> <td>是否强制使用 Unlit 材质或移除光照扩展。</td> </tr> <tr> <td><code>fetcher</code></td> <td><code>Fetcher</code></td> <td>-</td> <td>自定义 Fetcher。</td> </tr> </tbody> </table> <h3 id="loadply" class="tsd-anchor-link">loadPly<a href="#loadply" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3> <p>加载 <code>.ply</code> 文件。支持网格、线框、点云及 PBM 扩展格式。</p> <table> <thead> <tr> <th>参数</th> <th>类型</th> <th>默认值</th> <th>说明</th> </tr> </thead> <tbody> <tr> <td><code>type</code></td> <td>`'geometry'</td> <td>'line'</td> <td>'pbmMesh'</td> </tr> <tr> <td><code>customPropertyMapping</code></td> <td><code>Object</code></td> <td>-</td> <td>自定义属性映射(用于解析非标准 PLY 属性)。</td> </tr> <tr> <td><code>propertyNameMapping</code></td> <td><code>Object</code></td> <td>-</td> <td>属性名重映射 (e.g. <code>{'diffuse_red': 'red'}</code>)。</td> </tr> <tr> <td><code>modelUpAxis</code></td> <td>`'Y'</td> <td>'Z'`</td> <td><code>'Z'</code></td> </tr> <tr> <td><code>upAxis</code></td> <td>`'Y'</td> <td>'Z'`</td> <td><code>'Z'</code></td> </tr> <tr> <td><code>light</code></td> <td><code>boolean</code></td> <td><code>undefined</code></td> <td>是否使用简化材质。</td> </tr> <tr> <td><code>fetcher</code></td> <td><code>Fetcher</code></td> <td>-</td> <td>自定义 Fetcher。</td> </tr> </tbody> </table> <h3 id="loadsplat" class="tsd-anchor-link">loadSplat<a href="#loadsplat" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3> <p>加载 <code>.splat</code> 格式的高斯泼溅 (Gaussian Splat) 模型。</p> <table> <thead> <tr> <th>参数</th> <th>类型</th> <th>默认值</th> <th>说明</th> </tr> </thead> <tbody> <tr> <td><code>modelUpAxis</code></td> <td>`'Y'</td> <td>'Z'`</td> <td><code>'Y'</code></td> </tr> <tr> <td><code>upAxis</code></td> <td>`'Y'</td> <td>'Z'`</td> <td><code>'Z'</code></td> </tr> <tr> <td><code>fetcher</code></td> <td><code>Fetcher</code></td> <td>-</td> <td>自定义 Fetcher。</td> </tr> </tbody> </table> <h3 id="loadspz" class="tsd-anchor-link">loadSpz<a href="#loadspz" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3> <p>加载 <code>.spz</code> 格式的高斯泼溅 (Gaussian Splat) 模型。<code>.spz</code> 是对 <code>.splat</code> 的压缩格式。</p> <table> <thead> <tr> <th>参数</th> <th>类型</th> <th>默认值</th> <th>说明</th> </tr> </thead> <tbody> <tr> <td><code>modelUpAxis</code></td> <td>`'Y'</td> <td>'Z'`</td> <td><code>'Y'</code></td> </tr> <tr> <td><code>upAxis</code></td> <td>`'Y'</td> <td>'Z'`</td> <td><code>'Z'</code></td> </tr> <tr> <td><code>fetcher</code></td> <td><code>Fetcher</code></td> <td>-</td> <td>自定义 Fetcher。</td> </tr> </tbody> </table> <h3 id="loadfbx" class="tsd-anchor-link">loadFbx<a href="#loadfbx" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3> <p>加载 <code>.fbx</code> 文件。</p> <table> <thead> <tr> <th>参数</th> <th>类型</th> <th>默认值</th> <th>说明</th> </tr> </thead> <tbody> <tr> <td><code>upAxis</code></td> <td>`'Y'</td> <td>'Z'`</td> <td><code>'Z'</code></td> </tr> <tr> <td><code>light</code></td> <td><code>boolean</code></td> <td><code>undefined</code></td> <td>是否使用简化材质。</td> </tr> <tr> <td><code>fetcher</code></td> <td><code>Fetcher</code></td> <td>-</td> <td>自定义 Fetcher。</td> </tr> </tbody> </table> <h3 id="loadobj" class="tsd-anchor-link">loadObj<a href="#loadobj" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3> <p>加载 <code>.obj</code> 文件。会自动尝试加载同目录下的 <code>.mtl</code> 材质文件。</p> <table> <thead> <tr> <th>参数</th> <th>类型</th> <th>默认值</th> <th>说明</th> </tr> </thead> <tbody> <tr> <td><code>modelUpAxis</code></td> <td>`'Y'</td> <td>'Z'`</td> <td><code>'Z'</code></td> </tr> <tr> <td><code>upAxis</code></td> <td>`'Y'</td> <td>'Z'`</td> <td><code>'Z'</code></td> </tr> <tr> <td><code>light</code></td> <td><code>boolean</code></td> <td><code>undefined</code></td> <td>是否使用简化材质。</td> </tr> <tr> <td><code>fetcher</code></td> <td><code>Fetcher</code></td> <td>-</td> <td>自定义 Fetcher。</td> </tr> </tbody> </table> <h3 id="loadpbm" class="tsd-anchor-link">loadPbm<a href="#loadpbm" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3> <p>加载 Realsee 私有 PBM 格式。</p> <table> <thead> <tr> <th>参数</th> <th>类型</th> <th>默认值</th> <th>说明</th> </tr> </thead> <tbody> <tr> <td><code>upAxis</code></td> <td>`'Y'</td> <td>'Z'`</td> <td><code>'Z'</code></td> </tr> <tr> <td><code>light</code></td> <td><code>boolean</code></td> <td><code>false</code></td> <td>是否使用简化材质。</td> </tr> <tr> <td><code>textureBaseUri</code></td> <td><code>string</code></td> <td>自动推断</td> <td>纹理的基础路径。</td> </tr> <tr> <td><code>textureArray</code></td> <td><code>string[]</code></td> <td>-</td> <td>纹理路径列表。</td> </tr> <tr> <td><code>textureOptions</code></td> <td><code>TextureOptions</code></td> <td>-</td> <td>纹理加载配置 (size, quality 等)。</td> </tr> <tr> <td><code>fetcher</code></td> <td><code>Fetcher</code></td> <td>-</td> <td>自定义 Fetcher。</td> </tr> </tbody> </table> <h3 id="loaddome-loaddomez" class="tsd-anchor-link">loadDome / loadDomez<a href="#loaddome-loaddomez" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3> <p>加载 Dome 全景模型 (<code>.dome</code> 或 <code>.domez</code> 压缩格式)。</p> <table> <thead> <tr> <th>参数</th> <th>类型</th> <th>默认值</th> <th>说明</th> </tr> </thead> <tbody> <tr> <td><code>upAxis</code></td> <td>`'Y'</td> <td>'Z'`</td> <td><code>'Z'</code></td> </tr> <tr> <td><code>light</code></td> <td><code>boolean</code></td> <td><code>true</code></td> <td>是否使用简化材质。</td> </tr> <tr> <td><code>textureBaseUri</code></td> <td><code>string</code></td> <td>-</td> <td>纹理基础路径。</td> </tr> <tr> <td><code>textureOptions</code></td> <td><code>TextureOptions</code></td> <td>-</td> <td>纹理加载配置。</td> </tr> <tr> <td><code>fetcher</code></td> <td><code>Fetcher</code></td> <td>-</td> <td>自定义 Fetcher。</td> </tr> </tbody> </table> <h3 id="loadat3d" class="tsd-anchor-link">loadAt3d<a href="#loadat3d" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3> <p>加载 <code>.at3d</code> 格式模型。</p> <table> <thead> <tr> <th>参数</th> <th>类型</th> <th>默认值</th> <th>说明</th> </tr> </thead> <tbody> <tr> <td><code>upAxis</code></td> <td>`'Y'</td> <td>'Z'`</td> <td><code>'Z'</code></td> </tr> <tr> <td><code>light</code></td> <td><code>boolean</code></td> <td><code>false</code></td> <td>是否使用简化材质。</td> </tr> <tr> <td><code>textureBaseUri</code></td> <td><code>string</code></td> <td>自动推断</td> <td>纹理基础路径。</td> </tr> <tr> <td><code>textureArray</code></td> <td><code>string[]</code></td> <td>-</td> <td>纹理路径列表。</td> </tr> <tr> <td><code>textureOptions</code></td> <td><code>TextureOptions</code></td> <td>-</td> <td>纹理加载配置。</td> </tr> <tr> <td><code>fetcher</code></td> <td><code>Fetcher</code></td> <td>-</td> <td>自定义 Fetcher。</td> </tr> </tbody> </table> <h3 id="loadb3dm" class="tsd-anchor-link">loadB3dm<a href="#loadb3dm" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3> <p>加载 <code>.b3dm</code> (Batched 3D Model) 格式。</p> <table> <thead> <tr> <th>参数</th> <th>类型</th> <th>默认值</th> <th>说明</th> </tr> </thead> <tbody> <tr> <td><code>modelUpAxis</code></td> <td>`'Y'</td> <td>'Z'`</td> <td><code>'Y'</code></td> </tr> <tr> <td><code>upAxis</code></td> <td>`'Y'</td> <td>'Z'`</td> <td><code>'Z'</code></td> </tr> <tr> <td><code>light</code></td> <td><code>boolean</code></td> <td><code>undefined</code></td> <td>是否使用简化材质。</td> </tr> <tr> <td><code>fetcher</code></td> <td><code>Fetcher</code></td> <td>-</td> <td>自定义 Fetcher。</td> </tr> </tbody> </table> <h3 id="loadpnts" class="tsd-anchor-link">loadPnts<a href="#loadpnts" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3> <p>加载 <code>.pnts</code> (Point Cloud) 格式。</p> <table> <thead> <tr> <th>参数</th> <th>类型</th> <th>默认值</th> <th>说明</th> </tr> </thead> <tbody> <tr> <td><code>upAxis</code></td> <td>`'Y'</td> <td>'Z'`</td> <td><code>'Z'</code></td> </tr> <tr> <td><code>computeBoundingBox</code></td> <td><code>boolean</code></td> <td><code>true</code></td> <td>是否计算包围盒。</td> </tr> <tr> <td><code>fetcher</code></td> <td><code>Fetcher</code></td> <td>-</td> <td>自定义 Fetcher。</td> </tr> </tbody> </table> <h3 id="loadx3p" class="tsd-anchor-link">loadX3p<a href="#loadx3p" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3> <p>加载 <code>.x3p</code> 格式。</p> <table> <thead> <tr> <th>参数</th> <th>类型</th> <th>默认值</th> <th>说明</th> </tr> </thead> <tbody> <tr> <td><code>upAxis</code></td> <td>`'Y'</td> <td>'Z'`</td> <td><code>'Z'</code></td> </tr> <tr> <td><code>color</code></td> <td><code>THREE.Color</code></td> <td>-</td> <td>指定颜色。</td> </tr> <tr> <td><code>light</code></td> <td><code>boolean</code></td> <td><code>true</code></td> <td>是否使用简化材质。</td> </tr> <tr> <td><code>fetcher</code></td> <td><code>Fetcher</code></td> <td>-</td> <td>自定义 Fetcher。</td> </tr> </tbody> </table> <h2 id="examples" class="tsd-anchor-link">Examples<a href="#examples" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h2> <h3 id="基础用法:加载-gltf-模型-basic-usage" class="tsd-anchor-link">基础用法:加载 GLTF 模型 (Basic Usage)<a href="#基础用法:加载-gltf-模型-basic-usage" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3> <pre><code class="typescript"><span class="hl-10">import</span><span class="hl-1"> { </span><span class="hl-6">Five</span><span class="hl-1">, </span><span class="hl-6">FivePlugin</span><span class="hl-1"> } </span><span class="hl-10">from</span><span class="hl-1"> </span><span class="hl-9">&#39;@realsee/five&#39;</span><span class="hl-1">;</span><br/><span class="hl-10">import</span><span class="hl-1"> { </span><span class="hl-6">loadGltf</span><span class="hl-1"> } </span><span class="hl-10">from</span><span class="hl-1"> </span><span class="hl-9">&#39;@realsee/five&#39;</span><span class="hl-1">;</span><br/><span class="hl-10">import</span><span class="hl-1"> </span><span class="hl-3">*</span><span class="hl-1"> </span><span class="hl-10">as</span><span class="hl-1"> </span><span class="hl-6">THREE</span><span class="hl-1"> </span><span class="hl-10">from</span><span class="hl-1"> </span><span class="hl-9">&#39;three&#39;</span><span class="hl-1">;</span><br/><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">five</span><span class="hl-1"> = </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-5">Five</span><span class="hl-1">({</span><span class="hl-8">/*...*/</span><span class="hl-1">});</span><br/><br/><span class="hl-8">// 加载 GLB 模型</span><br/><span class="hl-5">loadGltf</span><span class="hl-1">(</span><span class="hl-9">&#39;https://example.com/model.glb&#39;</span><span class="hl-1">).</span><span class="hl-5">then</span><span class="hl-1">((</span><span class="hl-6">result</span><span class="hl-1">) </span><span class="hl-3">=&gt;</span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-8">// 1. 获取模型对象</span><br/><span class="hl-1"> </span><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">model</span><span class="hl-1"> = </span><span class="hl-6">result</span><span class="hl-1">.</span><span class="hl-6">scene</span><span class="hl-1">;</span><br/><br/><span class="hl-1"> </span><span class="hl-8">// 2. 设置位置和大小</span><br/><span class="hl-1"> </span><span class="hl-6">model</span><span class="hl-1">.</span><span class="hl-6">position</span><span class="hl-1">.</span><span class="hl-5">set</span><span class="hl-1">(</span><span class="hl-11">0</span><span class="hl-1">, </span><span class="hl-11">0</span><span class="hl-1">, </span><span class="hl-11">0</span><span class="hl-1">);</span><br/><span class="hl-1"> </span><span class="hl-6">model</span><span class="hl-1">.</span><span class="hl-6">scale</span><span class="hl-1">.</span><span class="hl-5">set</span><span class="hl-1">(</span><span class="hl-11">1</span><span class="hl-1">, </span><span class="hl-11">1</span><span class="hl-1">, </span><span class="hl-11">1</span><span class="hl-1">);</span><br/><br/><span class="hl-1"> </span><span class="hl-8">// 3. 添加到 Five 场景</span><br/><span class="hl-1"> </span><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-6">scene</span><span class="hl-1">.</span><span class="hl-5">add</span><span class="hl-1">(</span><span class="hl-6">model</span><span class="hl-1">);</span><br/><br/><span class="hl-1"> </span><span class="hl-8">// 4. (可选) 渲染一帧以确保显示</span><br/><span class="hl-1"> </span><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-6">needsRender</span><span class="hl-1"> = </span><span class="hl-3">true</span><span class="hl-1">;</span><br/><br/><span class="hl-1"> </span><span class="hl-8">// 保存 result 用于后续销毁</span><br/><span class="hl-1"> </span><span class="hl-8">// result.dispose();</span><br/><span class="hl-1">}).</span><span class="hl-5">catch</span><span class="hl-1">(</span><span class="hl-6">err</span><span class="hl-1"> </span><span class="hl-3">=&gt;</span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-6">console</span><span class="hl-1">.</span><span class="hl-5">error</span><span class="hl-1">(</span><span class="hl-9">&#39;加载失败&#39;</span><span class="hl-1">, </span><span class="hl-6">err</span><span class="hl-1">);</span><br/><span class="hl-1">});</span> </code><button type="button">Copy</button></pre> <h3 id="进阶用法:加载高斯泼溅-gaussian-splat" class="tsd-anchor-link">进阶用法:加载高斯泼溅 (Gaussian Splat)<a href="#进阶用法:加载高斯泼溅-gaussian-splat" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3> <pre><code class="typescript"><span class="hl-10">import</span><span class="hl-1"> { </span><span class="hl-6">loadSplat</span><span class="hl-1"> } </span><span class="hl-10">from</span><span class="hl-1"> </span><span class="hl-9">&#39;@realsee/five&#39;</span><span class="hl-1">;</span><br/><br/><span class="hl-5">loadSplat</span><span class="hl-1">(</span><span class="hl-9">&#39;https://example.com/scene.splat&#39;</span><span class="hl-1">, {</span><br/><span class="hl-1"> </span><span class="hl-6">modelUpAxis:</span><span class="hl-1"> </span><span class="hl-9">&#39;Y&#39;</span><span class="hl-1">, </span><span class="hl-8">// 假设原始数据是 Y-up</span><br/><span class="hl-1"> </span><span class="hl-6">upAxis:</span><span class="hl-1"> </span><span class="hl-9">&#39;Z&#39;</span><span class="hl-1">, </span><span class="hl-8">// 转换到 Five 的 Z-up</span><br/><span class="hl-1">}).</span><span class="hl-5">then</span><span class="hl-1">((</span><span class="hl-6">result</span><span class="hl-1">) </span><span class="hl-3">=&gt;</span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-4">splatMesh</span><span class="hl-1"> = </span><span class="hl-6">result</span><span class="hl-1">.</span><span class="hl-6">scene</span><span class="hl-1">;</span><br/><span class="hl-1"> </span><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-6">scene</span><span class="hl-1">.</span><span class="hl-5">add</span><span class="hl-1">(</span><span class="hl-6">splatMesh</span><span class="hl-1">);</span><br/><span class="hl-1"> </span><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-6">needsRender</span><span class="hl-1"> = </span><span class="hl-3">true</span><span class="hl-1">;</span><br/><span class="hl-1">});</span> </code><button type="button">Copy</button></pre> <h3 id="进阶用法:自定义-ply-属性映射-custom-ply-properties" class="tsd-anchor-link">进阶用法:自定义 PLY 属性映射 (Custom PLY Properties)<a href="#进阶用法:自定义-ply-属性映射-custom-ply-properties" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3> <pre><code class="typescript"><span class="hl-10">import</span><span class="hl-1"> { </span><span class="hl-6">loadPly</span><span class="hl-1"> } </span><span class="hl-10">from</span><span class="hl-1"> </span><span class="hl-9">&#39;@realsee/five&#39;</span><span class="hl-1">;</span><br/><br/><span class="hl-5">loadPly</span><span class="hl-1">(</span><span class="hl-9">&#39;https://example.com/data.ply&#39;</span><span class="hl-1">, {</span><br/><span class="hl-1"> </span><span class="hl-6">type:</span><span class="hl-1"> </span><span class="hl-9">&#39;pbmPointCloud&#39;</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-6">customPropertyMapping:</span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-6">intensity:</span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-6">itemType:</span><span class="hl-1"> </span><span class="hl-9">&#39;float32&#39;</span><span class="hl-1">,</span><br/><span class="hl-1"> </span><span class="hl-6">itemNames:</span><span class="hl-1"> [</span><span class="hl-9">&#39;intensity&#39;</span><span class="hl-1">],</span><br/><span class="hl-1"> </span><span class="hl-6">normalized:</span><span class="hl-1"> </span><span class="hl-3">true</span><br/><span class="hl-1"> }</span><br/><span class="hl-1"> }</span><br/><span class="hl-1">}).</span><span class="hl-5">then</span><span class="hl-1">((</span><span class="hl-6">result</span><span class="hl-1">) </span><span class="hl-3">=&gt;</span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-8">// result.scene 是一个 PBMPointCloud 对象</span><br/><span class="hl-1"> </span><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-6">scene</span><span class="hl-1">.</span><span class="hl-5">add</span><span class="hl-1">(</span><span class="hl-6">result</span><span class="hl-1">.</span><span class="hl-6">scene</span><span class="hl-1">);</span><br/><span class="hl-1">});</span> </code><button type="button">Copy</button></pre> <h3 id="基础用法:加载-obj-模型-basic-usage-obj" class="tsd-anchor-link">基础用法:加载 OBJ 模型 (Basic Usage - OBJ)<a href="#基础用法:加载-obj-模型-basic-usage-obj" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3> <pre><code class="typescript"><span class="hl-10">import</span><span class="hl-1"> { </span><span class="hl-6">loadObj</span><span class="hl-1"> } </span><span class="hl-10">from</span><span class="hl-1"> </span><span class="hl-9">&#39;@realsee/five&#39;</span><span class="hl-1">;</span><br/><br/><span class="hl-5">loadObj</span><span class="hl-1">(</span><span class="hl-9">&#39;https://example.com/model.obj&#39;</span><span class="hl-1">, {</span><br/><span class="hl-1"> </span><span class="hl-6">modelUpAxis:</span><span class="hl-1"> </span><span class="hl-9">&#39;Z&#39;</span><span class="hl-1">, </span><span class="hl-8">// OBJ 默认通常是 Z-up (或根据实际情况调整)</span><br/><span class="hl-1">}).</span><span class="hl-5">then</span><span class="hl-1">((</span><span class="hl-6">result</span><span class="hl-1">) </span><span class="hl-3">=&gt;</span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-6">scene</span><span class="hl-1">.</span><span class="hl-5">add</span><span class="hl-1">(</span><span class="hl-6">result</span><span class="hl-1">.</span><span class="hl-6">scene</span><span class="hl-1">);</span><br/><span class="hl-1"> </span><span class="hl-8">// OBJ 文件中定义的 .mtl 材质会自动加载</span><br/><span class="hl-1">});</span> </code><button type="button">Copy</button></pre> <h3 id="基础用法:加载-fbx-模型" class="tsd-anchor-link">基础用法:加载 FBX 模型<a href="#基础用法:加载-fbx-模型" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3> <pre><code class="typescript"><span class="hl-10">import</span><span class="hl-1"> { </span><span class="hl-6">loadFbx</span><span class="hl-1"> } </span><span class="hl-10">from</span><span class="hl-1"> </span><span class="hl-9">&#39;@realsee/five&#39;</span><span class="hl-1">;</span><br/><br/><span class="hl-5">loadFbx</span><span class="hl-1">(</span><span class="hl-9">&#39;https://example.com/model.fbx&#39;</span><span class="hl-1">).</span><span class="hl-5">then</span><span class="hl-1">((</span><span class="hl-6">result</span><span class="hl-1">) </span><span class="hl-3">=&gt;</span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-6">scene</span><span class="hl-1">.</span><span class="hl-5">add</span><span class="hl-1">(</span><span class="hl-6">result</span><span class="hl-1">.</span><span class="hl-6">scene</span><span class="hl-1">);</span><br/><span class="hl-1"> </span><span class="hl-8">// 动画会自动解析到 result.animations</span><br/><span class="hl-1">});</span> </code><button type="button">Copy</button></pre> <h3 id="进阶用法:加载-dome-全景-panorama" class="tsd-anchor-link">进阶用法:加载 Dome 全景 (Panorama)<a href="#进阶用法:加载-dome-全景-panorama" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3> <pre><code class="typescript"><span class="hl-10">import</span><span class="hl-1"> { </span><span class="hl-6">loadDome</span><span class="hl-1"> } </span><span class="hl-10">from</span><span class="hl-1"> </span><span class="hl-9">&#39;@realsee/five&#39;</span><span class="hl-1">;</span><br/><br/><span class="hl-8">// 加载 .dome 或 .domez 格式</span><br/><span class="hl-5">loadDome</span><span class="hl-1">(</span><span class="hl-9">&#39;https://example.com/panorama.domez&#39;</span><span class="hl-1">, {</span><br/><span class="hl-1"> </span><span class="hl-6">light:</span><span class="hl-1"> </span><span class="hl-3">false</span><span class="hl-1">, </span><span class="hl-8">// 全景模型通常不需要光照计算</span><br/><span class="hl-1"> </span><span class="hl-6">textureOptions:</span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-6">size:</span><span class="hl-1"> </span><span class="hl-11">4096</span><span class="hl-1">, </span><span class="hl-8">// 限制最大纹理尺寸</span><br/><span class="hl-1"> }</span><br/><span class="hl-1">}).</span><span class="hl-5">then</span><span class="hl-1">((</span><span class="hl-6">result</span><span class="hl-1">) </span><span class="hl-3">=&gt;</span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-6">result</span><span class="hl-1">.</span><span class="hl-6">scene</span><span class="hl-1">.</span><span class="hl-6">position</span><span class="hl-1">.</span><span class="hl-5">set</span><span class="hl-1">(</span><span class="hl-11">0</span><span class="hl-1">, </span><span class="hl-11">0</span><span class="hl-1">, </span><span class="hl-11">0</span><span class="hl-1">);</span><br/><span class="hl-1"> </span><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-6">scene</span><span class="hl-1">.</span><span class="hl-5">add</span><span class="hl-1">(</span><span class="hl-6">result</span><span class="hl-1">.</span><span class="hl-6">scene</span><span class="hl-1">);</span><br/><span class="hl-1">});</span> </code><button type="button">Copy</button></pre> <h3 id="进阶用法:加载压缩模型-at3d" class="tsd-anchor-link">进阶用法:加载压缩模型 (AT3D)<a href="#进阶用法:加载压缩模型-at3d" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h3> <pre><code class="typescript"><span class="hl-10">import</span><span class="hl-1"> { </span><span class="hl-6">loadAt3d</span><span class="hl-1"> } </span><span class="hl-10">from</span><span class="hl-1"> </span><span class="hl-9">&#39;@realsee/five&#39;</span><span class="hl-1">;</span><br/><br/><span class="hl-5">loadAt3d</span><span class="hl-1">(</span><span class="hl-9">&#39;https://example.com/model.at3d&#39;</span><span class="hl-1">, {</span><br/><span class="hl-1"> </span><span class="hl-6">light:</span><span class="hl-1"> </span><span class="hl-3">false</span><span class="hl-1">,</span><br/><span class="hl-1">}).</span><span class="hl-5">then</span><span class="hl-1">((</span><span class="hl-6">result</span><span class="hl-1">) </span><span class="hl-3">=&gt;</span><span class="hl-1"> {</span><br/><span class="hl-1"> </span><span class="hl-6">five</span><span class="hl-1">.</span><span class="hl-6">scene</span><span class="hl-1">.</span><span class="hl-5">add</span><span class="hl-1">(</span><span class="hl-6">result</span><span class="hl-1">.</span><span class="hl-6">scene</span><span class="hl-1">);</span><br/><span class="hl-1">});</span> </code><button type="button">Copy</button></pre> <h2 id="debugging" class="tsd-anchor-link">Debugging<a href="#debugging" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h2> <ul> <li><strong>查看网络请求</strong>: 检查 Network 面板,确认模型文件是否成功下载 (200 OK)。</li> <li><strong>检查模型位置</strong>: 如果加载成功但看不到,尝试 <code>console.log(result.scene)</code> 检查其 <code>position</code> 和 <code>scale</code>。模型可能太小、太大或位置偏离相机视野。</li> <li><strong>坐标轴辅助</strong>: 在模型上添加 <code>new THREE.AxesHelper(1)</code> 来确认其自身的坐标轴方向。</li> </ul> <h2 id="common-pitfalls" class="tsd-anchor-link">Common Pitfalls<a href="#common-pitfalls" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h2> <ol> <li><strong>坐标轴方向错误</strong>: 模型“躺着”或“倒立”。 <ul> <li><strong>解决</strong>: 调整 <code>modelUpAxis</code> 参数。如果是 GLTF 试着改为 'Z' 或 'Y';如果是 PLY 试着改为 'Y'。</li> </ul> </li> <li><strong>内存泄漏</strong>: 频繁加载/卸载模型但未调用 <code>dispose()</code>。 <ul> <li><strong>解决</strong>: 务必保存 <code>load</code> 返回的 result,并在移除模型时调用 <code>result.dispose()</code>。单纯 <code>scene.remove(object)</code> 不会释放 GPU 内存。</li> </ul> </li> <li><strong>纹理路径错误</strong>: 加载 OBJ/PBM 等带外部纹理的文件时,纹理 404。 <ul> <li><strong>解决</strong>: 确保模型文件内的纹理引用是相对路径,或者通过 <code>resourcePath</code> / <code>textureBaseUri</code> (视具体 loader 而定) 指定纹理目录。</li> </ul> </li> <li><strong>Draco 解码器缺失</strong>: 加载压缩的 GLTF 失败。 <ul> <li><strong>解决</strong>: <code>loadGltf</code> 内部集成了 DracoLoader,通常不需要额外配置。如果报错,检查构建配置或网络是否拦截了 wasm 文件。</li> </ul> </li> </ol> <h2 id="related" class="tsd-anchor-link">Related<a href="#related" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../assets/icons.svg#icon-anchor"></use></svg></a></h2> <ul> <li><a href="features_model.html">Model</a>: 关于 Five 内部模型加载机制的说明。</li> <li><a href="features_coordinate-system.html">Coordinate System</a>: 坐标系定义,理解 Y-up 与 Z-up 的转换。</li> <li><a href="features_request-proxy.html">Request Proxy</a>: 自定义请求拦截(鉴权、CDN),与 fetcher 配合使用。</li> </ul> <hr> <pre><code class="yaml"><span class="hl-0">tags</span><span class="hl-1">: [</span><span class="hl-2">加载模型</span><span class="hl-1">, </span><span class="hl-2">导入模型</span><span class="hl-1">, </span><span class="hl-2">点云</span><span class="hl-1">, </span><span class="hl-2">内存泄漏</span><span class="hl-1">, </span><span class="hl-2">loader</span><span class="hl-1">, </span><span class="hl-2">gltf</span><span class="hl-1">, </span><span class="hl-2">ply</span><span class="hl-1">, </span><span class="hl-2">splat</span><span class="hl-1">, </span><span class="hl-2">fbx</span><span class="hl-1">, </span><span class="hl-2">external-model</span><span class="hl-1">, </span><span class="hl-2">glb</span><span class="hl-1">, </span><span class="hl-2">obj</span><span class="hl-1">, </span><span class="hl-2">3d-model</span><span class="hl-1">, </span><span class="hl-2">gaussian-splatting</span><span class="hl-1">, </span><span class="hl-2">point-cloud</span><span class="hl-1">, </span><span class="hl-2">draco</span><span class="hl-1">, </span><span class="hl-2">dispose</span><span class="hl-1">]</span> </code><button type="button">Copy</button></pre> </div></div><div class="col-sidebar"><div class="page-menu"><div class="tsd-navigation settings"><details class="tsd-accordion"><summary class="tsd-accordion-summary"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-chevronDown"></use></svg><h3>Settings</h3></summary><div class="tsd-accordion-details"><div class="tsd-filter-visibility"><span class="settings-label">Member Visibility</span><ul id="tsd-filter-options"><li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-inherited" name="inherited" checked/><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></svg><span>Inherited</span></label></li></ul></div><div class="tsd-theme-toggle"><label class="settings-label" for="tsd-theme">Theme</label><select id="tsd-theme"><option value="os">OS</option><option value="light">Light</option><option value="dark">Dark</option></select></div></div></details></div><details open class="tsd-accordion tsd-page-navigation"><summary class="tsd-accordion-summary"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-chevronDown"></use></svg><h3>On This Page</h3></summary><div class="tsd-accordion-details"><a href="#加载外部模型-load-external-models"><span>加载外部模型 (<wbr/>Load <wbr/>External <wbr/>Models)</span></a><ul><li><a href="#schema"><span>Schema</span></a></li><li><a href="#concepts"><span>Concepts</span></a></li><li><ul><li><a href="#独立加载函数-standalone-functions"><span>独立加载函数 (<wbr/>Standalone <wbr/>Functions)</span></a></li><li><a href="#坐标系转换-up-axis-conversion"><span>坐标系转换 (<wbr/>Up-<wbr/>Axis <wbr/>Conversion)</span></a></li><li><a href="#资源销毁-disposal"><span>资源销毁 (<wbr/>Disposal)</span></a></li><li><a href="#fetcher"><span>Fetcher</span></a></li></ul></li><li><a href="#configuration"><span>Configuration</span></a></li><li><ul><li><a href="#loadgltf"><span>load<wbr/>Gltf</span></a></li><li><a href="#loadply"><span>load<wbr/>Ply</span></a></li><li><a href="#loadsplat"><span>load<wbr/>Splat</span></a></li><li><a href="#loadspz"><span>load<wbr/>Spz</span></a></li><li><a href="#loadfbx"><span>load<wbr/>Fbx</span></a></li><li><a href="#loadobj"><span>load<wbr/>Obj</span></a></li><li><a href="#loadpbm"><span>load<wbr/>Pbm</span></a></li><li><a href="#loaddome-loaddomez"><span>load<wbr/>Dome / load<wbr/>Domez</span></a></li><li><a href="#loadat3d"><span>load<wbr/>At3d</span></a></li><li><a href="#loadb3dm"><span>load<wbr/>B3dm</span></a></li><li><a href="#loadpnts"><span>load<wbr/>Pnts</span></a></li><li><a href="#loadx3p"><span>load<wbr/>X3p</span></a></li></ul></li><li><a href="#examples"><span>Examples</span></a></li><li><ul><li><a href="#基础用法:加载-gltf-模型-basic-usage"><span>基础用法:加载 <wbr/>GLTF 模型 (<wbr/>Basic <wbr/>Usage)</span></a></li><li><a href="#进阶用法:加载高斯泼溅-gaussian-splat"><span>进阶用法:加载高斯泼溅 (<wbr/>Gaussian <wbr/>Splat)</span></a></li><li><a href="#进阶用法:自定义-ply-属性映射-custom-ply-properties"><span>进阶用法:自定义 <wbr/>PLY 属性映射 (<wbr/>Custom <wbr/>PLY <wbr/>Properties)</span></a></li><li><a href="#基础用法:加载-obj-模型-basic-usage-obj"><span>基础用法:加载 <wbr/>OBJ 模型 (<wbr/>Basic <wbr/>Usage -<wbr/> <wbr/>OBJ)</span></a></li><li><a href="#基础用法:加载-fbx-模型"><span>基础用法:加载 <wbr/>FBX 模型</span></a></li><li><a href="#进阶用法:加载-dome-全景-panorama"><span>进阶用法:加载 <wbr/>Dome 全景 (<wbr/>Panorama)</span></a></li><li><a href="#进阶用法:加载压缩模型-at3d"><span>进阶用法:加载压缩模型 (<wbr/>AT3<wbr/>D)</span></a></li></ul></li><li><a href="#debugging"><span>Debugging</span></a></li><li><a href="#common-pitfalls"><span>Common <wbr/>Pitfalls</span></a></li><li><a href="#related"><span>Related</span></a></li></ul></div></details></div><div class="site-menu"><nav class="tsd-navigation"><a href="../modules.html">如视 Five SDK</a><ul class="tsd-small-nested-navigation" id="tsd-nav-container"><li>Loading...</li></ul></nav></div></div></div><footer><p class="tsd-generator">Generated using <a href="https://typedoc.org/" target="_blank">TypeDoc</a></p></footer><div class="overlay"></div></body></html>