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.