Page 7: Another three.js example

On this page, we’ll connect some of the most basic things in graphics to their concepts in Three.js.

Three.js’s coordinate system

Three.js is a scene graph API where we place graphics objects into the world, and then have it draw that world.

Three.js uses a right-handed coordinate system. For us, we’ll always think about y going up, so that the “ground” is the x-z plane.

This “y-up” model is also how we’ll view the screen. You can think of the screen as a box. The x-axis goes to the right. The y-axis goes up (so it’s like in math class, not like 2D Canvas). Because we do right-handed coordinates, the z-axis comes out of the screen.

Three.js’s world is pretty arbitrary: we can put objects wherever we want. There is an origin (0,0,0) where objects get placed by default. But we can position things anywhere we like. Similarly, the size of things (the units of the axes) is up to us.

Three.js lets us do whatever we want - the “world coordinates” are up to us. We just need to provide the transformation between world and screen. This is what the camera does.

Box 1: The Basic Abstractions

In order to work with Three.js, we need to work with a few kinds of objects:

• Renderer - this is the connection to an image that we draw into (like the rectangle on the web page as a DOM element). We will generally use the WebGLRenderer since it uses the built-in browser drawing functionality. We usually let the Renderer create the Canvas in the browser because the renderer will configure it correctly.
• Scene - this is the object that stores the world. It is little more than a list of objects (which themselves can have a list of objects, in order to make hierarchies).
• Camera - this is the transformation from the world to the image (where the image is the rectangle in a Renderer).
• Geometry - this is a collection of triangles, usually held in a special format so it can be drawn efficiently.
• Material - this is an object that describes how an object looks, including how it interacts with lights.
• Object3D - these are the objects in the world. Both the regular objects that we see and the lights and cameras.
• Mesh - this is a specific kind of Object3D that turns a Geometry (a collection of triangles) into something we can place in the world.
• Light - this is a special kind of Object3D that we generally do not see directly, but that instead is used by materials to determine how much light they are receiving (and therefore how they look).

In our programs, we can use as many or as few of these as we want. Here is an example of a scene that has a ground plane (gray square - it actually is a box, just very thin), a few cubes, and a few lights. We will make two pictures of this one world. The code is in 04-07-01.js (04-07-01.html). You probably want to read along.

On the left you see a scene with the ground and the three cubes. We also put in an AxesHelper so that you can see what the coordinate system is (we’ve left the AxesHelper at the origin, so this represents the “world” coordinates). Red = x, green = y, blue = z. Since the axes are there, you can tell that the camera is placed above the ground, and some distance along the X and Z axes. The small orange markings in the upper right is an artifact of the “camera helper” that we’ll discuss in a moment.

On the right, you can see a second picture of the same scene taken with a different camera. This camera is slightly farther away so you can actually see where the first camera is. Normally, we don’t see cameras. But we’ve added a CameraHelper object to the scene that is attached to the first camera and will draw the red and orange lines so we can see where the camera is. The orange markings in the first image represent the first camera looking at itself. We’ve also added a LightHelper so you can see where the light source is.

There are some things to notice in this example:

1. We used all of the key abstractions of Three.js: Renderer, Scene, Geometry, Material, Object3D (Mesh), Camera, and Light. We were able to make a picture without having to understand the details of how things work.
2. We made one world, and then used multiple cameras to take pictures of it.
3. We made one box geometry (a cube) and created multiple meshes from it. (There was a second box geometry for the ground plane.) Remember that in Three.js a Geometry is a collection of triangles, and a Mesh is a graphics object that combines a Geometry with the information needed to draw it. Many meshes can share a single geometry.
4. We used position and scaling to perform transformations to put the objects into the scene.
5. We had to make a separate renderer for each Canvas (rectangular area) on the screen. Each one gets drawn separately (with its own render call).
6. We can use helpers to help us see lights and cameras.
7. We work in the world coordinate system. The center of the world is at 0,0,0. We position objects relative to that, and as big as we want. To make the correct things show up, we need to position the camera appropriately.

In this workbook we’ll focus on understanding how to use these pieces to make pictures and animations. In the future, we will start to understand how they work.

Summary: The Basic Abstractions

In the Three.js API, we have objects that correspond to the basic abstractions in computer graphics. We create a world (with a right-handed coordinate system) and place objects into it. We give them surface properties (to determine how they look), and put lights in. Then we place cameras that take pictures of the world.