three

What is three?

The 'three' npm package is a JavaScript library that provides a wide array of functionalities for creating and displaying 3D graphics in web browsers. It uses WebGL under the hood and provides an easy-to-use API to create 3D scenes, render them, and add various elements like shapes, materials, lights, cameras, and more.

What are three's main functionalities?

Creating a Scene

This code sample demonstrates how to create a new 3D scene using Three.js. A scene is a container that holds all your objects, cameras, and lights.

const scene = new THREE.Scene();

Adding a Mesh

This code sample shows how to create a simple cube mesh with a green color and add it to the scene. A mesh consists of a geometry and a material.

const geometry = new THREE.BoxGeometry(1, 1, 1);
const material = new THREE.MeshBasicMaterial({ color: 0x00ff00 });
const cube = new THREE.Mesh(geometry, material);
scene.add(cube);

Setting up a Camera

This code sets up a perspective camera with a certain field of view, aspect ratio, and near and far clipping planes. The camera is positioned 5 units away from the origin along the z-axis.

const camera = new THREE.PerspectiveCamera(75, window.innerWidth / window.innerHeight, 0.1, 1000);
camera.position.z = 5;

Rendering the Scene

This code sample initializes a WebGL renderer, sets its size, and appends its DOM element to the body of the document. It also defines an animate function that continuously renders the scene using the camera.

const renderer = new THREE.WebGLRenderer();
renderer.setSize(window.innerWidth, window.innerHeight);
document.body.appendChild(renderer.domElement);
function animate() {
  requestAnimationFrame(animate);
  renderer.render(scene, camera);
}
animate();

Adding Lights

This code sample adds a point light to the scene, which emits light in all directions. The light's color, intensity, and distance are set, and its position is placed at coordinates (10, 10, 10).

const light = new THREE.PointLight(0xffffff, 1, 100);
light.position.set(10, 10, 10);
scene.add(light);

Other packages similar to three

babylonjs

Babylon.js is a powerful, beautiful, simple, and open game and rendering engine packed into a friendly JavaScript framework. Similar to Three.js, it allows developers to create 3D content for the web. Babylon.js has a different API and additional features like a physics engine and advanced particle systems.

playcanvas

PlayCanvas is an open-source 3D engine/IDE that is specifically designed for the web. It offers real-time collaboration features and is more focused on game development. It provides an editor for building 3D applications and has a different approach to workflow compared to Three.js.

aframe

A-Frame is a web framework for building virtual reality (VR) experiences. It is built on top of Three.js and abstracts away the complexity of Three.js with a declarative HTML-like syntax. A-Frame is designed for creating VR experiences and is more accessible for web developers who are familiar with HTML and JavaScript.

README

three.js

JavaScript 3D library

The aim of the project is to create an easy-to-use, lightweight, cross-browser, general-purpose 3D library. The current builds only include a WebGL renderer but WebGPU (experimental), SVG and CSS3D renderers are also available as addons.

Examples — Docs — Manual — Wiki — Migrating — Questions — Forum — Discord

Usage

This code creates a scene, a camera, and a geometric cube, and it adds the cube to the scene. It then creates a WebGL renderer for the scene and camera, and it adds that viewport to the document.body element. Finally, it animates the cube within the scene for the camera.

import * as THREE from 'three';

const width = window.innerWidth, height = window.innerHeight;

// init

const camera = new THREE.PerspectiveCamera( 70, width / height, 0.01, 10 );
camera.position.z = 1;

const scene = new THREE.Scene();

const geometry = new THREE.BoxGeometry( 0.2, 0.2, 0.2 );
const material = new THREE.MeshNormalMaterial();

const mesh = new THREE.Mesh( geometry, material );
scene.add( mesh );

const renderer = new THREE.WebGLRenderer( { antialias: true } );
renderer.setSize( width, height );
renderer.setAnimationLoop( animate );
document.body.appendChild( renderer.domElement );

// animation

function animate( time ) {

	mesh.rotation.x = time / 2000;
	mesh.rotation.y = time / 1000;

	renderer.render( scene, camera );

}

If everything goes well, you should see this.

Cloning this repository

Cloning the repo with all its history results in a ~2 GB download. If you don't need the whole history you can use the depth parameter to significantly reduce download size.

git clone --depth=1 https://github.com/mrdoob/three.js.git

Change log

Releases