ris-framework 0.1.0 → 0.2.0-dev.12

package/src/api/loaders/obj/ObjParser.ts

@@ -0,0 +1,301 @@
+import {
+    ObjMaterialDefinition,
+    type ObjColor,
+    type ObjLoadResult,
+    type ObjLoadOptions,
+    type ObjModel,
+    type ObjMaterialRange,
+} from "./ObjTypes.ts";
+
+function tokens(line: string): string[] {
+    return line.trim().split(/\s+/);
+}
+
+function readColor(parts: string[]): ObjColor | undefined {
+    // "Kd spectral ..." and "Kd xyz ..." are not supported.
+    if (parts.length < 2 || isNaN(parseFloat(parts[1]))) {
+        return undefined;
+    }
+    const r = parseFloat(parts[1]);
+    const g = parts.length > 2 ? parseFloat(parts[2]) : r;
+    const b = parts.length > 3 ? parseFloat(parts[3]) : r;
+    return [r, g, b];
+}
+
+/**
+ * Parses .obj models (and their .mtl materials) from text or a URL into plain data.
+ * Engine-independent; uses only `fetch` and `URL`, and creates no GPU resources.
+ * `framework.objLoader` (or the static `ObjLoader.parseAsync`) builds on it.
+ */
+export class ObjParser {
+
+    /**
+     * Parses .mtl text.
+     * @param text The .mtl contents.
+     * @returns The material definitions, in file order.
+     */
+    public parseMtl(text: string): ObjMaterialDefinition[] {
+        const materials: ObjMaterialDefinition[] = [];
+        let current: ObjMaterialDefinition | undefined;
+
+        for (const rawLine of text.split(/\r?\n/)) {
+            const line = rawLine.trim();
+            if (line.length == 0 || line.startsWith("#")) {
+                continue;
+            }
+            const parts = tokens(line);
+            const keyword = parts[0];
+
+            if (keyword == "newmtl") {
+                current = new ObjMaterialDefinition(line.substring(keyword.length).trim());
+                materials.push(current);
+                continue;
+            }
+            if (!current) {
+                continue;
+            }
+
+            switch (keyword) {
+                case "Ka":
+                    current.ambientColor = readColor(parts);
+                    break;
+                case "Kd":
+                    current.diffuseColor = readColor(parts);
+                    break;
+                case "Ks":
+                    current.specularColor = readColor(parts);
+                    break;
+                case "Ke":
+                    current.emissiveColor = readColor(parts);
+                    break;
+                case "Ns":
+                    current.specularExponent = parseFloat(parts[1]);
+                    break;
+                case "Ni":
+                    current.opticalDensity = parseFloat(parts[1]);
+                    break;
+                case "illum":
+                    current.illuminationModel = parseInt(parts[1]);
+                    break;
+                case "d":
+                    current.opacity = parseFloat(parts[parts.length - 1]);
+                    break;
+                case "Tr":
+                    // "d" wins when both are present.
+                    if (current.opacity === undefined) {
+                        current.opacity = 1 - parseFloat(parts[1]);
+                    }
+                    break;
+                default:
+                    if (keyword.startsWith("map_") || keyword == "bump" || keyword == "disp"
+                        || keyword == "decal" || keyword == "refl" || keyword == "norm") {
+                        if (parts.length >= 2) {
+                            current.maps[keyword] = parts[parts.length - 1];
+                            if (parts.length > 2) {
+                                current.mapOptions[keyword] = parts.slice(1, -1).join(" ");
+                            }
+                        }
+                    }
+                    break;
+            }
+        }
+
+        return materials;
+    }
+
+    /**
+     * Parses .obj text.
+     * @param text The .obj contents.
+     * @param materials Material definitions to use for `usemtl`, e.g. from {@link parseMtl}. Default none.
+     * @returns The geometry, materials and raw data.
+     */
+    public fromText(text: string, materials: ObjMaterialDefinition[] = []): ObjLoadResult {
+        const rawPositions: number[] = [];
+        const rawTextureCoords: number[] = [];
+        const rawNormals: number[] = [];
+        const faceIndices: number[] = [];
+        const materialLibraries: string[] = [];
+        const materialRanges: ObjMaterialRange[] = [];
+
+        const positions: number[] = [];
+        const textureCoords: number[] = [];
+        const normals: number[] = [];
+        const colors: number[] = [];
+        const indices: number[] = [];
+        const vertexLookup = new Map<string, number>();
+
+        const materialsByName = new Map(materials.map(m => [m.name, m]));
+        let materialName: string | undefined;
+        let rangeStart = 0;
+
+        const closeRange = () => {
+            if (indices.length > rangeStart) {
+                materialRanges.push({materialName, indexStart: rangeStart, indexCount: indices.length - rangeStart});
+            }
+            rangeStart = indices.length;
+        };
+
+        const resolve = (value: string | undefined, count: number): number => {
+            if (value === undefined || value.length == 0) {
+                return -1;
+            }
+            const index = parseInt(value);
+            // OBJ indices are one-based; negative values count back from the end.
+            return index < 0 ? count + index : index - 1;
+        };
+
+        const addCorner = (p: number, t: number, n: number): void => {
+            faceIndices.push(p, t, n);
+            const key = `${p}/${t}/${n}/${materialName ?? ""}`;
+            let vertex = vertexLookup.get(key);
+            if (vertex === undefined) {
+                vertex = positions.length / 3;
+                vertexLookup.set(key, vertex);
+                positions.push(rawPositions[p * 3], rawPositions[p * 3 + 1], rawPositions[p * 3 + 2]);
+                textureCoords.push(t >= 0 ? rawTextureCoords[t * 2] : 0, t >= 0 ? rawTextureCoords[t * 2 + 1] : 0);
+                normals.push(n >= 0 ? rawNormals[n * 3] : 0, n >= 0 ? rawNormals[n * 3 + 1] : 0, n >= 0 ? rawNormals[n * 3 + 2] : 0);
+                const material = materialName !== undefined ? materialsByName.get(materialName) : undefined;
+                const kd = material?.diffuseColor ?? [1, 1, 1];
+                colors.push(kd[0], kd[1], kd[2], material?.opacity ?? 1);
+            }
+            indices.push(vertex);
+        };
+
+        for (const rawLine of text.split(/\r?\n/)) {
+            const line = rawLine.trim();
+            if (line.length == 0 || line.startsWith("#")) {
+                continue;
+            }
+            const parts = tokens(line);
+
+            switch (parts[0]) {
+                case "v":
+                    rawPositions.push(parseFloat(parts[1]), parseFloat(parts[2]), parseFloat(parts[3]));
+                    break;
+                case "vt":
+                    rawTextureCoords.push(parseFloat(parts[1]), parts.length > 2 ? parseFloat(parts[2]) : 0);
+                    break;
+                case "vn":
+                    rawNormals.push(parseFloat(parts[1]), parseFloat(parts[2]), parseFloat(parts[3]));
+                    break;
+                case "f": {
+                    const corners = parts.slice(1).map(corner => {
+                        const [p, t, n] = corner.split("/");
+                        return [
+                            resolve(p, rawPositions.length / 3),
+                            resolve(t, rawTextureCoords.length / 2),
+                            resolve(n, rawNormals.length / 3),
+                        ];
+                    });
+                    // Triangulate polygons as a fan.
+                    for (let i = 1; i + 1 < corners.length; i++) {
+                        addCorner(corners[0][0], corners[0][1], corners[0][2]);
+                        addCorner(corners[i][0], corners[i][1], corners[i][2]);
+                        addCorner(corners[i + 1][0], corners[i + 1][1], corners[i + 1][2]);
+                    }
+                    break;
+                }
+                case "mtllib":
+                    materialLibraries.push(...parts.slice(1));
+                    break;
+                case "usemtl":
+                    closeRange();
+                    materialName = line.substring(parts[0].length).trim();
+                    break;
+            }
+        }
+        closeRange();
+
+        if(positions.length == 0){
+            throw new Error("Invalid obj file.");
+        }
+
+        return {
+            geometry: {
+                positions, textureCoords, normals, colors, indices,
+                vertexCount: positions.length / 3,
+                materialRanges,
+            },
+            materials,
+            materialLibraries,
+            raw: {positions: rawPositions, textureCoords: rawTextureCoords, normals: rawNormals, faceIndices},
+        };
+    }
+
+    /**
+     * Loads an .obj file and the .mtl files it references with `mtllib`.
+     * A missing or failing .mtl is skipped (logged as a warning); the model still loads with white vertex colours.
+     * @param filePath The .obj URL.
+     * @param options Optional: how to resolve `mtllib` names, or skip materials.
+     * @returns The geometry, materials and raw data.
+     */
+    public async loadAsync(filePath: string, options?: ObjLoadOptions): Promise<ObjLoadResult> {
+        const response = await fetch(filePath);
+        if (!response.ok) {
+            throw new Error(`Failed to load OBJ '${filePath}': ${response.status} ${response.statusText}`);
+        }
+        const text = await response.text();
+
+        const materials: ObjMaterialDefinition[] = [];
+
+        const libraries = options?.ignoreMaterials ? [] : text.split(/\r?\n/)
+            .map(line => tokens(line))
+            .filter(parts => parts[0] == "mtllib")
+            .flatMap(parts => parts.slice(1));
+
+        // data: and blob: URLs have no directory, so relative names cannot be resolved against them.
+        const opaqueUrl = /^(data|blob):/i.test(filePath);
+        for (const library of libraries) {
+            try {
+                let mtlUrl: string;
+                if (options?.resolveMaterialUrl) {
+                    mtlUrl = options.resolveMaterialUrl(library);
+                } else if (opaqueUrl) {
+                    throw new Error("the OBJ was loaded from a data: or blob: URL (e.g. a bundler-inlined asset), so the name cannot be resolved; pass options.resolveMaterialUrl");
+                } else {
+                    mtlUrl = filePath.substring(0, filePath.lastIndexOf("/") + 1) + library;
+                }
+                const mtlResponse = await fetch(mtlUrl);
+
+                if (!mtlResponse.ok) {
+                    throw new Error(`${mtlResponse.status} ${mtlResponse.statusText}`);
+                }
+                materials.push(...this.parseMtl(await mtlResponse.text()));
+            } catch (error) {
+                console.warn(`ObjParser: could not load material library '${library}'.`, error);
+            }
+        }
+
+
+        return this.fromText(text, materials);
+    }
+
+    /**
+     * Loads an .obj file (and its .mtl files) into an {@link ObjModel}: the geometry plus one sub mesh per `usemtl`
+     * range with its resolved material definition.
+     * @param filePath The .obj URL.
+     * @param options Optional: how to resolve `mtllib` names, or skip materials.
+     * @returns The model.
+     */
+    public async parseAsync(filePath: string, options?: ObjLoadOptions): Promise<ObjModel> {
+        return ObjParser.toModel(await this.loadAsync(filePath, options));
+    }
+
+    /**
+     * Turns a load result into an {@link ObjModel}.
+     * @param result The load result.
+     * @returns The model.
+     */
+    public static toModel(result: ObjLoadResult): ObjModel {
+        const byName = new Map(result.materials.map(m => [m.name, m]));
+        return {
+            ...result,
+            subMeshes: result.geometry.materialRanges.map(range => ({
+                materialName: range.materialName,
+                material: range.materialName === undefined ? undefined : byName.get(range.materialName),
+                indexStart: range.indexStart,
+                indexCount: range.indexCount,
+            })),
+        };
+    }
+}

package/src/api/loaders/obj/ObjTypes.ts

@@ -0,0 +1,142 @@
+/*
+ * Plain-data types produced by the OBJ loader.
+ * This folder is self-contained: files here import only each other, so it can move to its own package.
+ */
+
+/** An RGB colour as read from an .mtl file, each channel usually in 0..1. */
+export type ObjColor = [r: number, g: number, b: number];
+
+/**
+ * A material definition read from an .mtl file (`newmtl` block).
+ * This is plain data, not a GPU material; map it onto a framework material yourself.
+ */
+export class ObjMaterialDefinition {
+
+    /**
+     * The constructor.
+     * @param name The material name from `newmtl`.
+     */
+    public constructor(public name: string) {
+    }
+
+    /** Ambient colour (`Ka`). */
+    public ambientColor?: ObjColor;
+
+    /** Diffuse colour (`Kd`). */
+    public diffuseColor?: ObjColor;
+
+    /** Specular colour (`Ks`). */
+    public specularColor?: ObjColor;
+
+    /** Emissive colour (`Ke`). */
+    public emissiveColor?: ObjColor;
+
+    /** Specular exponent (`Ns`). */
+    public specularExponent?: number;
+
+    /** Opacity, from `d`, or `1 - Tr` when only `Tr` is given. */
+    public opacity?: number;
+
+    /** Optical density / index of refraction (`Ni`). */
+    public opticalDensity?: number;
+
+    /** Illumination model (`illum`). */
+    public illuminationModel?: number;
+
+    /**
+     * Texture maps by statement name, e.g. `map_Kd`, `map_Ks`, `map_Bump`, `bump`, `disp`, `decal`, `refl`.
+     * The value is the file name (last token); map options such as `-bm 1` are kept in {@link mapOptions}.
+     */
+    public maps: Record<string, string> = {};
+
+    /** Options written before the file name of a map statement, e.g. `{ map_Bump: "-bm 0.5" }`. */
+    public mapOptions: Record<string, string> = {};
+}
+
+/** A run of triangles in the geometry's index buffer drawn with one material (`usemtl`). */
+export interface ObjMaterialRange {
+    /** The material name from `usemtl`, or undefined for faces before any `usemtl`. */
+    readonly materialName?: string;
+    /** First index in `geometry.indices`. */
+    readonly indexStart: number;
+    /** Number of indices (3 per triangle). */
+    readonly indexCount: number;
+}
+
+/** The OBJ data exactly as listed in the file, before expansion. */
+export interface ObjRawData {
+    /** `v` values, 3 per position. */
+    readonly positions: number[];
+    /** `vt` values, 2 per texture coordinate (a third `w` value is dropped). */
+    readonly textureCoords: number[];
+    /** `vn` values, 3 per normal. */
+    readonly normals: number[];
+    /**
+     * Triangulated face corners as zero-based `position, texcoord, normal` triplets.
+     * A missing texcoord or normal is -1.
+     */
+    readonly faceIndices: number[];
+}
+
+/**
+ * Renderable geometry as plain data: one vertex per unique position/texcoord/normal/material corner.
+ * Has no dependency on any engine; convert it to engine geometry yourself.
+ */
+export interface ObjGeometryDefinition {
+    /** Positions, 3 per vertex. */
+    readonly positions: number[];
+    /** Texture coordinates, 2 per vertex (0,0 when the corner has none). */
+    readonly textureCoords: number[];
+    /** Normals, 3 per vertex (0,0,0 when the corner has none). */
+    readonly normals: number[];
+    /** RGBA colours, 4 per vertex: the material's `Kd` with alpha from `d`, white without a material. */
+    readonly colors: number[];
+    /** Triangle indices, 3 per triangle. */
+    readonly indices: number[];
+    /** Number of vertices (`positions.length / 3`). */
+    readonly vertexCount: number;
+    /** Index ranges per `usemtl`, in file order. */
+    readonly materialRanges: ObjMaterialRange[];
+}
+
+/** The result of loading an OBJ file. */
+export interface ObjLoadResult {
+    /** The renderable geometry as plain data. */
+    readonly geometry: ObjGeometryDefinition;
+    /** Material definitions from the referenced .mtl files. Empty when there is no `mtllib` or it could not be loaded. */
+    readonly materials: ObjMaterialDefinition[];
+    /** Library file names from `mtllib`, in order. */
+    readonly materialLibraries: string[];
+    /** The raw OBJ lists. */
+    readonly raw: ObjRawData;
+}
+
+/** Options for {@link ObjParser.loadAsync} and `ObjLoader.loadAsync`. */
+export interface ObjLoadOptions {
+    /**
+     * Maps an `mtllib` name to the URL to fetch.
+     * By default, the name is resolved relative to the OBJ URL, which fails for `data:` or `blob:` URLs
+     * (for example a bundler-inlined asset); use this to point at the real file.
+     */
+    resolveMaterialUrl?: (libraryName: string) => string;
+    /** Skip fetching .mtl files. */
+    ignoreMaterials?: boolean;
+}
+
+/** One `usemtl` range of an {@link ObjModel}: its index range and resolved material definition. */
+export interface ObjSubMesh {
+    /** The material name from `usemtl`, or undefined for faces before any `usemtl`. */
+    readonly materialName?: string;
+    /** The material definition from the .mtl files, or undefined when there is none. */
+    readonly material?: ObjMaterialDefinition;
+    /** First index in `geometry.indices`. */
+    readonly indexStart: number;
+    /** Number of indices. */
+    readonly indexCount: number;
+}
+
+/** A parsed OBJ model (C# `ObjModel`): geometry, sub meshes and material definitions. No GPU resources. */
+export interface ObjModel extends ObjLoadResult {
+    /** One entry per `usemtl` range, in file order. */
+    readonly subMeshes: ObjSubMesh[];
+}

package/src/api/loaders/obj/index.ts

@@ -0,0 +1,5 @@
+/*
+ * OBJ/MTL loader. Self-contained: no imports outside this folder.
+ */
+export * from "./ObjTypes.ts";
+export * from "./ObjParser.ts";