Hierarchy

  • EventDispatcher

    Hierarchy

    • CameraControls

Statics

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

    e.g

    CameraControls.install( { THREE: THREE } );
    

    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,
    MathUtils : {
    DEG2RAD: MathUtils.DEG2RAD,
    clamp: MathUtils.clamp,
    },
    };

    CameraControls.install( { THREE: subsetOfTHREE } );

    Parameters

    • libs: { THREE: THREESubset }
      • THREE: THREESubset

    Returns void

  • 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

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

    Parameters

    • camera: PerspectiveCamera | OrthographicCamera

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

    • domElement: HTMLElement

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

    Returns CameraControls

Properties

minPolarAngle: number = 0

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;
maxPolarAngle: number = Math.PI

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;
minAzimuthAngle: number = - Infinity

Minimum horizontal angle in radians.
The angle has to be less than .maxAzimuthAngle.
The default value is - Infinity.

e.g.

cameraControls.minAzimuthAngle = - Infinity;
maxAzimuthAngle: number = Infinity

Maximum horizontal angle in radians.
The angle has to be greater than .minAzimuthAngle.
The default value is Infinity.

e.g.

cameraControls.maxAzimuthAngle = Infinity;
minDistance: number = 0

Minimum distance for dolly. The value must be higher than 0.
PerspectiveCamera only.

maxDistance: number = Infinity

Maximum distance for dolly. The value must be higher than minDistance.
PerspectiveCamera only.

infinityDolly: boolean = false

true to enable Infinity Dolly.
When the Dolly distance is less than the minDistance, radius of the sphere will be set minDistance automatically.

minZoom: number = 0.01

Minimum camera zoom.

maxZoom: number = Infinity

Maximum camera zoom.

dampingFactor: number = 0.05

The damping inertia.
The value must be between Math.EPSILON to 1 inclusive.
Setting 1 to disable smooth transitions.

draggingDampingFactor: number = 0.25

The damping inertia while dragging.
The value must be between Math.EPSILON to 1 inclusive.
Setting 1 to disable smooth transitions.

azimuthRotateSpeed: number = 1.0

Speed of azimuth (horizontal) rotation.

polarRotateSpeed: number = 1.0

Speed of polar (vertical) rotation.

dollySpeed: number = 1.0

Speed of mouse-wheel dollying.

truckSpeed: number = 2.0

Speed of drag for truck and pedestal.

dollyToCursor: boolean = false

true to enable Dolly-in to the mouse cursor coords.

dragToOffset: boolean = false
verticalDragToForward: boolean = false

The same as .screenSpacePanning in three.js's OrbitControls.

boundaryFriction: number = 0.0

Friction ratio of the boundary.

restThreshold: number = 0.01

Controls how soon the rest event fires as the camera slows.

colliderMeshes: Object3D<Event>[] = []

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.

mouseButtons: MouseButtons

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
  1. Mouse wheel event for scroll "up/down" on mac "up/down/left/right"
  2. Mouse click on wheel event "button"
  • * is the default.
  • The default of mouseButtons.wheel is:
    • DOLLY for Perspective camera.
    • ZOOM for Orthographic camera, and can't set DOLLY.
touches: Touches

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_DOLLY_ROTATE | ACTION.TOUCH_ZOOM_TRUCK | ACTION.TOUCH_ZOOM_OFFSET | ACTION.TOUCH_ZOOM_ROTATE | 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_DOLLY_ROTATE | ACTION.TOUCH_ZOOM_TRUCK | ACTION.TOUCH_ZOOM_OFFSET | ACTION.TOUCH_ZOOM_ROTATE | CameraControls.ACTION.TOUCH_ROTATE | CameraControls.ACTION.TOUCH_TRUCK | CameraControls.ACTION.TOUCH_OFFSET | CameraControls.ACTION.NONE
  • * is the default.
  • The default of 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.
  • get camera(): PerspectiveCamera | OrthographicCamera
  • The camera to be controlled

    Returns PerspectiveCamera | OrthographicCamera

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

    • camera: PerspectiveCamera | OrthographicCamera

    Returns void

  • 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: boolean): void
  • Parameters

    • enabled: boolean

    Returns void

  • get active(): boolean
  • Returns true if the controls are active updating.
    readonly value.

    Returns boolean

  • get currentAction(): number
  • Getter for the current ACTION.
    readonly value.

    Returns number

  • 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: number): void
  • Parameters

    • azimuthAngle: number

    Returns void

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

    Returns number

  • set polarAngle(polarAngle: number): void
  • Parameters

    • polarAngle: number

    Returns void

  • get boundaryEnclosesCamera(): boolean
  • Whether camera position should be enclosed in the boundary or not.

    Returns boolean

  • set boundaryEnclosesCamera(boundaryEnclosesCamera: boolean): void
  • Parameters

    • boundaryEnclosesCamera: boolean

    Returns void

Methods

cancel: (() => void) = ...

Type declaration

    • (): void
    • Force cancel user dragging.

      Returns 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 );
    

    Type Parameters

    Type Parameters

    • K extends keyof CameraControlsEventMap

    Parameters

    • type: K

      event name

    • listener: ((event: CameraControlsEventMap[K]) => any)

      handler function

        • (event: CameraControlsEventMap[K]): any
        • Parameters

          • event: CameraControlsEventMap[K]

          Returns any

    Returns void

  • Removes the specified event listener
    e.g.

    cameraControl.addEventListener( 'controlstart', myCallbackFunction );
    

    Type Parameters

    Type Parameters

    • K extends keyof CameraControlsEventMap

    Parameters

    • type: K

      event name

    • listener: ((event: CameraControlsEventMap[K]) => any)

      handler function

        • (event: CameraControlsEventMap[K]): any
        • Parameters

          • event: CameraControlsEventMap[K]

          Returns any

    Returns 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>

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

    Parameters

    • azimuthAngle: number

      Azimuth rotate angle. In radian.

    • enableTransition: boolean = false

      Whether to move smoothly or immediately

    Returns 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 );
    

    Parameters

    • polarAngle: number

      Polar rotate angle. In radian.

    • enableTransition: boolean = false

      Whether to move smoothly or immediately

    Returns 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º
    direction angle
    front
    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

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

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

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

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

  • Deprecated

    pan() has been renamed to truck()

    Parameters

    • x: number
    • y: number
    • enableTransition: boolean = false

    Returns 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>

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

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

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

    Returns

    Transition end promise

    Parameters

    • box3OrObject: Box3 | Object3D<Event>

      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[]>

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

    Parameters

    • sphereOrMesh: Object3D<Event> | Sphere
    • enableTransition: boolean

    Returns Promise<void[]>

  • Make an orbit with given points.

    Parameters

    • positionX: number
    • positionY: number
    • positionZ: number
    • targetX: number
    • targetY: number
    • targetZ: number
    • enableTransition: boolean = false

    Returns 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>

  • setLookAt without target, keep gazing at the current target

    Parameters

    • positionX: number
    • positionY: number
    • positionZ: number
    • enableTransition: boolean = false

    Returns Promise<void>

  • setLookAt without position, Stay still at the position.

    Parameters

    • targetX: number
    • targetY: number
    • targetZ: number
    • enableTransition: boolean = false

    Returns 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>

  • 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

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

    Parameters

    • Optional box3: Box3

    Returns 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

  • Calculate the distance to fit the box.

    Returns

    distance

    Parameters

    • width: number

      box width

    • height: number

      box height

    • depth: number

      box depth

    • cover: boolean = false

    Returns number

  • Calculate the distance to fit the sphere.

    Returns

    distance

    Parameters

    • radius: number

      sphere radius

    Returns number

  • Returns its current gazing target, which is the center position of the orbit.

    Parameters

    • out: Vector3

      current gazing target

    Returns Vector3

  • Returns its current position.

    Parameters

    • out: Vector3

      current position

    Returns Vector3

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

    Parameters

    • out: Vector3

      current focal offset

    Returns Vector3

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

    Returns void

  • Reset all rotation and position to defaults.

    Parameters

    • enableTransition: boolean = false

    Returns Promise<void[]>

  • Set current camera position as the default position.

    Returns void

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

    Returns void

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

    Returns

    updated

    Parameters

    • delta: number

    Returns boolean

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

    Parameters

    • json: string
    • enableTransition: boolean = false

    Returns void

  • Dispose the cameraControls instance itself, remove all eventListeners.

    Returns void

  • Removes all event listeners

    Parameters

    • Optional type: string

      event name

    Returns void

  • Fire an event type.

    Parameters

    • event: DispatcherEvent

      DispatcherEvent

    Returns void

Generated using TypeDoc