Static
installStatic
ACTIONlist all ACTIONs
Creates a CameraControls
instance.
Note:
You must install three.js before using camera-controls. see #install
Not doing so will lead to runtime errors (undefined
references to THREE).
e.g.
CameraControls.install( { THREE } );
const cameraControls = new CameraControls( camera, domElement );
A THREE.PerspectiveCamera
or THREE.OrthographicCamera
to be controlled.
A HTMLElement
for the draggable area, usually renderer.domElement
.
Minimum vertical angle in radians.
The angle has to be between 0
and .maxPolarAngle
inclusive.
The default value is 0
.
e.g.
cameraControls.maxPolarAngle = 0;
Maximum vertical angle in radians.
The angle has to be between .maxPolarAngle
and Math.PI
inclusive.
The default value is Math.PI
.
e.g.
cameraControls.maxPolarAngle = Math.PI;
Minimum horizontal angle in radians.
The angle has to be less than .maxAzimuthAngle
.
The default value is - Infinity
.
e.g.
cameraControls.minAzimuthAngle = - Infinity;
Maximum horizontal angle in radians.
The angle has to be greater than .minAzimuthAngle
.
The default value is Infinity
.
e.g.
cameraControls.maxAzimuthAngle = Infinity;
Minimum distance for dolly. The value must be higher than 0
.
PerspectiveCamera only.
Maximum distance for dolly. The value must be higher than minDistance
.
PerspectiveCamera only.
true
to enable Infinity Dolly.
When the Dolly distance is less than the minDistance
, radius of the sphere will be set minDistance
automatically.
Minimum camera zoom.
Maximum camera zoom.
The damping inertia.
The value must be between Math.EPSILON
to 1
inclusive.
Setting 1
to disable smooth transitions.
The damping inertia while dragging.
The value must be between Math.EPSILON
to 1
inclusive.
Setting 1
to disable smooth transitions.
Speed of azimuth (horizontal) rotation.
Speed of polar (vertical) rotation.
Speed of mouse-wheel dollying.
Speed of drag for truck and pedestal.
true
to enable Dolly-in to the mouse cursor coords.
The same as .screenSpacePanning
in three.js's OrbitControls.
Friction ratio of the boundary.
Controls how soon the rest
event fires as the camera slows.
An array of Meshes to collide with camera.
Be aware colliderMeshes may decrease performance. The collision test uses 4 raycasters from the camera since the near plane has 4 corners.
User's mouse input config.
button to assign | behavior |
---|---|
mouseButtons.left |
CameraControls.ACTION.ROTATE * | CameraControls.ACTION.TRUCK | CameraControls.ACTION.OFFSET | CameraControls.ACTION.DOLLY | CameraControls.ACTION.ZOOM | CameraControls.ACTION.NONE |
mouseButtons.right |
CameraControls.ACTION.ROTATE | CameraControls.ACTION.TRUCK * | CameraControls.ACTION.OFFSET | CameraControls.ACTION.DOLLY | CameraControls.ACTION.ZOOM | CameraControls.ACTION.NONE |
mouseButtons.wheel ¹ |
CameraControls.ACTION.ROTATE | CameraControls.ACTION.TRUCK | CameraControls.ACTION.OFFSET | CameraControls.ACTION.DOLLY | CameraControls.ACTION.ZOOM | CameraControls.ACTION.NONE |
mouseButtons.middle ² |
CameraControls.ACTION.ROTATE | CameraControls.ACTION.TRUCK | CameraControls.ACTION.OFFSET | CameraControls.ACTION.DOLLY * | CameraControls.ACTION.ZOOM | CameraControls.ACTION.NONE |
mouseButtons.wheel
is:DOLLY
for Perspective camera.ZOOM
for Orthographic camera, and can't set DOLLY
.User's touch input config.
fingers to assign | behavior |
---|---|
touches.one |
CameraControls.ACTION.TOUCH_ROTATE * | CameraControls.ACTION.TOUCH_TRUCK | CameraControls.ACTION.TOUCH_OFFSET | CameraControls.ACTION.DOLLY |
touches.two |
ACTION.TOUCH_DOLLY_TRUCK | ACTION.TOUCH_DOLLY_OFFSET | ACTION.TOUCH_ZOOM_TRUCK | ACTION.TOUCH_ZOOM_OFFSET | ACTION.TOUCH_DOLLY | ACTION.TOUCH_ZOOM | CameraControls.ACTION.TOUCH_ROTATE | CameraControls.ACTION.TOUCH_TRUCK | CameraControls.ACTION.TOUCH_OFFSET | CameraControls.ACTION.NONE |
touches.three |
ACTION.TOUCH_DOLLY_TRUCK | ACTION.TOUCH_DOLLY_OFFSET | ACTION.TOUCH_ZOOM_TRUCK | ACTION.TOUCH_ZOOM_OFFSET | CameraControls.ACTION.TOUCH_ROTATE | CameraControls.ACTION.TOUCH_TRUCK | CameraControls.ACTION.TOUCH_OFFSET | CameraControls.ACTION.NONE |
touches.two
and touches.three
is:TOUCH_DOLLY_TRUCK
for Perspective camera.TOUCH_ZOOM_TRUCK
for Orthographic camera, and can't set TOUCH_DOLLY_TRUCK
and TOUCH_DOLLY
.The camera to be controlled
Whether or not the controls are enabled.false
to disable user dragging/touch-move, but all methods works.
Returns true
if the controls are active updating.
readonly value.
Getter for the current ACTION
.
readonly value.
get/set Current distance.
get/set the azimuth angle (horizontal) in radians.
Every 360 degrees turn is added to .azimuthAngle
value, which is accumulative.
get/set the polar angle (vertical) in radians.
Whether camera position should be enclosed in the boundary or not.
Force cancel user dragging.
Adds the specified event listener.
Applicable event types (which is K
) are:
Event name | Timing |
---|---|
'controlstart' |
When the user starts to control the camera via mouse / touches. ¹ |
'control' |
When the user controls the camera (dragging). |
'controlend' |
When the user ends to control the camera. ¹ |
'transitionstart' |
When any kind of transition starts, either user control or using a method with enableTransition = true |
'update' |
When the camera position is updated. |
'wake' |
When the camera starts moving. |
'rest' |
When the camera movement is below .restThreshold ². |
'sleep' |
When the camera end moving. |
mouseButtons.wheel
(Mouse wheel control) does not emit 'controlstart'
and 'controlend'
. mouseButtons.wheel
uses scroll-event internally, and scroll-event happens intermittently. That means "start" and "end" cannot be detected.sleep
will usually fire a few seconds after the camera appears to have stopped moving. If you want to do something (e.g. enable UI, perform another transition) at the point when the camera has stopped, you probably want the rest
event. This can be fine tuned using the .restThreshold
parameter. See the Rest and Sleep Example.e.g.
cameraControl.addEventListener( 'controlstart', myCallbackFunction );
event name
handler function
Removes the specified event listener
e.g.
cameraControl.addEventListener( 'controlstart', myCallbackFunction );
event name
handler function
Rotate azimuthal angle(horizontal) and polar angle(vertical).
Every value is added to the current value.
Azimuth rotate angle. In radian.
Polar rotate angle. In radian.
Whether to move smoothly or immediately
Rotate azimuthal angle(horizontal) to the given angle and keep the same polar angle(vertical) target.
e.g.
cameraControls.rotateAzimuthTo( 30 * THREE.MathUtils.DEG2RAD, true );
Azimuth rotate angle. In radian.
Whether to move smoothly or immediately
Rotate polar angle(vertical) to the given angle and keep the same azimuthal angle(horizontal) target.
e.g.
cameraControls.rotatePolarTo( 30 * THREE.MathUtils.DEG2RAD, true );
Polar rotate angle. In radian.
Whether to move smoothly or immediately
Rotate azimuthal angle(horizontal) and polar angle(vertical) to the given angle.
Camera view will rotate over the orbit pivot absolutely:
azimuthAngle
0º
\
90º -----+----- -90º
\
180º
direction | angle |
---|---|
front | 0º |
left | 90º (Math.PI / 2 ) |
right | -90º (- Math.PI / 2 ) |
back | 180º (Math.PI ) |
polarAngle
180º
|
90º
|
0º
direction | angle |
---|---|
top/sky | 180º (Math.PI ) |
horizontal from view | 90º (Math.PI / 2 ) |
bottom/floor | 0º |
Azimuth rotate angle to. In radian.
Polar rotate angle to. In radian.
Whether to move smoothly or immediately
Truck and pedestal camera using current azimuthal angle
Horizontal translate amount
Vertical translate amount
Whether to move smoothly or immediately
Move target position to given point.
x coord to move center position
y coord to move center position
z coord to move center position
Whether to move smoothly or immediately
Fit the viewport to the box or the bounding box of the object, using the nearest axis. paddings are in unit.
set cover: true
to fill enter screen.
e.g.
cameraControls.fitToBox( myMesh );
Transition end promise
Axis aligned bounding box to fit the view.
Whether to move smoothly or immediately.
| <object>
{ cover: boolean, paddingTop: number, paddingLeft: number, paddingBottom: number, paddingRight: number }
Make an orbit with given points.
Similar to setLookAt, but it interpolates between two states.
Set (or unset) the current viewport.
Set this when you want to use renderer viewport and .dollyToCursor feature at the same time.
Generated using TypeDoc
Injects THREE as the dependency. You can then proceed to use CameraControls.
e.g
Note: If you do not wish to use enter three.js to reduce file size(tree-shaking for example), make a subset to install.