README.md

three.js
========

#### Javascript 3D Engine ####

[![Flattr this](http://api.flattr.com/button/button-compact-static-100x17.png)](http://flattr.com/thing/287/three-js)

The aim of this project is to create a lightweight 3D engine with a very low level of abstraction (aka for dummies). Currently the examples are the documentation. Be aware that the API may change from revision to revision breaking backwards compatibility.

The engine can render using <canvas>, <svg> and WebGL.

More? irc.freenode.net #three.js

### Examples ###

#### Canvas ####

[![materials_reflection](http://mrdoob.github.com/three.js/assets/examples/27_materials_reflection.png)](http://mrdoob.github.com/three.js/examples/materials_reflection.html)
[![materials](http://mrdoob.github.com/three.js/assets/examples/13_materials.png)](http://mrdoob.github.com/three.js/examples/materials.html)
[![materials_depth](http://mrdoob.github.com/three.js/assets/examples/19_materials_depth.png)](http://mrdoob.github.com/three.js/examples/materials_depth.html)
[![materials_normal](http://mrdoob.github.com/three.js/assets/examples/22_materials_normal.png)](http://mrdoob.github.com/three.js/examples/materials_normal.html)
[![lights_pointlights](http://mrdoob.github.com/three.js/assets/examples/09_walthead.png)](http://mrdoob.github.com/three.js/examples/lights_pointlights.html)
[![interactive_cubes](http://mrdoob.github.com/three.js/assets/examples/11_interactive.png)](http://mrdoob.github.com/three.js/examples/interactive_cubes.html)
[![camera_ortographic](http://mrdoob.github.com/three.js/assets/examples/10_orthographic.png)](http://mrdoob.github.com/three.js/examples/camera_orthographic.html)
[![geometry_birds](http://mrdoob.github.com/three.js/assets/examples/08_birds.png)](http://mrdoob.github.com/three.js/examples/geometry_birds.html)
[![geometry_earth](http://mrdoob.github.com/three.js/assets/examples/07_earth.png)](http://mrdoob.github.com/three.js/examples/geometry_earth.html)
[![geometry_terrain](http://mrdoob.github.com/three.js/assets/examples/06_terrain.png)](http://mrdoob.github.com/three.js/examples/geometry_terrain.html)
[![materials_video](http://mrdoob.github.com/three.js/assets/examples/24_materials_video.png)](http://mrdoob.github.com/three.js/examples/materials_video.html)
[![geometry_panorama](http://mrdoob.github.com/three.js/assets/examples/04_vr.png)](http://mrdoob.github.com/three.js/examples/geometry_panorama.html)
[![geometry_cube](http://mrdoob.github.com/three.js/assets/examples/03_cube.png)](http://mrdoob.github.com/three.js/examples/geometry_cube.html)
[![particles_sprites](http://mrdoob.github.com/three.js/assets/examples/26_particles_sprites.png)](http://mrdoob.github.com/three.js/examples/particles_sprites.html)
[![particles_random](http://mrdoob.github.com/three.js/assets/examples/02_random.png)](http://mrdoob.github.com/three.js/examples/particles_random.html)
[![particles_wave](http://mrdoob.github.com/three.js/assets/examples/01_waves.png)](http://mrdoob.github.com/three.js/examples/particles_waves.html)
[![particles_floor](http://mrdoob.github.com/three.js/assets/examples/00_floor.png)](http://mrdoob.github.com/three.js/examples/particles_floor.html)

#### WebGL ####

[![materials_shader_fresnel](http://mrdoob.github.com/three.js/assets/examples/28_materials_shaders_fresnel.png)](http://mrdoob.github.com/three.js/examples/materials_shaders_fresnel.html)
[![materials_cars](http://mrdoob.github.com/three.js/assets/examples/25_materials_cars.png)](http://mrdoob.github.com/three.js/examples/materials_cars.html)
[![materials_cubemap_refraction](http://mrdoob.github.com/three.js/assets/examples/18_materials_cubemap_refraction.png)](http://mrdoob.github.com/three.js/examples/materials_cubemap_refraction.html)
[![materials_cubemap_balls_reflection](http://mrdoob.github.com/three.js/assets/examples/15_materials_cubemap_balls_reflection.png)](http://mrdoob.github.com/three.js/examples/materials_cubemap_balls_reflection.html)
[![materials_cubemap_balls_refraction](http://mrdoob.github.com/three.js/assets/examples/16_materials_cubemap_balls_refraction.png)](http://mrdoob.github.com/three.js/examples/materials_cubemap_balls_refraction.html)
[![materials_cubemap_escher](http://mrdoob.github.com/three.js/assets/examples/17_materials_cubemap_escher.png)](http://mrdoob.github.com/three.js/examples/materials_cubemap_escher.html)
[![materials_cubemap](http://mrdoob.github.com/three.js/assets/examples/14_materials_cubemap.png)](http://mrdoob.github.com/three.js/examples/materials_cubemap.html)
[![materials_gl](http://mrdoob.github.com/three.js/assets/examples/20_materials_gl.png)](http://mrdoob.github.com/three.js/examples/materials_gl.html)
[![materials_shaders](http://mrdoob.github.com/three.js/assets/examples/23_materials_shaders.png)](http://mrdoob.github.com/three.js/examples/materials_shaders.html)
[![large_mesh](http://mrdoob.github.com/three.js/assets/examples/12_large_mesh.png)](http://mrdoob.github.com/three.js/examples/geometry_large_mesh.html)


### Featured projects ###

[![Voxels](http://mrdoob.github.com/three.js/assets/projects/10_voxels.png)](http://mrdoob.com/projects/voxels/)
[![The Wilderness Downtown](http://mrdoob.github.com/three.js/assets/projects/09_arcadefire.png)](http://thewildernessdowntown.com/)
[![CloudSCAD](http://mrdoob.github.com/three.js/assets/projects/08_cloudscad.png)](http://cloudscad.com/stl_viewer/)
[![Or so they say...](http://mrdoob.github.com/three.js/assets/projects/07_orsotheysay.png)](http://xplsv.com/prods/demos/xplsv_orsotheysay/)
[![Rat](http://mrdoob.github.com/three.js/assets/projects/06_rat.png)](http://tech.lab212.org/2010/07/export-textured-models-from-blender2-5-to-three-js/)
[![Failure](http://mrdoob.github.com/three.js/assets/projects/05_failure.png)](http://www.is-real.net/experiments/three/failure/)
[![Space Cannon 3D](http://mrdoob.github.com/three.js/assets/projects/02_spacecannon.png)](http://labs.brian-stoner.com/spacecannon/)
[![Alocasia](http://mrdoob.github.com/three.js/assets/projects/04_alocasia.png)](http://arithmetric.com/projects/alocasia/)
[![DDD](http://mrdoob.github.com/three.js/assets/projects/01_ddd.png)](http://the389.com/works/three/)
[![jsflowfield4d](http://mrdoob.github.com/three.js/assets/projects/00_jsflowfield4d.png)](http://test.sjeiti.com/jsflowfield4d/)
[![spikeball](http://mrdoob.github.com/three.js/assets/projects/03_spikeball.png)](http://kile.stravaganza.org/lab/js/spikeball/)

### Usage ###

Download the [minified library](http://mrdoob.github.com/three.js/build/Three.js) and include it in your html.

	<script type="text/javascript" src="js/Three.js"></script>

This code creates a camera, then creates a scene object, adds a bunch of random particles in it, creates a &lt;canvas&gt; renderer and adds its viewport in the document.body element.

	<script type="text/javascript">

		var camera, scene, renderer;

		init();
		setInterval( loop, 1000 / 60 );

		function init() {

			camera = new THREE.Camera( 75, window.innerWidth / window.innerHeight, 1, 10000 );
			camera.position.z = 1000;

			scene = new THREE.Scene();

			for (var i = 0; i < 1000; i++) {

				var particle = new THREE.Particle( new THREE.ParticleCircleMaterial( { color: Math.random() * 0x808080 + 0x808080 } ) );
				particle.position.x = Math.random() * 2000 - 1000;
				particle.position.y = Math.random() * 2000 - 1000;
				particle.position.z = Math.random() * 2000 - 1000;
				particle.scale.x = particle.scale.y = Math.random() * 10 + 5;
				scene.addObject( particle );

			}

			renderer = new THREE.CanvasRenderer();
			renderer.setSize( window.innerWidth, window.innerHeight );

			document.body.appendChild( renderer.domElement );

		}

		function loop() {

			renderer.render( scene, camera );

		}

	</script>

For creating a customised version of the library, including the source files in this order would be a good way to start:

	<script type="text/javascript" src="../src/Three.js"></script>
	<script type="text/javascript" src="../src/core/Color.js"></script>
	<script type="text/javascript" src="../src/core/Vector2.js"></script>
	<script type="text/javascript" src="../src/core/Vector3.js"></script>
	<script type="text/javascript" src="../src/core/Vector4.js"></script>
	<script type="text/javascript" src="../src/core/Ray.js"></script>
	<script type="text/javascript" src="../src/core/Rectangle.js"></script>
	<script type="text/javascript" src="../src/core/Matrix3.js"></script>
	<script type="text/javascript" src="../src/core/Matrix4.js"></script>
	<script type="text/javascript" src="../src/core/Vertex.js"></script>
	<script type="text/javascript" src="../src/core/Face3.js"></script>
	<script type="text/javascript" src="../src/core/Face4.js"></script>
	<script type="text/javascript" src="../src/core/UV.js"></script>
	<script type="text/javascript" src="../src/core/Geometry.js"></script>
	<script type="text/javascript" src="../src/cameras/Camera.js"></script>
	<script type="text/javascript" src="../src/lights/Light.js"></script>
	<script type="text/javascript" src="../src/lights/AmbientLight.js"></script>
	<script type="text/javascript" src="../src/lights/DirectionalLight.js"></script>
	<script type="text/javascript" src="../src/lights/PointLight.js"></script>
	<script type="text/javascript" src="../src/objects/Object3D.js"></script>
	<script type="text/javascript" src="../src/objects/Particle.js"></script>
	<script type="text/javascript" src="../src/objects/Line.js"></script>
	<script type="text/javascript" src="../src/objects/Mesh.js"></script>
	<script type="text/javascript" src="../src/materials/Material.js"></script>
	<script type="text/javascript" src="../src/materials/LineBasicMaterial.js"></script>
	<script type="text/javascript" src="../src/materials/MeshBasicMaterial.js"></script>
	<script type="text/javascript" src="../src/materials/MeshLambertMaterial.js"></script>
	<script type="text/javascript" src="../src/materials/MeshPhongMaterial.js"></script>
	<script type="text/javascript" src="../src/materials/MeshDepthMaterial.js"></script>
	<script type="text/javascript" src="../src/materials/MeshNormalMaterial.js"></script>
	<script type="text/javascript" src="../src/materials/MeshFaceMaterial.js"></script>
	<script type="text/javascript" src="../src/materials/MeshCubeMaterial.js"></script>
	<script type="text/javascript" src="../src/materials/MeshShaderMaterial.js"></script>
	<script type="text/javascript" src="../src/materials/ParticleBasicMaterial.js"></script>
	<script type="text/javascript" src="../src/materials/ParticleCircleMaterial.js"></script>
	<script type="text/javascript" src="../src/materials/ParticleDOMMaterial.js"></script>
	<script type="text/javascript" src="../src/materials/Texture.js"></script>
	<script type="text/javascript" src="../src/materials/mappings/CubeReflectionMapping.js"></script>
	<script type="text/javascript" src="../src/materials/mappings/CubeRefractionMapping.js"></script>
	<script type="text/javascript" src="../src/materials/mappings/LatitudeReflectionMapping.js"></script>
	<script type="text/javascript" src="../src/materials/mappings/LatitudeRefractionMapping.js"></script>
	<script type="text/javascript" src="../src/materials/mappings/SphericalReflectionMapping.js"></script>
	<script type="text/javascript" src="../src/materials/mappings/SphericalRefractionMapping.js"></script>
	<script type="text/javascript" src="../src/materials/mappings/UVMapping.js"></script>
	<script type="text/javascript" src="../src/scenes/Scene.js"></script>
	<script type="text/javascript" src="../src/renderers/Projector.js"></script>
	<script type="text/javascript" src="../src/renderers/DOMRenderer.js"></script>
	<script type="text/javascript" src="../src/renderers/CanvasRenderer.js"></script>
	<script type="text/javascript" src="../src/renderers/SVGRenderer.js"></script>
	<script type="text/javascript" src="../src/renderers/WebGLRenderer.js"></script>
	<script type="text/javascript" src="../src/renderers/renderables/RenderableFace3.js"></script>
	<script type="text/javascript" src="../src/renderers/renderables/RenderableParticle.js"></script>
	<script type="text/javascript" src="../src/renderers/renderables/RenderableLine.js"></script>


### Change Log ###

2010 12 05 - **r31** (79.479 KB, gzip: 18.788 KB)

* Minor Materials API change (mappings). ([alteredq](http://github.com/alteredq) & [mrdoob](http://github.com/mrdoob))
* Added Filters to `WebGLRenderer`
* `python build.py --includes` generates includes string


2010 11 30 - **r30** (77.809 KB, gzip: 18.336 KB)

* Reflection and Refraction materials support in `WebGLRenderer` ([alteredq](http://github.com/alteredq))
* `SmoothShading` support on `CanvasRenderer`/`MeshLambertMaterial`
* `MeshShaderMaterial` for `WebGLRenderer` ([alteredq](http://github.com/alteredq))
* Removed `RenderableFace4` from `Projector`/`CanvasRenderer` (maybe just temporary).
* Added extras folder with `GeometryUtils`, `ImageUtils`, `SceneUtils` and `ShaderUtils` ([alteredq](http://github.com/alteredq) & [mrdoob](http://github.com/mrdoob))
* Blender 2.5x Slim now the default exporter (old exporter removed).


2010 11 17 - **r29** (69.563 KB)

* **New materials API** Still work in progress, but mostly there. ([alteredq](http://github.com/alteredq) & [mrdoob](http://github.com/mrdoob))
* Line clipping in `CanvasRenderer` ([julianwa](http://github.com/julianwa))
* Refactored `CanvasRenderer` and `SVGRenderer`. ([mrdoob](http://github.com/mrdoob))
* Switched to Closure compiler.


2010 11 04 - **r28** (62.802 KB)

* `Loader` class allows load geometry asynchronously at runtime. ([alteredq](http://github.com/alteredq))
* `MeshPhongMaterial` working with `WebGLRenderer`. ([alteredq](http://github.com/alteredq))
* Support for *huge* objects. Max 500k polys and counting. ([alteredq](http://github.com/alteredq))
* `Projector.unprojectVector` and `Ray` class to check intersections with faces (based on [mindlapse](https://github.com/mindlapse) work)
* Fixed `Projector` z-sorting (not as jumpy anymore).
* Fixed Orthographic projection (was y-inverted).
* Hmmm.. lib file size starting to get too big...


2010 10 28 - **r25** (54.480 KB)

* `WebGLRenderer` now up to date with other renderers! ([alteredq](http://github.com/alteredq))
* .obj to .js python converter ([alteredq](http://github.com/alteredq))
* Blender 2.54 exporter
* Added `MeshFaceMaterial` (multipass per face)
* Reworked `CanvasRenderer` and `SVGRenderer` material handling


2010 10 06 - **r18** (44.420 KB)

* Added `PointLight`
* `CanvasRenderer` and `SVGRenderer` basic lighting support (ColorStroke/ColorFill only)
* `Renderer` > `Projector`. `CanvasRenderer`, `SVGRenderer` and `DOMRenderer` do not extend anymore
* Added `computeCentroids` method to `Geometry`


2010 09 17 - **r17** (39.487 KB)

* Added `Light`, `AmbientLight` and `DirectionalLight` ([philogb](http://github.com/philogb))
* `WebGLRenderer` basic lighting support ([philogb](http://github.com/philogb))
* Memory optimisations


2010 08 21 - **r16** (35.592 KB)

* Workaround for Opera bug (clearRect not working with context with negative scale)
* Additional `Matrix4` and `Vector3` methods


2010 07 23 - **r15** (32.440 KB)

* Using new object `UV` instead of `Vector2` where it should be used
* Added `Mesh.flipSided` boolean (false by default)
* `CanvasRenderer` was handling UVs at 1,1 as bitmapWidth, bitmapHeight (instead of bitmapWidth - 1, bitmapHeight - 1)
* `ParticleBitmapMaterial.offset` added
* Fixed gap when rendering `Face4` with `MeshBitmapUVMappingMaterial`


2010 07 17 - **r14** (32.144 KB)

* Refactored `CanvasRenderer` (more duplicated code, but easier to handle)
* `Face4` now supports `MeshBitmapUVMappingMaterial`
* Changed order of `*StrokeMaterial` parameters. Now it's `color`, `opacity`, `lineWidth`.
* `BitmapUVMappingMaterial` > `MeshBitmapUVMappingMaterial`
* `ColorFillMaterial` > `MeshColorFillMaterial`
* `ColorStrokeMaterial` > `MeshColorStrokeMaterial`
* `FaceColorFillMaterial` > `MeshFaceColorFillMaterial`
* `FaceColorStrokeMaterial` > `MeshFaceColorStrokeMaterial`
* `ColorStrokeMaterial` > `LineColorMaterial`
* `Rectangle.instersects` returned false with rectangles with 0px witdh or height


2010 07 12 - **r13** (29.492 KB)

* Added `ParticleCircleMaterial` and `ParticleBitmapMaterial`
* `Particle` now use `ParticleCircleMaterial` instead of `ColorFillMaterial`
* `Particle.size` > `Particle.scale.x` and `Particle.scale.y`
* `Particle.rotation.z` for rotating the particle
* `SVGRenderer` currently out of sync


2010 07 07 - **r12** (28.494 KB)

* First version of the `WebGLRenderer` (`ColorFillMaterial` and `FaceColorFillMaterial` by now)
* `Matrix4.lookAt` fix (`CanvasRenderer` and `SVGRenderer` now handle the -Y)
* `Color` now using 0-1 floats instead of 0-255 integers


2010 07 03 - **r11** (23.541 KB)

* Blender 2.5 exporter (utils/export_threejs.py) now exports UV and normals (Thx [kikko](http://github.com/kikko))
* `Scene.add` > `Scene.addObject`
* Enabled `Scene.removeObject`


2010 06 22 - **r10** (23.959 KB)

* Changed Camera system. (Thx [Paul Brunt](http://github.com/supereggbert))
* `Object3D.overdraw = true` to enable CanvasRenderer screen space point expansion hack.


2010 06 20 - **r9** (23.753 KB)

* JSLinted.
* `autoClear` property for renderers.
* Removed SVG rgba() workaround for WebKit. (WebKit now supports it)
* Fixed matrix bug. (transformed objects outside the x axis would get infinitely tall :S)


2010 06 06 - **r8** (23.496 KB)

* Moved UVs to `Geometry`.
* `CanvasRenderer` expands screen space points (workaround for antialias gaps).
* `CanvasRenderer` supports `BitmapUVMappingMaterial`.


2010 06 05 - **r7** (22.387 KB)

* Added Line Object.
* Workaround for WebKit not supporting rgba() in SVG yet.
* No need to call updateMatrix(). Use .autoUpdateMatrix = false if needed. (Thx [Gregory Athons](http://github.com/gregmax17)).


2010 05 17 - **r6** (21.003 KB)

* 2d clipping on `CanvasRenderer` and `SVGRenderer`
* `clearRect` optimisations on `CanvasRenderer`


2010 05 16 - **r5** (19.026 KB)

* Removed Class.js dependency
* Added `THREE` namespace
* `Camera.x` -> `Camera.position.x`
* `Camera.target.x` > `Camera.target.position.x`
* `ColorMaterial` > `ColorFillMaterial`
* `FaceColorMaterial` > `FaceColorFillMaterial`
* Materials are now multipass (use array)
* Added `ColorStrokeMaterial` and `FaceColorStrokeMaterial`
* `geometry.faces.a` are now indexes instead of references


2010 04 26 - **r4** (16.274 KB)

* `SVGRenderer` Particle rendering
* `CanvasRenderer` uses `context.setTransform` to avoid extra calculations


2010 04 24 - **r3** (16.392 KB)

* Fixed incorrect rotation matrix transforms
* Added `Plane` and `Cube` primitives


2010 04 24 - **r2** (15.724 KB)

* Improved `Color` handling


2010 04 24 - **r1** (15.25 KB)

* First alpha release