资源管线

资源管线涵盖了 3D 模型、纹理和场景数据的导入与导出系统。这包括各种文件格式（glTF、FBX、OBJ 等）的加载器、支持压缩的纹理加载，以及将场景序列化回标准格式的导出器。该管线提供了将外部资源加载到 Three.js 场景图和材质中的统一接口。

有关程序化几何体生成的信息，请参阅程序化几何体。有关使用 ObjectLoader/toJSON 系统序列化完整场景的信息，请参阅场景序列化。

系统架构

资源管线构建在共享的基础类和工具之上，所有加载器都继承自此外。这为路径解析、进度跟踪、错误处理和资源缓存提供了一致的行为。

核心基础设施

100%

Loader 基类 (src/loaders/Loader.js) 为所有加载器提供通用属性：

属性	类型	用途
manager	LoadingManager	跨多个资源跟踪加载进度
crossOrigin	string	图像加载的 CORS 设置
withCredentials	boolean	是否在请求中发送凭据
path	string	预置到所有 URL 的基础路径
resourcePath	string	用于解析依赖资源的路径
requestHeader	Object	自定义 HTTP 头

格式支持矩阵

Three.js 为多种 3D 文件格式提供加载器，每种格式具有不同的功能和使用场景：

格式	加载器类	支持的功能	主要用途
glTF 2.0 (.gltf/.glb)	GLTFLoader	Mesh、材质（PBR）、纹理、动画、蒙皮、变形目标、灯光、相机、20+ 扩展	现代资源交付、游戏引擎、AR/VR
FBX (.fbx)	FBXLoader	Mesh、材质（Phong/Lambert）、纹理、动画、蒙皮、变形目标、相机、灯光	DCC 工具交换（Maya、3ds Max）
OBJ/MTL (.obj/.mtl)	OBJLoader/MTLLoader	Mesh、材质（Phong）、纹理	简单模型交换、旧格式
STL (.stl)	STLLoader	Mesh、顶点颜色（二进制）、多实体（ASCII）	CAD、3D 打印
PLY (.ply)	PLYLoader	Mesh、顶点颜色、法线、自定义属性	点云、扫描数据
3MF (.3mf)	ThreeMFLoader	Mesh、材质（基础+PBR）、纹理、顶点颜色	3D 打印、Microsoft 3D 生态系统
EXR (.exr)	EXRLoader	HDR 纹理、多种压缩模式	HDR 环境贴图、渲染通道
PCD (.pcd)	PCDLoader	点云、RGB、法线、强度	激光雷达、机器人
NRRD (.nrrd)	NRRDLoader	体数据（医学成像）	医学可视化

glTF 加载器系统

GLTFLoader 是 Three.js 中最复杂的加载器，实现了 glTF 2.0 规范并具备广泛的扩展支持。它使用插件架构来处理扩展和压缩。

GLTFLoader 架构

100%

扩展系统

GLTFLoader 在构造时注册扩展插件，并提供 register() 方法供第三方扩展使用。解析期间会查询扩展以处理特定的 glTF 扩展数据。

100%

扩展注册：

加载器支持 20+ 扩展，在构造函数中注册 examples/jsm/loaders/GLTFLoader.js141-248：

材质扩展： KHR_materials_clearcoat、KHR_materials_transmission、KHR_materials_volume、KHR_materials_ior、KHR_materials_specular、KHR_materials_iridescence、KHR_materials_sheen、KHR_materials_anisotropy、KHR_materials_dispersion、KHR_materials_emissive_strength、KHR_materials_unlit、EXT_materials_bump
纹理扩展： KHR_texture_basisu、EXT_texture_webp、EXT_texture_avif、KHR_texture_transform
压缩： KHR_draco_mesh_compression、KHR_meshopt_compression、EXT_meshopt_compression
其他： KHR_lights_punctual、KHR_mesh_quantization、EXT_mesh_gpu_instancing

配置压缩加载器

// 配置 DRACO 解码器用于网格压缩
const dracoLoader = new DRACOLoader();
dracoLoader.setDecoderPath( '/examples/jsm/libs/draco/' );
gltfLoader.setDRACOLoader( dracoLoader );

// 配置 KTX2 解码器用于纹理压缩
const ktx2Loader = new KTX2Loader();
ktx2Loader.setTranscoderPath( '/examples/jsm/libs/basis/' );
gltfLoader.setKTX2Loader( ktx2Loader );

// 配置 meshopt 解码器
gltfLoader.setMeshoptDecoder( MeshoptDecoder );

FBX 加载器

FBXLoader 处理 Autodesk FBX 格式，支持 ASCII（>= 7.0）和二进制（>= 6400）版本。它解析 FBX 树结构并将其转换为 Three.js 对象。

FBX 解析管线

100%

FBX 格式使用基于连接的系统，其中对象通过数字 ID 相互引用。解析器构建连接映射 examples/jsm/loaders/FBXLoader.js209-253，然后遍历它以构建最终场景图。

OBJ/MTL 加载器

Wavefront OBJ 格式是最古老和最简单的 3D 格式之一。OBJLoader 解析几何体，而 MTLLoader 解析配套材质文件。

OBJ 解析状态机

100%

OBJ 格式使用文本指令。面通过语法 f v1/vt1/vn1 v2/vt2/vn2 ... 按索引引用顶点。加载器维护一个 ParserState 对象 examples/jsm/loaders/OBJLoader.js38-201，累积几何数据并构建 Mesh 对象。

MTL 材质属性：

MTLLoader 解析材质属性并创建 MeshPhongMaterial 实例 examples/jsm/loaders/MTLLoader.js1-33：

MTL 指令	Three.js 属性	描述
Ka	ambient	环境色
Kd	color	漫反射色
Ks	specular	镜面色
Ns	shininess	镜面指数
d / Tr	opacity	透明度
map_Kd	map	漫反射纹理
map_Ks	specularMap	镜面纹理
map_Bump / bump	bumpMap	凹凸/法线贴图

纹理加载

纹理加载支持标准图像格式（JPEG、PNG 等）以及用于 HDR 和压缩纹理的专用格式。

纹理加载器层级

100%

EXR 加载器详情

EXRLoader 支持具有多种压缩方法的 OpenEXR 格式 examples/jsm/loaders/EXRLoader.js83-96：

未压缩： 原始像素数据
RLE： 游程编码
ZIP/ZIPS： Zlib 压缩（单/多扫描线）
PIZ： 小波压缩
DWA/DWAB： 有损 DCT 压缩

加载器使用 DataTextureLoader 作为基类，并支持输出为 HalfFloatType 或 FloatType examples/jsm/loaders/EXRLoader.js97-124：

const loader = new EXRLoader();
loader.type = THREE.HalfFloatType; // 或 FloatType
loader.outputFormat = THREE.RGBAFormat; // 或 RGFormat、RedFormat

导出系统

GLTFExporter 将 Three.js 场景转换回 glTF 格式，支持 JSON（.gltf）和二进制（.glb）输出。

GLTFExporter 架构

100%

导出选项

导出器支持多种选项 examples/jsm/exporters/GLTFExporter.js644-661：

选项	类型	默认值	描述
binary	boolean	false	导出为二进制 .glb 格式
trs	boolean	false	将变换导出为平移/旋转/缩放而非矩阵
onlyVisible	boolean	true	仅导出可见对象
maxTextureSize	number	Infinity	下采样的最大纹理尺寸
animations	Array	[]	要导出的动画剪辑
includeCustomExtensions	boolean	false	包含来自 userData.gltfExtensions 的自定义扩展

测试中的使用示例： examples/misc_exporter_gltf.html34-69

材质属性转换

导出器将 Three.js 材质转换为支持扩展的 glTF PBR 材质 examples/jsm/exporters/GLTFExporter.js120-203：

标准材质： 转换为 glTF PBR 金属粗糙度
物理材质： 支持清漆、透射、体积、折射率等扩展
基础材质： 使用 KHR_materials_unlit 扩展
纹理合并： 独立的金属度/粗糙度贴图合并为单个纹理

压缩集成

Three.js 集成了多种压缩技术以减少文件大小和 GPU 内存占用。

压缩技术概览

100%

DRACO 网格压缩

DRACO 使用量化和熵编码压缩网格几何体。GLTFDracoMeshCompressionExtension examples/jsm/loaders/GLTFLoader.js1614-1734 处理解压缩：

检测 glTF 图元中的 KHR_draco_mesh_compression 扩展
加载压缩缓冲区数据
调用 DRACOLoader 解码为 Three.js BufferGeometry
恢复属性语义（位置、法线、纹理坐标等）

Meshopt 压缩

Meshopt 压缩优化网格数据以提高 GPU 缓存效率，并可选择性地压缩。加载器处理 KHR_meshopt_compression 和 EXT_meshopt_compression examples/jsm/loaders/GLTFLoader.js1890-1957

KTX2 纹理压缩

KTX2/Basis Universal 提供通用纹理压缩，在加载时转码为 GPU 原生格式。GLTFTextureBasisUExtension examples/jsm/loaders/GLTFLoader.js1443-1500 将其与 glTF 集成：

ETC1S 模式： 高压缩比，较低质量
UASTC 模式： 更高质量，较低压缩
运行时转码： 根据 GPU 支持转换为 BC1-7、ETC2、ASTC 等

fflate 归档解压

fflate 库处理 ZIP、GZIP 和 ZLIB 解压，用于归档格式：

FBX： 二进制 FBX 文件可能包含 zlib 压缩段 examples/jsm/loaders/FBXLoader.js47
3MF： 3D 制造格式为 ZIP 归档 examples/jsm/loaders/3MFLoader.js22
EXR： OpenEXR 文件支持 ZIP 压缩 examples/jsm/loaders/EXRLoader.js12

加载管理器与进度跟踪

LoadingManager 协调多个文件加载并跟踪整体进度。

加载管理器流程

100%

使用示例：

const manager = new THREE.LoadingManager();

manager.onStart = function ( url, itemsLoaded, itemsTotal ) {
    console.log( '开始加载: ' + url );
};

manager.onProgress = function ( url, itemsLoaded, itemsTotal ) {
    console.log( '加载中: ' + (100 * itemsLoaded / itemsTotal) + '%' );
};

manager.onLoad = function () {
    console.log( '加载完成!' );
};

const loader = new GLTFLoader( manager );

缓存系统

Cache 单例 src/loaders/Cache.js 存储已加载的资源以避免冗余网络请求：

默认启用： Cache.enabled = true
存储： 将 URL 字符串映射到已加载的数据
跨加载器共享： 所有 FileLoader 实例使用同一缓存
手动管理： Cache.add(key, file)、Cache.get(key)、Cache.remove(key)、Cache.clear()

点云与体数据加载器

专用加载器处理点云和体积医学成像数据。

点云格式

PCDLoader examples/jsm/loaders/PCDLoader.js13-34 支持点云数据格式：

ASCII 和二进制编码（压缩和未压缩）
字段：位置（x, y, z）、RGB 颜色、法线、强度、标签
返回带 PointsMaterial 的 Points 对象

PLYLoader examples/jsm/loaders/PLYLoader.js12-27 支持 Stanford PLY 格式：

ASCII 和二进制编码
通过 setPropertyNameMapping() 和 setCustomPropertyNameMapping() 进行自定义属性映射
顶点颜色、法线、自定义属性
返回 BufferGeometry

体数据

NRRDLoader examples/jsm/loaders/NRRDLoader.js10-19 加载医学成像体数据：

NRRD（近乎原始栅格数据）格式
返回带 3D 数据数组的 Volume 对象
与 VolumeSlice 一起用于可视化 examples/jsm/misc/VolumeSlice.js12-16

Volume 类 examples/jsm/misc/Volume.js8-13 提供：

带 IJK 索引的 3D 数据存储
RAS（右-前-上）坐标系
可视化的窗宽/窗位
任意方向的切片提取

CAD 与 3D 打印格式

多个加载器面向 CAD 和 3D 打印工作流。

STL 加载器

STLLoader examples/jsm/loaders/STLLoader.js12-53 处理立体光刻格式：

二进制 STL： 可包含颜色数据（Magics 格式）
ASCII STL： 支持多实体作为几何体组
返回非索引 BufferGeometry
颜色处理：geometry.hasColors、geometry.alpha

3MF 加载器

ThreeMFLoader examples/jsm/loaders/3MFLoader.js26-52 支持 3D 制造格式：

基于 ZIP 的归档格式
核心规范：网格、组件、基础材质
扩展：纹理 2D、颜色组、金属显示（PBR）
返回带网格的 Group

加载器解析归档结构 examples/jsm/loaders/3MFLoader.js127-267：

提取 ZIP 内容（使用 fflate）
解析 _rels/.rels 获取关系
解析 3D 模型 XML 文件
解析纹理资源
构建 Three.js 场景图

AMF 加载器

AMFLoader examples/jsm/loaders/AMFLoader.js13-28 支持增材制造格式：

基于 XML 的格式
材质、颜色、ZIP 压缩
返回带彩色网格的 Group

VTK 科学可视化

VTKLoader examples/jsm/loaders/VTKLoader.js12-30 加载可视化工具包格式：

仅 POLYDATA 数据集（不支持结构化点/网格）
ASCII 和二进制编码
多边形、三角带、点数据、单元数据
法线、颜色、标量
返回 `BufferGeometry

资源管线 ​

系统架构 ​

核心基础设施 ​

格式支持矩阵 ​

glTF 加载器系统 ​

GLTFLoader 架构 ​

扩展系统 ​

配置压缩加载器 ​

FBX 加载器 ​

FBX 解析管线 ​

OBJ/MTL 加载器 ​

OBJ 解析状态机 ​

纹理加载 ​

纹理加载器层级 ​

EXR 加载器详情 ​

导出系统 ​

GLTFExporter 架构 ​

导出选项 ​

材质属性转换 ​

压缩集成 ​

压缩技术概览 ​

DRACO 网格压缩 ​

Meshopt 压缩 ​

KTX2 纹理压缩 ​

fflate 归档解压 ​

加载管理器与进度跟踪 ​

加载管理器流程 ​

缓存系统 ​

点云与体数据加载器 ​

点云格式 ​

体数据 ​

CAD 与 3D 打印格式 ​

STL 加载器 ​

3MF 加载器 ​

AMF 加载器 ​

VTK 科学可视化 ​

资源管线

系统架构

核心基础设施

格式支持矩阵

glTF 加载器系统

GLTFLoader 架构

扩展系统

配置压缩加载器

FBX 加载器

FBX 解析管线

OBJ/MTL 加载器

OBJ 解析状态机

纹理加载

纹理加载器层级

EXR 加载器详情

导出系统

GLTFExporter 架构

导出选项

材质属性转换

压缩集成

压缩技术概览

DRACO 网格压缩

Meshopt 压缩

KTX2 纹理压缩

fflate 归档解压

加载管理器与进度跟踪

加载管理器流程

缓存系统

点云与体数据加载器

点云格式

体数据

CAD 与 3D 打印格式

STL 加载器

3MF 加载器

AMF 加载器

VTK 科学可视化