gtf-threejs-loader

v1.0.1

Published

17 days ago

GTF: 3D model loader for Three.js — human-readable, awk-friendly, with vertex colors and PBR materials.

Downloads

310

0High
0Medium
0Low

wxy6987

threejs 3d loader model format gtf gmtf vertex-colors pbr material text human-readable cli awk geometry mesh

GTFLoader

Graphics Transmission Format — 一个轻量级、面向 Three.js 的 3D 模型加载器，支持材质、纹理、顶点颜色和几何数据的传输格式。

概述

GTF (Graphics Transmission Format) 是一种为 Three.js 设计的简洁 3D 数据交换格式。GTFLoader 提供了类似 Rust 编译器的 IDE 级错误诊断体验，帮助开发者快速定位和修复模型文件中的问题。

核心功能

完整的材质系统: 支持 MeshStandardMaterial 和 MeshPhysicalMaterial 的全部属性
顶点颜色支持: 每个顶点可独立定义颜色，实现平滑渐变和复杂着色效果
独立材质加载器 (GMTFLoader): GMTF (Graphics Material Transmission Format) 是 GTF 的材质子格式，GMTFLoader 可独立使用，支持 .gmtf 材质文件的加载和解析
纹理加载: 支持漫反射、法线、粗糙度、金属度、环境光遮蔽等 20 余种纹理贴图
智能错误诊断: 类似 Rust 编译器的 IDE 级错误提示，包含上下文代码行、建议修复方案
多材质支持: 一个模型可包含多个材质组，每个组使用独立的 .gmtf 文件
异步加载: 基于 Promise，支持 onProgress 回调
纹理缓存: 自动缓存已加载的纹理，避免重复加载
灵活的错误处理: 支持 throw、warn、silent 三种模式
路径解析: 支持绝对路径、相对路径和 ./ 相对路径解析

文件格式规范

GTF 主文件格式

GTF 文件包含几何数据（顶点、法线、UV）和面定义，并引用外部材质文件。文件扩展名通常为 .gtf。

命令: v (顶点)

定义三维空间中的一个顶点位置，并可选地指定顶点颜色。

语法:

v x y z
v x y z r g b

参数说明:

| 参数 | 类型 | 必需 | 描述 | |------|------|------|------| | x | 浮点数 | 是 | 顶点的 X 轴坐标 | | y | 浮点数 | 是 | 顶点的 Y 轴坐标 | | z | 浮点数 | 是 | 顶点的 Z 轴坐标 | | r | 浮点数 | 否 | 顶点颜色的红色分量，范围 [0.0, 1.0]，默认 1.0 | | g | 浮点数 | 否 | 顶点颜色的绿色分量，范围 [0.0, 1.0]，默认 1.0 | | b | 浮点数 | 否 | 顶点颜色的蓝色分量，范围 [0.0, 1.0]，默认 1.0 |

取值范围:

坐标值: 任意浮点数，无限制
颜色值: [0.0, 1.0]，超出范围会自动钳制

示例:

# 仅顶点坐标（默认颜色为白色）
v 0.0 0.0 0.0
v 1.5 -2.3 4.7

# 顶点坐标 + 顶点颜色（红色）
v -0.5 1.0 0.0 1.0 0.0 0.0

# RGB 立方体顶点
v -1.0 -1.0 -1.0 1.0 0.0 0.0
v  1.0 -1.0 -1.0 0.0 1.0 0.0
v  1.0  1.0 -1.0 0.0 0.0 1.0
v -1.0  1.0 -1.0 1.0 1.0 0.0

顶点颜色工作机制:

当 GTF 文件中任一顶点包含颜色值时，GTFLoader 会自动启用顶点颜色模式：

所有顶点数据会包含颜色信息（未指定颜色的顶点默认使用白色 1.0 1.0 1.0）
材质配置中的 vertexColors 属性会被自动设置为 true
材质会使用每个顶点的颜色进行着色，而不是使用材质的统一 color 属性

错误处理:

如果缺少坐标值（参数数量少于 3 个），GTFLoader 会报错 E100 (缺少顶点坐标)
如果坐标值不是有效的数字格式，GTFLoader 会报错 E101 (无效顶点)
如果颜色值不是有效的数字格式，GTFLoader 会报错 E006 (无效颜色值)
如果颜色值超出 [0.0, 1.0] 范围，GTFLoader 会自动钳制

命令: vn (法线)

定义顶点法线向量，用于光照计算。

语法:

vn x y z

参数说明:

| 参数 | 类型 | 必需 | 描述 | |------|------|------|------| | x | 浮点数 | 是 | 法线向量的 X 轴分量 | | y | 浮点数 | 是 | 法线向量的 Y 轴分量 | | z | 浮点数 | 是 | 法线向量的 Z 轴分量 |

取值范围: 任意浮点数，通常归一化到 [-1.0, 1.0] 之间

示例:

vn 0.0 0.0 1.0
vn 0.0 -1.0 0.0
vn 0.577 0.577 0.577

错误处理:

如果缺少分量值（参数数量少于 3 个），GTFLoader 会报错 E102 (缺少法线分量)
如果分量值不是有效的数字格式，GTFLoader 会报错 E103 (无效法线)
如果提供了超过 3 个分量值，GTFLoader 会报错 E103 (无效法线)

命令: vt (UV 纹理坐标)

定义纹理映射的 UV 坐标。

语法:

vt u v

参数说明:

| 参数 | 类型 | 必需 | 描述 | |------|------|------|------| | u | 浮点数 | 是 | 纹理坐标的水平分量，通常范围 [0.0, 1.0] | | v | 浮点数 | 是 | 纹理坐标的垂直分量，通常范围 [0.0, 1.0] |

取值范围: 任意浮点数，通常为 0.0 到 1.0，超过范围会导致纹理重复或拉伸

示例:

vt 0.0 0.0
vt 1.0 0.0
vt 0.5 0.5
vt 1.0 1.0

错误处理:

如果缺少坐标值（参数数量少于 2 个），GTFLoader 会报错 E104 (缺少 UV 坐标)
如果坐标值不是有效的数字格式，GTFLoader 会报错 E105 (无效 UV)
如果提供了超过 2 个坐标值，GTFLoader 会报错 E105 (无效 UV)

命令: f (面)

定义三角形面，由三个顶点组成。支持为每个顶点分别指定 UV 和法线索引。

语法:

f v1/vt1/vn1 v2/vt2/vn2 v3/vt3/vn3 [texIndex]

参数说明:

| 参数 | 类型 | 必需 | 描述 | |------|------|------|------| | v1, v2, v3 | 整数 | 是 | 顶点索引，对应 v 命令定义的顶点，从 0 开始 | | vt1, vt2, vt3 | 整数 | 否 | UV 索引，对应 vt 命令定义的 UV，从 0 开始 | | vn1, vn2, vn3 | 整数 | 否 | 法线索引，对应 vn 命令定义的法线，从 0 开始 | | texIndex | 整数 | 否 | 材质索引，对应 m 命令定义的材质顺序，从 0 开始 |

顶点引用格式:

| 格式 | 描述 | 示例 | |------|------|------| | v | 仅顶点索引 | f 0 1 2 | | v/vt | 顶点和 UV 索引 | f 0/0 1/1 2/2 | | v/vt/vn | 顶点、UV 和法线索引 | f 0/0/0 1/1/0 2/2/0 | | v//vn | 顶点和法线索引（UV 为空） | f 0//0 1//0 2//0 |

示例:

# 仅顶点
f 0 1 2

# 顶点和 UV
f 0/0 1/1 2/2

# 顶点、UV 和法线（完整格式）
f 0/0/0 1/1/0 2/2/0

# 顶点和法线（省略 UV）
f 0//0 1//0 2//0

# 指定材质索引
f 0/0/0 1/1/0 2/2/0 1

错误处理:

如果面定义的顶点少于 3 个，GTFLoader 会报错 E106 (无效面)
如果顶点索引不是非负整数，GTFLoader 会报错 E107 (无效索引)
如果顶点索引超出已定义顶点的数量，GTFLoader 会报错 E108 (索引超出范围)
如果 UV 索引超出已定义 UV 的数量，GTFLoader 会报错 E108 (索引超出范围)
如果法线索引超出已定义法线的数量，GTFLoader 会报错 E108 (索引超出范围)

命令: m (材质)

引用外部材质文件 (.gmtf)。材质文件定义了表面颜色、纹理、粗糙度等属性。

语法:

m path/to/material.gmtf

参数说明:

| 参数 | 类型 | 必需 | 描述 | |------|------|------|------| | path | 字符串 | 是 | 材质文件的路径，支持相对路径、绝对路径和 URL |

路径解析规则:

| 路径格式 | 解析方式 | 示例 | |----------|----------|------| | 以 http:// 或 https:// 开头 | 直接作为 URL 加载 | m https://example.com/mat.gmtf | | 以 / 开头 | 从项目根目录加载 | m /assets/mat.gmtf → assets/mat.gmtf | | 以 ./ 开头 | 相对于当前 GTF 文件所在目录 | m ./materials/mat.gmtf | | 其他 | 相对于基础路径（通过 setPath 设置） | m materials/mat.gmtf |

示例:

# 相对路径
m materials/wood.gmtf
m ./materials/metal.gmtf

# 绝对路径
m /assets/materials/glass.gmtf

# URL
m https://cdn.example.com/materials/plastic.gmtf

错误处理:

如果未提供路径参数，GTFLoader 会报错 E201 (空路径)
如果路径为空字符串，GTFLoader 会报错 E201 (空路径)
如果材质文件不存在或加载失败，GTFLoader 会使用默认材质配置并输出警告

重要说明: m 命令必须出现在使用该材质的 f 命令之前。一个 GTF 文件可以包含多个 m 命令，每个命令对应一个材质索引（从 0 开始）。

GMTF 材质文件格式

GMTF (Graphics Material Transmission Format) 是 GTF 的材质子格式，文件扩展名通常为 .gmtf。材质文件定义表面的视觉属性，包括颜色、纹理和渲染设置。文件采用键值对格式，每行一个属性。

纹理贴图属性

纹理贴图属性指定外部图像文件作为纹理。

语法:

propertyName /path/to/texture.png

参数说明:

| 参数 | 类型 | 必需 | 描述 | |------|------|------|------| | propertyName | 字符串 | 是 | 纹理属性名称（见下方列表） | | path | 字符串 | 是 | 图像文件的路径 |

支持的纹理属性:

| 属性名 | 描述 | Three.js 对应属性 | |--------|------|-------------------| | map | 漫反射贴图 | map | | roughnessMap | 粗糙度贴图 | roughnessMap | | metalnessMap | 金属度贴图 | metalnessMap | | normalMap | 法线贴图 | normalMap | | aoMap | 环境光遮蔽贴图 | aoMap | | emissiveMap | 自发光贴图 | emissiveMap | | displacementMap | 置换贴图 | displacementMap | | alphaMap | 透明度贴图 | alphaMap | | bumpMap | 凹凸贴图 | bumpMap | | clearcoatMap | 清漆层贴图 (Physical) | clearcoatMap | | clearcoatRoughnessMap | 清漆粗糙度贴图 (Physical) | clearcoatRoughnessMap | | clearcoatNormalMap | 清漆法线贴图 (Physical) | clearcoatNormalMap | | transmissionMap | 透射贴图 (Physical) | transmissionMap | | thicknessMap | 厚度贴图 (Physical) | thicknessMap | | specularColorMap | 高光颜色贴图 (Physical) | specularColorMap | | specularIntensityMap | 高光强度贴图 (Physical) | specularIntensityMap | | sheenColorMap | 丝绒颜色贴图 (Physical) | sheenColorMap | | sheenRoughnessMap | 丝绒粗糙度贴图 (Physical) | sheenRoughnessMap | | iridescenceMap | 虹彩贴图 (Physical) | iridescenceMap | | iridescenceThicknessMap | 虹彩厚度贴图 (Physical) | iridescenceThicknessMap |

示例:

map textures/diffuse.png
roughnessMap textures/roughness.png
normalMap textures/normal.png
aoMap textures/ao.png

错误处理:

如果未提供路径，GMTFLoader 会报错 E005 (缺少纹理路径)
如果纹理加载失败，GMTFLoader 会输出警告并继续使用默认值

颜色属性

颜色属性定义材质的颜色值，使用 RGB 三个分量表示。

语法:

propertyName r g b

参数说明:

| 参数 | 类型 | 必需 | 描述 | |------|------|------|------| | propertyName | 字符串 | 是 | 颜色属性名称（见下方列表） | | r | 浮点数 | 是 | 红色分量，范围 [0.0, 1.0] | | g | 浮点数 | 是 | 绿色分量，范围 [0.0, 1.0] | | b | 浮点数 | 是 | 蓝色分量，范围 [0.0, 1.0] |

支持的颜色属性:

| 属性名 | 描述 | Three.js 对应属性 | |--------|------|-------------------| | color | 漫反射颜色 | color | | emissive | 自发光颜色 | emissive | | specularColor | 高光颜色 (Physical) | specularColor | | sheenColor | 丝绒颜色 (Physical) | sheenColor |

示例:

# 红色
color 1.0 0.0 0.0

# 暖黄色
color 0.8 0.6 0.4

# 深蓝色
emissive 0.0 0.0 0.5

错误处理:

如果缺少颜色分量（参数少于 3 个），GMTFLoader 会报错 E001 (缺少值)
如果颜色分量不是有效的数字，GMTFLoader 会报错 E006 (无效颜色值)
如果颜色分量超出 [0.0, 1.0] 范围，GMTFLoader 会自动钳制到有效范围

数值属性

数值属性定义材质的标量参数。

语法:

propertyName value

参数说明:

| 参数 | 类型 | 必需 | 描述 | |------|------|------|------| | propertyName | 字符串 | 是 | 数值属性名称（见下方列表） | | value | 浮点数 | 是 | 属性值，具体范围见下方说明 |

支持的数值属性:

| 属性名 | 取值范围 | 默认值 | 描述 | |--------|----------|--------|------| | roughness | [0.0, 1.0] | 0.6 | 表面粗糙度 | | metalness | [0.0, 1.0] | 0.0 | 金属度 | | opacity | [0.0, 1.0] | 1.0 | 不透明度 | | emissiveIntensity | [0.0, ∞) | 1.0 | 自发光强度 | | aoMapIntensity | [0.0, 1.0] | 1.0 | 环境光遮蔽强度 | | displacementScale | [0.0, ∞) | 1.0 | 置换贴图缩放系数 | | bumpScale | [0.0, ∞) | 1.0 | 凹凸贴图缩放系数 | | normalScale | [0.0, ∞) | 1.0 | 法线贴图缩放系数 | | clearcoat | [0.0, 1.0] | 0.0 | 清漆层强度 (Physical) | | clearcoatRoughness | [0.0, 1.0] | 0.0 | 清漆层粗糙度 (Physical) | | transmission | [0.0, 1.0] | 0.0 | 透射强度 (Physical) | | thickness | [0.0, ∞) | 0.0 | 厚度值 (Physical) | | ior | [1.0, ∞) | 1.5 | 折射率 (Physical) | | envMapIntensity | [0.0, ∞) | 1.0 | 环境贴图强度 (Physical) | | specularIntensity | [0.0, 1.0] | 0.0 | 高光强度 (Physical) | | sheenRoughness | [0.0, 1.0] | 0.0 | 丝绒粗糙度 (Physical) | | iridescence | [0.0, 1.0] | 0.0 | 虹彩强度 (Physical) | | iridescenceThickness | [0.0, ∞) | 0.0 | 虹彩厚度 (Physical) |

示例:

roughness 0.7
metalness 0.0
opacity 0.8
emissiveIntensity 1.5
clearcoat 0.5
transmission 0.3
ior 1.45

错误处理:

如果缺少值（参数少于 2 个），GMTFLoader 会报错 E001 (缺少值)
如果值不是有效的数字，GMTFLoader 会报错 E002 (类型不匹配)
如果值超出范围，GMTFLoader 会报错 E003 (值超出范围)

渲染设置属性

渲染设置属性控制材质的渲染行为。

语法:

propertyName value

参数说明:

| 参数 | 类型 | 必需 | 描述 | |------|------|------|------| | propertyName | 字符串 | 是 | 渲染设置属性名称（见下方列表） | | value | 字符串/布尔值 | 是 | 属性值，具体类型见下方说明 |

支持的渲染设置属性:

| 属性名 | 值类型 | 可选值 | 默认值 | 描述 | |--------|--------|--------|--------|------| | side | 字符串 | front, back, double | double | 控制渲染哪些面 | | flatShading | 布尔值 | true, false | false | 是否使用平面着色 | | wireframe | 布尔值 | true, false | false | 是否以线框模式渲染 | | textSmt | 布尔值 | true, false | true | 是否对纹理进行平滑插值 |

示例:

side front
flatShading true
wireframe false
textSmt true

错误处理:

如果缺少值，GMTFLoader 会报错 E001 (缺少值)
如果值不是有效选项，GMTFLoader 会报错 E007 (无效枚举值) 或 E002 (类型不匹配)

安装

使用 NPM

npm install gtf-loader

使用 CDN

<script type="importmap">
{
  "imports": {
    "gtf-loader": "https://cdn.jsdelivr.net/npm/gtf-loader/dist/GTFLoader.js"
  }
}
</script>

手动引入

import { GTFLoader } from './path/to/GTFLoader.js';

使用指南

基础用法

加载一个 GTF 模型文件并将其添加到场景中。

import * as THREE from 'three';
import { GTFLoader } from 'gtf-loader';

// 创建场景
const scene = new THREE.Scene();
const camera = new THREE.PerspectiveCamera(75, window.innerWidth / window.innerHeight, 0.1, 1000);
const renderer = new THREE.WebGLRenderer();

// 创建加载器
const loader = new GTFLoader();

// 加载模型
loader.load(
    'models/cube.gtf',
    (group) => {
        // 加载成功，将模型添加到场景
        scene.add(group);
        console.log('模型加载成功');
    },
    (xhr) => {
        // 加载进度
        const progress = (xhr.loaded / xhr.total * 100).toFixed(2);
        console.log(`加载进度: ${progress}%`);
    },
    (error) => {
        // 加载失败
        console.error('加载失败:', error);
    }
);

使用异步加载

import { GTFLoader } from 'gtf-loader';

const loader = new GTFLoader();

async function loadModel() {
    try {
        // 使用 loadAsync 方法
        const group = await loader.loadAsync('models/cube.gtf');
        scene.add(group);
        return group;
    } catch (error) {
        console.error('加载失败:', error);
        throw error;
    }
}

loadModel();

使用物理材质

GTFLoader 默认使用 MeshStandardMaterial。启用物理材质可以使用更多的视觉效果，如清漆、透射、虹彩等。

import { GTFLoader } from 'gtf-loader';

const loader = new GTFLoader();

// 启用物理材质
loader.setUsePhysicalMaterial(true);

loader.load('models/glass.gtf', (group) => {
    scene.add(group);
});

注意: 物理材质会使用 MeshPhysicalMaterial，支持以下高级效果：

清漆层 (clearcoat)
透射/透明度 (transmission)
高光颜色 (specularColor)
丝绒效果 (sheen)
虹彩效果 (iridescence)

顶点颜色支持

GTFLoader 支持每个顶点独立定义颜色，实现平滑渐变和复杂着色效果。

顶点颜色文件格式

在 GTF 文件中，v 命令可以包含可选的 RGB 颜色值：

# 格式: v x y z [r g b]
v -1.0 -1.0 0.0 1.0 0.0 0.0    # 红色
v  1.0 -1.0 0.0 0.0 1.0 0.0    # 绿色
v  0.0  1.0 0.0 0.0 0.0 1.0    # 蓝色

使用顶点颜色的 GTF 文件示例

# 带顶点颜色的渐变三角形
v -1.0 -1.0 0.0 1.0 0.0 0.0
v  1.0 -1.0 0.0 0.0 1.0 0.0
v  0.0  1.0 0.0 0.0 0.0 1.0
f 0 1 2

# 混合顶点颜色和纹理
v -1.0 -1.0 0.0 1.0 0.5 0.0
v  1.0 -1.0 0.0 0.0 1.0 0.5
v  1.0  1.0 0.0 0.5 0.0 1.0
v -1.0  1.0 0.0 1.0 1.0 0.0
vt 0.0 0.0
vt 1.0 0.0
vt 1.0 1.0
vt 0.0 1.0
f 0/0 1/1 2/2
f 0/0 2/2 3/3

在代码中加载带顶点颜色的模型

import { GTFLoader } from 'gtf-loader';

const loader = new GTFLoader();

// 加载带顶点颜色的 GTF 文件
loader.load('models/colorful_triangle.gtf', (group) => {
    // 自动检测顶点颜色并启用 vertexColors
    group.children.forEach(child => {
        if (child.isMesh) {
            // 材质的 vertexColors 已自动设置为 true
            console.log(child.material.vertexColors); // true
        }
    });
    scene.add(group);
});

顶点颜色与材质颜色混合

当顶点颜色启用时，材质属性中的 color 值不会被使用。顶点颜色会完全覆盖材质的漫反射颜色。

# 此文件中的 color 设置将被忽略（因为顶点颜色已启用）
color 0.0 0.0 1.0

混合顶点颜色与纹理

顶点颜色可以与纹理贴图叠加使用。Three.js 默认使用 Multiply 混合模式，即顶点颜色与纹理颜色相乘。

# 顶点颜色与纹理混合
map textures/diffuse.png

顶点颜色性能考虑

顶点颜色会增加几何数据的内存占用（每个顶点增加 3 个浮点数）
对于大型模型，建议仅在需要颜色渐变效果时使用
如果所有顶点颜色相同，建议使用材质的 color 属性替代

错误处理模式

GTFLoader 提供三种错误处理模式，适应不同的开发场景。

import { GTFLoader } from 'gtf-loader';

const loader = new GTFLoader();

// 模式 1: throw (默认)
// 遇到错误时抛出异常，适合开发调试
loader.setErrorMode('throw');

// 模式 2: warn
// 遇到错误时输出警告并继续执行，使用默认值替代
loader.setErrorMode('warn');

// 模式 3: silent
// 静默处理错误，使用默认值替代，不输出任何信息
loader.setErrorMode('silent');

// 检查是否发生过错误
loader.clearErrors(); // 清除错误列表
if (loader.hasError()) {
    const errors = loader.getErrors();
    errors.forEach(err => {
        // err 是 GTFParseError 实例
        console.error(err.toString());
    });
}

三种模式对比:

| 模式 | 错误抛出 | 输出日志 | 使用默认值 | 适用场景 | |------|----------|----------|------------|----------| | throw | 是 | 是 | 否 | 开发调试 | | warn | 否 | 是 | 是 | 生产环境（需监控） | | silent | 否 | 否 | 是 | 生产环境（无需监控） |

加载外部材质

GTF 文件通过 m 命令引用外部材质文件。GTFLoader 会自动使用 GMTFLoader 解析路径并加载材质。

# GTF 文件示例
m materials/wood.gmtf
m ./materials/metal.gmtf
m /assets/materials/glass.gmtf
m https://cdn.example.com/materials/plastic.gmtf

材质文件加载逻辑：

import { GTFLoader } from 'gtf-loader';

const loader = new GTFLoader();

// 设置基础路径（可选）
// 相对路径会基于此路径解析
loader.setPath('/assets/');

// 加载 GTF 文件
loader.load('models/scene.gtf', (group) => {
    // 所有引用的材质文件会自动加载
    scene.add(group);
});

多材质模型

一个 GTF 文件可以包含多个材质组，每个材质组使用独立的材质文件。

# 材质组 0 - 红色金属材质
m materials/red_metal.gmtf

# 使用材质组 0 的面
f 0/0/0 1/1/0 2/2/0 0
f 3/0/0 4/1/0 5/2/0 0

# 材质组 1 - 蓝色塑料材质
m materials/blue_plastic.gmtf

# 使用材质组 1 的面
f 6/0/0 7/1/0 8/2/0 1
f 9/0/0 10/1/0 11/2/0 1

材质索引 texIndex 从 0 开始，对应 m 命令出现的顺序。

独立使用 GMTFLoader

GMTFLoader 可以独立于 GTFLoader 使用，适合只需要材质加载功能的场景。

import * as THREE from 'three';
import { GMTFLoader } from 'gtf-loader';

// 创建独立的材质加载器
const gmtfLoader = new GMTFLoader();

// 设置错误处理模式
gmtfLoader.setErrorMode('warn');

// 启用物理材质（可选）
gmtfLoader.setUsePhysicalMaterial(true);

// 加载材质文件
const config = await gmtfLoader.loadGMTF('materials/wood.gmtf', '/assets/');

// 加载纹理
const textures = await gmtfLoader.loadTexturesForConfig(config, '/assets/');

// 创建材质
const material = gmtfLoader.createMaterial(config, textures);

// 应用到网格
const mesh = new THREE.Mesh(geometry, material);

GMTFLoader 的纹理缓存

GMTFLoader 内置纹理缓存机制，相同路径的纹理只会加载一次：

const gmtfLoader = new GMTFLoader();

// 第一次加载纹理 - 实际加载
const tex1 = await gmtfLoader.loadTexture('textures/diffuse.png');

// 第二次加载相同纹理 - 从缓存返回
const tex2 = await gmtfLoader.loadTexture('textures/diffuse.png');

// tex1 === tex2 (同一个纹理对象)

GMTFLoader 的错误收集

const gmtfLoader = new GMTFLoader();
gmtfLoader.setErrorMode('warn');

await gmtfLoader.loadGMTF('invalid.gmtf');

// 检查是否有错误
if (gmtfLoader.hasError()) {
    const errors = gmtfLoader.getErrors();
    errors.forEach(err => {
        console.error(err.code, err.message);
        // 可以获取 HTML 格式的错误信息用于 UI 显示
        console.log(err.formattedHtmlMessage);
    });
}

API 参考

GTFLoader 类

GTFLoader 是主要的加载器类，负责解析 GTF 文件、加载材质和纹理、构建 Three.js 对象。

构造函数

new GTFLoader(manager?: THREE.LoadingManager)

参数:

| 参数 | 类型 | 可选 | 默认值 | 描述 | |------|------|------|--------|------| | manager | THREE.LoadingManager | 是 | 新的 LoadingManager 实例 | Three.js 加载管理器 |

方法

setErrorMode

设置错误处理模式。

setErrorMode(mode: 'throw' | 'warn' | 'silent'): this

参数:

| 参数 | 类型 | 描述 | |------|------|------| | mode | 'throw' | 'warn' | 'silent' | 错误处理模式 |

返回值: 返回 this，支持链式调用

setUsePhysicalMaterial

启用或禁用物理材质 (MeshPhysicalMaterial)。

setUsePhysicalMaterial(use: boolean): this

参数:

| 参数 | 类型 | 描述 | |------|------|------| | use | boolean | true 启用 MeshPhysicalMaterial，false 使用 MeshStandardMaterial |

返回值: 返回 this，支持链式调用

setPath

设置基础路径，用于解析相对路径。

setPath(path: string): this

参数:

| 参数 | 类型 | 描述 | |------|------|------| | path | string | 基础路径，通常以 / 结尾 |

返回值: 返回 this，支持链式调用

getErrors

获取所有已记录的错误列表。

getErrors(): GTFParseError[]

返回值: GTFParseError 数组

clearErrors

清除所有已记录的错误。

clearErrors(): void

hasError

检查是否发生过错误。

hasError(): boolean

返回值: true 表示发生过错误，false 表示没有错误

load

加载 GTF 文件。

load(
    url: string,
    onLoad?: (group: THREE.Group) => void,
    onProgress?: (xhr: XMLHttpRequest) => void,
    onError?: (error: Error) => void
): void

参数:

| 参数 | 类型 | 可选 | 描述 | |------|------|------|------| | url | string | 否 | GTF 文件的路径 | | onLoad | (group: THREE.Group) => void | 是 | 加载成功回调，返回 THREE.Group | | onProgress | (xhr: XMLHttpRequest) => void | 是 | 加载进度回调 | | onError | (error: Error) => void | 是 | 加载失败回调 |

loadAsync

以 Promise 方式加载 GTF 文件。

loadAsync(url: string): Promise<THREE.Group>

参数:

| 参数 | 类型 | 描述 | |------|------|------| | url | string | GTF 文件的路径 |

返回值: Promise，解析为 THREE.Group

GMTFLoader 类

GMTFLoader (Graphics Material Transmission Format Loader) 是 GTFLoader 的材质加载子模块，专门负责加载 .gmtf 材质文件。它独立于主加载器，也可以单独使用。

构造函数

new GMTFLoader(manager?: THREE.LoadingManager)

参数:

| 参数 | 类型 | 可选 | 默认值 | 描述 | |------|------|------|--------|------| | manager | THREE.LoadingManager | 是 | 新的 LoadingManager 实例 | Three.js 加载管理器 |

方法

setErrorMode

设置错误处理模式。

setErrorMode(mode: 'throw' | 'warn' | 'silent'): this

参数:

| 参数 | 类型 | 描述 | |------|------|------| | mode | 'throw' | 'warn' | 'silent' | 错误处理模式 |

返回值: 返回 this，支持链式调用

setUsePhysicalMaterial

启用或禁用物理材质 (MeshPhysicalMaterial)。

setUsePhysicalMaterial(use: boolean): this

参数:

| 参数 | 类型 | 描述 | |------|------|------| | use | boolean | true 启用 MeshPhysicalMaterial，false 使用 MeshStandardMaterial |

返回值: 返回 this，支持链式调用

setParentLoader

设置父加载器，用于错误处理共享。

setParentLoader(parent: GTFLoader): this

参数:

| 参数 | 类型 | 描述 | |------|------|------| | parent | GTFLoader | 父加载器实例 |

返回值: 返回 this，支持链式调用

getErrors

获取所有已记录的错误列表。

getErrors(): GTFParseError[]

返回值: GTFParseError 数组

clearErrors

清除所有已记录的错误。

clearErrors(): void

hasError

检查是否发生过错误。

hasError(): boolean

返回值: true 表示发生过错误，false 表示没有错误

loadGMTF

加载 GMTF 材质文件。

loadGMTF(path: string, contextPath?: string): Promise<object>

参数:

| 参数 | 类型 | 可选 | 描述 | |------|------|------|------| | path | string | 否 | GMTF 文件的路径 | | contextPath | string | 是 | 上下文路径，用于解析相对路径 |

返回值: Promise，解析为材质配置对象

示例:

const config = await gmtfLoader.loadGMTF('materials/wood.gmtf', '/models/');

loadTexture

加载纹理图像。

loadTexture(
    path: string,
    contextPath?: string,
    smooth?: boolean
): Promise<THREE.Texture | null>

参数:

| 参数 | 类型 | 可选 | 默认值 | 描述 | |------|------|------|--------|------| | path | string | 否 | - | 纹理图像的路径 | | contextPath | string | 是 | undefined | 上下文路径，用于解析相对路径 | | smooth | boolean | 是 | true | 是否启用平滑插值 |

返回值: Promise，解析为 THREE.Texture 或 null（加载失败时）

loadTexturesForConfig

为配置对象加载所有纹理。

loadTexturesForConfig(config: object, contextPath?: string): Promise<object>

参数:

| 参数 | 类型 | 可选 | 描述 | |------|------|------|------| | config | object | 否 | 材质配置对象（由 loadGMTF 返回） | | contextPath | string | 是 | 上下文路径，用于解析相对路径 |

返回值: Promise，解析为纹理映射对象

示例:

const config = await gmtfLoader.loadGMTF('materials/wood.gmtf');
const textures = await gmtfLoader.loadTexturesForConfig(config, '/models/');
// textures.map, textures.normalMap, etc.

createMaterial

根据配置和纹理创建 Three.js 材质。

createMaterial(
    config: object,
    textures: object,
    group?: { texIndex?: number }
): THREE.Material

参数:

| 参数 | 类型 | 可选 | 描述 | |------|------|------|------| | config | object | 否 | 材质配置对象（由 loadGMTF 返回） | | textures | object | 否 | 纹理映射对象（由 loadTexturesForConfig 返回） | | group | object | 是 | 组对象，包含 texIndex 用于生成默认颜色 |

返回值: THREE.MeshStandardMaterial 或 THREE.MeshPhysicalMaterial

示例:

const config = await gmtfLoader.loadGMTF('materials/wood.gmtf');
const textures = await gmtfLoader.loadTexturesForConfig(config);
const material = gmtfLoader.createMaterial(config, textures);

resolvePath

解析纹理或材质路径。

resolvePath(path: string, contextPath?: string): string | null

参数:

| 参数 | 类型 | 可选 | 描述 | |------|------|------|------| | path | string | 否 | 原始路径 | | contextPath | string | 是 | 上下文路径 |

返回值: 解析后的路径或 null

GTFParseError 类

GTFParseError 是自定义错误类，提供详细的错误信息和 IDE 级别的诊断输出。

构造函数

new GTFParseError({
    code: string,
    message: string,
    line?: number,
    lineContent?: string,
    errorStart?: number,
    errorLength?: number,
    correctFormat?: string,
    filename?: string,
    contextLines?: Array<{lineNum: number, content: string}>,
    note?: string | null,
    suggestion?: {
        message: string,
        code: string,
        additions?: { indent: number, length: number }
    } | null
})

参数说明:

| 参数 | 类型 | 描述 | |------|------|------| | code | string | 错误码，如 'E001' | | message | string | 错误描述信息 | | line | number | 错误所在行号（从 1 开始） | | lineContent | string | 错误行的内容 | | errorStart | number | 错误在行中的起始位置（从 0 开始） | | errorLength | number | 错误的长度（字符数） | | correctFormat | string | 正确的格式示例 | | filename | string | 发生错误的文件名 | | contextLines | Array | 上下文代码行数组 | | note | string | null | 附加说明 | | suggestion | object | null | 修复建议 |

属性

| 属性 | 类型 | 描述 | |------|------|------| | code | string | 错误码 | | message | string | 错误信息 | | line | number | 错误行号 | | lineContent | string | 错误行内容 | | errorStart | number | 错误起始位置 | | errorLength | number | 错误长度 | | filename | string | 文件名 | | contextLines | Array | 上下文行 | | note | string | null | 附加说明 | | suggestion | object | null | 修复建议 | | formattedMessage | string | 格式化后的文本错误信息 | | formattedHtmlMessage | string | 格式化后的 HTML 错误信息 |

方法

toString

返回格式化后的文本错误信息。

toString(): string

escapeHtml

转义 HTML 特殊字符。

escapeHtml(text: string): string

ERROR_CODES 常量

错误码常量定义，用于标识不同类型的错误。

const ERROR_CODES = {
    // 材质错误 (E001-E099)
    MISSING_VALUE: 'E001',
    INVALID_TYPE: 'E002',
    OUT_OF_RANGE: 'E003',
    UNKNOWN_PROPERTY: 'E004',
    MISSING_TEXTURE: 'E005',
    INVALID_COLOR: 'E006',
    INVALID_ENUM: 'E007',
    
    // 几何错误 (E100-E199)
    MISSING_VERTEX: 'E100',
    INVALID_VERTEX: 'E101',
    MISSING_NORMAL: 'E102',
    INVALID_NORMAL: 'E103',
    MISSING_UV: 'E104',
    INVALID_UV: 'E105',
    INVALID_FACE: 'E106',
    INVALID_INDEX: 'E107',
    INDEX_OUT_OF_RANGE: 'E108',
    UNKNOWN_COMMAND: 'E109',
    
    // 文件错误 (E200-E299)
    FILE_NOT_FOUND: 'E200',
    EMPTY_PATH: 'E201',
};

支持的材质属性

纹理贴图

纹理贴图属性使用图像文件路径作为值。

| 属性名 | 描述 | Three.js 属性 | 物理材质支持 | |--------|------|---------------|--------------| | map | 漫反射贴图 | map | 是 | | roughnessMap | 粗糙度贴图 | roughnessMap | 是 | | metalnessMap | 金属度贴图 | metalnessMap | 是 | | normalMap | 法线贴图 | normalMap | 是 | | aoMap | 环境光遮蔽贴图 | aoMap | 是 | | emissiveMap | 自发光贴图 | emissiveMap | 是 | | displacementMap | 置换贴图 | displacementMap | 是 | | alphaMap | 透明度贴图 | alphaMap | 是 | | bumpMap | 凹凸贴图 | bumpMap | 是 | | clearcoatMap | 清漆层贴图 | clearcoatMap | 仅物理材质 | | clearcoatRoughnessMap | 清漆粗糙度贴图 | clearcoatRoughnessMap | 仅物理材质 | | clearcoatNormalMap | 清漆法线贴图 | clearcoatNormalMap | 仅物理材质 | | transmissionMap | 透射贴图 | transmissionMap | 仅物理材质 | | thicknessMap | 厚度贴图 | thicknessMap | 仅物理材质 | | specularColorMap | 高光颜色贴图 | specularColorMap | 仅物理材质 | | specularIntensityMap | 高光强度贴图 | specularIntensityMap | 仅物理材质 | | sheenColorMap | 丝绒颜色贴图 | sheenColorMap | 仅物理材质 | | sheenRoughnessMap | 丝绒粗糙度贴图 | sheenRoughnessMap | 仅物理材质 | | iridescenceMap | 虹彩贴图 | iridescenceMap | 仅物理材质 | | iridescenceThicknessMap | 虹彩厚度贴图 | iridescenceThicknessMap | 仅物理材质 |

颜色属性

颜色属性使用三个 RGB 分量，范围 0.0 到 1.0。

| 属性名 | 描述 | Three.js 属性 | 物理材质支持 | |--------|------|---------------|--------------| | color | 漫反射颜色 | color | 是 | | emissive | 自发光颜色 | emissive | 是 | | specularColor | 高光颜色 | specularColor | 仅物理材质 | | sheenColor | 丝绒颜色 | sheenColor | 仅物理材质 |

数值属性

数值属性使用浮点数作为值。

| 属性名 | 范围 | 默认值 | 描述 | 物理材质支持 | |--------|------|--------|------|--------------| | roughness | [0.0, 1.0] | 0.6 | 粗糙度 | 是 | | metalness | [0.0, 1.0] | 0.0 | 金属度 | 是 | | opacity | [0.0, 1.0] | 1.0 | 不透明度 | 是 | | emissiveIntensity | [0.0, ∞) | 1.0 | 自发光强度 | 是 | | aoMapIntensity | [0.0, 1.0] | 1.0 | AO 强度 | 是 | | displacementScale | [0.0, ∞) | 1.0 | 置换缩放 | 是 | | bumpScale | [0.0, ∞) | 1.0 | 凹凸缩放 | 是 | | normalScale | [0.0, ∞) | 1.0 | 法线缩放 | 是 | | clearcoat | [0.0, 1.0] | 0.0 | 清漆强度 | 仅物理材质 | | clearcoatRoughness | [0.0, 1.0] | 0.0 | 清漆粗糙度 | 仅物理材质 | | transmission | [0.0, 1.0] | 0.0 | 透射强度 | 仅物理材质 | | thickness | [0.0, ∞) | 0.0 | 厚度 | 仅物理材质 | | ior | [1.0, ∞) | 1.5 | 折射率 | 仅物理材质 | | envMapIntensity | [0.0, ∞) | 1.0 | 环境贴图强度 | 仅物理材质 | | specularIntensity | [0.0, 1.0] | 0.0 | 高光强度 | 仅物理材质 | | sheenRoughness | [0.0, 1.0] | 0.0 | 丝绒粗糙度 | 仅物理材质 | | iridescence | [0.0, 1.0] | 0.0 | 虹彩强度 | 仅物理材质 | | iridescenceThickness | [0.0, ∞) | 0.0 | 虹彩厚度 | 仅物理材质 |

渲染设置

渲染设置属性控制材质的渲染行为。

| 属性名 | 值类型 | 可选值 | 默认值 | 描述 | |--------|--------|--------|--------|------| | side | 字符串 | front, back, double | double | 渲染面选择 | | flatShading | 布尔值 | true, false | false | 平面着色 | | wireframe | 布尔值 | true, false | false | 线框模式 | | textSmt | 布尔值 | true, false | true | 纹理平滑插值 |

错误诊断系统

GTFLoader 提供类似 Rust 编译器的详细错误信息，包含错误码、位置、上下文和修复建议。

错误码列表

材质错误 (E001-E099)

| 错误码 | 常量名 | 描述 | |--------|--------|------| | E001 | MISSING_VALUE | 缺少必要的值 | | E002 | INVALID_TYPE | 类型不匹配 | | E003 | OUT_OF_RANGE | 值超出允许范围 | | E004 | UNKNOWN_PROPERTY | 未知的属性名 | | E005 | MISSING_TEXTURE | 缺少纹理路径 | | E006 | INVALID_COLOR | 无效的颜色值 | | E007 | INVALID_ENUM | 无效的枚举值 |

几何错误 (E100-E199)

| 错误码 | 常量名 | 描述 | |--------|--------|------| | E100 | MISSING_VERTEX | 缺少顶点坐标 | | E101 | INVALID_VERTEX | 无效的顶点数据 | | E102 | MISSING_NORMAL | 缺少法线分量 | | E103 | INVALID_NORMAL | 无效的法线数据 | | E104 | MISSING_UV | 缺少 UV 坐标 | | E105 | INVALID_UV | 无效的 UV 数据 | | E106 | INVALID_FACE | 无效的面定义 | | E107 | INVALID_INDEX | 无效的索引值 | | E108 | INDEX_OUT_OF_RANGE | 索引超出范围 | | E109 | UNKNOWN_COMMAND | 未知的命令 |

文件错误 (E200-E299)

| 错误码 | 常量名 | 描述 | |--------|--------|------| | E200 | FILE_NOT_FOUND | 文件未找到 | | E201 | EMPTY_PATH | 空路径 |

错误输出示例

缺少属性值

error[E001]: Missing value for "roughness" in "model.gmtf"
  --> model.gmtf:42:15
   |
42 | roughness 
   |         +++ Missing value for "roughness"
   |
   = note: roughness expects a value in the range 0.0-1.0
help: provide a value between 0.0 and 1.0
   |
   | roughness 0.5
   |         +++

类型不匹配

error[E002]: mismatched types: expected f32, found "abc" in "model.gmtf"
  --> model.gmtf:45:12
   |
45 | roughness abc
   |            ^^^ expected f32
   |
help: use a numeric value between 0.0 and 1.0
   |
   | roughness 0.5
   |
   = note: roughness expects a number in the range 0.0-1.0

未知属性

error[E004]: Unknown material property "colr" in "material.gmtf"
  --> material.gmtf:1:1
   |
 1 | colr 1.0 0.0 0.0
   | ^^^^ unknown property
   |
help: did you mean "color"?
   |
   | color 1.0 0.0 0.0
   |
   = note: Valid properties: map, roughnessMap, metalnessMap, ...

索引超出范围

error[E108]: Vertex index 10 out of range (8 vertices defined) in "model.gtf"
  --> model.gtf:30:5
   |
30 | f 10/0/0 1/1/0 2/2/0
   |   ^^ index out of range
   |
help: use a valid vertex index between 0 and 7
   |
   | f 0 1 2
   |
   = note: this error occurred while processing face data

顶点颜色格式错误

error[E006]: Invalid vertex color "2.5" in "model.gtf"
  --> model.gtf:5:24
   |
 5 | v 0.0 0.0 0.0 1.0 2.5 0.0
   |                        ^^^ color value must be between 0.0 and 1.0
   |
help: use a numeric floating-point value between 0.0 and 1.0
   |
   | v 0.0 0.0 0.0 1.0 0.5 0.0
   |
   = note: vertex colors must be numbers between 0.0 and 1.0

最佳实践

文件组织结构

建议按照以下结构组织项目文件：

project/
├── assets/
│   ├── models/
│   │   ├── scene.gtf
│   │   └── objects/
│   │       ├── cube.gtf
│   │       └── sphere.gtf
│   ├── materials/
│   │   ├── wood.gmtf
│   │   ├── metal.gmtf
│   │   └── glass.gmtf
│   └── textures/
│       ├── diffuse/
│       │   └── wood_diffuse.png
│       ├── normal/
│       │   └── wood_normal.png
│       └── roughness/
│           └── wood_roughness.png
└── src/
    └── main.js

路径使用建议

在 GTF 文件中使用相对路径:

# 推荐：相对于 GTF 文件的路径
m ./materials/wood.gmtf
map ../textures/diffuse/wood_diffuse.png

# 不推荐：硬编码绝对路径
m /Users/username/project/assets/materials/wood.gmtf

在 JavaScript 中设置基础路径:

const loader = new GTFLoader();

// 设置基础路径，所有相对路径将基于此解析
loader.setPath('/assets/');

// 加载模型
loader.load('models/scene.gtf', (group) => {
    scene.add(group);
});

顶点颜色使用建议

1. 何时使用顶点颜色:

需要平滑颜色渐变效果
模型顶点着色（如热力图、高度图）
需要每个顶点独立颜色的场景

2. 顶点颜色与纹理配合:

# 顶点颜色与纹理结合使用
v -1.0 -1.0 0.0 1.0 0.0 0.0
v  1.0 -1.0 0.0 0.0 1.0 0.0
v  1.0  1.0 0.0 0.0 0.0 1.0
vt 0.0 0.0
vt 1.0 0.0
vt 1.0 1.0
f 0/0 1/1 2/2

3. 批量生成顶点颜色:

// 在 JavaScript 中为几何体生成顶点颜色
const geometry = new THREE.BoxGeometry(1, 1, 1);
const positionAttribute = geometry.getAttribute('position');
const colors = new Float32Array(positionAttribute.count * 3);

for (let i = 0; i < positionAttribute.count; i++) {
    const x = positionAttribute.getX(i);
    const y = positionAttribute.getY(i);
    const z = positionAttribute.getZ(i);
    
    // 基于位置生成颜色
    colors[i * 3] = (x + 1) / 2;
    colors[i * 3 + 1] = (y + 1) / 2;
    colors[i * 3 + 2] = (z + 1) / 2;
}

geometry.setAttribute('color', new THREE.Float32BufferAttribute(colors, 3));

性能优化建议

1. 使用纹理缓存:

GTFLoader 自动缓存纹理，避免重复加载。

// 多个模型使用相同的纹理，只会加载一次
loader.load('models/cube.gtf', (group) => { scene.add(group); });
loader.load('models/sphere.gtf', (group) => { scene.add(group); });
// 两个模型共享纹理缓存

2. 合并几何体:

对于不需要单独操作的网格，可以合并几何体以减少绘制调用。

import { mergeGeometries } from 'three/addons/utils/BufferGeometryUtils.js';

loader.load('models/scene.gtf', (group) => {
    const geometries = [];
    group.children.forEach(child => {
        if (child.isMesh) {
            geometries.push(child.geometry);
        }
    });
    const merged = mergeGeometries(geometries);
    const mesh = new THREE.Mesh(merged, material);
    scene.add(mesh);
});

3. 使用 LOD (Level of Detail):

对于大型场景，使用 LOD 可以提高渲染性能。

import { LOD } from 'three';

const lod = new LOD();
loader.load('models/high_detail.gtf', (group) => {
    lod.addLevel(group, 0);
});
loader.load('models/low_detail.gtf', (group) => {
    lod.addLevel(group, 50);
});
scene.add(lod);

4. 启用物理材质时注意性能:

MeshPhysicalMaterial 比 MeshStandardMaterial 性能开销更大，仅在需要高级效果时启用。

// 仅对需要玻璃/清漆效果的模型启用物理材质
loader.setUsePhysicalMaterial(true);
loader.load('models/glass.gtf', (group) => {
    scene.add(group);
});

// 其他模型使用标准材质
loader.setUsePhysicalMaterial(false);
loader.load('models/wood.gtf', (group) => {
    scene.add(group);
});

5. 顶点颜色性能提示:

顶点颜色会增加几何数据的内存占用（每顶点 +12 字节）
对于大型模型（10万+顶点），考虑使用纹理替代顶点颜色
如果不需要顶点颜色，不要在 GTF 文件中包含颜色值

错误处理最佳实践

开发环境:

// 开发时使用 throw 模式，快速发现问题
const loader = new GTFLoader();
loader.setErrorMode('throw');

try {
    const group = await loader.loadAsync('models/scene.gtf');
    scene.add(group);
} catch (error) {
    if (error instanceof GTFParseError) {
        // 显示详细的错误信息
        console.error(error.toString());
        // 在 UI 中显示 HTML 格式的错误
        document.getElementById('error-panel').innerHTML = error.formattedHtmlMessage;
    }
}

生产环境:

// 生产时使用 warn 或 silent 模式，保证应用稳定运行
const loader = new GTFLoader();
loader.setErrorMode('warn');

loader.load('models/scene.gtf', (group) => {
    scene.add(group);
}, undefined, (error) => {
    // 上报错误到监控服务
    reportError(error);
    // 显示友好的用户提示
    showToast('模型加载失败，请刷新重试');
});

// 检查是否发生错误
if (loader.hasError()) {
    const errors = loader.getErrors();
    // 记录错误日志
    errors.forEach(err => {
        console.error(err.code, err.message);
    });
}

浏览器兼容性

| 浏览器 | 最低版本 | 支持情况 | |--------|----------|----------| | Chrome | 90+ | 完全支持 | | Firefox | 88+ | 完全支持 | | Safari | 15+ | 完全支持 | | Edge | 90+ | 完全支持 | | Opera | 76+ | 完全支持 |

要求:

ES Module 支持
Promise 支持
Fetch API 支持（用于加载文件）
Canvas 支持（用于纹理处理）

许可证

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

GTFLoader — Graphics Transmission Format Loader for Three.js

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

GTFLoader

目录

概述

核心功能

文件格式规范

GTF 主文件格式

命令: v (顶点)

命令: vn (法线)

命令: vt (UV 纹理坐标)

命令: f (面)

命令: m (材质)

GMTF 材质文件格式

纹理贴图属性

颜色属性

数值属性

渲染设置属性

安装

使用 NPM

使用 CDN

手动引入

使用指南

基础用法

使用异步加载

使用物理材质

顶点颜色支持

顶点颜色文件格式

使用顶点颜色的 GTF 文件示例

在代码中加载带顶点颜色的模型

顶点颜色与材质颜色混合

混合顶点颜色与纹理

顶点颜色性能考虑

错误处理模式

加载外部材质

多材质模型

独立使用 GMTFLoader

GMTFLoader 的纹理缓存

GMTFLoader 的错误收集

API 参考

GTFLoader 类

构造函数

方法

setErrorMode

setUsePhysicalMaterial

setPath

getErrors

clearErrors

hasError

load

loadAsync

GMTFLoader 类

构造函数

方法

setErrorMode

setUsePhysicalMaterial

setParentLoader

getErrors

clearErrors

hasError

loadGMTF

loadTexture

loadTexturesForConfig

createMaterial

resolvePath

GTFParseError 类

构造函数

属性

方法

toString

escapeHtml

ERROR_CODES 常量

支持的材质属性

纹理贴图

颜色属性

数值属性