Three.js 101 : Hello World!

What is Three.js?

Three.js is a JavaScript library that provides a framework for creating and displaying 3D computer graphics on the web. It is built on top of WebGL, a web standard for rendering 3D graphics in the browser, and simplifies the process of working with complex 3D scenes, objects, and animations.

What do you need?

An up-to-date browser.
Basic knowledge of HTML and Javascript.
IDE or Texteditor (e.g., Notepad++)

HTML Page

The first thing you need to use three.js is a simple HTML page. you can start with the following basic code.

<!doctype html>
<html>
<head>
  <meta charset="UTF-8">
  <meta name="viewport"
        content="width=device-width, user-scalable=no, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0">
  <title>Three.js Cube and Cylinder</title>
  <style>
    body { margin: 0; }
    canvas { display: block; }
  </style>
</head>
<body>

</body>
</html>

Initialize three.js

In order to use the three.js library, first you need to add it as a script to your HTML page. you can add the flowing code to the head section.

<!-- three.js -->
  <script src="https://unpkg.com/three@0.126.0/build/three.js"></script>

WebGlRenderer, Scene and Camera

This is the first common pattern we are going to see in every Three.js app.

Create a Renderer.
Create a Scene.
Create a Camera. The renderer is the place where we are going to put the result of our scene. In Three.js we can have multiple scenes and each one can have different objects.

Here we create our WebGLRenderer, we pass it the size of the window as a parameter and then append it to the DOM. The empty scene is where we are going to add our objects. And by last we create a camera, passing as parameters the FOV, the Aspect ratio and the near plane and far plan.

Once this is done we have the 3 fundamental elements of a Three.js application.

// BASIC SETUP
// ------------------------------------------------

// Create an empty scene
var scene = new THREE.Scene();

// Create a basic perspective camera
var camera = new THREE.PerspectiveCamera( 75, window.innerWidth/window.innerHeight, 0.1, 1000 );
camera.position.z = 4;

// Create a renderer with Antialiasing
var renderer = new THREE.WebGLRenderer({antialias:true});

// Configure renderer red color
renderer.setClearColor("#ff0000");

// Configure renderer size
renderer.setSize( window.innerWidth, window.innerHeight );

// Append Renderer to DOM
document.body.appendChild( renderer.domElement );

Geometry, Material and Mesh

The second common pattern is adding objects to the scene:

Create a Geometry
Create a Material
Create a Mesh.
Add mesh to scene. In Three.js a Mesh is the composition of a Geometry with a Material.

A Geometry is the mathematical formula of an object, in Three.js we have many geometries, we’ll explore it in future chapters. A Geometry give us the vertices of the object we want to add to the scene.

A Material can be defined as the properties of an object and its behavior with the light sources of the scene. As you can see in the following image there are different types of materials.

Now that we know what a mesh, a geometry and a material are, we are going to add them to the scene. In this case we are creating a cube with basic Material.

RequestAnimationFrame

The last piece of code is the one that allows us to animate the scene, for this purpose we use requestAnimationFrame, which allows us to have a function that runs at 60 frames per second (at best).

// Render Loop
var render = function () {
  requestAnimationFrame( render );
// Your animated code goes here
renderer.render(scene, camera);
};
render();

Animating the cube

In order to animate the cube inside our render loop, we need to change it’s properties. When we create a Mesh we have access to a gr0up of properties that are very useful at the moment of animating.

// Rotation (XYZ) in radians. 
cube.rotation.x
cube.rotation.y
cube.rotation.z
// Position (XYZ)
cube.position.x
cube.position.y
cube.position.z
// Scale (XYZ) 
cube.scale.x
cube.scale.y
cube.scale.z

In our example we animate the X and Y rotation of the cube:

cube.rotation.x += 0.01;
cube.rotation.y += 0.01;

BufferGeometry

A representation of mesh, line, or point geometry. Includes vertex positions, face indices, normals, colors, UVs, and custom attributes within buffers, reducing the cost of passing all this data to the GPU.

const geometry = new THREE.BufferGeometry();

const vertices = new Float32Array( [
	-1.0, -1.0,  1.0, // v0
	 1.0, -1.0,  1.0, // v1
	 1.0,  1.0,  1.0, // v2
	-1.0,  1.0,  1.0, // v3
] );

const indices = [
	0, 1, 2,
	2, 3, 0,
];

geometry.setIndex( indices );
geometry.setAttribute( 'position', new THREE.BufferAttribute( vertices, 3 ) );

const material = new THREE.MeshBasicMaterial( { color: 0xff0000 } );
const mesh = new THREE.Mesh( geometry, material );