Welcome to the Missing Manual for three.js! 0


This book will teach you everything you need to know to create stunning 3D web applications using three.js, in no time at all. Together, we’ll work through a series of small apps and cases studies until we’ve reached a solid understanding of how to create amazing 3D browser-based applications using the three.js WebGL framework.

If you want to leverage the power of your graphics card to create websites that really stand out - whether it be product displays, data visualization, music videos, advertising, gaming, or anything else - there is no other library today that combines the power, breadth of features and ease of use that three.js has.

Using your graphics card means that you have access to far more power than is possible using traditional CSS or 2D JavaScript animations. Of course, this power does come at a cost of increased complexity, but three.js does a good job of hiding that and makes the task of displaying complex 3D scenes a breeze, as we’ll see soon.

If you need some inspiration to get started, have a look at the threejs.org frontpage which features a regularly updated collection of cutting-edge work from around the web. Virtual Art Sessions and Paperplanes.world are a couple of personal favorites - and of course, while three.js specializes in 3D, it’s equally good at 2D, as this lovely Short Trip by Alexander Perrin demonstrates.

You should use this book alongside the official documentation and you’ll be referred there regularly. Also, the best resources for understanding what three.js is capable of, once you are a little familiar with the library, are the official examples. Go through them and get to know the source code in depth, you won’t regret it.

You should have a basic grasp of JavaScript and know how to get your code running in a web browser, although we will be covering everything that you need to know as we go along.

Let’s take a quick look at what we’ll be covering throughout this book.

Section 0: Setting Up

We’ll start with an overview of WebGL and what you need to get it running on a computer, tablet or phone. Then we’ll take a look at the three.js repo on GitHub, which is where all the magic happens. We’ll finish up the introduction with some tips on getting help, reporting bugs and dealing with the different versions of three.js.

Section 1: Getting Started

The scene graph

We’ll get going properly here, making sure we have a thorough understanding of the basics - the components that make up every 3D scene, how to create objects, lights, and cameras and how to apply simple materials and textures to our creations, as well as how to work with the Scene, how to Group objects, how to set up our canvas to resize automatically if the browser window size changes, and how to set up camera controls. We’ll even do some basic animation.

We’ll end the section by taking a look at how to load complex animated models created in a separate modeling program.

Section 2: Components, Helpers, and Inheritance


In Section 1: Getting Started we looked at how a 3D scene works, and we’ll follow on from this by looking at how three.js itself is put together. The base class for nearly everything else in the library is the Object3D, and we’ll take a look at that in detail here. All the other object’s which can have a position in 3D space, including the Scene and Group objects which we looked at earlier, inherit from this object, so we’ll take at how inheritance works in the library here too.

We’ll also go over the various helper objects that enable you to see and position otherwise invisible things such as lights and cameras.

Finally, in this section, we’ll examine some of the common pitfalls that you will encounter when getting started with three.js, and how to debug your app to identify and solve them.

Section 3: Cameras

Orthographic and perspective projection

Cameras in three.js (actually, in all 3D apps), share a lot of characteristics with real cameras - especially the PerspectiveCamera, which uses Perspective Projection to draw your scene. This mimics the way your eyes see the world, and you’ll be using this camera whenever you want a realistic looking 3D scene.

The other important camera is the OrthographicCamera, which draws your scene using Orthographic Projection. This means that objects don’t get smaller as they get further away from the camera, and you’ll use this camera for drawing 2D elements such as overlays and UIs - or even creating full 2D scenes. In other words, if you want to create an old-school Super Mario clone using three.js, or add a health bar to a 3D game, you will use the OrthographicCamera.

Section 4: Materials and Textures

Materials and textures

Three.js ships with lots of different material types. We saw a couple of them in Section 1: Getting Started, but we’ll take a much deeper look at them here. Materials and textures work together to describe how your 3D objects actually look - how they react to light, whether they are shiny, bumpy, metallic, plastic, or wooden and so on.

We’ll start by looking at the base Material class, then some of the older materials available - the MeshBasicMaterial, MeshLambertMaterial and MeshPhongMaterial (as well as the new MeshToonMaterial which is based on the Phong material), before moving on to the newer physically based rendering workflow in the form of the MeshStandardMaterial and MeshPhysicalMaterial. Note that although this workflow is newer, and in many ways superior, it is not intended to replace the older materials since it has higher computational requirements, meaning you will probably have to use the old materials if you need to support mobile devices.

We also briefly saw Texture and the corresponding TextureLoader in Chapter 1.4. There’s not much more to say about the loader, but there’s quite a bit to say about textures and how best to create and use them, and we’ll cover that here.

The Texture object works with any format that your browser can load, such as JPG, PNG, GIF, BMP, SVG etc., however, you can also use videos as textures with the VideoTexture, or use the 2D Canvas API with CanvasTexture which will allow fancy effects such as drawing on a mesh with your mouse.

Three.js also comes with many more advanced material and texture types. We’ll finish up this section by taking a look at these.

Section 5: Lights and Shadows


Most materials need light to even show up in a scene (with the notable exception of MeshBasicMaterial, as well as a couple of others). In this regard, you can think of your scene in the same way you would any space in the real world - if there is no light, you cannot see anything.

We’ll take a look at the various light types here, such as AmbientLight which adds realism by simulating light bouncing infinitely in all directions, PointLight which simulates a nearby light source like a light bulb, DirectionalLight which simulates faraway light such as the sun, HemisphereLight which simulates light fading between two different colors, such as daylight on a cloudy day (cloud color at the top, ground color at the bottom), SpotLight which simulates a … wait for it … spotlight, and finally the RectAreaLight, a fairly recent addition which simulates area lights such as glowing windows or fluorescent bulbs.

Once we’ve done this, we’ll take a look at how to use these lights to cast shadows. Shadows, when used correctly, add a huge amount of realism and believability to a scene. They are a common point of frustration for new developers as they can be tricky to set up and if used incorrectly will quickly lead to poor performance in your app. The light and camera helpers which we studied in Section 2: Components, Helpers, and Inheritance are a secret weapon here. Once you’re done with this section setting up shadows in your scenes will be a cinch!

Section 6: Understanding Geometry

Vertices and normals of a cube geometry

In this section, we’ll learn how geometry works. Geometries describe the underlying shape of an object. We’ll learn all the basic concepts such as vertices, faces, UV mapping, and normals.

There are two kinds of geometry in available in three.js - the older Geometry, and the newer BufferGeometry.

We’ll get to grips with the basic concepts using Geometry since these are easier to work with and understand. However, they have largely been replaced by BufferGeometry so we’ll quickly move on to using those.

There are a number of built-in simple geometric shapes in three.js with names like CubeBufferGeometry, SphereBufferGeometry and so on, and you can go quite far in using just these in your apps. However, for complex shapes like humans, cats, airplanes, and cars, you’ll need to use a separate modeling program. We’ll cover how to do this in Section 10: Working with other Applications.

Section 7: The WebGLRenderer

The Renderer

The WebGLRenderer takes as input a Scene filled with 3D objects, and a Camera, and outputs beautiful pictures onto your screen using the power of your graphics card. We’ll dedicate this entire section to learning how this powerful renderer works.

There are other renderers available, although you’ll need to include them separately to the main three.js script. Most useful are the CSS2DRender and CSS3DRender which can be used to combine HTML elements seamlessly with your 3D scenes.

Other renderers, such as the RayTraceRender, the SoftwareRenderer, and the SVGRenderer serve as replacements for the WebGLRenderer. These days though, they are much less useful and you should always use the WebGLRenderer in a production app, so we will not cover them further here.

Section 8: Animation

Dancing animation selected frames

Three.js comes equipped with a powerful animation system which can handle all kinds of other fancy things such as morph targets and skeletal animation. However, its main purpose is to load animations created in other applications (as we’ll see in Section 10: Working with other Applications). This means that you can create complex animations in a 3D modeling application such as Blender, 3D Studio Max, Maya, Cinema 4D, MotionBuilder, or hundreds of others, then load them into three.js and they will just work, with almost no effort on your part.

Section 9: RenderTargets, Post-Processing, Shaders, and Effects

Sometimes you’ll want to make changes to your scene after it’s been rendered - for example, you might want to adjust the brightness, contrast or saturation. Or perhaps you want to add a glowing outline, apply an antialiasing pass, a mask, or even a crazy glitch effect. Well, three.js has got you covered for all of these and many more with a wealth of post-processing, shaders, and effects.

We’ll see how to use these, and then take a look at how they work under the hood. They all start by drawing the scene to an off-screen texture, then editing that texture (for example, the brightness post-processing effect will simple brighten or darken the image), before returning the edited texture to you to finally be drawn on the screen. This texture is called a WebGLRenderTarget and we’ll see how to use one here.

If you are thinking “Wow! it must take a lot of processing power and memory to draw the scene to an image off-screen, then edit that image and finally draw it to the screen, all at 60 frames per second!”, then you would be right. You’ll want to use these techniques sparingly and perhaps do without them completely for low powered devices.

Section 10: Working with Other Applications

Apps and assets formats

Three.js is an amazing library, and you can do a lot without reaching for any other tools beyond your favorite text editor. However, it is not a modeling or animation program and you will at some point find yourself needing some things that the library doesn’t provide - or at least, you will save yourself a lot of work by using a dedicated program. Or perhaps you are working with a 3D artist or animator and you need to let them know how they should prepare the assets before sending them to you.

We’ll start by looking at the various 3D formats that work well with three.js and then take look at typical workflows with some popular 3D applications such as 3D Studio Max, Maya, and Blender.

Section 11: Extras

We’ll finish up by taking a whirlwind tour of the /examples folder in the three.js GitHub repository. There is a lot to see here - to start with, all the code for the official three.js examples (which you can see live here), but also loads of plugins such as controls, loaders for many different texture and model formats, post-processing (which we’ll cover in Section 9: RenderTargets, Post-processing, Shaders, and Effects), additional renderers, cameras, modifiers and much more. There are even free to use 3D fonts, models, sounds and textures you can use for testing, all licensed with the same open (MIT) license as three.js itself.