ThreeJS Raycaster
This class is intended to help with raycasting. Raycasting is used for a variety of purposes, including mouse picking (determining which objects in 3D space the mouse is over).
Code Example
const raycaster = new THREE.Raycaster();
const pointer = new THREE.Vector2();
function onPointerMove( event ) {
// calculate pointer position in normalized device coordinates
// (-1 to +1) for both components
pointer.x = ( event.clientX / window.innerWidth ) * 2 - 1;
pointer.y = - ( event.clientY / window.innerHeight ) * 2 + 1;
}
function render() {
// update the picking ray with the camera and pointer position
raycaster.setFromCamera( pointer, camera );
// calculate objects intersecting the picking ray
const intersects = raycaster.intersectObjects( scene.children );
for ( let i = 0; i < intersects.length; i ++ ) {
intersects[ i ].object.material.color.set( 0xff0000 );
}
renderer.render( scene, camera );
}
window.addEventListener( 'pointermove', onPointerMove );
window.requestAnimationFrame(render);
Constructor
Raycaster( origin : Vector3, direction : Vector3, near : Float, far : Float )
- origin — The origin vector where the ray casts from.
- direction — The direction vector that gives direction to the ray. Should be normalized.
- near — All results returned are further away than near. Near can't be negative. Default value is 0.
- far — All results returned are closer than far. Far can't be lower than near. Default value is Infinity.
This creates a new raycaster object.
Properties
.far : Float
The far factor of the raycaster. This value indicates which objects can be discarded based on the distance. This value shouldn't be negative and should be larger than the near property.
.near : Float
The near factor of the raycaster. This value indicates which objects can be discarded based on the distance. This value shouldn't be negative and should be smaller than the far property.
.camera : Camera
The camera to use when raycasting against view-dependent objects such as billboarded objects like Sprites. This field can be set manually or is set when calling "setFromCamera". Defaults to null.
.layers : Layers
Used by Raycaster to selectively ignore 3D objects when performing intersection tests. The following code example ensures that only 3D objects on layer 1 will be honored by the instance of Raycaster.
raycaster.layers.set( 1 );
object.layers.enable( 1 );
.params : Object
An object with the following properties:
{
Mesh: {},
Line: { threshold: 1 },
LOD: {},
Points: { threshold: 1 },
Sprite: {}
}
Where threshold is the precision of the raycaster when intersecting objects, in world units.
.ray : Ray
The Ray used for the raycasting.
Methods
.set ( origin : Vector3, direction : Vector3 ) : undefined
origin — The origin vector where the ray casts from.
direction — The normalized direction vector that gives direction to the ray.
Updates the ray with a new origin and direction. Please note that this method only copies the values from the arguments.
.setFromCamera ( coords : Vector2, camera : Camera ) : undefined
coords — 2D coordinates of the mouse, in normalized device coordinates (NDC)---X and Y components should be between -1 and 1.
camera — camera from which the ray should originate
Updates the ray with a new origin and direction.
.intersectObject ( object : Object3D, recursive : Boolean, optionalTarget : Array ) : Array
object — The object to check for intersection with the ray.
recursive — If true, it also checks all descendants. Otherwise it only checks intersection with the object. Default is true.
optionalTarget — (optional) target to set the result. Otherwise a new Array is instantiated. If set, you must clear this array prior to each call (i.e., array.length = 0;).
Checks all intersection between the ray and the object with or without the descendants. Intersections are returned sorted by distance, closest first. An array of intersections is returned...
[ { distance, point, face, faceIndex, object }, ... ]
distance – distance between the origin of the ray and the intersection
point – point of intersection, in world coordinates
face – intersected face
faceIndex – index of the intersected face
object – the intersected object
uv - U,V coordinates at point of intersection
uv2 - Second set of U,V coordinates at point of intersection
instanceId – The index number of the instance where the ray intersects the InstancedMesh
When determining whether or not the ray intersects the object, Raycaster delegated to the raycast method of the passed object. Meshes, unlike lines and pointclouds, can respond differently to ray casting.
Faces must be pointed towards the origin of the ray in order to be detected for meshes; intersections of the ray passing through the back of a face will not be detected. Set the material's side property to THREE to raycast against both faces of an object. DoubleSide.
.intersectObjects ( objects : Array, recursive : Boolean, optionalTarget : Array ) : Array
objects — The objects to check for intersection with the ray.
recursive — If true, it also checks all descendants of the objects. Otherwise it only checks intersection with the objects. Default is true.
optionalTarget — (optional) target to set the result. Otherwise a new Array is instantiated. If set, you must clear this array prior to each call (i.e., array.length = 0;).
Examines all intersections between the ray and the objects, with or without descendants. Intersections are returned in order of proximity, closest first. Intersections take the same shape as those returned by .intersectObject.