Ember 3D

Ember 3D is an Ember addon for using Three.js - an easy to use, lightweight, javascript 3D library.

It is designed to:

Prescribe a solid file structure to Three.js code using ES6 modules.
Enable fast creation of Three.js scenes, renderers, cameras, lighting and objects using a well defined set of abstractions.

Installation

ember install ember-3d

Ember 3D includes a shim for the Three.js library. Installing Ember 3D will allow you to use imports from the three module, like so:

import { BoxGeometry, Mesh, MeshPhongMaterial, Scene } from 'three';

Requirements

Ember CLI >=2.9.0

The shim uses app.import's new AMD transformation feature released in Ember CLI 2.9.0.

Ember.js >=2.7.0

Due to the use of the uniqBy method, this lib needs ember.js 2.7.0 or upwards.

Folder structure

Ember 3D adds a folder named 3d to your project's app folder. Ember 3D expects projects to be structured in the following manner:

app/
├── 3d/
|   └── scene-id/
|       ├── camera.js
|       ├── interactions/
|           └── interaction-id.js
|       ├── lighting.js
|       ├── objects/
|           └── object-id.js
|       ├── renderer.js
|       └── scene.js

Components

To add a 3D scene to a template, use the 3d-scene component with a dasherized version of the scene id:

{{3d-scene id="scene-id"}}

Scenes

The BaseSceneMixin simply creates a Three.js scene from the renderer defined in renderer.js & camera defined in camera.js and appends it to the DOM.

// app/scene-id/scene.js
import SceneMixin from 'ember-3d/scenes/base';

export default SceneMixin.extend();

Renderers

Ember 3D's WebGLRendererMixin extends the BaseRendererMixin, which automatically resizes the renderer on dimension changes of the 3d-scene.

// app/scene-id/renderer.js
import WebGLRendererMixin from 'ember-3d/renderers/webgl';

export default WebGLRendererMixin.extend({
  options: {
    alpha: true,
    shadowMap: { enabled: true }
  }
});

Cameras

Ember 3D allows for the creation of two types of Three.js camera, perspectiveCamera and orthographicCamera.

Perspective Camera

The PerspectiveCameraMixin creates a Three.js PerspectiveCamera. The camera's aspect value is dynamically updated when the 3d-scene dimensions change.

// app/scene-id/camera.js
import PerspectiveCameraMixin from 'ember-3d/cameras/perspective';

export default PerspectiveCameraMixin.extend({
  viewAngle: 75,
  near: 1,
  far: 10000,
  setAspectDynamically: true,
  position: {
    x: 0,
    y: 0,
    z: 1000
  }
});

Orthographic Camera

The OrthographicCameraMixin creates a Three.js OrthographicCamera. Left, right, top and bottom frustums are dynamically updated when the 3d-scene dimensions change.

// app/scene-id/camera.js
import OrthographicCameraMixin from 'ember-3d/cameras/orthographic';

export default OrthographicCameraMixin.extend({
  near: 1,
  far: 10000,

  position: {
    x: 50,
    y: 75,
    z: 1000
  }
});

Lighting

The BaseLightingMixin offers a simple method of registering lighting onto the Three.js scene using the addLighting function.

// app/scene-id/lighting.js
import BaseLightingMixin from 'ember-3d/lighting/base';

export default BaseLightingMixin.extend({

  addLighting() {
    // Add lighting using:
    // get(this, 'scene').add(YOUR_LIGHTING);
  }

});

Objects

The BaseObjectMixin prescribes a set of functions for registering 3D objects on your Three.js scene. It also exposes an animate function for animating your objects. The BaseObjectMixin can't be used to create objects itself, but you can use one of the following mixins extended from it:

Mesh

Triangular polygon mesh based objects can be created and attached to the scene using the MeshObjectMixin. For example, the following code creates a cube and animates it:

// app/scene-id/objects/cube.js
import Ember from 'ember';
import MeshObjectMixin from 'ember-3d/objects/mesh';
import { BoxGeometry, MeshBasicMaterial } from 'three';

const { get } = Ember;

export default MeshObjectMixin.extend({

  geometry: new BoxGeometry(700, 700, 700, 10, 10, 10),
  material: new MeshBasicMaterial({color: 0xfffff, wireframe: true}),

  animate() {
    let cube = get(this, 'object');

    function loop() {
      requestAnimationFrame(loop);
      cube.rotation.x += 0.01;
      cube.rotation.y += 0.01;
    }

    loop();
  }

});

Group

The GroupObjectMixin enables complex object building. Multiple meshes can be attached to a group, like so:

// app/scene-id/objects/cube-group.js
import GroupObjectMixin from 'ember-3d/objects/group';
import { BoxGeometry, Mesh, MeshPhongMaterial } from 'three';

export default GroupObjectMixin.extend({

  buildObject() {

    // Add our cube to the group
    let cube = this.createObject('cube');

    this.addToGroup([
      cube,
      this.one(),
      this.two()
    ]);

  },

  one() {
    const geometry = new BoxGeometry(60,50,50,1,1,1);
    const material = new MeshPhongMaterial({color: 0xf25346 });
    return new Mesh(geometry, material);

  },

  two() {
    let one = this.one();
    one.position.x = 50;
    return one;

  }

});

Out-of-the-box support for other Three.js object types will be added in the near future.

Interactions

Interactions offer a structured way to manage methods of interaction with your scene.

Mouse Move

The MouseMoveInteractionMixin listens to movements of the mouse and sets mouseX and mouseY properties on the component, accessible by all Ember 3D modules. The mixin can also return normalized positive or negative values based upon the height and width of the scene.

// app/scene-id/interactions/mouse-move.js
import MouseMoveInteractionMixin from 'ember-3d/interactions/mouse-move';

export default MouseMoveInteractionMixin.extend({
  normalizeMouseValues: true
});

More interactions will be added in the near future.

Plugins

Ember 3D offers plugins for any features not included in the Three.js core module.

Orbit Controls ember-3d-orbit-controls by @willviles

Using Three.js

For more information on how to use Three.js, please refer to the documentation.

Contributing

Ember 3D is in its infancy. It will seek to be a flexible and elegant addon for creating complex 3D scenes. Please feel free to contribute.

Feature requests

Create feature requests here and please tag your issue with feature-request.

willviles / ember-3d

readme