OBJ2GLTF

Convert OBJ assets to glTF 2.0.

Getting Started

Install Node.js if you don't already have it, and then:

npm install -g obj2gltf

Using obj2gltf as a command-line tool:

obj2gltf -i model.obj

obj2gltf -i model.obj -o model.gltf

obj2gltf -i model.obj -o model.glb

Using obj2gltf as a library:

Converting an obj model to gltf:

const obj2gltf = require('obj2gltf');
const fs = require('fs');
obj2gltf('model.obj')
    .then(function(gltf) {
        const data = Buffer.from(JSON.stringify(gltf));
        fs.writeFileSync('model.gltf', data);
    });

Converting an obj model to glb

const obj2gltf = require('obj2gltf');
const fs = require('fs');
const options = {
    binary : true
}
obj2gltf('model.obj', options)
    .then(function(glb) {
        fs.writeFileSync('model.glb', glb);
    });

Material types

Traditionally the .mtl file format describes the Blinn-Phong shading model. Meanwhile glTF 2.0 introduces physically-based materials.

There are three shading models supported by obj2gltf:

• Metallic roughness PBR
• Specular glossiness PBR (via KHR_materials_pbrSpecularGlossiness extension)
• Unlit materials (via KHR_materials_unlit extension)

If the material type is known in advance, it should be specified with either the metallicRoughness or specularGlossiness flag.

If lighting information is already present in the model, the unlit flag should be used. This will save the glTF with the KHR_materials_unlit extension.

If the model is created with PBR textures, either the metallicRoughness or specularGlossiness flag should be passed in. See the table below for more information about how to specify PBR values inside the .mtl file.

If none of these flags are provided, the .mtl is assumed to contain traditional Blinn-Phong materials which will be converted to metallic-roughness PBR. There may be some quality loss as traditional materials do not map perfectly to PBR materials.

Commonly in PBR workflows the the .mtl file may not exist or its values may be outdated or incorrect. As a convenience the PBR textures may be supplied directly to the command line.

Mapping of mtl slots to shading models

Usage

Command line flags:

Build Instructions

Run the tests:

npm run test

To run ESLint on the entire codebase, run:

npm run eslint

To run ESLint automatically when a file is saved, run the following and leave it open in a console window:

npm run eslint-watch

Running Test Coverage

Coverage uses nyc. Run:

npm run coverage

For complete coverage details, open coverage/lcov-report/index.html.

The tests and coverage covers the Node.js module; it does not cover the command-line interface, which is tiny.

Generating Documentation

To generate the documentation:

npm run jsdoc

The documentation will be placed in the doc folder.

Contributions

Pull requests are appreciated. Please use the same Contributor License Agreement (CLA) used for CesiumJS.

Developed by the Cesium team.