Three.js Tutorial

Three.js Tutorial Three.js Installation Compatibility and Running Locally Three.js Lines and Texts Three.js Loading 3D Models Three.js Updating Things Three.js Disposing of an Object Three.js Creating VR Content Three.js Using post-processing Three.js Matrix Transformations Three.js Animation Systems Three.js Testing with NPM Three.js AnimationAction Three.js AnimationClip Three.js AnimationMixer Animation Object Group and Utils Three.js Keyframe Track Property Binding and Mixer Three.js Animation/ Tracks Three.js Audio Three.js Camera Three.js Buffer Attribute Three.js Buffer Geometry Three.js Interleaved Buffer Three.js Layers Three.js Object3D Three.js Raycaster Three.js Uniform Three.js Curves Three.js Geometries- 1 Three.js Helpers- 1 Three.js Helpers- 2 Three.js Lights Three.js Shadows Three.js Loaders- 1 Three.js Loaders- 2 Three.js Managers Three.js Materials Three.js Materials- Mesh Three.js Materials- 3 Three.js Math Three.js Interpolant Three.js Objects Three.js Renderers Three.js Scenes

ThreeJS Lights
2022-05-01 08:35:14

ThreeJS Lights

Light

Abstract base class for lights - all other light types inherit the properties and methods described here.

Constructor

Light( color : Integer, intensity : Float )

color - (optional) hexadecimal color of the light. Default is 0xffffff (white).

intensity - (optional) numeric value of the light's strength/intensity. Default is 1.

Creates a new Light. Note that this is not intended to be called directly (use one of derived classes instead).

Properties

See the base Object3D class for common properties.

.color : Color

Color of the light. Defaults to a new Color set to white, if not passed in the constructor.

.intensity : Float

The light's intensity, or strength.

In physically correct mode, the units of intensity depend on the type of light.

Default - 1.0.

Methods

See the base Object3D class for common methods.

.dispose () : undefined

Abstract dispose method for lights; implemented by subclasses that have disposable resources.

.copy ( source : Light ) : this

Copies the value of color and intensity from the source light into this one.

.toJSON ( meta : Object ) : Object

meta -- object containing metadata such as materials, textures for objects.

Convert the light to three.js JSON Object/Scene format.

LightProbe

Light probes are a different way to add light to a 3D scene. Light probes, unlike traditional light sources (such as directional, point, or spot lights), do not emit light. Instead, they save data about light as it moves through 3D space. The light that strikes a 3D object is approximated during rendering by using data from the light probe.

Light probes are typically built using (radiance) environment maps. Light probes can be generated using the LightProbeGenerator class from instances of CubeTexture or WebGLCubeRenderTarget. However, light estimation data could be provided in other ways, such as by WebXR. This allows for the creation of augmented reality content that responds to real-world lighting.

The current probe implementation in three.js supports so-called diffuse light probes. This type of light probe is functionally equivalent to an irradiance environment map.

Constructor

LightProbe( sh : SphericalHarmonics3, intensity : Float )

sh - (optional) An instance of SphericalHarmonics3.

intensity - (optional) Numeric value of the light probe's intensity. Default is 1.

Creates a new LightProbe.

Properties

See the base Light class for common properties. The color property is currently not evaluated and thus has no effect.

.sh : SphericalHarmonics3

A light probe uses spherical harmonics to encode lighting information.

PointLight

A light that gets emitted from a single point in all directions. A common use case for this is to replicate the light emitted from a bare lightbulb.

Code Example

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

Constructor

PointLight( color : Integer, intensity : Float, distance : Number, decay : Float )

color - (optional) hexadecimal color of the light. Default is 0xffffff (white).

intensity - (optional) numeric value of the light's strength/intensity. Default is 1.

distance - Maximum range of the light. Default is 0 (no limit).

decay - The amount the light dims along the distance of the light. Default is 1. For physically correct lighting, set this to 2.

Creates a new PointLight.

Properties

See the base Light class for common properties.

.decay : Float

The amount the light dims along the distance of the light

In physically correct mode, decay = 2 leads to physically realistic light falloff.

Default is 1.

.distance : Float

Default mode — When distance is zero, light does not attenuate. When distance is non-zero, light will attenuate linearly from maximum intensity at the light's position down to zero at this distance from the light.

Physically correct mode — When distance is zero, light will attenuate according to inverse-square law to infinite distance. When distance is non-zero, light will attenuate according to inverse-square law until near the distance cutoff, where it will then attenuate quickly and smoothly to 0. Inherently, cutoffs are not physically correct.

Default is 0.0.

.intensity : Float

The light's intensity. Default is 1.

In physically correct mode, intensity is the luminous intensity of the light measured in candela (cd).

Changing the intensity will also change the light's power.

.power : Float

The light's power.

In physically correct mode, power is the luminous power of the light measured in lumens (lm).

Changing the power will also change the light's intensity.

.shadow : PointLightShadow

A PointLightShadow used to calculate shadows for this light.

The lightShadow's camera is set to a PerspectiveCamera with fov of 90, aspect of 1, near clipping plane at 0.5 and far clipping plane at 500.

Methods

See the base Light class for common methods.

.dispose () : undefined

Override of base class's dispose. Disposes of this light's shadow.

.copy ( source : PointLight ) : this

Copies value of all the properties from the source to this PointLight.

RectAreaLight

RectAreaLight emits light uniformly across the face a rectangular plane. This light type can be used to simulate light sources such as bright windows or strip lighting.

Important Notes:

  • There is no shadow support.
  • Only MeshStandardMaterial and MeshPhysicalMaterial are supported.
  • You have to include RectAreaLightUniformsLib into your scene and call init().

Code Example

const width = 10;
const height = 10;
const intensity = 1;
const rectLight = new THREE.RectAreaLight( 0xffffff, intensity,  width, height );
rectLight.position.set( 5, 5, 0 );
rectLight.lookAt( 0, 0, 0 );
scene.add( rectLight )


const rectLightHelper = new THREE.RectAreaLightHelper( rectLight );
rectLight.add( rectLightHelper );

Constructor

RectAreaLight( color : Integer, intensity : Float, width : Float, height : Float )

color - (optional) hexadecimal color of the light. Default is 0xffffff (white).

intensity - (optional) the light's intensity, or brightness. Default is 1.

width - (optional) width of the light. Default is 10.

height - (optional) height of the light. Default is 10.

Creates a new RectAreaLight.

Properties

See the base Light class for common properties.

.intensity : Float

The light's intensity. Default is 1.

In physically correct mode, intensity is the luminance (brightness) of the light measured in nits (cd/m^2).

Changing the intensity will also change the light's power.

.power : Float

The light's power.

In physically correct mode, power is the luminous power of the light measured in lumens (lm).

Changing the power will also change the light's intensity.

Methods

See the base Light class for common methods.

.copy ( source : RectAreaLight ) : this

Copies value of all the properties from the source to this RectAreaLight.

SpotLight

This light gets emitted from a single point in one direction, along a cone that increases in size the further from the light it gets.

This light can cast shadows - see the SpotLightShadow page for details.

Code Example

// white spotlight shining from the side, casting a shadow


const spotLight = new THREE.SpotLight( 0xffffff );
spotLight.position.set( 100, 1000, 100 );


spotLight.castShadow = true;


spotLight.shadow.mapSize.width = 1024;
spotLight.shadow.mapSize.height = 1024;


spotLight.shadow.camera.near = 500;
spotLight.shadow.camera.far = 4000;
spotLight.shadow.camera.fov = 30;


scene.add( spotLight );

Constructor

SpotLight( color : Integer, intensity : Float, distance : Float, angle : Radians, penumbra : Float, decay : Float )

color - (optional) hexadecimal color of the light. Default is 0xffffff (white).

intensity - (optional) numeric value of the light's strength/intensity. Default is 1.

distance - Maximum range of the light. Default is 0 (no limit).

angle - Maximum angle of light dispersion from its direction whose upper bound is Math.PI/2.

penumbra - Percent of the spotlight cone that is attenuated due to penumbra. Takes values between zero and 1. Default is zero.

decay - The amount the light dims along the distance of the light.

Creates a new SpotLight.

Properties

See the base Light class for common properties.

.angle : Float

Maximum extent of the spotlight, in radians, from its direction. Should be no more than Math.PI/2. The default is Math.PI/3.

.castShadow : Boolean

If set to true light will cast dynamic shadows. Warning: This is expensive and requires tweaking to get shadows looking right. See the SpotLightShadow for details. The default is false.

.decay : Float

The amount the light dims along the distance of the light.

In physically correct mode, decay = 2 leads to physically realistic light falloff. The default is 1.

.distance : Float

Default mode — When distance is zero, light does not attenuate. When distance is non-zero, light will attenuate linearly from maximum intensity at the light's position down to zero at this distance from the light.

Physically correct mode — When distance is zero, light will attenuate according to inverse-square law to infinite distance. When distance is non-zero, light will attenuate according to inverse-square law until near the distance cutoff, where it will then attenuate quickly and smoothly to 0. Inherently, cutoffs are not physically correct.

Default is 0.0.

.intensity : Float

The light's intensity. Default is 1.

In physically correct mode, intensity is the luminous intensity of the light measured in candela (cd).

Changing the power will also change the light's intensity.

.penumbra : Float

Percent of the spotlight cone that is attenuated due to penumbra. Takes values between zero and 1. The default is 0.0.

.position : Vector3

This is set equal to Object3D.DefaultUp (0, 1, 0), so that the light shines from the top down.

.power : Float

The light's power.

In physically correct mode, power is the luminous power of the light measured in lumens (lm).

Changing this will also change the light's intensity.

.shadow : SpotLightShadow

A SpotLightShadow used to calculate shadows for this light.

.target : Object3D

The Spotlight points from its position to target.position. The default position of the target is (0, 0, 0).

Note: For the target's position to be changed to anything other than the default, it must be added to the scene using

scene.add( light.target );

This is so that the target's matrixWorld gets automatically updated each frame.

It is also possible to set the target to be another object in the scene (anything with a position property), like so:

const targetObject = new THREE.Object3D();
scene.add(targetObject);


light.target = targetObject;

The spotlight will now track the target object.

Methods

See the base Light class for common methods.

.dispose () : undefined

Override of base class's dispose. Disposes of this light's shadow.

.copy ( source : SpotLight ) : this

Copies value of all the properties from the source to this SpotLight.

AmbientLight

This light globally illuminates all objects in the scene equally.

This light cannot be used to cast shadows as it does not have a direction.

Code Example

const light = new THREE.AmbientLight( 0x404040 ); // soft white light
scene.add( light );

Constructor

AmbientLight( color : Integer, intensity : Float )

color - (optional) Numeric value of the RGB component of the color. Default is 0xffffff.

intensity - (optional) Numeric value of the light's strength/intensity. Default is 1.

Creates a new AmbientLight.

AmbientLightProbe

Light probes are an alternative way of adding light to a 3D scene. AmbientLightProbe is the light estimation data of a single ambient light in the scene.

Constructor

AmbientLightProbe( color : Color, intensity : Float )

color - (optional) An instance of Color, string representing a color or a number representing a color.

intensity - (optional) Numeric value of the light probe's intensity. Default is 1.

Creates a new AmbientLightProbe.

DirectionalLight

A light that is emitted in only one direction. This light will behave as if it is infinitely far away, and the rays it produces will all be parallel. The most common application is to simulate daylight; the sun is far enough away that its position can be considered infinite, and all light rays emanating from it are parallel.

A Note about Position, Target and rotation

Setting the rotation has no effect on directional lights, which is a common source of confusion. This is due to the fact that three.js' DirectionalLight is the equivalent of what is commonly referred to as a 'Target Direct Light' in other applications.

This means that its direction is calculated as a ray pointing from the light's position to the target's position (as opposed to a 'Free Direct Light' with only a rotation component).

This is done to allow the light to cast shadows - the shadow camera requires a position from which to calculate shadows.

Code Example

// White directional light at half intensity shining from the top.
const directionalLight = new THREE.DirectionalLight( 0xffffff, 0.5 );
scene.add( directionalLight );

Constructor

DirectionalLight( color : Integer, intensity : Float )

color - (optional) hexadecimal color of the light. Default is 0xffffff (white).

intensity - (optional) numeric value of the light's strength/intensity. Default is 1.

Creates a new DirectionalLight.

Properties

See the base Light class for common properties.

.castShadow : Boolean

If set to true light will cast dynamic shadows. Warning: This is expensive and requires tweaking to get shadows looking right. See the DirectionalLightShadow for details. The default is false.

.position : Vector3

This is set equal to Object3D.DefaultUp (0, 1, 0), so that the light shines from the top down.

.shadow : DirectionalLightShadow

A DirectionalLightShadow used to calculate shadows for this light.

.target : Object3D

The DirectionalLight points from its position to target.position. The default position of the target is (0, 0, 0).

Note: For the target's position to be changed to anything other than the default, it must be added to the scene using

scene.add( light.target );

This is so that the target's matrixWorld gets automatically updated each frame.

It is also possible to set the target to be another object in the scene (anything with a position property), like so:

const targetObject = new THREE.Object3D();
scene.add(targetObject);


light.target = targetObject;

The directionalLight will now track the target object.

Methods

See the base Light class for common methods.

.dispose () : undefined

Override of base class's dispose. Disposes of this light's shadow.

.copy ( source : DirectionalLight ) : this

Copies value of all the properties from the source to this DirectionalLight.

HemisphereLight

A light source positioned directly above the scene, with color fading from the sky color to the ground color.

This light cannot be used to cast shadows.

Code Example

const light = new THREE.HemisphereLight( 0xffffbb, 0x080820, 1 );
scene.add( light );

Constructor

HemisphereLight( skyColor : Integer, groundColor : Integer, intensity : Float )

skyColor - (optional) hexadecimal color of the sky. Default is 0xffffff.

groundColor - (optional) hexadecimal color of the ground. Default is 0xffffff.

intensity - (optional) numeric value of the light's strength/intensity. Default is 1.

Creates a new HemisphereLight.

Properties

See the base Light class for common properties.

.color : Float

The light's sky color, as passed in the constructor. Default is a new Color set to white (0xffffff).

.groundColor : Float

The light's ground color, as passed in the constructor. Default is a new Color set to white (0xffffff).

.position : Vector3

This is set equal to Object3D.DefaultUp (0, 1, 0), so that the light shines from the top down.

Methods

See the base Light class for common methods.

.copy ( source : HemisphereLight ) : this

Copies the value of color, intensity and groundColor from the source light into this one.

HemisphereLightProbe

Light probes are an alternative way of adding light to a 3D scene. HemisphereLightProbe is the light estimation data of a single hemisphere light in the scene.

Constructor

HemisphereLightProbe( skyColor : Color, groundColor : Color, intensity : Float )

skyColor - (optional) An instance of Color, string representing a color or a number representing a color.

groundColor - (optional) An instance of Color, string representing a color or a number representing a color.

intensity - (optional) Numeric value of the light probe's intensity. Default is 1.

Creates a new HemisphereLightProbe.