加载外部模型 (Load External Models)

• Summary: 提供了一系列独立的加载函数 (loadGltf, loadPly, loadFbx 等)，用于加载各种格式的外部 3D 模型（如 .glb, .ply, .splat, .fbx），并将其转换为 Three.js 对象以便添加到 Five 场景中。
• Schema: 涉及 LoadResultType 返回结构及各加载器的配置项 (LoaderOptions)。
• Concepts: 独立加载函数、坐标系转换 (UpAxis)、资源销毁 (Dispose)、Fetcher。
• Configuration: modelUpAxis, upAxis, fetcher 等通用及特定配置。
• Examples: 加载 GLTF 模型、加载高斯泼溅 (Gaussian Splat)、加载点云。

Schema

Definition: LoadResultType

所有加载函数均返回 Promise<LoadResultType>。

// 通用返回类型
export type LoadResultType<Scene = THREE.Object3D> = {
  type: 'gltf' | 'obj' | 'ply' | 'fbx' | 'pbm' | 'splat' | 'spz' | 'b3dm' | 'pnts' | 'at3d' | 'dome' | 'domez' | 'x3p'; // 模型类型
  modelUpAxis: 'Y' | 'Z';     // 原始模型的上轴
  upAxis: 'Y' | 'Z';          // 输出模型的上轴 (通常为 Z)
  byteLength: number;         // 文件字节大小
  memoryUsage: number;        // 显存/内存占用估算
  uri: string;                // 模型地址
  scene: Scene;               // Three.js 对象 (Group 或 Object3D)，可直接添加到场景
  textures: THREE.Texture[];  // 加载的纹理列表
  animations: THREE.AnimationClip[]; // 动画剪辑列表
  rtcCenter?: THREE.Vector3;  // 若存在 RTC (Relative To Center) 坐标偏移
  dispose: () => void;        // 销毁资源函数
}

// 通用配置项接口
interface BaseLoaderOptions {
  upAxis?: 'Y' | 'Z';         // 期望输出的上轴，默认为 'Z' (Five 坐标系)
  modelUpAxis?: 'Y' | 'Z';    // (部分加载器支持) 原始模型的上轴，用于自动旋转修正
  fetcher?: Fetcher;          // 自定义网络请求 Fetcher
  light?: boolean;            // 是否使用简化/无光照材质 (取决于加载器实现)
  onDownloadProgress?: (progress: { loaded: number, total: number }) => void; // 下载进度回调
}
Copy

Concepts

独立加载函数 (Standalone Functions)

这些加载函数（如 loadGltf, loadPly）是 @realsee/five 包导出的独立函数，而非 Five 实例的方法。你需要单独引入它们使用。

坐标系转换 (Up-Axis Conversion)

Five 使用 Z-up (Z 轴向上) 的右手坐标系。 许多外部模型（如 standard GLTF, FBX）通常是 Y-up 的。 加载器提供了 upAxis 和 modelUpAxis 选项来自动处理旋转：

• upAxis: 你期望得到的结果坐标系上轴（通常保持默认 'Z'）。
• modelUpAxis: 原始文件的上轴（如 GLTF 默认为 'Y'，PLY 默认为 'Z'）。 如果不指定，加载器会尝试使用合理的默认值将模型旋转到 Z 轴向上。

资源销毁 (Disposal)

加载的模型包含 Geometry、Material 和 Texture 等 WebGL 资源。当你不再需要该模型时（例如切换场景或移除物体），必须调用返回结果中的 dispose() 方法来释放内存，否则会导致内存泄漏。

Fetcher

所有加载器支持传入自定义 fetcher。这在需要鉴权、自定义 Header 或处理特定 CDN 逻辑时非常有用。如果不传，默认使用内部的 internalFetcher。

Configuration

loadGltf

加载 .gltf 或 .glb 文件。支持 Draco 压缩。 支持扩展：

• KHR_binary_glTF
• KHR_draco_mesh_compression
• KHR_texture_basisu
• KHR_texture_transform
• KHR_mesh_quantization
• KHR_materials_unlit
• KHR_node_visibility
• KHR_animation_pointer
• EXT_meshopt_compression
• KHR_materials_clearcoat
• KHR_materials_sheen
• KHR_materials_transmission
• KHR_materials_emissive_strength
• EXT_texture_webp
• CESIUM_RTC
• REALSEE_materials_lightmap
• KHR_gaussian_splatting
• KHR_gaussian_splatting_compression_spz
• KHR_gaussian_splatting_compression_spz_2

参数	类型	默认值	说明
modelUpAxis	`'Y'	'Z'`	'Y'
upAxis	`'Y'	'Z'`	'Z'
light	boolean	undefined	是否强制使用 Unlit 材质或移除光照扩展。
fetcher	Fetcher	-	自定义 Fetcher。

loadPly

加载 .ply 文件。支持网格、线框、点云及 PBM 扩展格式。

参数	类型	默认值	说明
type	`'geometry'	'line'	'pbmMesh'
customPropertyMapping	Object	-	自定义属性映射（用于解析非标准 PLY 属性）。
propertyNameMapping	Object	-	属性名重映射 (e.g. {'diffuse_red': 'red'})。
modelUpAxis	`'Y'	'Z'`	'Z'
upAxis	`'Y'	'Z'`	'Z'
light	boolean	undefined	是否使用简化材质。
fetcher	Fetcher	-	自定义 Fetcher。

loadSplat

加载 .splat 格式的高斯泼溅 (Gaussian Splat) 模型。

参数	类型	默认值	说明
modelUpAxis	`'Y'	'Z'`	'Y'
upAxis	`'Y'	'Z'`	'Z'
fetcher	Fetcher	-	自定义 Fetcher。

loadSpz

加载 .spz 格式的高斯泼溅 (Gaussian Splat) 模型。.spz 是对 .splat 的压缩格式。

参数	类型	默认值	说明
modelUpAxis	`'Y'	'Z'`	'Y'
upAxis	`'Y'	'Z'`	'Z'
fetcher	Fetcher	-	自定义 Fetcher。

loadFbx

加载 .fbx 文件。

参数	类型	默认值	说明
upAxis	`'Y'	'Z'`	'Z'
light	boolean	undefined	是否使用简化材质。
fetcher	Fetcher	-	自定义 Fetcher。

loadObj

加载 .obj 文件。会自动尝试加载同目录下的 .mtl 材质文件。

参数	类型	默认值	说明
modelUpAxis	`'Y'	'Z'`	'Z'
upAxis	`'Y'	'Z'`	'Z'
light	boolean	undefined	是否使用简化材质。
fetcher	Fetcher	-	自定义 Fetcher。

loadPbm

加载 Realsee 私有 PBM 格式。

参数	类型	默认值	说明
upAxis	`'Y'	'Z'`	'Z'
light	boolean	false	是否使用简化材质。
textureBaseUri	string	自动推断	纹理的基础路径。
textureArray	string[]	-	纹理路径列表。
textureOptions	TextureOptions	-	纹理加载配置 (size, quality 等)。
fetcher	Fetcher	-	自定义 Fetcher。

loadDome / loadDomez

加载 Dome 全景模型 (.dome 或 .domez 压缩格式)。

参数	类型	默认值	说明
upAxis	`'Y'	'Z'`	'Z'
light	boolean	true	是否使用简化材质。
textureBaseUri	string	-	纹理基础路径。
textureOptions	TextureOptions	-	纹理加载配置。
fetcher	Fetcher	-	自定义 Fetcher。

loadAt3d

加载 .at3d 格式模型。

参数	类型	默认值	说明
upAxis	`'Y'	'Z'`	'Z'
light	boolean	false	是否使用简化材质。
textureBaseUri	string	自动推断	纹理基础路径。
textureArray	string[]	-	纹理路径列表。
textureOptions	TextureOptions	-	纹理加载配置。
fetcher	Fetcher	-	自定义 Fetcher。

loadB3dm

加载 .b3dm (Batched 3D Model) 格式。

参数	类型	默认值	说明
modelUpAxis	`'Y'	'Z'`	'Y'
upAxis	`'Y'	'Z'`	'Z'
light	boolean	undefined	是否使用简化材质。
fetcher	Fetcher	-	自定义 Fetcher。

loadPnts

加载 .pnts (Point Cloud) 格式。

参数	类型	默认值	说明
upAxis	`'Y'	'Z'`	'Z'
computeBoundingBox	boolean	true	是否计算包围盒。
fetcher	Fetcher	-	自定义 Fetcher。

loadX3p

加载 .x3p 格式。

参数	类型	默认值	说明
upAxis	`'Y'	'Z'`	'Z'
color	THREE.Color	-	指定颜色。
light	boolean	true	是否使用简化材质。
fetcher	Fetcher	-	自定义 Fetcher。

Examples

基础用法：加载 GLTF 模型 (Basic Usage)

import { Five, FivePlugin } from '@realsee/five';
import { loadGltf } from '@realsee/five';
import * as THREE from 'three';

const five = new Five({/*...*/});

// 加载 GLB 模型
loadGltf('https://example.com/model.glb').then((result) => {
  // 1. 获取模型对象
  const model = result.scene;

  // 2. 设置位置和大小
  model.position.set(0, 0, 0);
  model.scale.set(1, 1, 1);

  // 3. 添加到 Five 场景
  five.scene.add(model);

  // 4. (可选) 渲染一帧以确保显示
  five.needsRender = true;

  // 保存 result 用于后续销毁
  // result.dispose();
}).catch(err => {
  console.error('加载失败', err);
});
Copy

进阶用法：加载高斯泼溅 (Gaussian Splat)

import { loadSplat } from '@realsee/five';

loadSplat('https://example.com/scene.splat', {
  modelUpAxis: 'Y', // 假设原始数据是 Y-up
  upAxis: 'Z',      // 转换到 Five 的 Z-up
}).then((result) => {
  const splatMesh = result.scene;
  five.scene.add(splatMesh);
  five.needsRender = true;
});
Copy

进阶用法：自定义 PLY 属性映射 (Custom PLY Properties)

import { loadPly } from '@realsee/five';

loadPly('https://example.com/data.ply', {
  type: 'pbmPointCloud',
  customPropertyMapping: {
    intensity: {
      itemType: 'float32',
      itemNames: ['intensity'],
      normalized: true
    }
  }
}).then((result) => {
  // result.scene 是一个 PBMPointCloud 对象
  five.scene.add(result.scene);
});
Copy

基础用法：加载 OBJ 模型 (Basic Usage - OBJ)

import { loadObj } from '@realsee/five';

loadObj('https://example.com/model.obj', {
  modelUpAxis: 'Z', // OBJ 默认通常是 Z-up (或根据实际情况调整)
}).then((result) => {
  five.scene.add(result.scene);
  // OBJ 文件中定义的 .mtl 材质会自动加载
});
Copy

基础用法：加载 FBX 模型

import { loadFbx } from '@realsee/five';

loadFbx('https://example.com/model.fbx').then((result) => {
  five.scene.add(result.scene);
  // 动画会自动解析到 result.animations
});
Copy

进阶用法：加载 Dome 全景 (Panorama)

import { loadDome } from '@realsee/five';

// 加载 .dome 或 .domez 格式
loadDome('https://example.com/panorama.domez', {
  light: false, // 全景模型通常不需要光照计算
  textureOptions: {
    size: 4096, // 限制最大纹理尺寸
  }
}).then((result) => {
  result.scene.position.set(0, 0, 0);
  five.scene.add(result.scene);
});
Copy

进阶用法：加载压缩模型 (AT3D)

import { loadAt3d } from '@realsee/five';

loadAt3d('https://example.com/model.at3d', {
  light: false,
}).then((result) => {
  five.scene.add(result.scene);
});
Copy

Debugging

• 查看网络请求: 检查 Network 面板，确认模型文件是否成功下载 (200 OK)。
• 检查模型位置: 如果加载成功但看不到，尝试 console.log(result.scene) 检查其 position 和 scale。模型可能太小、太大或位置偏离相机视野。
• 坐标轴辅助: 在模型上添加 new THREE.AxesHelper(1) 来确认其自身的坐标轴方向。

Common Pitfalls

1. 坐标轴方向错误: 模型“躺着”或“倒立”。
   • 解决: 调整 modelUpAxis 参数。如果是 GLTF 试着改为 'Z' 或 'Y'；如果是 PLY 试着改为 'Y'。
2. 内存泄漏: 频繁加载/卸载模型但未调用 dispose()。
   • 解决: 务必保存 load 返回的 result，并在移除模型时调用 result.dispose()。单纯 scene.remove(object) 不会释放 GPU 内存。
3. 纹理路径错误: 加载 OBJ/PBM 等带外部纹理的文件时，纹理 404。
   • 解决: 确保模型文件内的纹理引用是相对路径，或者通过 resourcePath / textureBaseUri (视具体 loader 而定) 指定纹理目录。
4. Draco 解码器缺失: 加载压缩的 GLTF 失败。
   • 解决: loadGltf 内部集成了 DracoLoader，通常不需要额外配置。如果报错，检查构建配置或网络是否拦截了 wasm 文件。

Related

• Model: 关于 Five 内部模型加载机制的说明。
• Coordinate System: 坐标系定义，理解 Y-up 与 Z-up 的转换。
• Request Proxy: 自定义请求拦截（鉴权、CDN），与 fetcher 配合使用。

---

tags: [加载模型, 导入模型, 点云, 内存泄漏, loader, gltf, ply, splat, fbx, external-model, glb, obj, 3d-model, gaussian-splatting, point-cloud, draco, dispose]
Copy