gitadmin
/
three.js
mirror of https://github.com/mrdoob/three.js.git


			
				
					
						
						
							123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238
							<!DOCTYPE html>
<html lang="en">
	<head>
		<meta charset="utf-8" />
		<base href="../../../" />
		<script src="page.js"></script>
		<link type="text/css" rel="stylesheet" href="page.css" />
	</head>
	<body>
		<h1>[name]</h1>

		<p class="desc">
			This class is designed to assist with
			[link:https://en.wikipedia.org/wiki/Ray_casting raycasting]. Raycasting is
			used for mouse picking (working out what objects in the 3d space the mouse
			is over) amongst other things.
		</p>

		<h2>Code Example</h2>
		<code>
		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);

		</code>

		<h2>Examples</h2>

		<p>
			[example:webgl_interactive_cubes Raycasting to a Mesh]<br />
			[example:webgl_interactive_cubes_ortho Raycasting to a Mesh in using an OrthographicCamera]<br />
			[example:webgl_interactive_buffergeometry Raycasting to a Mesh with BufferGeometry]<br />
			[example:webgl_instancing_raycast Raycasting to a InstancedMesh]<br />
			[example:webgl_interactive_lines Raycasting to a Line]<br />
			[example:webgl_interactive_raycasting_points Raycasting to Points]<br />
			[example:webgl_geometry_terrain_raycast Terrain raycasting]<br />
			[example:webgl_interactive_voxelpainter Raycasting to paint voxels]<br />
			[example:webgl_raycaster_texture Raycast to a Texture]
		</p>

		<h2>Constructor</h2>

		<h3>[name]( [param:Vector3 origin], [param:Vector3 direction], [param:Float near], [param:Float far] )</h3>
		<p>
			[page:Vector3 origin] — The origin vector where the ray casts from.<br />
			[page:Vector3 direction] — The direction vector that gives direction to
			the ray. Should be normalized.<br />
			[page:Float near] — All results returned are further away than near. Near
			can't be negative. Default value is `0`.<br />
			[page:Float far] — All results returned are closer than far. Far can't be
			lower than near. Default value is Infinity.
		</p>
		<p>This creates a new raycaster object.<br /></p>

		<h2>Properties</h2>

		<h3>[property:Float far]</h3>
		<p>
			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.
		</p>

		<h3>[property:Float near]</h3>
		<p>
			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.
		</p>

		<h3>[property:Camera camera]</h3>
		<p>
			The camera to use when raycasting against view-dependent objects such as
			billboarded objects like [page:Sprites]. This field can be set manually or
			is set when calling "setFromCamera". Defaults to null.
		</p>

		<h3>[property:Layers layers]</h3>
		<p>
			Used by [name] 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 [name].

			<code>
raycaster.layers.set( 1 );
object.layers.enable( 1 );
			</code>
		</p>

		<h3>[property:Object params]</h3>
		<p>
			An object with the following properties:

			<code>
{
	Mesh: {},
	Line: { threshold: 1 },
	LOD: {},
	Points: { threshold: 1 },
	Sprite: {}
}
			</code>

			Where threshold is the precision of the raycaster when intersecting
			objects, in world units.
		</p>

		<h3>[property:Ray ray]</h3>
		<p>The [Page:Ray] used for the raycasting.</p>

		<h2>Methods</h2>

		<h3>[method:undefined set]( [param:Vector3 origin], [param:Vector3 direction])</h3>
		<p>
			[page:Vector3 origin] — The origin vector where the ray casts from.<br />
			[page:Vector3 direction] — The normalized direction vector that gives
			direction to the ray.
		</p>
		<p>
			Updates the ray with a new origin and direction. Please note that this
			method only copies the values from the arguments.
		</p>

		<h3>[method:undefined setFromCamera]( [param:Vector2 coords], [param:Camera camera] )</h3>
		<p>
			[page:Vector2 coords] — 2D coordinates of the mouse, in normalized device
			coordinates (NDC)---X and Y components should be between `-1` and `1`.<br />
			[page:Camera camera] — camera from which the ray should originate
		</p>
		<p>Updates the ray with a new origin and direction.</p>

		<h3>[method:this setFromXRController]( [param:WebXRController controller] )</h3>
		<p>
			[page:WebXRController controller] — The controller to copy the position and direction from.
		</p>
		<p>Updates the ray with a new origin and direction.</p>

		<h3>[method:Array intersectObject]( [param:Object3D object], [param:Boolean recursive], [param:Array optionalTarget] )</h3>
		<p>
			[page:Object3D object] — The object to check for intersection with the
			ray.<br />
			[page:Boolean recursive] — If true, it also checks all descendants.
			Otherwise it only checks intersection with the object. Default is true.<br />
			[page:Array optionalTarget] — (optional) target to set the result.
			Otherwise a new [page:Array] is instantiated. If set, you must clear this
			array prior to each call (i.e., array.length = 0;).
		</p>
		<p>
			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...
		</p>
		<code> [ { distance, point, face, faceIndex, object }, ... ] </code>
		<p>
			[page:Float distance] – distance between the origin of the ray and the
			intersection<br />
			[page:Vector3 point] – point of intersection, in world coordinates<br />
			[page:Object face] – intersected face<br />
			[page:Integer faceIndex] – index of the intersected face<br />
			[page:Object3D object] – the intersected object<br />
			[page:Vector2 uv] - U,V coordinates at point of intersection<br />
			[page:Vector2 uv1] - Second set of U,V coordinates at point of
			intersection<br />
			[page:Vector3 normal] - interpolated normal vector at point of
			intersection<br />
			[page:Integer instanceId] – The index number of the instance where the ray
			intersects the InstancedMesh
		</p>
		<p>
			`Raycaster` delegates to the [page:Object3D.raycast raycast] method of the
			passed object, when evaluating whether the ray intersects the object or
			not. This allows [page:Mesh meshes] to respond differently to ray casting
			than [page:Line lines] and [page:Points pointclouds].
		</p>
		<p>
			*Note* that for meshes, faces must be pointed towards the origin of the
			[page:.ray ray] in order to be detected; intersections of the ray passing
			through the back of a face will not be detected. To raycast against both
			faces of an object, you'll want to set the [page:Mesh.material material]'s
			[page:Material.side side] property to `THREE.DoubleSide`.
		</p>

		<h3>[method:Array intersectObjects]( [param:Array objects], [param:Boolean recursive], [param:Array optionalTarget] )</h3>
		<p>
			[page:Array objects] — The objects to check for intersection with the
			ray.<br />
			[page:Boolean recursive] — If true, it also checks all descendants of the
			objects. Otherwise it only checks intersection with the objects. Default
			is true.<br />
			[page:Array optionalTarget] — (optional) target to set the result.
			Otherwise a new [page:Array] is instantiated. If set, you must clear this
			array prior to each call (i.e., array.length = 0;).
		</p>
		<p>
			Checks all intersection between the ray and the objects with or without
			the descendants. Intersections are returned sorted by distance, closest
			first. Intersections are of the same form as those returned by
			[page:.intersectObject].
		</p>

		<h2>Source</h2>

		<p>
			[link:https://github.com/mrdoob/three.js/blob/master/src/[path].js src/[path].js]
		</p>
	</body>
</html>