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: