ThreeJS Objects

Bone

A bone that is part of a Skeleton. The skeleton in turn is used by the SkinnedMesh. Bones are almost identical to a blank Object3D.

Code Example

const root = new THREE.Bone();
const child = new THREE.Bone();


root.add( child );
child.position.y = 5;

Constructor

Bone( )

Creates a new Bone.

Properties

See the base Object3D class for common properties.

.isBone : Boolean

Read-only flag to check whether a given object is of type Bone.

.type : String

Set to 'Bone', this can be used to find all Bones in a scene.

Methods

See the base Object3D class for common methods.

Group

This is almost identical to an Object3D. Its purpose is to make working with groups of objects syntactically clearer.

Code Example

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


const cubeA = new THREE.Mesh( geometry, material );
cubeA.position.set( 100, 100, 0 );


const cubeB = new THREE.Mesh( geometry, material );
cubeB.position.set( -100, -100, 0 );


//create a group and add the two cubes
//These cubes can now be rotated / scaled etc as a group
const group = new THREE.Group();
group.add( cubeA );
group.add( cubeB );


scene.add( group );

Constructor

Group( )

Properties

See the base Object3D class for common properties.

.isGroup : Boolean

Read-only flag to check whether a given object is of type Group.

.type : String

A string 'Group'. This should not be changed.

Methods

See the base Object3D class for common methods.

InstancedMesh

A special version of Mesh with instanced rendering support. Use InstancedMesh if you have to render a large number of objects with the same geometry and material but with different world transformations. The usage of InstancedMesh will help you to reduce the number of draw calls and thus improve the overall rendering performance in your application.

Constructor

InstancedMesh( geometry : BufferGeometry, material : Material, count : Integer )

geometry - an instance of BufferGeometry.

material - an instance of Material. Default is a new MeshBasicMaterial.

count - the number of instances.

Properties

See the base Mesh class for common properties.

.count : Integer

The number of instances. The count value passed into the constructor represents the maximum number of instances of this mesh. You can change the number of instances at runtime to an integer value in the range [0, count].

If you need more instances than the original count value, you have to create a new InstancedMesh.

.instanceColor : InstancedBufferAttribute

Represents the colors of all instances. null by default. You have to set its needsUpdate flag to true if you modify instanced data via .setColorAt().

.instanceMatrix : InstancedBufferAttribute

Represents the local transformation of all instances. You have to set its needsUpdate flag to true if you modify instanced data via .setMatrixAt().

.isInstancedMesh : Boolean

Read-only flag to check whether a given object is of type InstancedMesh.

Methods

See the base Mesh class for common methods.

.dispose () : undefined

Frees the internal resources of this instance.

.getColorAt ( index : Integer, color : Color ) : undefined

index: The index of an instance. Values have to be in the range [0, count].

color: This color object will be set to the color of the defined instance.

Get the color of the defined instance.

.getMatrixAt ( index : Integer, matrix : Matrix4 ) : undefined

index: The index of an instance. Values have to be in the range [0, count].

matrix: This 4x4 matrix will be set to the local transformation matrix of the defined instance.

Get the local transformation matrix of the defined instance.

.setColorAt ( index : Integer, color : Color ) : undefined

index: The index of an instance. Values have to be in the range [0, count].

color: The color of a single instance.

Sets the given color to the defined instance. Make sure you set .instanceColor.needsUpdate to true after updating all the colors.

.setMatrixAt ( index : Integer, matrix : Matrix4 ) : undefined

index: The index of an instance. Values have to be in the range [0, count].

matrix: A 4x4 matrix representing the local transformation of a single instance.

Sets the given local transformation matrix to the defined instance. Make sure you set .instanceMatrix.needsUpdate to true after updating all the matrices.

Line

A continuous line.

This is nearly the same as LineSegments; the only difference is that it is rendered using gl.LINE_STRIP instead of gl.LINES

Code Example

const material = new THREE.LineBasicMaterial({
	color: 0x0000ff
});


const points = [];
points.push( new THREE.Vector3( - 10, 0, 0 ) );
points.push( new THREE.Vector3( 0, 10, 0 ) );
points.push( new THREE.Vector3( 10, 0, 0 ) );


const geometry = new THREE.BufferGeometry().setFromPoints( points );


const line = new THREE.Line( geometry, material );
scene.add( line );

Constructor

Line( geometry : BufferGeometry, material : Material )

geometry — vertices representing the line segment(s). Default is a new BufferGeometry.

material — material for the line. Default is a new LineBasicMaterial.

Properties

See the base Object3D class for common properties.

.geometry : BufferGeometry

Vertices representing the line segment(s).

.isLine : Boolean

Read-only flag to check whether a given object is of type Line.

.material : Material

Material for the line.

.morphTargetInfluences : Array

An array of weights typically from 0-1 that specify how much of the morph is applied. Undefined by default, but reset to a blank array by .updateMorphTargets().

.morphTargetDictionary : Object

A dictionary of morphTargets based on the morphTarget.name property. Undefined by default, but rebuilt .updateMorphTargets().

Methods

See the base Object3D class for common methods.

.computeLineDistances () : this

Computes an array of distance values which are necessary for LineDashedMaterial. For each vertex in the geometry, the method calculates the cumulative length from the current point to the very beginning of the line.

.raycast ( raycaster : Raycaster, intersects : Array ) : undefined

Get intersections between a casted Ray and this Line. Raycaster.intersectObject will call this method.

.clone () : Line

Returns a clone of this Line object and its descendants.

.updateMorphTargets () : undefined

Updates the morphTargets to have no influence on the object. Resets the .morphTargetInfluences and .morphTargetDictionary properties.

LineLoop

A continuous line that connects back to the start.

This is nearly the same as Line; the only difference is that it is rendered using gl.LINE_LOOP instead of gl.LINE_STRIP, which draws a straight line to the next vertex, and connects the last vertex back to the first.

Constructor

LineLoop( geometry : BufferGeometry, material : Material )

geometry — List of vertices representing points on the line loop.

material — Material for the line. Default is LineBasicMaterial.

Properties

See the base Line class for common properties.

.isLineLoop : Boolean

Read-only flag to check whether a given object is of type LineLoop.

Methods

See the base Line class for common methods

LineSegments

A series of lines drawn between pairs of vertices.

This is nearly the same as Line; the only difference is that it is rendered using gl.LINES instead of gl.LINE_STRIP.

Constructor

LineSegments( geometry : BufferGeometry, material : Material )

geometry — Pair(s) of vertices representing each line segment(s).

material — Material for the line. Default is LineBasicMaterial.

Properties

See the base Line class for common properties.

.isLineSegments : Boolean

Read-only flag to check whether a given object is of type LineSegments.

Methods

See the base Line class for common methods.

LOD

Level of Detail - show meshes with more or less geometry based on distance from the camera.

Every level is associated with an object, and rendering can be switched between them at the distances specified. Typically you would create, say, three meshes, one for far away (low detail), one for mid range (medium detail) and one for close up (high detail).

Code Example

const lod = new THREE.LOD();


//Create spheres with 3 levels of detail and create new LOD levels for them
for( let i = 0; i < 3; i++ ) {


	const geometry = new THREE.IcosahedronGeometry( 10, 3 - i )


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


	lod.addLevel( mesh, i * 75 );


}

scene.add( lod );

Constructor

LOD( )

Creates a new LOD.

Properties

See the base Object3D class for common properties.

.autoUpdate : Boolean

Whether the LOD object is updated automatically by the renderer per frame or not. If set to false, you have to call LOD.update() in the render loop by yourself. Default is true.

.isLOD : Boolean

Read-only flag to check whether a given object is of type LOD.

.levels : Array

An array of level objects

Each level is an object with two properties:

object - The Object3D to display at this level.

distance - The distance at which to display this level of detail.

Methods

See the base Object3D class for common methods.

.addLevel ( object : Object3D, distance : Float ) : this

object - The Object3D to display at this level.

distance - The distance at which to display this level of detail.

Adds a mesh that will display at a certain distance and greater. Typically the further away the distance, the lower the detail on the mesh.

.clone () : LOD

Returns a clone of this LOD object and its associated distance specific objects.

.getCurrentLevel () : Integer

Get the currently active LOD level. As index of the levels array.

.getObjectForDistance ( distance : Float ) : Object3D

Get a reference to the first Object3D (mesh) that is greater than distance.

.raycast ( raycaster : Raycaster, intersects : Array ) : Array

Get intersections between a casted Ray and this LOD. Raycaster.intersectObject will call this method.

.toJSON ( meta ) : Object

Create a JSON structure with details of this LOD object.

.update ( camera : Camera ) : undefined

Set the visibility of each level's object based on distance from the camera.

Mesh

Class representing triangular polygon mesh based objects. Also serves as a base for other classes such as SkinnedMesh.

Code Example

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

Constructor

Mesh( geometry : BufferGeometry, material : Material )

geometry — (optional) an instance of BufferGeometry. Default is a new BufferGeometry.

material — (optional) a single or an array of Material. Default is a new MeshBasicMaterial

Properties

See the base Object3D class for common properties.

.geometry : BufferGeometry

An instance of BufferGeometry (or derived classes), defining the object's structure.

.isMesh : Boolean

Read-only flag to check whether a given object is of type Mesh.

.material : Material

An instance of material derived from the Material base class or an array of materials, defining the object's appearance. Default is a MeshBasicMaterial.

.morphTargetInfluences : Array

An array of weights typically from 0-1 that specify how much of the morph is applied. Undefined by default, but reset to a blank array by updateMorphTargets.

.morphTargetDictionary : Object

A dictionary of morphTargets based on the morphTarget.name property. Undefined by default, but rebuilt updateMorphTargets.

Methods

See the base Object3D class for common methods.

.clone () : Mesh

Returns a clone of this Mesh object and its descendants.

.raycast ( raycaster : Raycaster, intersects : Array ) : undefined

Get intersections between a casted ray and this mesh. Raycaster.intersectObject will call this method, but the results are not ordered.

.updateMorphTargets () : undefined

Updates the morphTargets to have no influence on the object. Resets the morphTargetInfluences and morphTargetDictionary properties.

Points

A class for displaying points. The points are rendered by the WebGLRenderer using gl.POINTS.

Constructor

Points( geometry : BufferGeometry, material : Material )

geometry — (optional) an instance of BufferGeometry. Default is a new BufferGeometry.

material — (optional) a Material. Default is a new PointsMaterial.

Properties

See the base Object3D class for common properties.

.geometry : BufferGeometry

An instance of BufferGeometry (or derived classes), defining the object's structure.

.isPoints : Boolean

Read-only flag to check whether a given object is of type Points.

.material : Material

An instance of Material, defining the object's appearance. Default is a PointsMaterial.

.morphTargetInfluences : Array

An array of weights typically from 0-1 that specify how much of the morph is applied. Undefined by default, but reset to a blank array by updateMorphTargets.

.morphTargetDictionary : Object

A dictionary of morphTargets based on the morphTarget.name property. Undefined by default, but rebuilt updateMorphTargets.

Methods

See the base Object3D class for common methods.

.raycast ( raycaster : Raycaster, intersects : Array ) : undefined

Get intersections between a casted ray and this Points. Raycaster.intersectObject will call this method.

.clone () : Points

Returns a clone of this Points object and its descendants.

.updateMorphTargets () : undefined

Updates the morphTargets to have no influence on the object. Resets the morphTargetInfluences and morphTargetDictionary properties.

Skeleton

Use an array of bones to create a skeleton that can be used by a SkinnedMesh.

Code Example

// Create a simple "arm"


const bones = [];


const shoulder = new THREE.Bone();
const elbow = new THREE.Bone();
const hand = new THREE.Bone();


shoulder.add( elbow );
elbow.add( hand );


bones.push( shoulder );
bones.push( elbow );
bones.push( hand );


shoulder.position.y = -5;
elbow.position.y = 0;
hand.position.y = 5;


const armSkeleton = new THREE.Skeleton( bones );

See the SkinnedMesh page for an example of usage with standard BufferGeometry.

Constructor

Skeleton( bones : Array, boneInverses : Array )

bones - The array of bones. Default is an empty array.

boneInverses - (optional) An array of Matrix4s.

Creates a new Skeleton.

Properties

.bones : Array

The array of bones. Note this is a copy of the original array, not a reference, so you can modify the original array without effecting this one.

.boneInverses : Array

An array of Matrix4s that represent the inverse of the matrixWorld of the individual bones.

.boneMatrices : Float32Array

The array buffer holding the bone data when using a vertex texture.

.boneTexture : DataTexture

The DataTexture holding the bone data when using a vertex texture.

.boneTextureSize : Integer

The size of the .boneTexture.

Methods

.clone () : Skeleton

Returns a clone of this Skeleton object.

.calculateInverses () : undefined

Generates the boneInverses array if not provided in the constructor.

.computeBoneTexture () : this

Computes an instance of DataTexture in order to pass the bone data more efficiently to the shader. The texture is assigned to boneTexture.

.pose () : undefined

Returns the skeleton to the base pose.

.update () : undefined

Updates the boneMatrices and boneTexture after changing the bones. This is called automatically by the WebGLRenderer if the skeleton is used with a SkinnedMesh.

.getBoneByName ( name : String ) : Bone

name -- String to match to the Bone's .name property.

Searches through the skeleton's bone array and returns the first with a matching name.

.dispose () : undefined

Can be used if an instance of Skeleton becomes obsolete in an application. The method will free internal resources.

SkinnedMesh

A mesh that has a Skeleton with bones that can then be used to animate the vertices of the geometry.

Code Example

const geometry = new THREE.CylinderGeometry( 5, 5, 5, 5, 15, 5, 30 );


// create the skin indices and skin weights manually
// (typically a loader would read this data from a 3D model for you)


const position = geometry.attributes.position;


const vertex = new THREE.Vector3();


const skinIndices = [];
const skinWeights = [];


for ( let i = 0; i < position.count; i ++ ) {


	vertex.fromBufferAttribute( position, i );


	// compute skinIndex and skinWeight based on some configuration data


	const y = ( vertex.y + sizing.halfHeight );


	const skinIndex = Math.floor( y / sizing.segmentHeight );
	const skinWeight = ( y % sizing.segmentHeight ) / sizing.segmentHeight;


	skinIndices.push( skinIndex, skinIndex + 1, 0, 0 );
	skinWeights.push( 1 - skinWeight, skinWeight, 0, 0 );


}


geometry.setAttribute( 'skinIndex', new THREE.Uint16BufferAttribute( skinIndices, 4 ) );
geometry.setAttribute( 'skinWeight', new THREE.Float32BufferAttribute( skinWeights, 4 ) );


// create skinned mesh and skeleton


const mesh = new THREE.SkinnedMesh( geometry, material );
const skeleton = new THREE.Skeleton( bones );


// see example from THREE.Skeleton


const rootBone = skeleton.bones[ 0 ];
mesh.add( rootBone );


// bind the skeleton to the mesh


mesh.bind( skeleton );


// move the bones and manipulate the model


skeleton.bones[ 0 ].rotation.x = -0.1;
skeleton.bones[ 1 ].rotation.x = 0.2;

Constructor

SkinnedMesh( geometry : BufferGeometry, material : Material )

geometry - an instance of BufferGeometry.

material - (optional) an instance of Material. Default is a new MeshBasicMaterial.

Properties

See the base Mesh class for common properties.

.bindMode : String

Either "attached" or "detached". "attached" uses the SkinnedMesh.matrixWorld property for the base transform matrix of the bones. "detached" uses the SkinnedMesh.bindMatrix. Default is "attached".

.bindMatrix : Matrix4

The base matrix that is used for the bound bone transforms.

.bindMatrixInverse : Matrix4

The base matrix that is used for resetting the bound bone transforms.

.isSkinnedMesh : Boolean

Read-only flag to check whether a given object is of type SkinnedMesh.

.skeleton : Skeleton

Skeleton representing the bone hierarchy of the skinned mesh.

Methods

See the base Mesh class for common methods.

.bind ( skeleton : Skeleton, bindMatrix : Matrix4 ) : undefined

skeleton - Skeleton created from a Bones tree.

bindMatrix - Matrix4 that represents the base transform of the skeleton.

Bind a skeleton to the skinned mesh. The bindMatrix gets saved to .bindMatrix property and the .bindMatrixInverse gets calculated.

.clone () : SkinnedMesh

This method does currently not clone an instance of SkinnedMesh correctly. Please use SkeletonUtils.clone() in the meanwhile.

.normalizeSkinWeights () : undefined

Normalizes the skin weights.

.pose () : undefined

This method sets the skinned mesh in the rest pose (resets the pose).

.boneTransform ( index : Integer, target : Vector3 ) : Vector3

Calculates the position of the vertex at the given index relative to the current bone transformations. Target vector must be initialized with the vetrex coordinates prior to the transformation:

const target = new THREE.Vector3();

target.fromBufferAttribute( mesh.geometry.attributes.position, index );

mesh.boneTransform( index, target );

Sprite

A sprite is a plane that always faces towards the camera, generally with a partially transparent texture applied.

Sprites do not cast shadows, setting

castShadow = truewill have no effect.

Code Example

const map = new THREE.TextureLoader().load( 'sprite.png' );
const material = new THREE.SpriteMaterial( { map: map } );


const sprite = new THREE.Sprite( material );
scene.add( sprite );

Constructor

Sprite( material : Material )

material - (optional) an instance of SpriteMaterial. Default is a white SpriteMaterial.

Creates a new Sprite.

Properties

See the base Object3D class for common properties.

.isSprite : Boolean

Read-only flag to check whether a given object is of type Sprite.

.material : SpriteMaterial

An instance of SpriteMaterial, defining the object's appearance. Default is a white SpriteMaterial.

.center : Vector2

The sprite's anchor point, and the point around which the sprite rotates. A value of (0.5, 0.5) corresponds to the midpoint of the sprite. A value of (0, 0) corresponds to the lower left corner of the sprite. The default is (0.5, 0.5).

Methods

See the base Object3D class for common methods.

.clone () : Sprite

Returns a clone of this Sprite object and any descendants.

.copy ( sprite : Sprite ) : this

Copies the properties of the passed sprite to this one.

.raycast ( raycaster : Raycaster, intersects : Array ) : undefined

Get intersections between a casted ray and this sprite. Raycaster.intersectObject() will call this method. The raycaster must be initialized by calling Raycaster.setFromCamera() before raycasting against sprites.