Code-first video & image, rendered natively on WebGPU.
import fs from "node:fs";
import {
accumulateVertexNormals,
computeBounds,
createIndexArray,
resolveModelTransform,
transformModelBounds,
transformPositions,
} from "./mesh-utils.js";
import type {
LoadModelOptions,
Material3D,
Mesh3DData,
Model3DData,
} from "./types.js";
interface PlyProperty {
name: string;
type: string;
isList?: boolean;
countType?: string;
itemType?: string;
}
interface PlyElement {
name: string;
count: number;
properties: PlyProperty[];
}
export class PlyLoader {
/**
* Parses PLY data (ASCII string or binary buffer) into Model3DData.
*/
public static parse(
data: string | Uint8Array | ArrayBuffer,
options: LoadModelOptions = {},
): Model3DData {
const bytes =
typeof data === "string"
? new TextEncoder().encode(data)
: data instanceof Uint8Array
? data
: new Uint8Array(data);
// Find end_header
const headerText = PlyLoader.extractHeader(bytes);
const header = PlyLoader.parseHeader(headerText.text);
if (header.format === "ascii") {
const bodyText = new TextDecoder("utf-8").decode(
bytes.subarray(headerText.endOffset),
);
return PlyLoader.parseAsciiBody(header, bodyText, options);
}
const isLittleEndian = header.format === "binary_little_endian";
return PlyLoader.parseBinaryBody(
header,
bytes.subarray(headerText.endOffset),
isLittleEndian,
options,
);
}
private static extractHeader(bytes: Uint8Array): {
text: string;
endOffset: number;
} {
const searchLen = Math.min(bytes.length, 10000);
const slice = bytes.subarray(0, searchLen);
const str = new TextDecoder("utf-8").decode(slice);
const endIdx = str.indexOf("end_header");
if (endIdx === -1) {
throw new Error("Invalid PLY file: 'end_header' marker not found");
}
// Find newline after end_header
let newlineOffset = str.indexOf("\n", endIdx);
if (newlineOffset === -1) newlineOffset = endIdx + 10;
else newlineOffset += 1;
return {
text: str.substring(0, newlineOffset),
endOffset: newlineOffset,
};
}
private static parseHeader(headerStr: string): {
format: "ascii" | "binary_little_endian" | "binary_big_endian";
version: string;
elements: PlyElement[];
} {
const lines = headerStr.split(/\r?\n/);
let format: "ascii" | "binary_little_endian" | "binary_big_endian" =
"ascii";
let version = "1.0";
const elements: PlyElement[] = [];
let currentElement: PlyElement | null = null;
for (const rawLine of lines) {
const line = rawLine.trim();
if (!line || line.startsWith("comment")) continue;
const parts = line.split(/\s+/);
const cmd = parts[0]?.toLowerCase();
if (cmd === "ply") continue;
if (cmd === "format") {
const fmt = parts[1]?.toLowerCase();
if (fmt === "binary_little_endian") format = "binary_little_endian";
else if (fmt === "binary_big_endian") format = "binary_big_endian";
else format = "ascii";
version = parts[2] ?? "1.0";
} else if (cmd === "element") {
const name = parts[1] ?? "";
const count = Number.parseInt(parts[2] ?? "0", 10);
currentElement = { name, count, properties: [] };
elements.push(currentElement);
} else if (cmd === "property" && currentElement) {
if (parts[1]?.toLowerCase() === "list") {
currentElement.properties.push({
name: parts[4] ?? "",
type: "list",
isList: true,
countType: parts[2] ?? "uchar",
itemType: parts[3] ?? "int",
});
} else {
currentElement.properties.push({
name: parts[2] ?? "",
type: parts[1]?.toLowerCase() ?? "float",
});
}
} else if (cmd === "end_header") {
break;
}
}
return { format, version, elements };
}
private static parseAsciiBody(
header: { elements: PlyElement[] },
bodyText: string,
options: LoadModelOptions,
): Model3DData {
const vertexElement = header.elements.find((e) => e.name === "vertex");
const faceElement = header.elements.find((e) => e.name === "face");
const vertexCount = vertexElement?.count ?? 0;
const faceCount = faceElement?.count ?? 0;
const rawPositions: number[] = [];
const rawNormals: number[] = [];
const rawUvs: number[] = [];
const rawColors: number[] = [];
const rawIndices: number[] = [];
const vProps = vertexElement?.properties ?? [];
const xIdx = vProps.findIndex((p) => p.name === "x");
const yIdx = vProps.findIndex((p) => p.name === "y");
const zIdx = vProps.findIndex((p) => p.name === "z");
const nxIdx = vProps.findIndex((p) => p.name === "nx");
const nyIdx = vProps.findIndex((p) => p.name === "ny");
const nzIdx = vProps.findIndex((p) => p.name === "nz");
const uIdx = vProps.findIndex(
(p) => p.name === "u" || p.name === "s" || p.name === "texture_u",
);
const vCoordIdx = vProps.findIndex(
(p) => p.name === "v" || p.name === "t" || p.name === "texture_v",
);
const rIdx = vProps.findIndex((p) => p.name === "red" || p.name === "r");
const gIdx = vProps.findIndex((p) => p.name === "green" || p.name === "g");
const bIdx = vProps.findIndex((p) => p.name === "blue" || p.name === "b");
const aIdx = vProps.findIndex((p) => p.name === "alpha" || p.name === "a");
const hasNormals = nxIdx !== -1 && nyIdx !== -1 && nzIdx !== -1;
const hasColors = rIdx !== -1 && gIdx !== -1 && bIdx !== -1;
const hasUvs = uIdx !== -1 && vCoordIdx !== -1;
const lines = bodyText.trim().split(/\r?\n/);
let lineIdx = 0;
for (let v = 0; v < vertexCount; v++) {
if (lineIdx >= lines.length) break;
const line = lines[lineIdx++]?.trim();
if (!line) continue;
const parts = line.split(/\s+/);
const x = Number.parseFloat(parts[xIdx] ?? "0") || 0;
const y = Number.parseFloat(parts[yIdx] ?? "0") || 0;
const z = Number.parseFloat(parts[zIdx] ?? "0") || 0;
rawPositions.push(x, y, z);
if (hasNormals) {
const nx = Number.parseFloat(parts[nxIdx] ?? "0") || 0;
const ny = Number.parseFloat(parts[nyIdx] ?? "0") || 0;
const nz = Number.parseFloat(parts[nzIdx] ?? "0") || 0;
rawNormals.push(nx, ny, nz);
} else {
rawNormals.push(0, 0, 0);
}
if (hasUvs) {
const u = Number.parseFloat(parts[uIdx] ?? "0") || 0;
const vCoord = Number.parseFloat(parts[vCoordIdx] ?? "0") || 0;
rawUvs.push(u, 1.0 - vCoord);
} else {
rawUvs.push(0, 0);
}
if (hasColors) {
const r = (Number.parseFloat(parts[rIdx] ?? "255") || 0) / 255;
const g = (Number.parseFloat(parts[gIdx] ?? "255") || 0) / 255;
const b = (Number.parseFloat(parts[bIdx] ?? "255") || 0) / 255;
const a =
aIdx !== -1
? (Number.parseFloat(parts[aIdx] ?? "255") || 0) / 255
: 1.0;
rawColors.push(r, g, b, a);
}
}
for (let f = 0; f < faceCount; f++) {
if (lineIdx >= lines.length) break;
const line = lines[lineIdx++]?.trim();
if (!line) continue;
const parts = line.split(/\s+/);
const n = Number.parseInt(parts[0] ?? "0", 10);
if (n >= 3) {
const v0 = Number.parseInt(parts[1] ?? "0", 10);
for (let i = 1; i < n - 1; i++) {
const v1 = Number.parseInt(parts[i + 1] ?? "0", 10);
const v2 = Number.parseInt(parts[i + 2] ?? "0", 10);
rawIndices.push(v0, v1, v2);
}
}
}
return PlyLoader.finalizeModel(
rawPositions,
rawNormals,
rawUvs,
hasColors ? rawColors : undefined,
rawIndices,
hasNormals,
options,
);
}
private static parseBinaryBody(
header: { elements: PlyElement[] },
bodyBytes: Uint8Array,
isLittleEndian: boolean,
options: LoadModelOptions,
): Model3DData {
const view = new DataView(
bodyBytes.buffer,
bodyBytes.byteOffset,
bodyBytes.byteLength,
);
let offset = 0;
const vertexElement = header.elements.find((e) => e.name === "vertex");
const faceElement = header.elements.find((e) => e.name === "face");
const vertexCount = vertexElement?.count ?? 0;
const faceCount = faceElement?.count ?? 0;
const rawPositions: number[] = [];
const rawNormals: number[] = [];
const rawUvs: number[] = [];
const rawColors: number[] = [];
const rawIndices: number[] = [];
const vProps = vertexElement?.properties ?? [];
const hasNormals = vProps.some((p) => p.name === "nx");
const hasColors = vProps.some((p) => p.name === "red" || p.name === "r");
const readType = (typeStr: string): number => {
let val = 0;
switch (typeStr.toLowerCase()) {
case "char":
case "int8":
val = view.getInt8(offset);
offset += 1;
break;
case "uchar":
case "uint8":
val = view.getUint8(offset);
offset += 1;
break;
case "short":
case "int16":
val = view.getInt16(offset, isLittleEndian);
offset += 2;
break;
case "ushort":
case "uint16":
val = view.getUint16(offset, isLittleEndian);
offset += 2;
break;
case "int":
case "int32":
val = view.getInt32(offset, isLittleEndian);
offset += 4;
break;
case "uint":
case "uint32":
val = view.getUint32(offset, isLittleEndian);
offset += 4;
break;
case "float":
case "float32":
val = view.getFloat32(offset, isLittleEndian);
offset += 4;
break;
case "double":
case "float64":
val = view.getFloat64(offset, isLittleEndian);
offset += 8;
break;
default:
val = view.getFloat32(offset, isLittleEndian);
offset += 4;
break;
}
return val;
};
for (let v = 0; v < vertexCount; v++) {
let x = 0,
y = 0,
z = 0;
let nx = 0,
ny = 0,
nz = 0;
let u = 0,
vCoord = 0;
let r = 1,
g = 1,
b = 1,
a = 1;
for (const prop of vProps) {
const val = readType(prop.type);
const pName = prop.name.toLowerCase();
if (pName === "x") x = val;
else if (pName === "y") y = val;
else if (pName === "z") z = val;
else if (pName === "nx") nx = val;
else if (pName === "ny") ny = val;
else if (pName === "nz") nz = val;
else if (pName === "u" || pName === "s") u = val;
else if (pName === "v" || pName === "t") vCoord = val;
else if (pName === "red" || pName === "r")
r = prop.type.includes("int") ? val / 255 : val;
else if (pName === "green" || pName === "g")
g = prop.type.includes("int") ? val / 255 : val;
else if (pName === "blue" || pName === "b")
b = prop.type.includes("int") ? val / 255 : val;
else if (pName === "alpha" || pName === "a")
a = prop.type.includes("int") ? val / 255 : val;
}
rawPositions.push(x, y, z);
rawNormals.push(nx, ny, nz);
rawUvs.push(u, 1.0 - vCoord);
if (hasColors) rawColors.push(r, g, b, a);
}
const faceProps = faceElement?.properties ?? [];
const listProp = faceProps.find((p) => p.isList);
for (let f = 0; f < faceCount; f++) {
if (offset >= bodyBytes.byteLength) break;
if (listProp) {
const count = readType(listProp.countType ?? "uchar");
const verts: number[] = [];
for (let k = 0; k < count; k++) {
verts.push(readType(listProp.itemType ?? "int"));
}
if (verts.length >= 3) {
const v0 = verts[0]!;
for (let i = 1; i < verts.length - 1; i++) {
rawIndices.push(v0, verts[i]!, verts[i + 1]!);
}
}
}
}
return PlyLoader.finalizeModel(
rawPositions,
rawNormals,
rawUvs,
hasColors ? rawColors : undefined,
rawIndices,
hasNormals,
options,
);
}
private static finalizeModel(
rawPositions: number[],
rawNormals: number[],
rawUvs: number[],
rawColors: number[] | undefined,
rawIndices: number[],
hasNormals: boolean,
options: LoadModelOptions,
): Model3DData {
// Calculate face normals if missing
if (!hasNormals || options.smoothNormals) {
accumulateVertexNormals(rawPositions, rawIndices, rawNormals);
}
const bounds = computeBounds(rawPositions);
const transform = resolveModelTransform(bounds, options);
const positions = transformPositions(rawPositions, transform);
const indexArray = createIndexArray(rawIndices, positions.length / 3);
const defaultMaterial: Material3D = {
name: "ply_default",
// Vertex colors carry the color; the neutral gray would only dim them.
diffuseColor: rawColors ? [1, 1, 1, 1] : [0.8, 0.8, 0.85, 1.0],
shininess: 32.0,
specularIntensity: 0.5,
...options.defaultMaterial,
};
const meshes: Mesh3DData[] = [
{
id: "ply_mesh_0",
name: "ply_geometry",
positions,
normals: new Float32Array(rawNormals),
uvs: new Float32Array(rawUvs),
colors: rawColors ? new Float32Array(rawColors) : undefined,
indices: indexArray,
materialName: "ply_default",
},
];
return {
name: "PLY_Model",
meshes,
materials: { ply_default: defaultMaterial },
animations: [],
bounds: transformModelBounds(bounds, transform),
};
}
/**
* Loads a PLY file synchronously or asynchronously from a path or URL.
*/
public static load(
srcOrData: string | ArrayBuffer | Uint8Array,
options: LoadModelOptions = {},
): Model3DData {
if (typeof srcOrData !== "string") {
return PlyLoader.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 PlyLoader.parse(buf, options);
}
return PlyLoader.parse(srcOrData, options);
}
}
export function parsePLY(
data: string | Uint8Array | ArrayBuffer,
options: LoadModelOptions = {},
): Model3DData {
return PlyLoader.parse(data, options);
}
export function loadPLY(
srcOrData: string | ArrayBuffer | Uint8Array,
options: LoadModelOptions = {},
): Model3DData {
return PlyLoader.load(srcOrData, options);
}