How to Import a 3D Blender Object into a Three.js Project as a glTF File
If you’re coding 3D visualizations with Three.js, sooner or later you’ll want to move beyond using the library’s basic native shapes and start using complex custom 3D objects wrapped in UV mapped material.
Blender is a fantastic free open-source software for creating beautiful 3D objects. Since Three.js dropped support of its Blender exporter plugin in favor of relying on its glTF loader, exporting via the popular and versatile glTF file format is now the way to go for bringing Blender objects into your Three.js projects.
This tutorial will walk through each step from creating a Three.js-compatible UV-wrapped 3D object in Blender to loading the object into a Three.js scene. Here’s what we’ll cover:
Part 1: Creating a Three.js-Compatible UV Mapped 3D Object in Blender
Part 2: Importing the UV Image into Blender as glTF Material
Part 3: Exporting the glTF file from Blender
Part 4: Loading the glTF file into a Three.js Scene
Part 1: Creating a Three.js-Compatible UV Mapped 3D Object in Blender
This tutorial will use Bus Derby, a 3D browser-based video game built with Three.js, to provide examples for each step. The game and all of the source code can be found on CodePen here or on GitHub here for reference. (The design case study is also available on Behance here.)
We’ll be using this bus image as a model to base our 3D Blender object on.
To begin, you’ll first need to have a 3D object shaped in Blender. This tutorial won’t cover the details of using the software to create shapes. If you’re new to Blender, there are tons of existing tutorials to bring you up to speed. I’d recommend this YouTube Blender Beginner Tutorial. When I began the Bus Derby project, I’d barely heard of Blender, and the series gave me the know-how to create this bus body shape below, which we’ll be using as an example.
Unwrapping UVs in Blender to Create a UV map
If you’re already familiar with unwrapping UVs, go ahead and skip down to Part 2. If not, stick around. The first step toward UV unwrapping in Blender is to open a new area as a UV/Image Editor.
Hit TAB to toggle into Edit mode, then “A” to select all. Hit “U” (for unwrap), then select Smart UV Project. Hit “Okay” to accept the default settings. This will automatically unwrap the UVs and place them on the UV map.
(Alternatively, for more control over how Blender unwraps the UV, you can designate seams. Select the edges where you’d like the seams to be, hit CONTROL-E, then select Mark Seams. Seams will appear as red edges. When all of the seams are marked, hit “U”, then select Unwrap.)
Exporting the UV Map as a PNG file
Position the segments on the UV Map in a way that will be easy to work with when creating the images. Group them by their expected color and arrange them relationally so it’s clear how each segment corresponds to the 3D shape. (Select the “island” mode to easily select and move isolated segments.)
Hit “A” to make sure the the entire map is selected. Open the “UVs” menu at the bottom of the UV/Image Editor area, and select Export UV Layout. Enter the name and location for the file, then click the “Export UV Layout” button. This will export a .png image of the UV map outlines over a transparent background.
Creating the UV Image with Image Editing Software
Open the exported .png file in any image editing software like Sketch, Illustrator, or Photoshop. Add a new image layer beneath the UV map, and fill in the outlines with any combination of color, illustration, or photos. When you’re done with the image, hide or delete the UV map layer, and export as a new image file to the same directory as the .blend file.
Part 2: Importing the UV Image into Blender as glTF Material
To import the UV image .png into Blender in a way that’s compatible with exporting to Three.js, we’ll need bring in the KhronosGroup glTF Blender Exporter plugin. To do so, clone or download the exporter from GitHub into the same directory as the .blend file, and unzip it.
Back in Blender, append the glTF Blender Exporter file’s glTF Metallic Roughness material. To do this, go to File > Append, then navigate to glTF-Blender-Exporter-master/pbr_node/glTF2.blend/NodeTree, and select the glTF Metalic Roughness material. (We’ll use this material in the tutorial, but if you want you can repeat this step to append the glTF Specular Glossiness material as well, which is also compatible with Three.js)
Select Cycles Render from the menu on the top bar.
Now, open another new area as a Node Editor.
In the Properties panel on the right side of the Blender interface, select the Material display, and give the material a recognizable name. We’ll call it “bus_material” here.
In the node editor, Add a new Metallic Roughness glTF material node. To do this, go to Add > Group > glTF Metallic Roughess, and place the new glTF Metallic Roughness node.
Delete the “Diffuse BSDF node”. Just select it, then hit “X”.
Add a new image texture node. Go to Add > Texture > Image Texture, and place the new node. Then, on the new image texture node, go to Open > select UV image, and select your UV Image file.
Connect the Image Texture node’s Color and Alpha connectors to the glTF Metallic Roughness node’s BaseColor and Alpha connectors, respectively. Connect the glTF Metallic Roughness node’s Shader connector to the Material Output node’s Surface connector.
In the 3D view editor, you should now see the UV image projected onto the 3D shape. Looking pretty damn good.
Adjust the MetallicFactor and RoughnessFactor on the glTF Metallic Roughness node as desired.
Part 3: Exporting the glTF file from Blender
To send the object to our Three.js project, we’ll first need to point Blender to the Khronos glTF Blender Exporter script. To do this, go to File > User Preferences to open the User Preferences window. Under the File tab, click the “Scripts” folder icon. Navigate to glTF-Blender-Exporter-master/scripts, and click the “Accept” button. Click the “Save User Settings” button. Close the User Preferences window.
Save, close Blender, and re-open Blender for the plugin to persist.
Add the glTF 2.0 format to Blender. Go back to File > User Preferences. This time, open the “Add-ons” tab. Use the search bar to search for “glTF”, then check “Import-Export: glTF 2.0 format”. Click the “Save User Settings” button, and close the window.
Now we’re ready to export the glTF as a Three.js-compatible .glb file. Go to File > Export > glTF 2.0 (.glb). Check “Export all layers”, “Export materials”, “Export texture coordinates”, “Export normals”, and any other properties you’ll need to include for your project. Give the file an appropriate name. I’m calling mine “bus_body_green.glb”. Navigate to wherever you want to save the file, and hit the “Export glTF 2.0 binary” button.
Part 4: Loading the glTF file into a Three.js Scene
And now, at last, we’re ready to load the 3D object into your Three.js project. (Have a look at the Bus Derby example in CodePen or the GitHub repo for fuller context of the code.)
In your Three.js app’s index HTML file, add the Three.js glTF loader library source.
<script src=”https://cdn.rawgit.com/mrdoob/three.js/master/examples/js/loaders/GLTFLoader.js"></script>Finally, create a new glTF loader object. Load the .glb file and apply the 3D object (which lives at `gltf.scene.children[0]`) to an object that will be added to the scene. Position and scale as needed. In the example I’m also attaching the bus body to an already-present bus frame object so the body moves along with the bus. For a static glTF object, you can just add it directly to the scene.
var loader = new THREE.GLTFLoader();
loader.load(
"/path/to/bus_body_green.glb",
function ( gltf ) {
var scale = 5.6;
bus.body = gltf.scene.children[0];
bus.body.name = “body”;
bus.body.rotation.set ( 0, -1.5708, 0 );
bus.body.scale.set (scale,scale,scale);
bus.body.position.set ( 0, 3.6, 0 );
bus.body.castShadow = true;
bus.frame.add(bus.body);
},
);scene.add( bus.frame )
That’s it! You’ve brought your 3D Blender object into your Three.js project. You’re good to go. :)
Matthew Main is a UI designer & developer in New York. Follow on Twitter, Codepen, GitHub, Behance.
