Code-first video & image, rendered natively on WebGPU.
import fs from "node:fs";
import path from "node:path";
import draco from "draco3dgltf";
import { MeshoptDecoder } from "meshoptimizer/decoder";
import { type Mat4, Matrix4Math, type Vec3 } from "../math3d/index.js";
import { poseNodes } from "./pose.js";
import { textureMime } from "./texture-files.js";
import type {
AnimationClip3D,
LoadModelOptions,
Material3D,
MaterialMapSlot,
MaterialSurface,
Model3DData,
ModelNode3D,
MorphTarget3D,
NodeAnimationTrack3D,
TextureSampling,
} from "./types.js";
const COMPONENTS: Record<string, number> = {
SCALAR: 1,
VEC2: 2,
VEC3: 3,
VEC4: 4,
MAT2: 4,
MAT3: 9,
MAT4: 16,
};
const COMPONENT_BYTES: Record<number, number> = {
5120: 1,
5121: 1,
5122: 2,
5123: 2,
5125: 4,
5126: 4,
};
/** Reads one component; normalized integers map to [0, 1] (unsigned) or [-1, 1] (signed). */
function componentReader(
componentType: number,
normalized = false,
): (dv: DataView, at: number) => number {
switch (componentType) {
case 5120:
return normalized
? (dv, at) => Math.max(dv.getInt8(at) / 127, -1)
: (dv, at) => dv.getInt8(at);
case 5121:
return normalized
? (dv, at) => dv.getUint8(at) / 255
: (dv, at) => dv.getUint8(at);
case 5122:
return normalized
? (dv, at) => Math.max(dv.getInt16(at, true) / 32767, -1)
: (dv, at) => dv.getInt16(at, true);
case 5123:
return normalized
? (dv, at) => dv.getUint16(at, true) / 65535
: (dv, at) => dv.getUint16(at, true);
case 5125:
return (dv, at) => dv.getUint32(at, true);
default:
return (dv, at) => dv.getFloat32(at, true);
}
}
interface GltfAccessor {
bufferView?: number;
byteOffset?: number;
componentType: number;
normalized?: boolean;
count: number;
type: "SCALAR" | "VEC2" | "VEC3" | "VEC4" | "MAT2" | "MAT3" | "MAT4";
max?: number[];
min?: number[];
sparse?: {
count: number;
indices: {
bufferView: number;
byteOffset?: number;
componentType: 5121 | 5123 | 5125;
};
values: { bufferView: number; byteOffset?: number };
};
}
interface MeshoptExtension {
buffer: number;
byteOffset?: number;
byteLength: number;
byteStride: number;
count: number;
mode: "ATTRIBUTES" | "TRIANGLES" | "INDICES";
filter?: "NONE" | "OCTAHEDRAL" | "QUATERNION" | "EXPONENTIAL" | "COLOR";
}
interface GltfBufferView {
buffer: number;
byteOffset?: number;
byteLength: number;
byteStride?: number;
target?: number;
extensions?: {
EXT_meshopt_compression?: MeshoptExtension;
KHR_meshopt_compression?: MeshoptExtension;
};
}
interface GltfBuffer {
uri?: string;
byteLength: number;
}
interface GltfPrimitive {
attributes: {
POSITION?: number;
NORMAL?: number;
TANGENT?: number;
TEXCOORD_0?: number;
TEXCOORD_1?: number;
COLOR_0?: number;
JOINTS_0?: number;
WEIGHTS_0?: number;
JOINTS_1?: number;
WEIGHTS_1?: number;
};
indices?: number;
material?: number;
mode?: number; // 4 = TRIANGLES
targets?: { POSITION?: number; NORMAL?: number; TANGENT?: number }[];
extensions?: {
KHR_draco_mesh_compression?: {
bufferView: number;
attributes: Record<string, number>;
};
};
decodedDraco?: {
attributes: Record<number, Float32Array>;
indices: Uint16Array | Uint32Array;
};
}
interface GltfMesh {
name?: string;
weights?: number[];
primitives: GltfPrimitive[];
/** `targetNames`: the de-facto convention for naming morph targets. */
extras?: { targetNames?: string[] };
}
interface GltfTextureTransform {
offset?: [number, number];
rotation?: number;
scale?: [number, number];
texCoord?: number;
}
interface GltfTextureInfo {
index: number;
texCoord?: number;
extensions?: { KHR_texture_transform?: GltfTextureTransform };
}
interface GltfMaterial {
name?: string;
pbrMetallicRoughness?: {
baseColorFactor?: [number, number, number, number];
metallicFactor?: number;
roughnessFactor?: number;
baseColorTexture?: GltfTextureInfo;
metallicRoughnessTexture?: GltfTextureInfo;
};
normalTexture?: GltfTextureInfo & { scale?: number };
occlusionTexture?: GltfTextureInfo & { strength?: number };
emissiveTexture?: GltfTextureInfo;
emissiveFactor?: [number, number, number];
doubleSided?: boolean;
alphaMode?: "OPAQUE" | "MASK" | "BLEND";
alphaCutoff?: number;
extensions?: {
KHR_materials_unlit?: Record<string, never>;
KHR_materials_emissive_strength?: { emissiveStrength?: number };
/** VRM 1.0 toon material: the base is lit flat, the shadowed side tinted by shadeColorFactor. */
VRMC_materials_mtoon?: { shadeColorFactor?: [number, number, number] };
KHR_materials_clearcoat?: {
clearcoatFactor?: number;
clearcoatRoughnessFactor?: number;
};
KHR_materials_sheen?: {
sheenColorFactor?: [number, number, number];
sheenRoughnessFactor?: number;
};
KHR_materials_anisotropy?: {
anisotropyStrength?: number;
anisotropyRotation?: number;
};
KHR_materials_transmission?: { transmissionFactor?: number };
KHR_materials_ior?: { ior?: number };
KHR_materials_volume?: { thicknessFactor?: number };
KHR_materials_iridescence?: {
iridescenceFactor?: number;
iridescenceIor?: number;
iridescenceThicknessMinimum?: number;
iridescenceThicknessMaximum?: number;
};
};
extras?: {
framefields?: {
subsurface?: { factor?: number; color?: [number, number, number] };
};
};
}
interface GltfImage {
uri?: string;
mimeType?: string;
bufferView?: number;
}
interface GltfTexture {
source?: number;
sampler?: number;
extensions?: {
EXT_texture_webp?: { source?: number };
KHR_texture_basisu?: { source?: number };
};
}
interface GltfSampler {
magFilter?: number;
minFilter?: number;
wrapS?: number;
wrapT?: number;
}
interface GltfNode {
name?: string;
camera?: number;
children?: number[];
skin?: number;
matrix?: number[];
mesh?: number;
weights?: number[];
rotation?: [number, number, number, number]; // [x, y, z, w] quaternion
scale?: [number, number, number];
translation?: [number, number, number];
}
interface GltfSkin {
name?: string;
inverseBindMatrices?: number;
skeleton?: number;
joints: number[];
}
interface GltfAnimationSampler {
input: number; // Accessor index for timestamps
output: number; // Accessor index for values
interpolation?: "LINEAR" | "STEP" | "CUBICSPLINE";
}
interface GltfAnimationChannel {
sampler: number;
target: {
node?: number;
path: "translation" | "rotation" | "scale" | "weights";
};
}
interface GltfAnimation {
name?: string;
samplers: GltfAnimationSampler[];
channels: GltfAnimationChannel[];
}
interface GltfDocument {
asset?: { version: string };
extensionsUsed?: string[];
extensionsRequired?: string[];
scene?: number;
scenes?: Array<{
name?: string;
nodes?: number[];
extras?: { framefields?: { drivers?: Model3DData["drivers"] } };
}>;
nodes?: GltfNode[];
meshes?: GltfMesh[];
materials?: GltfMaterial[];
skins?: GltfSkin[];
animations?: GltfAnimation[];
images?: GltfImage[];
textures?: GltfTexture[];
samplers?: GltfSampler[];
accessors?: GltfAccessor[];
bufferViews?: GltfBufferView[];
buffers?: GltfBuffer[];
}
/** Required extensions whose semantics this loader implements. */
const SUPPORTED_REQUIRED_EXTENSIONS = new Set([
"KHR_materials_unlit",
"KHR_materials_emissive_strength",
"KHR_materials_clearcoat",
"KHR_materials_sheen",
"KHR_materials_anisotropy",
"KHR_materials_iridescence",
"KHR_materials_transmission",
"KHR_materials_ior",
"KHR_materials_volume",
"KHR_texture_transform",
"KHR_texture_basisu",
"EXT_texture_webp",
]);
/** Converts glTF's strip, loop and fan modes to GPU list primitives. */
function expandPrimitive(
indices: Uint16Array | Uint32Array,
mode: number,
): {
indices: Uint16Array | Uint32Array;
topology: "triangle-list" | "line-list" | "point-list";
} {
if (mode === 0) return { indices, topology: "point-list" };
if (mode === 1) {
if (indices.length % 2 !== 0)
throw new Error("glTF LINES index count must be even");
return { indices, topology: "line-list" };
}
if (mode === 4) return { indices, topology: "triangle-list" };
if (![2, 3, 5, 6].includes(mode))
throw new Error(`Invalid glTF primitive mode ${mode}`);
const out: number[] = [];
if (mode === 2 || mode === 3) {
for (let i = 1; i < indices.length; i++)
out.push(indices[i - 1]!, indices[i]!);
if (mode === 2 && indices.length > 1)
out.push(indices[indices.length - 1]!, indices[0]!);
} else {
for (let i = 2; i < indices.length; i++) {
if (mode === 6) out.push(indices[0]!, indices[i - 1]!, indices[i]!);
else if (i % 2 === 0)
out.push(indices[i - 2]!, indices[i - 1]!, indices[i]!);
else out.push(indices[i - 1]!, indices[i - 2]!, indices[i]!);
}
}
return {
indices:
indices instanceof Uint32Array
? Uint32Array.from(out)
: Uint16Array.from(out),
topology: mode <= 3 ? "line-list" : "triangle-list",
};
}
const GLB_MAGIC = 0x46546c67; // "glTF"
const CHUNK_TYPE_JSON = 0x4e4f534a; // "JSON"
const CHUNK_TYPE_BIN = 0x004e4942; // "BIN\0"
export class GltfLoader {
/**
* Checks if the given buffer starts with the GLB binary container magic bytes.
*/
public static isGlb(buffer: Uint8Array | ArrayBuffer): boolean {
const bytes =
buffer instanceof Uint8Array ? buffer : new Uint8Array(buffer);
if (bytes.length < 12) return false;
const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
return view.getUint32(0, true) === GLB_MAGIC;
}
/**
* Parses glTF or GLB data into Model3DData.
*/
public static parse(
data: string | Uint8Array | ArrayBuffer,
options: LoadModelOptions = {},
basePath?: string,
): Model3DData {
const { doc, binaryBuffers } = GltfLoader.readDocument(data, basePath);
GltfLoader.checkExtensions(doc);
for (const mesh of doc.meshes ?? []) {
for (const primitive of mesh.primitives) {
const compressed = primitive.extensions?.KHR_draco_mesh_compression;
if (!compressed) continue;
if (primitive.indices !== undefined) {
const indexAccessor = doc.accessors?.[primitive.indices];
if (
!indexAccessor ||
(indexAccessor.bufferView === undefined && !indexAccessor.sparse)
) {
throw new Error(
"Draco indices without an uncompressed fallback require GltfLoader.parseAsync",
);
}
}
for (const semantic of Object.keys(compressed.attributes)) {
const index = (
primitive.attributes as Record<string, number | undefined>
)[semantic];
const accessor =
index === undefined ? undefined : doc.accessors?.[index];
if (
!accessor ||
(accessor.bufferView === undefined && !accessor.sparse)
) {
throw new Error(
"Draco geometry without an uncompressed fallback requires GltfLoader.parseAsync",
);
}
}
}
}
return GltfLoader.buildModel(doc, binaryBuffers, options, basePath);
}
/** Asynchronous import initializes WASM decoders before reading compressed buffers. */
public static async parseAsync(
data: string | Uint8Array | ArrayBuffer,
options: LoadModelOptions = {},
basePath?: string,
): Promise<Model3DData> {
const { doc, binaryBuffers } = GltfLoader.readDocument(data, basePath);
GltfLoader.checkExtensions(
doc,
new Set([
"EXT_meshopt_compression",
"KHR_meshopt_compression",
"KHR_draco_mesh_compression",
]),
);
await GltfLoader.decodeMeshopt(doc, binaryBuffers);
await GltfLoader.decodeDraco(doc, binaryBuffers);
return GltfLoader.buildModel(doc, binaryBuffers, options, basePath);
}
private static checkExtensions(
doc: GltfDocument,
extra: Set<string> = new Set(),
): void {
for (const ext of doc.extensionsRequired ?? []) {
if (!SUPPORTED_REQUIRED_EXTENSIONS.has(ext) && !extra.has(ext)) {
throw new Error(
`glTF file requires ${ext}, which framefields cannot decode or render`,
);
}
}
}
private static async decodeMeshopt(
doc: GltfDocument,
buffers: Uint8Array[],
): Promise<void> {
const views = (doc.bufferViews ?? []).filter(
(view) =>
view.extensions?.EXT_meshopt_compression ||
view.extensions?.KHR_meshopt_compression,
);
if (!views.length) return;
await MeshoptDecoder.ready;
for (const view of views) {
if (
view.extensions?.EXT_meshopt_compression &&
view.extensions?.KHR_meshopt_compression
) {
throw new Error(
"A buffer view cannot use both EXT and KHR meshopt compression",
);
}
const ext =
view.extensions?.KHR_meshopt_compression ??
view.extensions?.EXT_meshopt_compression;
if (!ext) continue;
const source = buffers[ext.buffer];
if (!source) throw new Error(`meshopt buffer ${ext.buffer} not loaded`);
const offset = ext.byteOffset ?? 0;
if (
offset < 0 ||
ext.byteLength < 0 ||
offset + ext.byteLength > source.byteLength
)
throw new Error("Invalid meshopt compressed buffer range");
const length = ext.count * ext.byteStride;
if (
!Number.isSafeInteger(ext.count) ||
ext.count < 0 ||
!Number.isSafeInteger(ext.byteStride) ||
ext.byteStride < 1 ||
!Number.isSafeInteger(length) ||
length !== view.byteLength
) {
throw new Error("Invalid meshopt decoded buffer length");
}
if (
!["ATTRIBUTES", "TRIANGLES", "INDICES"].includes(ext.mode) ||
!["NONE", "OCTAHEDRAL", "QUATERNION", "EXPONENTIAL", "COLOR"].includes(
ext.filter ?? "NONE",
)
) {
throw new Error("Invalid meshopt compression mode or filter");
}
const decoded = new Uint8Array(length);
MeshoptDecoder.decodeGltfBuffer(
decoded,
ext.count,
ext.byteStride,
source.subarray(offset, offset + ext.byteLength),
ext.mode,
ext.filter ?? "NONE",
);
view.buffer = buffers.length;
view.byteOffset = 0;
buffers.push(decoded);
}
}
private static async decodeDraco(
doc: GltfDocument,
buffers: Uint8Array[],
): Promise<void> {
const primitives = (doc.meshes ?? [])
.flatMap((mesh) => mesh.primitives)
.filter((primitive) => primitive.extensions?.KHR_draco_mesh_compression);
if (!primitives.length) return;
const module = await draco.createDecoderModule({});
const decoder = new module.Decoder();
try {
for (const primitive of primitives) {
const ext = primitive.extensions?.KHR_draco_mesh_compression;
if (!ext) continue;
const view = doc.bufferViews?.[ext.bufferView];
if (!view)
throw new Error(`Draco bufferView ${ext.bufferView} not found`);
const source = buffers[view.buffer];
if (!source) throw new Error(`Draco buffer ${view.buffer} not loaded`);
const offset = view.byteOffset ?? 0;
if (offset < 0 || offset + view.byteLength > source.byteLength)
throw new Error("Invalid Draco buffer range");
const compressed = source.subarray(offset, offset + view.byteLength);
const input = new module.DecoderBuffer();
const mesh = new module.Mesh();
try {
input.Init(
new Int8Array(
compressed.buffer,
compressed.byteOffset,
compressed.byteLength,
),
compressed.byteLength,
);
if (decoder.GetEncodedGeometryType(input) !== module.TRIANGULAR_MESH)
throw new Error("Draco primitive is not a triangular mesh");
const status = decoder.DecodeBufferToMesh(input, mesh);
const success = status.ok();
const message = success ? "" : status.error_msg();
module.destroy(status);
if (!success) throw new Error(`Draco decode failed: ${message}`);
const attributes: Record<number, Float32Array> = {};
for (const [semantic, id] of Object.entries(ext.attributes)) {
const accessorIndex = (
primitive.attributes as Record<string, number | undefined>
)[semantic];
const accessor =
accessorIndex === undefined
? undefined
: doc.accessors?.[accessorIndex];
if (accessorIndex === undefined || !accessor)
throw new Error(`Draco ${semantic} accessor not found`);
const attribute = decoder.GetAttributeByUniqueId(mesh, id);
if (!attribute)
throw new Error(`Draco ${semantic} attribute ${id} not found`);
const array = new module.DracoFloat32Array();
try {
if (
!decoder.GetAttributeFloatForAllPoints(mesh, attribute, array)
)
throw new Error(`Failed to decode Draco ${semantic}`);
const count =
mesh.num_points() * (COMPONENTS[accessor.type] ?? 1);
if (
accessor.count !== mesh.num_points() ||
array.size() !== count
)
throw new Error(`Invalid Draco ${semantic} attribute size`);
const values = new Float32Array(count);
for (let i = 0; i < count; i++) {
let value = array.GetValue(i);
if (accessor.normalized) {
if (accessor.componentType === 5120)
value = Math.max(value / 127, -1);
else if (accessor.componentType === 5121) value /= 255;
else if (accessor.componentType === 5122)
value = Math.max(value / 32767, -1);
else if (accessor.componentType === 5123) value /= 65535;
}
values[i] = value;
}
attributes[accessorIndex] = values;
} finally {
module.destroy(array);
}
}
const indices =
mesh.num_points() > 65535
? new Uint32Array(mesh.num_faces() * 3)
: new Uint16Array(mesh.num_faces() * 3);
const face = new module.DracoInt32Array();
try {
for (let i = 0; i < mesh.num_faces(); i++) {
if (!decoder.GetFaceFromMesh(mesh, i, face))
throw new Error(`Failed to decode Draco face ${i}`);
for (let j = 0; j < 3; j++) indices[i * 3 + j] = face.GetValue(j);
}
} finally {
module.destroy(face);
}
primitive.decodedDraco = { attributes, indices };
} finally {
module.destroy(mesh);
module.destroy(input);
}
}
} finally {
module.destroy(decoder);
}
}
private static readDocument(
data: string | Uint8Array | ArrayBuffer,
basePath?: string,
): { doc: GltfDocument; binaryBuffers: Uint8Array[] } {
let doc: GltfDocument;
const binaryBuffers: Uint8Array[] = [];
if (typeof data === "string") {
try {
doc = JSON.parse(data) as GltfDocument;
} catch (err) {
throw new Error(`Failed to parse glTF JSON: ${String(err)}`);
}
} else {
const bytes = data instanceof Uint8Array ? data : new Uint8Array(data);
if (GltfLoader.isGlb(bytes)) {
const glb = GltfLoader.unpackGlb(bytes);
doc = glb.doc;
if (glb.binBuffer) {
binaryBuffers.push(glb.binBuffer);
}
} else {
const text = new TextDecoder("utf-8").decode(bytes);
doc = JSON.parse(text) as GltfDocument;
}
}
// Load referenced external buffers or data URIs
if (doc.buffers) {
for (let i = 0; i < doc.buffers.length; i++) {
if (i === 0 && binaryBuffers.length > 0) continue; // Already provided by GLB BIN chunk
const buf = doc.buffers[i]!;
if (buf.uri) {
if (buf.uri.startsWith("data:")) {
const base64Index = buf.uri.indexOf("base64,");
if (base64Index !== -1) {
const b64 = buf.uri.substring(base64Index + 7);
const rawBuf = Buffer.from(b64, "base64");
binaryBuffers[i] = new Uint8Array(
rawBuf.buffer,
rawBuf.byteOffset,
rawBuf.byteLength,
);
}
} else if (basePath) {
const resolved = path.isAbsolute(buf.uri)
? buf.uri
: path.join(basePath, buf.uri);
if (fs.existsSync(resolved)) {
const fileBuf = fs.readFileSync(resolved);
binaryBuffers[i] = new Uint8Array(
fileBuf.buffer,
fileBuf.byteOffset,
fileBuf.byteLength,
);
}
}
}
}
}
return { doc, binaryBuffers };
}
private static unpackGlb(bytes: Uint8Array): {
doc: GltfDocument;
binBuffer?: Uint8Array;
} {
const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
const magic = view.getUint32(0, true);
const totalLength = view.getUint32(8, true);
if (magic !== GLB_MAGIC) {
throw new Error("Invalid GLB header: magic mismatch");
}
let offset = 12;
let doc: GltfDocument | null = null;
let binBuffer: Uint8Array | undefined;
while (offset < totalLength && offset < bytes.byteLength) {
const chunkLength = view.getUint32(offset, true);
const chunkType = view.getUint32(offset + 4, true);
offset += 8;
const chunkData = bytes.subarray(offset, offset + chunkLength);
offset += chunkLength;
if (chunkType === CHUNK_TYPE_JSON) {
const jsonStr = new TextDecoder("utf-8").decode(chunkData);
doc = JSON.parse(jsonStr) as GltfDocument;
} else if (chunkType === CHUNK_TYPE_BIN) {
binBuffer = chunkData;
}
}
if (!doc) {
throw new Error("Invalid GLB: JSON chunk not found");
}
return { doc, binBuffer };
}
/**
* Reads an accessor as floats: honours interleaved views (byteStride) and
* normalized integer components. Integer data that is not normalized
* (joint indices) keeps its values.
*/
private static readFloats(
doc: GltfDocument,
binaryBuffers: Uint8Array[],
accessorIndex: number,
): { data: Float32Array; itemSize: number; count: number } {
const accessor = doc.accessors?.[accessorIndex];
if (!accessor) throw new Error(`Accessor ${accessorIndex} not found`);
const itemSize = COMPONENTS[accessor.type] ?? 1;
const out = new Float32Array(accessor.count * itemSize);
const bytes = COMPONENT_BYTES[accessor.componentType] ?? 4;
const read = componentReader(accessor.componentType, accessor.normalized);
if (accessor.bufferView !== undefined) {
const view = doc.bufferViews?.[accessor.bufferView];
if (!view) throw new Error(`BufferView ${accessor.bufferView} not found`);
const raw = binaryBuffers[view.buffer];
if (!raw) throw new Error(`Binary buffer ${view.buffer} not loaded`);
const stride = view.byteStride ?? bytes * itemSize;
const dv = new DataView(raw.buffer, raw.byteOffset, raw.byteLength);
const base = (view.byteOffset ?? 0) + (accessor.byteOffset ?? 0);
for (let i = 0; i < accessor.count; i++) {
for (let c = 0; c < itemSize; c++)
out[i * itemSize + c] = read(dv, base + i * stride + c * bytes);
}
}
if (accessor.sparse) {
const sparse = GltfLoader.readSparse(doc, binaryBuffers, accessorIndex);
for (let i = 0; i < sparse.indices.length; i++)
for (let c = 0; c < itemSize; c++)
out[(sparse.indices[i] as number) * itemSize + c] = sparse.values[
i * itemSize + c
] as number;
}
return { data: out, itemSize, count: accessor.count };
}
/** A sparse accessor's indices and their values (`itemSize` per index). */
private static readSparse(
doc: GltfDocument,
binaryBuffers: Uint8Array[],
accessorIndex: number,
): { indices: Uint32Array; values: Float32Array } {
const accessor = doc.accessors?.[accessorIndex];
const sparse = accessor?.sparse;
if (!accessor || !sparse)
throw new Error(`Accessor ${accessorIndex} is not sparse`);
const itemSize = COMPONENTS[accessor.type] ?? 1;
const indexView = doc.bufferViews?.[sparse.indices.bufferView];
const valueView = doc.bufferViews?.[sparse.values.bufferView];
if (!indexView || !valueView)
throw new Error(
`Sparse accessor ${accessorIndex} references a missing buffer view`,
);
const indexData = binaryBuffers[indexView.buffer];
const valueData = binaryBuffers[valueView.buffer];
if (!indexData || !valueData)
throw new Error(
`Sparse accessor ${accessorIndex} references a missing buffer`,
);
const indexReader = componentReader(sparse.indices.componentType);
const indexBytes = COMPONENT_BYTES[sparse.indices.componentType] ?? 4;
const read = componentReader(accessor.componentType, accessor.normalized);
const bytes = COMPONENT_BYTES[accessor.componentType] ?? 4;
const indexDv = new DataView(
indexData.buffer,
indexData.byteOffset,
indexData.byteLength,
);
const valueDv = new DataView(
valueData.buffer,
valueData.byteOffset,
valueData.byteLength,
);
const indexBase =
(indexView.byteOffset ?? 0) + (sparse.indices.byteOffset ?? 0);
const valueBase =
(valueView.byteOffset ?? 0) + (sparse.values.byteOffset ?? 0);
const indices = new Uint32Array(sparse.count);
const values = new Float32Array(sparse.count * itemSize);
for (let i = 0; i < sparse.count; i++) {
const index = indexReader(indexDv, indexBase + i * indexBytes);
if (index >= accessor.count)
throw new Error(
`Sparse accessor ${accessorIndex} index ${index} is out of range`,
);
indices[i] = index;
for (let c = 0; c < itemSize; c++)
values[i * itemSize + c] = read(
valueDv,
valueBase + (i * itemSize + c) * bytes,
);
}
return { indices, values };
}
/**
* A morph target, kept sparse when its accessors are sparse over zeros
* (only the moved vertices, `indices`): a face with hundreds of
* corrective shapes stays small. Otherwise dense.
*/
private static readMorphTarget(
doc: GltfDocument,
binaryBuffers: Uint8Array[],
target: Record<string, number | undefined>,
numVerts: number,
label: string,
): MorphTarget3D {
const sparseOnly = (acc: number | undefined) => {
const a = acc === undefined ? undefined : doc.accessors?.[acc];
return !a || (a.sparse !== undefined && a.bufferView === undefined);
};
const check = (acc: number | undefined) => {
const a = acc === undefined ? undefined : doc.accessors?.[acc];
if (a && (a.count !== numVerts || (COMPONENTS[a.type] ?? 1) !== 3))
throw new Error(`Invalid morph target on ${label}`);
};
check(target.POSITION);
check(target.NORMAL);
if (!sparseOnly(target.POSITION) || !sparseOnly(target.NORMAL)) {
const read = (acc: number | undefined) =>
acc === undefined
? undefined
: GltfLoader.readFloats(doc, binaryBuffers, acc).data;
return {
positions: read(target.POSITION),
normals: read(target.NORMAL),
};
}
const parts = [target.POSITION, target.NORMAL].map((acc) =>
acc === undefined
? undefined
: GltfLoader.readSparse(doc, binaryBuffers, acc),
);
// One index list for both: the union, in order.
const union = new Set<number>();
for (const p of parts) if (p) for (const i of p.indices) union.add(i);
const indices = Uint32Array.from([...union].sort((x, y) => x - y));
const slot = new Map<number, number>();
indices.forEach((v, i) => {
slot.set(v, i);
});
const gather = (p: (typeof parts)[number]) => {
if (!p) return undefined;
const out = new Float32Array(indices.length * 3);
p.indices.forEach((v, i) => {
out.set(
p.values.subarray(i * 3, i * 3 + 3),
(slot.get(v) as number) * 3,
);
});
return out;
};
return {
indices,
positions: gather(parts[0]),
normals: gather(parts[1]),
};
}
private static readIndices(
doc: GltfDocument,
binaryBuffers: Uint8Array[],
accessorIndex: number,
): Uint16Array | Uint32Array {
const { data } = GltfLoader.readFloats(doc, binaryBuffers, accessorIndex);
const max = data.reduce((m, v) => (v > m ? v : m), 0);
return max > 65535 ? Uint32Array.from(data) : Uint16Array.from(data);
}
/** An image's encoded bytes, from the binary chunk, a data URI or a file next to the model. */
private static imageBytes(
doc: GltfDocument,
binaryBuffers: Uint8Array[],
imageIndex: number,
basePath?: string,
): { bytes: Uint8Array; mime: string } | undefined {
const image = doc.images?.[imageIndex];
if (!image) return undefined;
if (image.bufferView !== undefined) {
const view = doc.bufferViews?.[image.bufferView];
const raw = view ? binaryBuffers[view.buffer] : undefined;
if (!view || !raw) return undefined;
const start = view.byteOffset ?? 0;
return {
bytes: raw.subarray(start, start + view.byteLength),
mime: image.mimeType ?? "image/png",
};
}
if (!image.uri) return undefined;
if (image.uri.startsWith("data:")) {
const comma = image.uri.indexOf(",");
const mime = image.uri.slice(5, image.uri.indexOf(";"));
return {
bytes: new Uint8Array(
Buffer.from(image.uri.slice(comma + 1), "base64"),
),
mime,
};
}
if (!basePath) return undefined;
const file = path.isAbsolute(image.uri)
? image.uri
: path.join(basePath, decodeURIComponent(image.uri));
if (!fs.existsSync(file)) {
GltfLoader.warn(
`Image "${image.uri}" was not found next to the model; textures using it are skipped.`,
);
return undefined;
}
return {
bytes: new Uint8Array(fs.readFileSync(file)),
mime: image.mimeType ?? textureMime(file),
};
}
private static warn(message: string): void {
console.warn(`[GltfLoader] ${message}`);
}
/** The UV set of a texture reference (KHR_texture_transform may override it). */
private static texCoordOf(info: GltfTextureInfo): number {
return (
info.extensions?.KHR_texture_transform?.texCoord ?? info.texCoord ?? 0
);
}
/**
* A texture's decodable image: EXT_texture_webp's source when present.
* Basis KTX2 and EXT_texture_webp override a texture's fallback source.
*/
private static textureImage(
doc: GltfDocument,
binaryBuffers: Uint8Array[],
textureIndex: number,
basePath: string | undefined,
label: string,
): { bytes: Uint8Array; mime: string; sampler?: GltfSampler } | undefined {
const texture = doc.textures?.[textureIndex];
if (!texture) return undefined;
const source =
texture.extensions?.KHR_texture_basisu?.source ??
texture.extensions?.EXT_texture_webp?.source ??
texture.source;
if (source === undefined) return undefined;
const image = GltfLoader.imageBytes(doc, binaryBuffers, source, basePath);
if (!image) return undefined;
if (!SUPPORTED_IMAGE_MIMES.has(image.mime)) {
GltfLoader.warn(
`${label} is ${image.mime}, which framefields cannot decode; it is skipped (use PNG, JPEG or WebP).`,
);
return undefined;
}
const sampler =
texture.sampler !== undefined
? doc.samplers?.[texture.sampler]
: undefined;
return { ...image, sampler };
}
private static buildMaterial(
doc: GltfDocument,
binaryBuffers: Uint8Array[],
mat: GltfMaterial,
name: string,
basePath?: string,
): Material3D {
const pbr = mat.pbrMetallicRoughness;
const [r, g, b, a] = pbr?.baseColorFactor ?? [1, 1, 1, 1];
const material: Material3D = {
name,
// baseColorFactor is linear; Material3D colors are display (sRGB), like COLOR_0 below.
diffuseColor: [linearToSrgb(r), linearToSrgb(g), linearToSrgb(b), a],
roughness: pbr?.roughnessFactor ?? 0.5,
metallic: pbr?.metallicFactor ?? 0.0,
shininess: 32.0 * (1.0 - (pbr?.roughnessFactor ?? 0.5)),
twoSided: mat.doubleSided ?? true,
alphaMode:
mat.alphaMode === "MASK"
? "mask"
: mat.alphaMode === "BLEND"
? "blend"
: "opaque",
alphaCutoff: mat.alphaMode === "MASK" ? (mat.alphaCutoff ?? 0.5) : 0,
};
const e = mat.emissiveFactor;
if (e && (e[0] > 0 || e[1] > 0 || e[2] > 0)) {
material.emissive = [e[0], e[1], e[2]];
material.emissiveStrength =
mat.extensions?.KHR_materials_emissive_strength?.emissiveStrength ?? 1;
}
const surface = materialSurface(mat);
if (surface) material.surface = surface;
const mtoon = mat.extensions?.VRMC_materials_mtoon;
if (mtoon) {
material.shading = "toon";
material.shadeColor = mtoon.shadeColorFactor ?? [1, 1, 1];
} else if (mat.extensions?.KHR_materials_unlit) {
material.shading = "unlit";
} else if (
(mat.extensions?.KHR_materials_transmission?.transmissionFactor ?? 0) > 0
) {
// Transmissive surfaces (corneas, windows, potions) render as glass
// that refracts the scene behind them.
material.shading = "glass";
material.ior = mat.extensions?.KHR_materials_ior?.ior ?? 1.5;
const t = mat.extensions?.KHR_materials_volume?.thicknessFactor;
if (t !== undefined) material.thickness = t;
}
const image = (info: GltfTextureInfo | undefined, slot: string) => {
if (!info) return undefined;
return GltfLoader.textureImage(
doc,
binaryBuffers,
info.index,
basePath,
`The ${slot} map of material "${name}"`,
);
};
const base = image(pbr?.baseColorTexture, "base color");
if (base) {
material.diffuseTextureBuffer = base.bytes;
material.diffuseTextureMime = base.mime;
const sampling = textureSampling(base.sampler);
material.textureWrap = sampling.wrapU;
if (sampling.filter === "nearest") material.textureFilter = "nearest";
}
const mapBytes = (
info: GltfTextureInfo | undefined,
slot: string,
key: MaterialMapSlot,
) => {
const map = image(info, slot);
if (!map) return undefined;
material.mapSampling = {
...material.mapSampling,
[key]: textureSampling(map.sampler),
};
return map.bytes;
};
const normal = mapBytes(mat.normalTexture, "normal", "normal");
if (normal) {
material.normalTextureBuffer = normal;
material.normalScale = mat.normalTexture?.scale ?? 1;
}
const mr = mapBytes(
pbr?.metallicRoughnessTexture,
"metallic-roughness",
"metallicRoughness",
);
if (mr) {
material.metallicRoughnessTextureBuffer = mr;
// With a map the factors scale it, and glTF's default factor is 1.
material.roughness = pbr?.roughnessFactor ?? 1;
material.metallic = pbr?.metallicFactor ?? 1;
}
const occlusion = mapBytes(mat.occlusionTexture, "occlusion", "occlusion");
if (occlusion) {
material.occlusionTextureBuffer = occlusion;
material.occlusionStrength = mat.occlusionTexture?.strength ?? 1;
}
// glTF's emissiveFactor defaults to 0: a map alone does not glow.
const emissiveMap =
material.emissive &&
mapBytes(mat.emissiveTexture, "emissive", "emissive");
if (emissiveMap) material.emissiveTextureBuffer = emissiveMap;
return material;
}
private static buildNodes(doc: GltfDocument): ModelNode3D[] {
const nodes: ModelNode3D[] = (doc.nodes ?? []).map((n, i) => ({
name: n.name ?? `node_${i}`,
parent: -1,
translation: n.translation ?? [0, 0, 0],
rotation: n.rotation ?? [0, 0, 0, 1],
scale: n.scale ?? [1, 1, 1],
matrix: n.matrix ? (n.matrix as Mat4) : undefined,
}));
(doc.nodes ?? []).forEach((n, i) => {
for (const c of n.children ?? []) {
const child = nodes[c];
if (child) child.parent = i;
}
});
return nodes;
}
private static buildAnimations(
doc: GltfDocument,
binaryBuffers: Uint8Array[],
nodes: ModelNode3D[],
): AnimationClip3D[] {
return (doc.animations ?? []).map((animDef, animIdx) => {
const tracks: NodeAnimationTrack3D[] = [];
let duration = 0;
for (const chan of animDef.channels) {
const sampler = animDef.samplers[chan.sampler];
const node = chan.target.node;
if (!sampler || node === undefined) continue;
const times = GltfLoader.readFloats(
doc,
binaryBuffers,
sampler.input,
).data;
const values = GltfLoader.readFloats(
doc,
binaryBuffers,
sampler.output,
).data;
duration = Math.max(duration, times[times.length - 1] ?? 0);
const track: NodeAnimationTrack3D = {
nodeName: nodes[node]?.name ?? `node_${node}`,
node,
times,
interpolation:
sampler.interpolation === "STEP"
? "step"
: sampler.interpolation === "CUBICSPLINE"
? "cubic"
: "linear",
};
if (chan.target.path === "translation") track.translations = values;
else if (chan.target.path === "rotation") track.rotations = values;
else if (chan.target.path === "scale") track.scales = values;
else track.weights = values;
tracks.push(track);
}
return {
name: animDef.name ?? `Animation_${animIdx}`,
duration: duration > 0 ? duration : 1.0,
fps: 30,
tracks,
};
});
}
private static buildModel(
doc: GltfDocument,
binaryBuffers: Uint8Array[],
options: LoadModelOptions,
basePath?: string,
): Model3DData {
// Material keys must be unique: glTF names are optional and may repeat.
const materialKeys = (doc.materials ?? []).map((mat, idx, all) => {
const name = mat.name ?? `material_${idx}`;
return all.findIndex((m, j) => (m.name ?? `material_${j}`) === name) ===
idx
? name
: `${name}#${idx}`;
});
const materials: Record<string, Material3D> = {};
(doc.materials ?? []).forEach((mat, idx) => {
const key = materialKeys[idx]!;
materials[key] = GltfLoader.buildMaterial(
doc,
binaryBuffers,
mat,
key,
basePath,
);
});
const nodes = GltfLoader.buildNodes(doc);
const skins = (doc.skins ?? []).map((skin) => ({
joints: skin.joints,
inverseBindMatrices:
skin.inverseBindMatrices !== undefined
? GltfLoader.readFloats(doc, binaryBuffers, skin.inverseBindMatrices)
.data
: Float32Array.from(
skin.joints.flatMap(() => Matrix4Math.identity()),
),
}));
const animations = GltfLoader.buildAnimations(doc, binaryBuffers, nodes);
// Meshes are drawn where nodes place them; a file without nodes draws each mesh once.
const placed = (doc.nodes ?? []).flatMap((n, node) =>
n.mesh !== undefined ? [{ mesh: n.mesh, node, skin: n.skin }] : [],
);
const instances: { mesh: number; node?: number; skin?: number }[] =
placed.length > 0
? placed
: (doc.meshes ?? []).map((_, mesh) => ({ mesh }));
const model: Model3DData = {
name: "glTF_Model",
meshes: [],
materials,
nodes,
skins,
animations,
bounds: {
min: [0, 0, 0],
max: [0, 0, 0],
center: [0, 0, 0],
size: [0, 0, 0],
boundingSphereRadius: 0,
},
};
const drivers = doc.scenes?.[doc.scene ?? 0]?.extras?.framefields?.drivers;
if (drivers?.length) model.drivers = drivers;
const rest = poseNodes(model, undefined, 0);
let minX = Infinity,
minY = Infinity,
minZ = Infinity;
let maxX = -Infinity,
maxY = -Infinity,
maxZ = -Infinity;
const grow = (x: number, y: number, z: number) => {
if (x < minX) minX = x;
if (x > maxX) maxX = x;
if (y < minY) minY = y;
if (y > maxY) maxY = y;
if (z < minZ) minZ = z;
if (z > maxZ) maxZ = z;
};
for (const inst of instances) {
const meshDef = doc.meshes?.[inst.mesh];
if (!meshDef) continue;
meshDef.primitives.forEach((prim, primIdx) => {
if (prim.attributes.POSITION === undefined) {
throw new Error(
`glTF mesh ${inst.mesh} primitive ${primIdx} has no POSITION attribute`,
);
}
const read = (acc: number | undefined) => {
if (acc === undefined) return undefined;
const data = prim.decodedDraco?.attributes[acc];
if (!data) return GltfLoader.readFloats(doc, binaryBuffers, acc);
const accessor = doc.accessors?.[acc];
if (!accessor) throw new Error(`Accessor ${acc} not found`);
return {
data,
itemSize: COMPONENTS[accessor.type] ?? 1,
count: accessor.count,
};
};
const pos = read(prim.attributes.POSITION)!;
const numVerts = pos.count;
const mat =
prim.material === undefined
? undefined
: doc.materials?.[prim.material];
const attributes = prim.attributes as Record<
string,
number | undefined
>;
const mapUv = (
info: GltfTextureInfo | undefined,
): Float32Array | undefined => {
if (!info) return undefined;
const set = GltfLoader.texCoordOf(info);
const accessor = attributes[`TEXCOORD_${set}`];
if (accessor === undefined)
throw new Error(
`glTF mesh ${inst.mesh} primitive ${primIdx} lacks TEXCOORD_${set} required by a texture`,
);
const uv = read(accessor);
if (!uv)
throw new Error(
`glTF mesh ${inst.mesh} has missing texture coordinates`,
);
if (uv.itemSize !== 2 || uv.count !== numVerts)
throw new Error(
`Invalid TEXCOORD_${set} on glTF mesh ${inst.mesh} primitive ${primIdx}`,
);
const transform = info.extensions?.KHR_texture_transform;
if (transform) applyTextureTransform(uv.data, transform);
return uv.data;
};
const uvs =
mapUv(mat?.pbrMetallicRoughness?.baseColorTexture) ??
read(prim.attributes.TEXCOORD_0)?.data ??
new Float32Array(numVerts * 2);
const mapUvs = {
normal: mapUv(mat?.normalTexture),
metallicRoughness: mapUv(
mat?.pbrMetallicRoughness?.metallicRoughnessTexture,
),
occlusion: mapUv(mat?.occlusionTexture),
emissive: mapUv(mat?.emissiveTexture),
};
const colors = read(prim.attributes.COLOR_0);
let rgba: Float32Array | undefined;
if (colors) {
// COLOR_0 is linear; Mesh3DData colors are display (sRGB), like base colors.
rgba = new Float32Array(numVerts * 4).fill(1);
for (let v = 0; v < numVerts; v++)
for (let c = 0; c < colors.itemSize; c++) {
const value = colors.data[v * colors.itemSize + c] ?? 1;
rgba[v * 4 + c] = c < 3 ? linearToSrgb(value) : value;
}
}
let indices: Uint16Array | Uint32Array;
if (prim.decodedDraco) {
indices = prim.decodedDraco.indices;
} else if (prim.indices !== undefined) {
indices = GltfLoader.readIndices(doc, binaryBuffers, prim.indices);
} else {
indices =
numVerts > 65535
? new Uint32Array(numVerts)
: new Uint16Array(numVerts);
for (let i = 0; i < numVerts; i++) indices[i] = i;
}
const primitive = expandPrimitive(indices, prim.mode ?? 4);
indices = primitive.indices;
// Skinned vertices are in bind (model) space; others sit under their node.
const skinned =
inst.skin !== undefined && prim.attributes.JOINTS_0 !== undefined;
const place =
!skinned && inst.node !== undefined ? rest[inst.node] : undefined;
for (let i = 0; i < numVerts; i++) {
const x = pos.data[i * 3]!;
const y = pos.data[i * 3 + 1]!;
const z = pos.data[i * 3 + 2]!;
if (place) {
const p = Matrix4Math.projectPoint(place, [x, y, z]);
grow(p[0], p[1], p[2]);
} else grow(x, y, z);
}
const morphTargets = prim.targets?.map((target) =>
GltfLoader.readMorphTarget(
doc,
binaryBuffers,
target,
numVerts,
`glTF mesh ${inst.mesh} primitive ${primIdx}`,
),
);
const defaultWeights =
(inst.node === undefined
? undefined
: doc.nodes?.[inst.node]?.weights) ?? meshDef.weights;
const morphWeights = morphTargets?.map(
(_, i) => defaultWeights?.[i] ?? 0,
);
model.meshes.push({
id: `gltf_mesh_${inst.mesh}_${primIdx}${inst.node !== undefined ? `_n${inst.node}` : ""}`,
name: meshDef.name ?? `Mesh_${inst.mesh}`,
positions: pos.data,
normals:
read(prim.attributes.NORMAL)?.data ??
new Float32Array(numVerts * 3),
uvs,
mapUvs,
morphTargets,
morphWeights,
...(morphTargets &&
meshDef.extras?.targetNames?.length === morphTargets.length
? { morphTargetNames: meshDef.extras.targetNames }
: {}),
colors: rgba,
jointIndices: skinned
? read(prim.attributes.JOINTS_0)?.data
: undefined,
jointWeights: skinned
? read(prim.attributes.WEIGHTS_0)?.data
: undefined,
...(skinned &&
prim.attributes.JOINTS_1 !== undefined &&
prim.attributes.WEIGHTS_1 !== undefined && {
jointIndices1: read(prim.attributes.JOINTS_1)?.data,
jointWeights1: read(prim.attributes.WEIGHTS_1)?.data,
}),
indices,
topology: primitive.topology,
materialName:
prim.material !== undefined
? materialKeys[prim.material]
: undefined,
node: inst.node,
skin: skinned ? inst.skin : undefined,
});
});
}
if (!Number.isFinite(minX)) {
minX = minY = minZ = 0;
maxX = maxY = maxZ = 0;
}
const maxDimension = Math.max(
maxX - minX,
maxY - minY,
maxZ - minZ,
0.0001,
);
const fit =
options.normalizeSize && options.normalizeSize > 0
? options.normalizeSize / maxDimension
: 1.0;
const extra: Vec3 =
typeof options.scale === "number"
? [options.scale, options.scale, options.scale]
: (options.scale ?? [1, 1, 1]);
const scale: Vec3 = [fit * extra[0], fit * extra[1], fit * extra[2]];
const offset: Vec3 = options.center
? [(minX + maxX) * 0.5, (minY + maxY) * 0.5, (minZ + maxZ) * 0.5]
: [0, 0, 0];
// Skinned vertices move with their joints, so centering and size are a
// root transform above the scene graph rather than baked into vertices.
model.rootTransform = Matrix4Math.multiply(
Matrix4Math.scale(scale[0], scale[1], scale[2]),
Matrix4Math.translate(-offset[0], -offset[1], -offset[2]),
);
const lo: Vec3 = [
(minX - offset[0]) * scale[0],
(minY - offset[1]) * scale[1],
(minZ - offset[2]) * scale[2],
];
const hi: Vec3 = [
(maxX - offset[0]) * scale[0],
(maxY - offset[1]) * scale[1],
(maxZ - offset[2]) * scale[2],
];
model.bounds = {
min: lo,
max: hi,
center: [
(lo[0] + hi[0]) * 0.5,
(lo[1] + hi[1]) * 0.5,
(lo[2] + hi[2]) * 0.5,
],
size: [hi[0] - lo[0], hi[1] - lo[1], hi[2] - lo[2]],
boundingSphereRadius:
Math.hypot(hi[0] - lo[0], hi[1] - lo[1], hi[2] - lo[2]) * 0.5,
};
return model;
}
/**
* Loads a glTF / GLB file synchronously or asynchronously from a path or URL.
*/
public static async loadAsync(
srcOrData: string | ArrayBuffer | Uint8Array,
options: LoadModelOptions = {},
): Promise<Model3DData> {
if (typeof srcOrData !== "string")
return GltfLoader.parseAsync(srcOrData, options);
const cleanPath = srcOrData.startsWith("file://")
? srcOrData.replace("file://", "")
: srcOrData;
if (!srcOrData.trimStart().startsWith("{") && fs.existsSync(cleanPath)) {
return GltfLoader.parseAsync(
fs.readFileSync(cleanPath),
options,
path.dirname(cleanPath),
);
}
return GltfLoader.parseAsync(srcOrData, options);
}
public static load(
srcOrData: string | ArrayBuffer | Uint8Array,
options: LoadModelOptions = {},
): Model3DData {
if (typeof srcOrData !== "string") {
return GltfLoader.parse(srcOrData, options);
}
const cleanPath = srcOrData.startsWith("file://")
? srcOrData.replace("file://", "")
: srcOrData;
if (
srcOrData.startsWith("/") ||
srcOrData.startsWith("./") ||
srcOrData.startsWith("../") ||
srcOrData.startsWith("file://") ||
// A relative path such as "models/robot.glb" (inline glTF JSON starts with "{").
(!srcOrData.trimStart().startsWith("{") && fs.existsSync(cleanPath))
) {
const buf = fs.readFileSync(cleanPath);
const basePath = path.dirname(cleanPath);
return GltfLoader.parse(buf, options, basePath);
}
return GltfLoader.parse(srcOrData, options);
}
}
export function parseGLTF(
data: string | Uint8Array | ArrayBuffer,
options: LoadModelOptions = {},
): Model3DData {
return GltfLoader.parse(data, options);
}
export function loadGLTF(
srcOrData: string | ArrayBuffer | Uint8Array,
options: LoadModelOptions = {},
): Model3DData {
return GltfLoader.load(srcOrData, options);
}
export async function loadGLTFAsync(
srcOrData: string | ArrayBuffer | Uint8Array,
options: LoadModelOptions = {},
): Promise<Model3DData> {
return GltfLoader.loadAsync(srcOrData, options);
}
export function parseGLB(
data: Uint8Array | ArrayBuffer,
options: LoadModelOptions = {},
): Model3DData {
return GltfLoader.parse(data, options);
}
export function loadGLB(
srcOrData: string | ArrayBuffer | Uint8Array,
options: LoadModelOptions = {},
): Model3DData {
return GltfLoader.load(srcOrData, options);
}
/** The layered lobes a glTF material's extensions describe (display colors, degrees). */
function materialSurface(mat: GltfMaterial): MaterialSurface | undefined {
const ext = mat.extensions;
const out: MaterialSurface = {};
const display = (c: [number, number, number]): [number, number, number] => [
linearToSrgb(c[0]),
linearToSrgb(c[1]),
linearToSrgb(c[2]),
];
const cc = ext?.KHR_materials_clearcoat;
if (cc && (cc.clearcoatFactor ?? 0) > 0) {
out.clearcoat = cc.clearcoatFactor;
out.clearcoatRoughness = cc.clearcoatRoughnessFactor ?? 0;
}
const sh = ext?.KHR_materials_sheen;
if (sh) {
const c = sh.sheenColorFactor ?? [0, 0, 0];
const peak = Math.max(c[0], c[1], c[2]);
if (peak > 0) {
// The lobe takes a strength and a tint; glTF folds both into one color.
out.sheen = Math.min(1, peak);
out.sheenColor = display([c[0] / peak, c[1] / peak, c[2] / peak]);
out.sheenRoughness = sh.sheenRoughnessFactor ?? 0;
}
}
const an = ext?.KHR_materials_anisotropy;
if (an && (an.anisotropyStrength ?? 0) > 0) {
out.anisotropy = an.anisotropyStrength;
out.anisotropyRotation = ((an.anisotropyRotation ?? 0) * 180) / Math.PI;
}
const ir = ext?.KHR_materials_iridescence;
if (ir && (ir.iridescenceFactor ?? 0) > 0) {
out.iridescence = ir.iridescenceFactor;
out.iridescenceIor = ir.iridescenceIor ?? 1.3;
out.iridescenceThickness = ir.iridescenceThicknessMaximum ?? 400;
}
const ss = mat.extras?.framefields?.subsurface;
if (ss && (ss.factor ?? 0) > 0) {
out.subsurface = ss.factor;
out.subsurfaceColor = display(ss.color ?? [1, 0.2, 0.1]);
}
return Object.keys(out).length ? out : undefined;
}
function linearToSrgb(c: number): number {
const x = Math.min(Math.max(c, 0), 1);
return x <= 0.0031308 ? x * 12.92 : 1.055 * x ** (1 / 2.4) - 0.055;
}
/** The image types the renderer decodes (sharp). */
const SUPPORTED_IMAGE_MIMES = new Set([
"image/png",
"image/jpeg",
"image/webp",
"image/gif",
"image/tiff",
"image/avif",
"image/ktx2",
]);
/**
* Bakes KHR_texture_transform into UVs in place: uv' = T * R * S * uv
* (offset, then rotation counter-clockwise in UV space, then scale).
*/
function applyTextureTransform(
uvs: Float32Array,
{ offset = [0, 0], rotation = 0, scale = [1, 1] }: GltfTextureTransform,
): void {
const c = Math.cos(rotation);
const s = Math.sin(rotation);
for (let i = 0; i < uvs.length; i += 2) {
const u = uvs[i]! * scale[0];
const v = uvs[i + 1]! * scale[1];
uvs[i] = c * u - s * v + offset[0];
uvs[i + 1] = s * u + c * v + offset[1];
}
}
const WRAP: Record<number, TextureSampling["wrapU"]> = {
33071: "clamp",
33648: "mirror",
};
/** A glTF sampler as addressing and filtering (glTF's defaults: repeat, linear). */
function textureSampling(sampler: GltfSampler | undefined): TextureSampling {
return {
wrapU: WRAP[sampler?.wrapS ?? 10497] ?? "repeat",
wrapV: WRAP[sampler?.wrapT ?? 10497] ?? "repeat",
filter: sampler?.magFilter === 9728 ? "nearest" : "linear",
};
}