Class CameraControls

Static install

• install(libs): void

• Injects THREE as the dependency. You can then proceed to use CameraControls.

  e.g

  CameraControls.install( { THREE: THREE } );
  Copy

  Note: If you do not wish to use enter three.js to reduce file size(tree-shaking for example), make a subset to install.

  import {
      Vector2,
      Vector3,
      Vector4,
      Quaternion,
      Matrix4,
      Spherical,
      Box3,
      Sphere,
      Raycaster,
      MathUtils,
  } from 'three';
  
  const subsetOfTHREE = {
      Vector2   : Vector2,
      Vector3   : Vector3,
      Vector4   : Vector4,
      Quaternion: Quaternion,
      Matrix4   : Matrix4,
      Spherical : Spherical,
      Box3      : Box3,
      Sphere    : Sphere,
      Raycaster : Raycaster,
  };
  
  CameraControls.install( { THREE: subsetOfTHREE } );
  Copy

  Parameters

  • libs: {
        THREE: THREESubset;
    }

    • THREE: THREESubset

  Returns void

Static ACTION

• get ACTION(): Readonly<{
      NONE: 0;
      ROTATE: 1;
      TRUCK: 2;
      OFFSET: 4;
      DOLLY: 8;
      ZOOM: 16;
      TOUCH_ROTATE: 32;
      TOUCH_TRUCK: 64;
      TOUCH_OFFSET: 128;
      TOUCH_DOLLY: 256;
      TOUCH_ZOOM: 512;
      TOUCH_DOLLY_TRUCK: 1024;
      TOUCH_DOLLY_OFFSET: 2048;
      TOUCH_DOLLY_ROTATE: 4096;
      TOUCH_ZOOM_TRUCK: 8192;
      TOUCH_ZOOM_OFFSET: 16384;
      TOUCH_ZOOM_ROTATE: 32768;
  }>

• list all ACTIONs

  Returns Readonly<{
      NONE: 0;
      ROTATE: 1;
      TRUCK: 2;
      OFFSET: 4;
      DOLLY: 8;
      ZOOM: 16;
      TOUCH_ROTATE: 32;
      TOUCH_TRUCK: 64;
      TOUCH_OFFSET: 128;
      TOUCH_DOLLY: 256;
      TOUCH_ZOOM: 512;
      TOUCH_DOLLY_TRUCK: 1024;
      TOUCH_DOLLY_OFFSET: 2048;
      TOUCH_DOLLY_ROTATE: 4096;
      TOUCH_ZOOM_TRUCK: 8192;
      TOUCH_ZOOM_OFFSET: 16384;
      TOUCH_ZOOM_ROTATE: 32768;
  }>

constructor

• new CameraControls(camera, domElement?): CameraControls

• 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 );
  Copy

  Parameters

  • camera: PerspectiveCamera | OrthographicCamera

    A THREE.PerspectiveCamera or THREE.OrthographicCamera to be controlled.

  • Optional domElement: HTMLElement

    A HTMLElement for the draggable area, usually renderer.domElement.

  Returns CameraControls

minPolarAngle

cameraControls.maxPolarAngle = 0;
Copy

maxPolarAngle

cameraControls.maxPolarAngle = Math.PI;
Copy

minAzimuthAngle

cameraControls.minAzimuthAngle = - Infinity;
Copy

maxAzimuthAngle

cameraControls.maxAzimuthAngle = Infinity;
Copy

minDistance

maxDistance

infinityDolly

minZoom

maxZoom

smoothTime

draggingSmoothTime

maxSpeed

azimuthRotateSpeed

polarRotateSpeed

dollySpeed

dollyDragInverted

truckSpeed

dollyToCursor

dragToOffset

verticalDragToForward

boundaryFriction

restThreshold

colliderMeshes

mouseButtons

touches

camera

• get camera(): PerspectiveCamera | OrthographicCamera

• The camera to be controlled

  Returns PerspectiveCamera | OrthographicCamera
• set camera(camera): void

• Parameters

  • camera: PerspectiveCamera | OrthographicCamera

  Returns void

enabled

• get enabled(): boolean

• Whether or not the controls are enabled.
  false to disable user dragging/touch-move, but all methods works.

  Returns boolean
• set enabled(enabled): void

• Parameters

  • enabled: boolean

  Returns void

active

• get active(): boolean

• Returns true if the controls are active updating.
  readonly value.

  Returns boolean

currentAction

• get currentAction(): number

• Getter for the current ACTION.
  readonly value.

  Returns number

distance

• get distance(): number

• get/set Current distance.

  Returns number
• set distance(distance): void

• Parameters

  • distance: number

  Returns void

azimuthAngle

• get azimuthAngle(): number

• get/set the azimuth angle (horizontal) in radians.
  Every 360 degrees turn is added to .azimuthAngle value, which is accumulative.

  Returns number
• set azimuthAngle(azimuthAngle): void

• Parameters

  • azimuthAngle: number

  Returns void

polarAngle

• get polarAngle(): number

• get/set the polar angle (vertical) in radians.

  Returns number
• set polarAngle(polarAngle): void

• Parameters

  • polarAngle: number

  Returns void

boundaryEnclosesCamera

• get boundaryEnclosesCamera(): boolean

• Whether camera position should be enclosed in the boundary or not.

  Returns boolean
• set boundaryEnclosesCamera(boundaryEnclosesCamera): void

• Parameters

  • boundaryEnclosesCamera: boolean

  Returns void

interactiveArea

• set interactiveArea(interactiveArea): void

• Set drag-start, touches and wheel enable area in the domElement.
  each values are between 0 and 1 inclusive, where 0 is left/top and 1 is right/bottom of the screen.
  e.g. { x: 0, y: 0, width: 1, height: 1 } for entire area.

  Parameters

  • interactiveArea: DOMRect | {
        x: number;
        y: number;
        width: number;
        height: number;
    }

  Returns void

dampingFactor

• get dampingFactor(): number

• backward compatible

  Returns number

  Deprecated

  use smoothTime (in seconds) instead

• set dampingFactor(_): void

• backward compatible

  Parameters

  • _: number

  Returns void

  Deprecated

  use smoothTime (in seconds) instead

draggingDampingFactor

• get draggingDampingFactor(): number

• backward compatible

  Returns number

  Deprecated

  use draggingSmoothTime (in seconds) instead

• set draggingDampingFactor(_): void

• backward compatible

  Parameters

  • _: number

  Returns void

  Deprecated

  use draggingSmoothTime (in seconds) instead

cancel

lockPointer

unlockPointer

addEventListener

• addEventListener<K>(type, listener): void

• 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.

  1. 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.
  2. Due to damping, 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 );
  Copy

  Type Parameters

  • K extends keyof CameraControlsEventMap

  Parameters

  • type: K

    event name

  • listener: ((event) => any)

    handler function

    • • (event): any

      • Parameters

        • event: CameraControlsEventMap[K]

        Returns any

  Returns void

removeEventListener

• removeEventListener<K>(type, listener): void

• Removes the specified event listener
  e.g.

  cameraControl.addEventListener( 'controlstart', myCallbackFunction );
  Copy

  Type Parameters

  • K extends keyof CameraControlsEventMap

  Parameters

  • type: K

    event name

  • listener: ((event) => any)

    handler function

    • • (event): any

      • Parameters

        • event: CameraControlsEventMap[K]

        Returns any

  Returns void

rotate

• rotate(azimuthAngle, polarAngle, enableTransition?): Promise<void>

• Rotate azimuthal angle(horizontal) and polar angle(vertical).
  Every value is added to the current value.

  Parameters

  • azimuthAngle: number

    Azimuth rotate angle. In radian.

  • polarAngle: number

    Polar rotate angle. In radian.

  • enableTransition: boolean = false

    Whether to move smoothly or immediately

  Returns Promise<void>

rotateAzimuthTo

• rotateAzimuthTo(azimuthAngle, enableTransition?): Promise<void>

• 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 );
  Copy

  Parameters

  • azimuthAngle: number

    Azimuth rotate angle. In radian.

  • enableTransition: boolean = false

    Whether to move smoothly or immediately

  Returns Promise<void>

rotatePolarTo

• rotatePolarTo(polarAngle, enableTransition?): Promise<void>

• 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 );
  Copy

  Parameters

  • polarAngle: number

    Polar rotate angle. In radian.

  • enableTransition: boolean = false

    Whether to move smoothly or immediately

  Returns Promise<void>

rotateTo

• rotateTo(azimuthAngle, polarAngle, enableTransition?): Promise<void>

• 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º
  Copy

  direction	angle
  front	0º
  left	90º (Math.PI / 2)
  right	-90º (- Math.PI / 2)
  back	180º (Math.PI)

  polarAngle

      180º
       |
       90º
       |
       0º
  Copy

  direction	angle
  top/sky	180º (Math.PI)
  horizontal from view	90º (Math.PI / 2)
  bottom/floor	0º

  Parameters

  • azimuthAngle: number

    Azimuth rotate angle to. In radian.

  • polarAngle: number

    Polar rotate angle to. In radian.

  • enableTransition: boolean = false

    Whether to move smoothly or immediately

  Returns Promise<void>

dolly

• dolly(distance, enableTransition?): Promise<void>

• Dolly in/out camera position.

  Parameters

  • distance: number

    Distance of dollyIn. Negative number for dollyOut.

  • enableTransition: boolean = false

    Whether to move smoothly or immediately.

  Returns Promise<void>

dollyTo

• dollyTo(distance, enableTransition?): Promise<void>

• Dolly in/out camera position to given distance.

  Parameters

  • distance: number

    Distance of dolly.

  • enableTransition: boolean = false

    Whether to move smoothly or immediately.

  Returns Promise<void>

dollyInFixed

• dollyInFixed(distance, enableTransition?): Promise<void>

• Dolly in, but does not change the distance between the target and the camera, and moves the target position instead.
  Specify a negative value for dolly out.

  Parameters

  • distance: number

    Distance of dolly.

  • enableTransition: boolean = false

    Whether to move smoothly or immediately.

  Returns Promise<void>

zoom

• zoom(zoomStep, enableTransition?): Promise<void>

• Zoom in/out camera. The value is added to camera zoom.
  Limits set with .minZoom and .maxZoom

  Parameters

  • zoomStep: number

    zoom scale

  • enableTransition: boolean = false

    Whether to move smoothly or immediately

  Returns Promise<void>

zoomTo

• zoomTo(zoom, enableTransition?): Promise<void>

• Zoom in/out camera to given scale. The value overwrites camera zoom.
  Limits set with .minZoom and .maxZoom

  Parameters

  • zoom: number

  • enableTransition: boolean = false

  Returns Promise<void>

pan

• pan(x, y, enableTransition?): Promise<void>

• Parameters

  • x: number

  • y: number

  • enableTransition: boolean = false

  Returns Promise<void>

  Deprecated

  pan() has been renamed to truck()

truck

• truck(x, y, enableTransition?): Promise<void>

• Truck and pedestal camera using current azimuthal angle

  Parameters

  • x: number

    Horizontal translate amount

  • y: number

    Vertical translate amount

  • enableTransition: boolean = false

    Whether to move smoothly or immediately

  Returns Promise<void>

forward

• forward(distance, enableTransition?): Promise<void>

• Move forward / backward.

  Parameters

  • distance: number

    Amount to move forward / backward. Negative value to move backward

  • enableTransition: boolean = false

    Whether to move smoothly or immediately

  Returns Promise<void>

elevate

• elevate(height, enableTransition?): Promise<void>

• Move up / down.

  Parameters

  • height: number

    Amount to move up / down. Negative value to move down

  • enableTransition: boolean = false

    Whether to move smoothly or immediately

  Returns Promise<void>

moveTo

• moveTo(x, y, z, enableTransition?): Promise<void>

• Move target position to given point.

  Parameters

  • x: number

    x coord to move center position

  • y: number

    y coord to move center position

  • z: number

    z coord to move center position

  • enableTransition: boolean = false

    Whether to move smoothly or immediately

  Returns Promise<void>

lookInDirectionOf

• lookInDirectionOf(x, y, z, enableTransition?): Promise<void>

• Look in the given point direction.

  Parameters

  • x: number

    point x.

  • y: number

    point y.

  • z: number

    point z.

  • enableTransition: boolean = false

    Whether to move smoothly or immediately.

  Returns Promise<void>

  Transition end promise

fitToBox

• fitToBox(box3OrObject, enableTransition, options?): Promise<void[]>

• 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 );
  Copy

  Parameters

  • box3OrObject: Box3 | Object3D<Object3DEventMap>

    Axis aligned bounding box to fit the view.

  • enableTransition: boolean

    Whether to move smoothly or immediately.

  • options: Partial<FitToOptions> = {}

    | <object> { cover: boolean, paddingTop: number, paddingLeft: number, paddingBottom: number, paddingRight: number }

  Returns Promise<void[]>

  Transition end promise

fitToSphere

• fitToSphere(sphereOrMesh, enableTransition): Promise<void[]>

• Fit the viewport to the sphere or the bounding sphere of the object.

  Parameters

  • sphereOrMesh: Sphere | Object3D<Object3DEventMap>

  • enableTransition: boolean

  Returns Promise<void[]>

setLookAt

• setLookAt(positionX, positionY, positionZ, targetX, targetY, targetZ, enableTransition?): Promise<void>

• Look at the target from the position.

  Parameters

  • positionX: number

  • positionY: number

  • positionZ: number

  • targetX: number

  • targetY: number

  • targetZ: number

  • enableTransition: boolean = false

  Returns Promise<void>

lerpLookAt

• lerpLookAt(positionAX, positionAY, positionAZ, targetAX, targetAY, targetAZ, positionBX, positionBY, positionBZ, targetBX, targetBY, targetBZ, t, enableTransition?): Promise<void>

• Similar to setLookAt, but it interpolates between two states.

  Parameters

  • positionAX: number

  • positionAY: number

  • positionAZ: number

  • targetAX: number

  • targetAY: number

  • targetAZ: number

  • positionBX: number

  • positionBY: number

  • positionBZ: number

  • targetBX: number

  • targetBY: number

  • targetBZ: number

  • t: number

  • enableTransition: boolean = false

  Returns Promise<void>

setPosition

• setPosition(positionX, positionY, positionZ, enableTransition?): Promise<void>

• Set angle and distance by given position.
  An alias of setLookAt(), without target change. Thus keep gazing at the current target

  Parameters

  • positionX: number

  • positionY: number

  • positionZ: number

  • enableTransition: boolean = false

  Returns Promise<void>

setTarget

• setTarget(targetX, targetY, targetZ, enableTransition?): Promise<void>

• Set the target position where gaze at.
  An alias of setLookAt(), without position change. Thus keep the same position.

  Parameters

  • targetX: number

  • targetY: number

  • targetZ: number

  • enableTransition: boolean = false

  Returns Promise<void>

setFocalOffset

• setFocalOffset(x, y, z, enableTransition?): Promise<void>

• Set focal offset using the screen parallel coordinates. z doesn't affect in Orthographic as with Dolly.

  Parameters

  • x: number

  • y: number

  • z: number

  • enableTransition: boolean = false

  Returns Promise<void>

setOrbitPoint

• setOrbitPoint(targetX, targetY, targetZ): void

• Set orbit point without moving the camera.
  SHOULD NOT RUN DURING ANIMATIONS. setOrbitPoint() will immediately fix the positions.

  Parameters

  • targetX: number

  • targetY: number

  • targetZ: number

  Returns void

setBoundary

• setBoundary(box3?): void

• Set the boundary box that encloses the target of the camera. box3 is in THREE.Box3

  Parameters

  • Optional box3: Box3

  Returns void

setViewport

• setViewport(viewportOrX, y, width, height): void

• Set (or unset) the current viewport.
  Set this when you want to use renderer viewport and .dollyToCursor feature at the same time.

  Parameters

  • viewportOrX: null | number | Vector4

  • y: number

  • width: number

  • height: number

  Returns void

getDistanceToFitBox

• getDistanceToFitBox(width, height, depth, cover?): number

• Calculate the distance to fit the box.

  Parameters

  • width: number

    box width

  • height: number

    box height

  • depth: number

    box depth

  • cover: boolean = false

  Returns number

  distance

getDistanceToFitSphere

• getDistanceToFitSphere(radius): number

• Calculate the distance to fit the sphere.

  Parameters

  • radius: number

    sphere radius

  Returns number

  distance

getTarget

• getTarget(out, receiveEndValue?): Vector3

• Returns the orbit center position, where the camera looking at.

  Parameters

  • out: Vector3

    The receiving Vector3 instance to copy the result

  • receiveEndValue: boolean = true

    Whether receive the transition end coords or current. default is true

  Returns Vector3

getPosition

• getPosition(out, receiveEndValue?): Vector3

• Returns the camera position.

  Parameters

  • out: Vector3

    The receiving Vector3 instance to copy the result

  • receiveEndValue: boolean = true

    Whether receive the transition end coords or current. default is true

  Returns Vector3

getSpherical

• getSpherical(out, receiveEndValue?): Spherical

• Returns the spherical coordinates of the orbit.

  Parameters

  • out: Spherical

    The receiving Spherical instance to copy the result

  • receiveEndValue: boolean = true

    Whether receive the transition end coords or current. default is true

  Returns Spherical

getFocalOffset

• getFocalOffset(out, receiveEndValue?): Vector3

• Returns the focal offset, which is how much the camera appears to be translated in screen parallel coordinates.

  Parameters

  • out: Vector3

    The receiving Vector3 instance to copy the result

  • receiveEndValue: boolean = true

    Whether receive the transition end coords or current. default is true

  Returns Vector3

normalizeRotations

• normalizeRotations(): void

• Normalize camera azimuth angle rotation between 0 and 360 degrees.

  Returns void

reset

• reset(enableTransition?): Promise<void[]>

• Reset all rotation and position to defaults.

  Parameters

  • enableTransition: boolean = false

  Returns Promise<void[]>

saveState

• saveState(): void

• Set current camera position as the default position.

  Returns void

updateCameraUp

• updateCameraUp(): void

• Sync camera-up direction.
  When camera-up vector is changed, .updateCameraUp() must be called.

  Returns void

applyCameraUp

• applyCameraUp(): void

• Apply current camera-up direction to the camera.
  The orbit system will be re-initialized with the current position.

  Returns void

update

• update(delta): boolean

• Update camera position and directions.
  This should be called in your tick loop every time, and returns true if re-rendering is needed.

  Parameters

  • delta: number

  Returns boolean

  updated

toJSON

• toJSON(): string

• Get all state in JSON string

  Returns string

fromJSON

• fromJSON(json, enableTransition?): void

• Reproduce the control state with JSON. enableTransition is where anim or not in a boolean.

  Parameters

  • json: string

  • enableTransition: boolean = false

  Returns void

connect

• connect(domElement): void

• Attach all internal event handlers to enable drag control.

  Parameters

  • domElement: HTMLElement

  Returns void

dispose

• dispose(): void

• Dispose the cameraControls instance itself, remove all eventListeners.

  Returns void

disconnect

• disconnect(): void

• Detach all internal event handlers to disable drag control.

  Returns void

Static createBoundingSphere

• createBoundingSphere(object3d, out?): Sphere

• Parameters

  • object3d: Object3D<Object3DEventMap>

  • out: Sphere = ...

  Returns Sphere