canvas-js-3d 0.1.0

package/README.md

@@ -0,0 +1,15 @@
+Canvas JS 3D is a lightweight 3D graphics library that uses the Canvas API for wireframe rendering. The library has zero dependencies and is written in purely vanilla JavaScript.
+
+
+
+Features
+
+* Pure JavaScript - No external dependencies
+* ES6 Modules - Clean, modular architecture
+* Wavefront OBJ Loading - Import 3D models from .obj files
+* Wireframe Rendering - Canvas 2D-based edge rendering
+* Transform System - Position, rotation, and scale
+* Frame Update Hook - Per-frame client logic with delta-time for framerate-independent animations
+* Scene Object System - Manage multiple meshes with independent transforms
+* Mobile Responsive Demo - Touch-friendly demo with responsive layout
+

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "canvas-js-3d",
+  "version": "0.1.0",
+  "description": "Canvas JS 3D is a lightweight 3D graphics library that uses the Canvas API for wireframe rendering.",
+  "type": "module",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./wavefront-loading": "./src/wavefront-loading/index.js"
+  },
+  "files": [
+    "src/"
+  ],
+  "scripts": {
+    "dev": "npx http-server -p 8080 -c-1"
+  },
+  "keywords": [
+    "3d",
+    "graphics",
+    "canvas",
+    "wireframe",
+    "obj",
+    "wavefront"
+  ],
+  "author": {
+  "name": "Sebastian Bathrick",
+  "email": "sebastianbathrick@gmail.com"
+},
+  "license": "MIT"
+}

package/src/core/engine.js

@@ -0,0 +1,108 @@
+import { Renderer } from '../rendering/renderer.js';
+import { Camera } from '../rendering/camera.js';
+import { Vector2 } from '../math/vector2.js';
+
+/**
+ * The main engine that manages the render loop, camera, and scene objects.
+ */
+export class Engine {
+    /**
+     * Creates a new Engine.
+     * @param {HTMLCanvasElement} canvas - The canvas element to render to.
+     * @param {string} fgColor - The foreground/wireframe color.
+     * @param {string} bgColor - The background/clear color.
+     */
+    constructor(canvas, fgColor, bgColor) {
+        /** @type {Renderer} */
+        this.renderer = new Renderer(canvas, fgColor, bgColor);
+        /** @type {Camera} */
+        this.camera = new Camera(new Vector2(canvas.width, canvas.height));
+        /** @type {SceneObject[]} */
+        this.sceneObjects = [];
+        /** @type {boolean} */
+        this.running = false;
+        /** @type {number|null} */
+        this.lastFrameTime = null;
+        /**
+         * Callback invoked each frame with delta time.
+         * @type {((deltaTime: number) => void)|null}
+         */
+        this.onUpdate = null;
+    }
+
+    /**
+     * Internal frame update loop. Calculates delta time, calls onUpdate, and renders.
+     * @private
+     */
+    frameUpdate() {
+        if (!this.running)
+            return;
+
+        const now = performance.now();
+        const deltaTime = this.lastFrameTime ? (now - this.lastFrameTime) / 1000 : 0;
+        this.lastFrameTime = now;
+
+        if (this.onUpdate)
+            this.onUpdate(deltaTime);
+
+        this.renderer.clear();
+        this.renderAllObjects();
+
+        requestAnimationFrame(() => this.frameUpdate());
+    }
+
+    /**
+     * Renders all scene objects as wireframes.
+     * @private
+     */
+    renderAllObjects() {
+        for (const obj of this.sceneObjects) {
+            const projectedFaces = this.camera.projectSceneObject(obj);
+
+            for (const face of projectedFaces) {
+                const positions = face.screenPositions;
+
+                for (let i = 0; i < positions.length; i++) {
+                    this.renderer.renderEdge(
+                        positions[i],
+                        positions[(i + 1) % positions.length]
+                    );
+                }
+            }
+        }
+    }
+
+    /**
+     * Adds a scene object to be rendered.
+     * @param {SceneObject} sceneObject - The object to add.
+     */
+    addSceneObject(sceneObject) {
+        this.sceneObjects.push(sceneObject);
+    }
+
+    /**
+     * Removes a scene object from rendering.
+     * @param {SceneObject} sceneObject - The object to remove.
+     */
+    removeSceneObject(sceneObject) {
+        const idx = this.sceneObjects.indexOf(sceneObject);
+
+        if (idx !== -1)
+            this.sceneObjects.splice(idx, 1);
+    }
+
+    /**
+     * Starts the render loop.
+     */
+    start() {
+        this.running = true;
+        this.frameUpdate();
+    }
+
+    /**
+     * Stops the render loop.
+     */
+    stop() {
+        this.running = false;
+    }
+}

package/src/core/mesh.js

@@ -0,0 +1,32 @@
+/**
+ * Represents a 3D mesh with vertices and face index definitions.
+ */
+export class Mesh {
+    /**
+     * Creates a new Mesh.
+     * @param {Vector3[]} vertices - Array of vertex positions.
+     * @param {number[][]} faceIndices - Array of faces, each face is an array of vertex indices.
+     */
+    constructor(vertices, faceIndices) {
+        /** @type {Vector3[]} */
+        this.vertices = vertices;
+        /** @type {number[][]} */
+        this.faceIndices = faceIndices;
+    }
+
+    /**
+     * Gets the vertices of the mesh.
+     * @returns {Vector3[]} The vertex array.
+     */
+    getVertices() {
+        return this.vertices;
+    }
+
+    /**
+     * Gets the face indices of the mesh.
+     * @returns {number[][]} Array of faces, each containing vertex indices.
+     */
+    getFaceIndices() {
+        return this.faceIndices;
+    }
+}

package/src/core/sceneObject.js

@@ -0,0 +1,45 @@
+/**
+ * An object with a position, rotation, scale, and mesh in the scene.
+ */
+export class SceneObject {
+    /**
+     * Creates a new SceneObject.
+     * @param {Mesh} mesh - The mesh geometry.
+     * @param {Transform} transform - The position, rotation, and scale.
+     */
+    constructor(mesh, transform) {
+        /** @type {Mesh} */
+        this.mesh = mesh;
+        /** @type {Transform} */
+        this.transform = transform;
+    }
+
+    /**
+     * Gets the mesh geometry.
+     * @returns {Mesh} The mesh.
+     */
+    getMesh() {
+        return this.mesh;
+    }
+
+    /**
+     * Gets the transform.
+     * @returns {Transform} The transform.
+     */
+    getTransform() {
+        return this.transform;
+    }
+
+    /**
+     * Gets all vertices transformed to scene's world space.
+     * Applies transformations in order: scale → rotate → translate.
+     * @returns {Vector3[]} Array of transformed vertex positions.
+     */
+    getSceneVertices() {
+        return this.mesh.vertices.map(v =>
+            v.getScaled(this.transform.scale)
+             .getRotatedXZ(this.transform.rotation)
+             .getTranslated(this.transform.position)
+        );
+    }
+}

package/src/index.js

@@ -0,0 +1,26 @@
+/**
+ * canvas-js-3d - A lightweight 3D graphics library that uses the Canvas API for wireframe rendering.
+ * @module canvas-js-3d
+ */
+
+// Core math
+export { Vector2 } from './math/vector2.js';
+export { Vector3 } from './math/vector3.js';
+export { Transform } from './math/transform.js';
+
+// Scene components
+export { Mesh } from './core/mesh.js';
+export { SceneObject } from './core/sceneObject.js';
+
+// Rendering
+export { Camera } from './rendering/camera.js';
+export { Renderer } from './rendering/renderer.js';
+
+// Engine
+export { Engine } from './core/engine.js';
+
+// OBJ loading
+export { WavefrontMeshConverter } from './wavefront-loading/wavefront-mesh-converter.js';
+export { WavefrontFileLoader } from './wavefront-loading/wavefront-file-loader.js';
+export { WavefrontLexer } from './wavefront-loading/wavefront-lexer.js';
+export { WavefrontParser } from './wavefront-loading/wavefront-parser.js';

package/src/math/transform.js

@@ -0,0 +1,43 @@
+/**
+ * Represents the position, rotation, and scale of an object in 3D space.
+ */
+export class Transform {
+    /**
+     * Creates a new Transform.
+     * @param {Vector3} position - The position in 3D space.
+     * @param {number} rotation - The rotation angle in radians (XZ plane only).
+     * @param {number} scale - The uniform scale factor.
+     */
+    constructor(position, rotation, scale) {
+        /** @type {Vector3} */
+        this.position = position;
+        /** @type {number} */
+        this.rotation = rotation;
+        /** @type {number} */
+        this.scale = scale;
+    }
+
+    /**
+     * Translates the position by the given vector.
+     * @param {Vector3} translation - The translation to apply.
+     */
+    translate(translation) {
+        this.position = this.position.getTranslated(translation);
+    }
+
+    /**
+     * Rotates around the Y axis by the given angle.
+     * @param {number} angle - The angle to rotate by in radians.
+     */
+    rotateXZ(angle) {
+        this.rotation += angle;
+    }
+
+    /**
+     * Multiplies the scale by a scalar value.
+     * @param {number} scalar - The scalar to multiply by.
+     */
+    scaleBy(scalar) {
+        this.scale *= scalar;
+    }
+}

package/src/math/vector2.js

@@ -0,0 +1,40 @@
+/**
+ * A 2D vector class for screen coordinates and 2D math operations.
+ * Methods return new instances (immutable style).
+ */
+export class Vector2 {
+    /**
+     * Creates a new Vector2.
+     * @param {number} x - The x component.
+     * @param {number} y - The y component.
+     */
+    constructor(x, y) {
+        this.x = x;
+        this.y = y;
+    }
+
+    /**
+     * Checks if both x and y are zero.
+     * @returns {boolean} True if the vector is zero.
+     */
+    isZero() {
+        return this.x === 0 && this.y === 0;
+    }
+
+    /**
+     * Gets a unit vector pointing in the same direction.
+     * @returns {Vector2} A new normalized vector.
+     */
+    getNormalized() {
+        const mag = Math.sqrt(this.x * this.x + this.y * this.y);
+        return new Vector2(this.x / mag, this.y / mag);
+    }
+
+    /**
+     * Gets the length of the vector.
+     * @returns {number} The magnitude.
+     */
+    getMagnitude() {
+        return Math.sqrt(this.x * this.x + this.y * this.y);
+    }
+}

package/src/math/vector3.js

@@ -0,0 +1,115 @@
+/**
+ * A 3D vector class for positions and directions in 3D space.
+ * Methods return new instances (immutable style).
+ */
+export class Vector3 {
+    /**
+     * Creates a new Vector3.
+     * @param {number} x - The x component.
+     * @param {number} y - The y component.
+     * @param {number} z - The z component.
+     */
+    constructor(x, y, z) {
+        this.x = x;
+        this.y = y;
+        this.z = z;
+    }
+
+    /**
+     * The zero vector (0, 0, 0).
+     * @type {Vector3}
+     */
+    static zero = Object.freeze(new Vector3(0, 0, 0));
+
+    /**
+     * The one vector (1, 1, 1).
+     * @type {Vector3}
+     */
+    static one = Object.freeze(new Vector3(1, 1, 1));
+
+    /**
+     * The left direction (-1, 0, 0).
+     * @type {Vector3}
+     */
+    static left = Object.freeze(new Vector3(-1, 0, 0));
+
+    /**
+     * The right direction (1, 0, 0).
+     * @type {Vector3}
+     */
+    static right = Object.freeze(new Vector3(1, 0, 0));
+
+    /**
+     * The up direction (0, 1, 0).
+     * @type {Vector3}
+     */
+    static up = Object.freeze(new Vector3(0, 1, 0));
+
+    /**
+     * The down direction (0, -1, 0).
+     * @type {Vector3}
+     */
+    static down = Object.freeze(new Vector3(0, -1, 0));
+
+    /**
+     * Returns a new vector translated by the given direction.
+     * @param {Vector3} dir - The direction to translate by.
+     * @returns {Vector3} A new translated vector.
+     */
+    getTranslated(dir) {
+        return new Vector3(this.x + dir.x, this.y + dir.y, this.z + dir.z);
+    }
+
+    /**
+     * Returns a new vector rotated around the Y axis (XZ plane rotation).
+     * @param {number} angle - The rotation angle in radians.
+     * @returns {Vector3} A new rotated vector.
+     */
+    getRotatedXZ(angle) {
+        const cos = Math.cos(angle);
+        const sin = Math.sin(angle);
+
+        return new Vector3(
+            this.x * cos - this.z * sin,
+            this.y,
+            this.x * sin + this.z * cos
+        );
+    }
+
+    /**
+     * Returns a new vector scaled by a scalar value.
+     * @param {number} scalar - The scalar to multiply by.
+     * @returns {Vector3} A new scaled vector.
+     */
+    getScaled(scalar) {
+        return new Vector3(this.x * scalar, this.y * scalar, this.z * scalar);
+    }
+
+    /**
+     * Checks if all components are zero.
+     * @returns {boolean} True if the vector is zero.
+     */
+    isZero() {
+        return this.x === 0 && this.y === 0 && this.z === 0;
+    }
+
+    /**
+     * Gets a unit vector pointing in the same direction.
+     * @returns {Vector3} A new normalized vector, or zero vector if magnitude is 0.
+     */
+    getNormalized() {
+        const mag = Math.sqrt(this.x * this.x + this.y * this.y + this.z * this.z);
+
+        if (mag === 0) return Vector3.zero;
+
+        return new Vector3(this.x / mag, this.y / mag, this.z / mag);
+    }
+
+    /**
+     * Gets the length of the vector.
+     * @returns {number} The magnitude.
+     */
+    getMagnitude() {
+        return Math.sqrt(this.x * this.x + this.y * this.y + this.z * this.z);
+    }
+}

package/src/rendering/camera.js

@@ -0,0 +1,87 @@
+import { Vector2 } from '../math/vector2.js';
+
+/**
+ * Projects 3D scene coordinates to 2D screen coordinates.
+ */
+export class Camera {
+    /**
+     * Creates a new Camera.
+     * @param {Vector2} screenSize - The canvas dimensions (width, height).
+     */
+    constructor(screenSize) {
+        /** @type {Vector2} */
+        this.screenSize = screenSize;
+    }
+
+    /**
+     * Projects all faces of a scene object to screen coordinates.
+     * @param {SceneObject} sceneObject - The scene object to project.
+     * @returns {{screenPositions: Vector2[]}[]} Array of projected faces with screen positions.
+     */
+    projectSceneObject(sceneObject) {
+        const sceneVerts = sceneObject.getSceneVertices();
+        const projectedFaces = [];
+        
+        // Map vertices to their associated face indices
+        for (const face of sceneObject.getMesh().getFaceIndices()) {
+            const faceVerts = face.map(idx => sceneVerts[idx]);
+            const screenPositions = this.getScreenPositions(faceVerts);
+            
+            projectedFaces.push({ screenPositions });
+        }
+
+        return projectedFaces;
+    }
+
+    /**
+     * Converts a normalized screen position to a screen position based on the screen's/canvas's size.
+     * @param {Vector2} normScreenPos - The normalized screen position of a point
+     * @returns {Vector2} The screen position of the point relative to the screen's/canvas's size
+     */
+    getScaledScreenPosition(normScreenPos) {
+        /* Currently (0, 0) is the top left corner of the canvas
+
+        * Convert from normalized coordinates to respective screen coordinates based on the canvas size:
+
+        * (0, 0) -> (canvas width / 2, canvas height / 2) = Center of the canvas
+        * (-1, 1) -> (canvas width / 2, -(canvas height / 2)) = Top right corner of the canvas
+        * (1, -1) -> (-(canvas width / 2), canvas height / 2) = Bottom left corner of the canvas
+        */
+
+        return new Vector2(
+            (normScreenPos.x + 1) / 2 * this.screenSize.x, 
+            (1 - (normScreenPos.y + 1) / 2) * this.screenSize.y);
+    }
+
+    /**
+     * Converts a point's 3D position in the scene to a normalized screen position by dividing x and y by z individually.
+     * @param {Vector3} scenePos - The 3D position of a point in the scene
+     * @returns {Vector2} The normalized screen position of the point
+     */
+    getNormalizedScreenPosition(scenePos) {
+        /* 
+        * If > 0 the point is in front of the camera, if <= 0 the point is not visible, because the divisor 
+        * would be zero. Thus it is in the same 3D position as the camera. As z increases the 3D point moves 
+        * further away from the camera. */
+
+        return new Vector2(scenePos.x / scenePos.z, scenePos.y / scenePos.z);
+    }
+
+    /**
+     * Projects a 3D position to screen pixel coordinates.
+     * @param {Vector3} scenePos - The 3D position in scene/world space.
+     * @returns {Vector2} The position in pixel coordinates.
+     */
+    getVertexScreenPos(scenePos) {
+        return this.getScaledScreenPosition(this.getNormalizedScreenPosition(scenePos));
+    }
+
+    /**
+     * Projects multiple 3D positions to screen pixel coordinates.
+     * @param {Vector3[]} vertices - Array of 3D positions.
+     * @returns {Vector2[]} Array of screen positions in pixels.
+     */
+    getScreenPositions(vertices) {
+        return vertices.map(v => this.getVertexScreenPos(v));
+    }
+}

package/src/rendering/renderer.js

@@ -0,0 +1,58 @@
+/**
+ * Handles drawing wireframe graphics to a Canvas 2D context.
+ */
+export class Renderer {
+    /**
+     * Creates a new Renderer.
+     * @param {HTMLCanvasElement} canvas - The canvas element to render to.
+     * @param {string} fgColor - The foreground/stroke color (e.g., 'green', '#00ff00').
+     * @param {string} bgColor - The background/clear color (e.g., 'black', '#000000').
+     */
+    constructor(canvas, fgColor, bgColor) {
+        /** @type {HTMLCanvasElement} */
+        this.canvas = canvas;
+        /** @type {CanvasRenderingContext2D} */
+        this.ctx = canvas.getContext('2d');
+        /** @type {string} */
+        this.fgColor = fgColor;
+        /** @type {string} */
+        this.bgColor = bgColor;
+        /** @type {number} */
+        this.pointSize = 20;
+    }
+
+    /**
+     * Clears the canvas with the background color.
+     */
+    clear() {
+        this.ctx.fillStyle = this.bgColor;
+        this.ctx.fillRect(0, 0, this.canvas.width, this.canvas.height);
+    }
+
+    /**
+     * Renders a line between two screen positions.
+     * @param {Vector2} startVector2 - The start position in screen coordinates.
+     * @param {Vector2} endVector2 - The end position in screen coordinates.
+     */
+    renderEdge(startVector2, endVector2) {
+        this.ctx.strokeStyle = this.fgColor;
+        this.ctx.beginPath();
+        this.ctx.moveTo(startVector2.x, startVector2.y);
+        this.ctx.lineTo(endVector2.x, endVector2.y);
+        this.ctx.stroke();
+    }
+
+    /**
+     * Renders a point as a square at the given screen position.
+     * @param {Vector2} vector2 - The position in screen coordinates.
+     */
+    renderPoint(vector2) {
+        this.ctx.fillStyle = this.fgColor;
+        this.ctx.fillRect(
+            vector2.x - this.pointSize / 2,
+            vector2.y - this.pointSize / 2,
+            this.pointSize,
+            this.pointSize
+        );
+    }
+}

package/src/wavefront-loading/index.js

@@ -0,0 +1,9 @@
+/**
+ * Wavefront OBJ file loading module.
+ * @module canvas-js-3d/wavefront-loading
+ */
+
+export { WavefrontMeshConverter } from './wavefront-mesh-converter.js';
+export { WavefrontFileLoader } from './wavefront-file-loader.js';
+export { WavefrontLexer } from './wavefront-lexer.js';
+export { WavefrontParser } from './wavefront-parser.js';

package/src/wavefront-loading/wavefront-file-loader.js

@@ -0,0 +1,64 @@
+/**
+ * Handles loading OBJ file content from various sources (URL, File, file dialog).
+ */
+export class WavefrontFileLoader {
+    /**
+     * Loads OBJ file content from an HTTP URL.
+     * @param {string} url - The URL to fetch the OBJ file from.
+     * @returns {Promise<string>} The text content of the OBJ file.
+     * @throws {Error} If the fetch request fails.
+     */
+    static async loadFromUrl(url) {
+        const response = await fetch(url);
+
+        if (!response.ok)
+            throw new Error(`Failed to load OBJ file: ${response.status} ${response.statusText}`);
+
+        return await response.text();
+    }
+
+    /**
+     * Loads OBJ file content from a File object.
+     * @param {File} file - The File object from an input element.
+     * @returns {Promise<string>} The text content of the OBJ file.
+     * @throws {Error} If reading the file fails.
+     */
+    static async loadFromFile(file) {
+        return new Promise((resolve, reject) => {
+            const reader = new FileReader();
+
+            reader.onload = () => resolve(reader.result);
+            reader.onerror = () => reject(new Error('Failed to read file'));
+
+            reader.readAsText(file);
+        });
+    }
+
+    /**
+     * Opens a file dialog for the user to select an OBJ file.
+     * @returns {Promise<string>} The text content of the selected OBJ file.
+     * @throws {Error} If no file is selected or reading fails.
+     */
+    static async loadFromFileDialog() {
+        return new Promise((resolve, reject) => {
+            const input = document.createElement('input');
+            input.type = 'file';
+            input.accept = '.obj';
+
+            input.onchange = async () => {
+                if (input.files && input.files[0]) {
+                    try {
+                        const text = await this.loadFromFile(input.files[0]);
+                        resolve(text);
+                    } catch (err) {
+                        reject(err);
+                    }
+                } else {
+                    reject(new Error('No file selected'));
+                }
+            };
+
+            input.click();
+        });
+    }
+}

package/src/wavefront-loading/wavefront-lexer.js

@@ -0,0 +1,193 @@
+/**
+ * Tokenizes OBJ file content into a stream of tokens.
+ * Produces tokens of type: KEYWORD, NUMBER, SLASH, NEWLINE, EOF.
+ */
+export class WavefrontLexer {
+    /**
+     * Creates a new WavefrontLexer.
+     * @param {string} source - The OBJ file content to tokenize.
+     */
+    constructor(source) {
+        /** @type {string} */
+        this.source = source;
+        /** @type {Array<{type: string, value: *}>} */
+        this.tokens = [];
+        /** @type {number} */
+        this.start = 0;
+        /** @type {number} */
+        this.current = 0;
+    }
+
+    /**
+     * Tokenizes all content and returns the token array.
+     * @returns {Array<{type: string, value: *}>} Array of token objects.
+     */
+    lexTokens() {
+        while (!this.isAtEnd()) {
+            this.start = this.current;
+            this.lexToken();
+        }
+
+        this.tokens.push({ type: 'EOF', value: null });
+        return this.tokens;
+    }
+
+    /**
+     * Lexes a single token from the current position.
+     * @private
+     */
+    lexToken() {
+        const c = this.advance();
+
+        // Skip whitespace (except newlines)
+        if (c === ' ' || c === '\t' || c === '\r')
+            return;
+
+        // Newline
+        if (c === '\n') {
+            this.tokens.push({ type: 'NEWLINE', value: '\n' });
+            return;
+        }
+
+        // Comment - skip to end of line
+        if (c === '#') {
+            while (this.peek() !== '\n' && !this.isAtEnd())
+                this.advance();
+            return;
+        }
+
+        // Slash (for face format like 1/2/3)
+        if (c === '/') {
+            this.tokens.push({ type: 'SLASH', value: '/' });
+            return;
+        }
+
+        // Number (including negative)
+        if (this.isDigit(c) || (c === '-' && this.isDigit(this.peek()))) {
+            this.lexNumber();
+            return;
+        }
+
+        // Keyword/identifier
+        if (this.isAlpha(c)) {
+            this.lexKeyword();
+            return;
+        }
+    }
+
+    /**
+     * Lexes a number token (integer, float, or scientific notation).
+     * @private
+     */
+    lexNumber() {
+        // Consume digits before decimal
+        while (this.isDigit(this.peek()))
+            this.advance();
+
+        // Look for decimal part
+        if (this.peek() === '.' && this.isDigit(this.peekNext())) {
+            this.advance(); // consume '.'
+
+            while (this.isDigit(this.peek()))
+                this.advance();
+        }
+
+        // Handle scientific notation (e.g., 1.5e-10)
+        if (this.peek() === 'e' || this.peek() === 'E') {
+            this.advance(); // consume 'e'
+
+            if (this.peek() === '+' || this.peek() === '-')
+                this.advance(); // consume sign
+
+            while (this.isDigit(this.peek()))
+                this.advance();
+        }
+
+        const value = parseFloat(this.source.substring(this.start, this.current));
+        this.tokens.push({ type: 'NUMBER', value: value });
+    }
+
+    /**
+     * Lexes a keyword token.
+     * @private
+     */
+    lexKeyword() {
+        while (this.isAlphaNumeric(this.peek()))
+            this.advance();
+
+        const value = this.source.substring(this.start, this.current);
+        this.tokens.push({ type: 'KEYWORD', value: value });
+    }
+
+    /**
+     * Returns the current character and advances the position.
+     * @returns {string} The current character.
+     * @private
+     */
+    advance() {
+        return this.source.charAt(this.current++);
+    }
+
+    /**
+     * Returns the current character without advancing.
+     * @returns {string} The current character, or '\0' if at end.
+     * @private
+     */
+    peek() {
+        if (this.isAtEnd())
+            return '\0';
+
+        return this.source.charAt(this.current);
+    }
+
+    /**
+     * Returns the next character without advancing.
+     * @returns {string} The next character, or '\0' if at end.
+     * @private
+     */
+    peekNext() {
+        if (this.current + 1 >= this.source.length)
+            return '\0';
+
+        return this.source.charAt(this.current + 1);
+    }
+
+    /**
+     * Checks if we've reached the end of the source.
+     * @returns {boolean} True if at end.
+     * @private
+     */
+    isAtEnd() {
+        return this.current >= this.source.length;
+    }
+
+    /**
+     * Checks if a character is a digit (0-9).
+     * @param {string} c - The character to check.
+     * @returns {boolean} True if digit.
+     * @private
+     */
+    isDigit(c) {
+        return c >= '0' && c <= '9';
+    }
+
+    /**
+     * Checks if a character is alphabetic (a-z, A-Z, _).
+     * @param {string} c - The character to check.
+     * @returns {boolean} True if alphabetic.
+     * @private
+     */
+    isAlpha(c) {
+        return (c >= 'a' && c <= 'z') || (c >= 'A' && c <= 'Z') || c === '_';
+    }
+
+    /**
+     * Checks if a character is alphanumeric.
+     * @param {string} c - The character to check.
+     * @returns {boolean} True if alphanumeric.
+     * @private
+     */
+    isAlphaNumeric(c) {
+        return this.isAlpha(c) || this.isDigit(c);
+    }
+}

package/src/wavefront-loading/wavefront-mesh-converter.js

@@ -0,0 +1,54 @@
+import { WavefrontFileLoader } from './wavefront-file-loader.js';
+import { WavefrontLexer } from './wavefront-lexer.js';
+import { WavefrontParser } from './wavefront-parser.js';
+import { Mesh } from '../core/mesh.js';
+
+/**
+ * High-level API for loading OBJ files and converting them to Mesh objects.
+ * Orchestrates the file loading, lexing, and parsing pipeline.
+ */
+export class WavefrontMeshConverter {
+    /**
+     * Loads an OBJ file from a URL and converts it to a Mesh.
+     * @param {string} url - The URL to fetch the OBJ file from.
+     * @returns {Promise<Mesh>} The loaded mesh.
+     */
+    static async fromUrl(url) {
+        const text = await WavefrontFileLoader.loadFromUrl(url);
+        return this.fromText(text);
+    }
+
+    /**
+     * Loads an OBJ file from a File object and converts it to a Mesh.
+     * @param {File} file - The File object from an input element.
+     * @returns {Promise<Mesh>} The loaded mesh.
+     */
+    static async fromFile(file) {
+        const text = await WavefrontFileLoader.loadFromFile(file);
+        return this.fromText(text);
+    }
+
+    /**
+     * Opens a file dialog and converts the selected OBJ file to a Mesh.
+     * @returns {Promise<Mesh>} The loaded mesh.
+     */
+    static async fromFileDialog() {
+        const text = await WavefrontFileLoader.loadFromFileDialog();
+        return this.fromText(text);
+    }
+
+    /**
+     * Converts OBJ text content directly to a Mesh.
+     * @param {string} text - The OBJ file content as a string.
+     * @returns {Mesh} The parsed mesh.
+     */
+    static fromText(text) {
+        const lexer = new WavefrontLexer(text);
+        const tokens = lexer.lexTokens();
+
+        const parser = new WavefrontParser(tokens);
+        const { vertices, faceIndices } = parser.parse();
+
+        return new Mesh(vertices, faceIndices);
+    }
+}

package/src/wavefront-loading/wavefront-parser.js

@@ -0,0 +1,178 @@
+import { Vector3 } from '../math/vector3.js';
+
+/**
+ * Parses OBJ tokens into vertices and face indices.
+ * Handles 'v' (vertex) and 'f' (face) keywords, ignoring texture coords and normals.
+ */
+export class WavefrontParser {
+    /**
+     * Creates a new WavefrontParser.
+     * @param {Array<{type: string, value: *}>} tokens - The tokens from WavefrontLexer.
+     */
+    constructor(tokens) {
+        /** @type {Array<{type: string, value: *}>} */
+        this.tokens = tokens;
+        /** @type {number} */
+        this.current = 0;
+        /** @type {Vector3[]} */
+        this.vertices = [];
+        /** @type {number[][]} */
+        this.faceIndices = [];
+    }
+
+    /**
+     * Parses all tokens and returns the extracted mesh data.
+     * @returns {{vertices: Vector3[], faceIndices: number[][]}} The parsed mesh data.
+     */
+    parse() {
+        while (!this.isAtEnd()) {
+            this.parseStatement();
+        }
+
+        return {
+            vertices: this.vertices,
+            faceIndices: this.faceIndices
+        };
+    }
+
+    /**
+     * Parses a single statement (line).
+     * @private
+     */
+    parseStatement() {
+        const token = this.peek();
+
+        // Skip newlines
+        if (token.type === 'NEWLINE') {
+            this.advance();
+            return;
+        }
+
+        // Handle keywords
+        if (token.type === 'KEYWORD') {
+            const keyword = token.value;
+
+            if (keyword === 'v') {
+                this.advance(); // consume 'v'
+                this.parseVertex();
+            } else if (keyword === 'f') {
+                this.advance(); // consume 'f'
+                this.parseFace();
+            } else {
+                // Unknown keyword - skip to end of line
+                this.skipToNextLine();
+            }
+            return;
+        }
+
+        // Skip anything else
+        this.advance();
+    }
+
+    /**
+     * Parses a vertex definition (v x y z).
+     * @private
+     */
+    parseVertex() {
+        const x = this.consumeNumber();
+        const y = this.consumeNumber();
+        const z = this.consumeNumber();
+
+        this.vertices.push(new Vector3(x, y, z));
+        this.skipToNextLine();
+    }
+
+    /**
+     * Parses a face definition (f v1 v2 v3 ... or f v1/vt1/vn1 ...).
+     * Converts OBJ's 1-indexed vertices to 0-indexed.
+     * @private
+     */
+    parseFace() {
+        const indices = [];
+
+        // Consume all vertex indices until newline or EOF
+        while (!this.isAtEnd() && this.peek().type !== 'NEWLINE') {
+            if (this.peek().type === 'NUMBER') {
+                // Get vertex index (1-indexed in OBJ, convert to 0-indexed)
+                const vertexIndex = this.consumeNumber() - 1;
+                indices.push(vertexIndex);
+
+                // Skip texture/normal indices (e.g., /2/3)
+                while (this.peek().type === 'SLASH') {
+                    this.advance(); // consume '/'
+
+                    // Consume the index after slash if present
+                    if (this.peek().type === 'NUMBER')
+                        this.advance();
+                }
+            } else {
+                this.advance();
+            }
+        }
+
+        if (indices.length >= 3)
+            this.faceIndices.push(indices);
+
+        this.skipToNextLine();
+    }
+
+    /**
+     * Consumes and returns a number token value.
+     * @returns {number} The number value, or 0 if not a number token.
+     * @private
+     */
+    consumeNumber() {
+        const token = this.peek();
+
+        if (token.type === 'NUMBER') {
+            this.advance();
+            return token.value;
+        }
+
+        // Return 0 if no number found (error case)
+        return 0;
+    }
+
+    /**
+     * Skips tokens until the next newline or EOF.
+     * @private
+     */
+    skipToNextLine() {
+        while (!this.isAtEnd() && this.peek().type !== 'NEWLINE')
+            this.advance();
+
+        // Consume the newline
+        if (!this.isAtEnd() && this.peek().type === 'NEWLINE')
+            this.advance();
+    }
+
+    /**
+     * Returns the current token without advancing.
+     * @returns {{type: string, value: *}} The current token.
+     * @private
+     */
+    peek() {
+        return this.tokens[this.current];
+    }
+
+    /**
+     * Returns the current token and advances the position.
+     * @returns {{type: string, value: *}} The current token.
+     * @private
+     */
+    advance() {
+        if (!this.isAtEnd())
+            this.current++;
+
+        return this.tokens[this.current - 1];
+    }
+
+    /**
+     * Checks if we've reached the end of tokens.
+     * @returns {boolean} True if at end or at EOF token.
+     * @private
+     */
+    isAtEnd() {
+        return this.current >= this.tokens.length || this.peek().type === 'EOF';
+    }
+}