Load a 3D OBJ + MTL model with Three.js

Import OBJLoader and MTLLoader classes

When a 3D object is modeled in an external tool such as Blender, it is possible to export it in several formats. One of these possibilities is the .OBJ + .MTL format.

Three.js does not provide a solution to natively import OBJ + MTL 3D models . However, classes for this purpose are available in the official add-ons of the library :

• OBJLoader – OBJ Files
• MTLLoader – MTL Files

import { MTLLoader } from '../js/examples/jsm/loaders/MTLLoader.js';
import { OBJLoader } from '../js/examples/jsm/loaders/OBJLoader.js';

Use of the OBJLoader and MTLLoader classes

These two classes often work in association, an OBJ file is often accompanied by an MTL.

Concretely, the OBJ file is comparable to a Three.js Geometry, and MTL to a Material.
The loaded 3D object is the result of the fusion of these two elements. Note however that there are OBJ files without a MTL file!

The use of these two classes is therefore strongly linked. As explained, OBJLoader will be used to load the Geometry of our 3D object, and MTLLoader its Material.

Using MTLLoader

The constructor of this class does not need any argument. To start with, we create a MTLLoader instance.

var mtlLoader = new MTLLoader();

Then, with the load method, we load a MTL :

var mtlLoader = new MTLLoader();
mtlLoader.load("plant_block.mtl", function(materials)
{
    materials.preload();
    [...]
});

This method requires two arguments :

• MTL File – The path to the MTL file to be loaded
• Callback – A callback function called when the MTL file is finished loading

Further operations require the MTL file to be loaded, to ensure this, the following operations are performed in the callback function.

Using OBJLoader

When the MTL file is loaded, we can start loading the OBJ file. For this we use the OBJLoader class.

The constructor of this class requires no arguments. To begin with, we create a OBJLoader instance.

var objLoader = new OBJLoader();

As a reminder, we use OBJLoader in the callback function executed after loading the MTL file.

As explained, the previously loaded “material” is passed as a parameter, and therefore available for use by OBJLoader.

The setMaterials method of the OBJLoader class allows us to associate the future loaded “Geometry” with a “Material“.

Then we load the OBJ file with the load method :

var objLoader = new OBJLoader();
objLoader.setMaterials(materials);
objLoader.load("plant_block.obj", function(object)
{    
    [...]
});

This method requires two arguments:

• OBJ File – The path to the OBJ file to load
• Callback – A callback function called at the end of the OBJ file loading

As explained, at the end of the OBJ file loading, the callback function will be executed.

The 3D Mesh object generated by the loading of the OBJ combined with the “Material” of the previous paragraph, will be passed as a parameter of the callback function, to be used there.

objLoader.load("plant_block.obj", function(object)
{    
    plant_cube = object;
});

It is in this callback function that we have access to the final Mesh object, resulting from the loading of a set of two files : The OBJ + MTL duo.

We can now use the 3D object in our Three.js application !

scene.add( plant_cube );

Result and final code

var plant_cube = undefined;
mtlLoader.load("plant_block.mtl", function(materials)
{
    materials.preload();
    var objLoader = new OBJLoader();
    objLoader.setMaterials(materials);
    objLoader.load("plant_block.obj", function(object)
    {    
        plant_cube = object;
        scene.add( plant_cube );
    });
});

Feel free to download the complete Three.js University guide to progress even faster !

We still have a lot to learn about loading 3D objects into Three.js !

In chapter 9 and 10 of the downloadable guide, we will discover the details of loading 3D objects, and all the related notions (dynamic shadows, animations …).

You can download the complete guide here :