obj-renderer v0.2.1

OBJ Renderer

A simple library to parse and render Wavefront 3D (.OBJ) files and Material Template Library (.MTL) files.

Installation

npm install obj-renderer

Examples

This repository comes with an easy to run demonstration using webpack development server. To see the example application, clone this repo, run npm install, then npm run examples. Then open localhost:8080 in a browser tab.

Renderer

The principle type of object used with this library is a Renderer. A renderer performs the task of rendering a given scene over a canvas, and limits the rendering to a rectangular area of the canvas (the viewport).

const Renderer = require('obj-renderer').Renderer;

// Create a renderer for drawing to an HTML canvas element
const renderer = new Renderer(canvas);

// Customize rendering parameters
renderer.setClearColor(0, 0, 255); // blue backdrop

// Load model(s) from .obj files.
// These are then referenced by the objects in a scene to draw models to given locations within the scene.
const crateModel = require('raw-loader!./Crate.obj'); // gets file's contents as a string
const otherModels = require('raw-loader!./OtherModels.obj');
renderer.loadOBJFile(crateModel, 'Crate'); // Gives an untitled object (one with no preceding "o modelName" statement) a name
renderer.loadOBJFile(otherModels);

// Draw a scene of objects to the canvas
renderer.renderScene(myScene);

Scene

A scene object represents a 3D world, with a camera, and an array scene objects. The objects can themselves have objects, forming a hierarchy of objects under the scene. A scene can be constructed and initialized by passing in an object literal:

  const Scene = require('obj-renderer').Scene;

  const myScene = new Scene({
    camera: {
      x: 0,
      y: 2,
      z: 10,
      rx: -20
    },
    objects: [
      { 
        modelName: 'Box',
        x: 0,
        y: 0,
        z: 0
      },
      {
        name: 'parentBox',
        modelName: 'Crate',
        x: 0,
        y: 1,
        z: 0,
        objects: [
          { 
            name: 'childBox',
            modelName: 'Crate',
            x: 3,
            y: 0,
            z: 0,
            sx: 0.5,
            sy: 0.5,
            sz: 0.5,
            rx: 0,
            ry: 0,
            rz: 0
          }
        ]
      }
    ]
  });

Scene Objects

A scene object represents a 3D object that can be placed in a scene. Each scene object can be directly attached to the scene, or another object within a scene.

Each scene object has a position, scale and rotation, that positions it relative to its parent object (or the scene itself for top-level objects).

Rotation:

The rotation of an object is specified by three Euler angles, which are applied sequentially in order of x, y then z, relative to the parent object.

• rx rotates the object in degrees, clockwise (when facing the direction the x-axis points) around the x-axis.
• ry rotates the object in degrees, clockwise (when facing the direction the y-axis points) around the y-axis.
• rz rotates the object in degrees, clockwise (when facing the direction the z-axis points) around the z-axis.

Scale:

• sx scales the object by a float, in the x-axis
• sy scales the object by a float, in the y-axis
• sz scales the object by a float, in the z-axis

Position:

Each object is positioned in space relative to its parent, by three signed floats, following a "left handed" coordinate system:

• x increases to the right
• y increases upwards
• z increases towards the camera

A scene object can be assigned a model name or not. When assigned a model name, that model is rendered at the position of the scene object. Scene objects with no model name will not render anything (but can be used to group child objects that may or may not render a model).

  const SceneObject = require('obj-renderer').SceneObject;

  const myObject = new SceneObject({ modelName: 'Crate', x: 0, y: 0, z: 0 });

  myObject.setScale(1, 2, 1); // Stretch vertically by a factor of two
  myObject.setRotation(45, 0, 1, 0); // Then rotate it 45 degrees to the left

  // Add any sub-objects
  myObject.addObject(new SceneObject({ name: 'childObject', modelName: null }));

  // Add the object (and its children) to a scene:
  myScene.addObject(myObject);