Skip to content

Code-first video & image, rendered natively on WebGPU.

8.3 KB
Raw Blame
import fs from "node:fs";
import { type Vec3, Vector3Math } from "../math3d/index.js";
import type { LoadModelOptions, Material3D, Mesh3DData, Model3DData } from "./types.js";
import { computeBounds, createIndexArray, resolveModelTransform, transformModelBounds, transformPositions } from "./mesh-utils.js";

export class StlLoader {
	/**
	 * Checks if buffer is Binary STL or ASCII STL.
	 */
	public static isBinary(buffer: Uint8Array | ArrayBuffer): boolean {
		const bytes = buffer instanceof Uint8Array ? buffer : new Uint8Array(buffer);
		if (bytes.length < 84) return false;

		// Binary STL has 80 byte header + 4 byte triangle count
		const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
		const triangleCount = view.getUint32(80, true);
		const expectedBinarySize = 84 + triangleCount * 50;

		if (bytes.length === expectedBinarySize) return true;

		// Check for non-ASCII characters in the first 512 bytes
		const checkLength = Math.min(bytes.length, 512);
		for (let i = 0; i < checkLength; i++) {
			const b = bytes[i]!;
			if (b > 127 || (b < 32 && b !== 9 && b !== 10 && b !== 13)) {
				return true;
			}
		}

		// Check if it starts with 'solid'
		const headerText = new TextDecoder("utf-8").decode(bytes.subarray(0, 80)).trim();
		if (headerText.startsWith("solid") && !headerText.includes("\n")) {
			// Some binary STLs put "solid" in their 80-byte header, but if length matches binary it's binary
			return bytes.length >= 84 + triangleCount * 50;
		}

		return !headerText.startsWith("solid");
	}

	/**
	 * Parses STL data (binary Uint8Array/ArrayBuffer or ASCII string) into Model3DData.
	 */
	public static parse(
		data: string | Uint8Array | ArrayBuffer,
		options: LoadModelOptions = {},
	): Model3DData {
		if (typeof data === "string") {
			return StlLoader.parseAscii(data, options);
		}

		const bytes = data instanceof Uint8Array ? data : new Uint8Array(data);
		if (StlLoader.isBinary(bytes)) {
			return StlLoader.parseBinary(bytes, options);
		}

		const text = new TextDecoder("utf-8").decode(bytes);
		return StlLoader.parseAscii(text, options);
	}

	/**
	 * Parses Binary STL.
	 */
	public static parseBinary(
		bytes: Uint8Array,
		options: LoadModelOptions = {},
	): Model3DData {
		const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
		const triangleCount = view.getUint32(80, true);

		const positions: number[] = [];
		const normals: number[] = [];
		const indices: number[] = [];

		let offset = 84;
		for (let i = 0; i < triangleCount; i++) {
			if (offset + 50 > bytes.byteLength) break;

			const nx = view.getFloat32(offset, true);
			const ny = view.getFloat32(offset + 4, true);
			const nz = view.getFloat32(offset + 8, true);
			offset += 12;

			const v0x = view.getFloat32(offset, true);
			const v0y = view.getFloat32(offset + 4, true);
			const v0z = view.getFloat32(offset + 8, true);
			offset += 12;

			const v1x = view.getFloat32(offset, true);
			const v1y = view.getFloat32(offset + 4, true);
			const v1z = view.getFloat32(offset + 8, true);
			offset += 12;

			const v2x = view.getFloat32(offset, true);
			const v2y = view.getFloat32(offset + 4, true);
			const v2z = view.getFloat32(offset + 8, true);
			offset += 12;

			// 2-byte attribute byte count
			offset += 2;

			let finalNx = nx;
			let finalNy = ny;
			let finalNz = nz;

			// If facet normal is 0, compute face normal from vertices
			if (finalNx === 0 && finalNy === 0 && finalNz === 0) {
				const e1 = Vector3Math.subtract([v1x, v1y, v1z], [v0x, v0y, v0z]);
				const e2 = Vector3Math.subtract([v2x, v2y, v2z], [v0x, v0y, v0z]);
				const fn = Vector3Math.normalize(Vector3Math.cross(e1, e2));
				finalNx = fn[0];
				finalNy = fn[1];
				finalNz = fn[2];
			}

			const startIdx = positions.length / 3;
			positions.push(v0x, v0y, v0z, v1x, v1y, v1z, v2x, v2y, v2z);
			normals.push(
				finalNx, finalNy, finalNz,
				finalNx, finalNy, finalNz,
				finalNx, finalNy, finalNz,
			);
			indices.push(startIdx, startIdx + 1, startIdx + 2);
		}

		return StlLoader.finalizeModel(positions, normals, indices, options);
	}

	/**
	 * Parses ASCII STL text.
	 */
	public static parseAscii(
		text: string,
		options: LoadModelOptions = {},
	): Model3DData {
		const positions: number[] = [];
		const normals: number[] = [];
		const indices: number[] = [];

		const lines = text.split(/\r?\n/);
		let currentNormal: Vec3 = [0, 0, 1];
		let currentVerts: Vec3[] = [];

		for (const rawLine of lines) {
			const line = rawLine.trim();
			if (!line) continue;

			if (line.startsWith("facet normal")) {
				const parts = line.split(/\s+/);
				const nx = Number.parseFloat(parts[2] ?? "0") || 0;
				const ny = Number.parseFloat(parts[3] ?? "0") || 0;
				const nz = Number.parseFloat(parts[4] ?? "0") || 0;
				currentNormal = [nx, ny, nz];
				currentVerts = [];
			} else if (line.startsWith("vertex")) {
				const parts = line.split(/\s+/);
				const x = Number.parseFloat(parts[1] ?? "0") || 0;
				const y = Number.parseFloat(parts[2] ?? "0") || 0;
				const z = Number.parseFloat(parts[3] ?? "0") || 0;
				currentVerts.push([x, y, z]);
			} else if (line.startsWith("endfacet")) {
				if (currentVerts.length >= 3) {
					const v0 = currentVerts[0]!;
					const v1 = currentVerts[1]!;
					const v2 = currentVerts[2]!;

					let fn = currentNormal;
					if (fn[0] === 0 && fn[1] === 0 && fn[2] === 0) {
						const e1 = Vector3Math.subtract(v1, v0);
						const e2 = Vector3Math.subtract(v2, v0);
						fn = Vector3Math.normalize(Vector3Math.cross(e1, e2));
					}

					for (let i = 1; i < currentVerts.length - 1; i++) {
						const vi = currentVerts[i]!;
						const viNext = currentVerts[i + 1]!;
						const startIdx = positions.length / 3;

						positions.push(v0[0], v0[1], v0[2], vi[0], vi[1], vi[2], viNext[0], viNext[1], viNext[2]);
						normals.push(fn[0], fn[1], fn[2], fn[0], fn[1], fn[2], fn[0], fn[1], fn[2]);
						indices.push(startIdx, startIdx + 1, startIdx + 2);
					}
				}
				currentVerts = [];
			}
		}

		return StlLoader.finalizeModel(positions, normals, indices, options);
	}

	private static finalizeModel(
		rawPositions: number[],
		rawNormals: number[],
		rawIndices: number[],
		options: LoadModelOptions = {},
	): Model3DData {
		const bounds = computeBounds(rawPositions);
		const transform = resolveModelTransform(bounds, options);
		const positions = transformPositions(rawPositions, transform);

		// Planar UV fallback based on bounding size
		const [minX, minY] = bounds.min;
		const [sizeX, sizeY] = bounds.size;
		const uvs = new Float32Array((rawPositions.length / 3) * 2);
		for (let i = 0; i < rawPositions.length; i += 3) {
			const uvIdx = (i / 3) * 2;
			uvs[uvIdx] = sizeX > 0 ? (rawPositions[i]! - minX) / sizeX : 0;
			uvs[uvIdx + 1] = sizeY > 0 ? (rawPositions[i + 1]! - minY) / sizeY : 0;
		}

		const indexArray = createIndexArray(rawIndices, positions.length / 3);

		const defaultMaterial: Material3D = {
			name: "stl_default",
			diffuseColor: [0.8, 0.8, 0.85, 1.0],
			shininess: 32.0,
			specularIntensity: 0.5,
			...options.defaultMaterial,
		};

		const meshes: Mesh3DData[] = [
			{
				id: "stl_mesh_0",
				name: "stl_geometry",
				positions,
				normals: new Float32Array(rawNormals),
				uvs,
				indices: indexArray,
				materialName: "stl_default",
			},
		];


		return {
			name: "STL_Model",
			meshes,
			materials: { stl_default: defaultMaterial },
			animations: [],
			bounds: transformModelBounds(bounds, transform),
		};
	}

	/**
	 * Loads an STL file synchronously or asynchronously from a path or URL.
	 */
	public static load(
		srcOrData: string | ArrayBuffer | Uint8Array,
		options: LoadModelOptions = {},
	): Model3DData {
		if (typeof srcOrData !== "string") {
			return StlLoader.parse(srcOrData, options);
		}

		if (
			srcOrData.startsWith("/") ||
			srcOrData.startsWith("./") ||
			srcOrData.startsWith("../") ||
			srcOrData.startsWith("file://")
		) {
			const cleanPath = srcOrData.startsWith("file://")
				? srcOrData.replace("file://", "")
				: srcOrData;
			const buf = fs.readFileSync(cleanPath);
			return StlLoader.parse(buf, options);
		}

		return StlLoader.parse(srcOrData, options);
	}
}

export function parseSTL(
	data: string | Uint8Array | ArrayBuffer,
	options: LoadModelOptions = {},
): Model3DData {
	return StlLoader.parse(data, options);
}

export function loadSTL(
	srcOrData: string | ArrayBuffer | Uint8Array,
	options: LoadModelOptions = {},
): Model3DData {
	return StlLoader.load(srcOrData, options);
}