Hans Dulimarta

ThreeJS and Yo

Introduction

ThreeJS is a famous library for developing OpenGL programs that run on a web-browser. We generally call them WebGL programs. WebGL and OpenGL ES are both designed based on OpenGL, with redundant APIs removed. ThreeJS itself is built on top of WebGL.

Pre-requisite Steps

  1. Install MinGW (at least you are able to run mingw32-make)
  2. Install Git
  3. Install Python 2.7. Edit your PATH (environment variable) to make sure your can run python from the command prompt
  4. Install Node.js (a run-time environment for running Javascript programs outside of a web browser)
    • Windows Users: you will get an MSI installer
    • Linux users: you will get a .tar.gz file
    • OSX user: you will get a .pkg file
  5. Install YeoMan (web app generator)

    npm install -g global yo bower grunt-cli

    Linux/OSX users may have to run the above command as a super user using sudo.

    sudo npm install -g global yo bower grunt-cli

  6. Install ThreeJS generator

    npm install -g generator-threejs-boilerplate

YeoMan has the following dependencies:

  • bower (package manager)
  • grunt (build system: similar to make, ant, cmake, gradle, …)

Create a ThreeJS webapp

1
2
3
mkdir SampleProject
cd SampleProject
yo threejs-boilerplate

Running the WebApp

1
2
mingw32-make server    # for Windows users
make server            # for Linux/OSX users

Use your Web browser to visit localhost:8000, you should see a spinning cube.

Upgrade ThreeJS

If the local copy of your three.js installed by YeoMan is not the latest revision (you can check it by peeking into vendor/three.js/build/three.js), upgrade to the latest copy (as of March 2015, the latest revision is r70):

bower install threejs

The above command should install the latest copy of threejs under bower_components/threejs/build. To use the updated copy, edit the <script> tag of your index.html from

<script scr="vendor/three.js/build/three.js">

to

<script scr="bower_components/threejs/build/three.js">

The alternate file three.min.js in the same directory is a minified version of three.js. Minified Javascript files are not human readable, unnecessary white spaces are removed, and function names are transcribed to short names (only a few letters). To help debugging rendering problems, we want to use the non-minified version.

Edit the Code

There are several well-known IDEs for Javascript programs (in alphabetical order): Komodo, NetBeans, Notepad++, Sublime Text, Visual Studio, WebStorm, and we have a site license for WebStorm.

A quick browse through the generated code in index.html shows that ThreeJS objects are created by using the new THREE.____ constructor calls:

1
2
var scene = new THREE.Scene();
var camera = new THREE.PerspectiveCamera (45, window.innerWidth / window.innerHeight, 1, 250);

For a complete description of three.js classes, refer to its online documentation. A typical WebGL program uses the following classes:

  • PerspectiveCamera
  • Geometry (BoxGeometry, CubeGeometry, …)
  • PointLight, DirectionalLight, SpotLight
  • MeshBasicMaterial, MeshPhongaterial
  • Vector3, Vector4, Matrix4
  • Mesh
  • WebGLRenderer
  • Scene

Stop the Spinning Cube

If the spinning cube becomes too dizzy to watch, you can stop it by commenting out one of the functions that gets pushed into onRenderFcts array. This array holds all the functions that are invoked by the render “loop” (towards the end of index.html). You will find three functions that are pushed onto the onRenderFcts array:

  1. A function to rotate the cube
  2. A function to change the camera position
  3. A function that renders the graphics

The autogenerated code in index.html can be organized into the following groups:

  1. WebGL setup
  2. Camera, Lighting, and Scene setup
  3. 3D model setup
  4. User interaction handlers (event listeners)
  5. The render “loop”

Mesh: Geometry + Material

In order to render a simple 3D object using Three.js, we have create a Mesh, which in turn requires Geometry and Material. For instance, the cube was created by the following code snippet:

1
2
3
var geometry = new THREE.CubeGeometry (1, 1, 1);
var material = new THREE.MeshPhongMaterial();
var mesh     = new THREE.Mesh (geometry, material);

and to show the cube on your graphics, it must be placed on your scene:

1
scene.add (mesh)