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.
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';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.
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
To add a 3D scene to a template, use the 3d-scene component with a dasherized version of the scene id:
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();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 }
}
});Ember 3D allows for the creation of two types of Three.js camera, perspectiveCamera and orthographicCamera.
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
}
});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
}
});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);
}
});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:
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();
}
});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 offer a structured way to manage methods of interaction with your scene.
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.
Ember 3D offers plugins for any features not included in the Three.js core module.
- Orbit Controls ember-3d-orbit-controls by @willviles
For more information on how to use Three.js, please refer to the documentation.
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.
Create feature requests here and please tag your issue with feature-request.