OrbitControls

Orbit controls allow the camera to orbit around a target object.

Example


    const renderer = new v3d.WebGLRenderer();
    renderer.setSize(window.innerWidth, window.innerHeight);
    document.body.appendChild(renderer.domElement);

    const scene = new v3d.Scene();
    const camera = new v3d.PerspectiveCamera(45, window.innerWidth / window.innerHeight, 1, 10000);
    const controls = new v3d.OrbitControls(camera);

    //controls.update() must be called after any manual changes to the camera's transform
    camera.position.set(0, 20, 100);
    controls.update();

    function animate() {
        requestAnimationFrame(animate);

        // required if controls.enableDamping or controls.autoRotate are set to true
        controls.update();

        renderer.render(scene, camera);
    }

Constructor

OrbitControls(object : Camera, domElement : HTMLElement)

object: The camera to be controlled (required).
domElement: The HTML element used for event listeners (optional). By default this is the whole document, however if you only want to the controls to work over a specific element (e.g. the canvas) you can specify that here.

Properties

# .autoRotate : Boolean

Set to true to automatically rotate around the target object.

Note that if this is enabled, you must call .update() in your animation loop.

# .autoRotateSpeed : Float

How fast to rotate around the target object if .autoRotate is true. Default is 2.0, which equates to 30 seconds per rotation at 60fps.

Note that if .autoRotate is enabled, you must call .update() in your animation loop.

# .domElement : HTMLElement

The HTMLElement used to listen for mouse / touch events. This must be passed in the constructor; changing it here will not set up new event listeners. Default is the whole document.

# .enabled : Boolean

Whether or not the controls are enabled.

# .enableDamping : Boolean

Whether to enable damping (inertia), which is used to give a sense of weight to the controls. Default is true.

Note that if this is enabled, you must call .update() in your animation loop.

# .enableKeys : Boolean

Enable or disable the use of keyboard controls. Default is true.

# .enablePan : Boolean

Enable or disable camera panning. Default is true.

# .enableRotate : Boolean

Enable or disable horizontal and vertical rotation of the camera. Default is true.

Note that it is possible to disable a single axis by setting the min and max of the polar angle or azimuth angle to the same value, which will cause the vertical or horizontal rotation to be fixed at that value.

# .enableTurnover : Boolean

Enable or disable moving the camera over the head. Default is false.

# .enableZoom : Boolean

Enable or disable zooming (dollying) of the camera.

# .inTween : Boolean

Flag which says whether the camera is currently in the state of tweening.

# .maxAzimuthAngle : Float

How far you can orbit horizontally, upper limit. Range is -Math.PI to Math.PI (or Infinity for no limit) and default is Infinity;

# .maxDistance : Float

How far you can dolly out (PerspectiveCamera only). Default is Infinity.

# .maxPolarAngle : Float

How far you can orbit vertically, upper limit. Range is 0 to Math.PI radians, and default is Math.PI.

# .maxZoom : Float

How far you can zoom out (OrthographicCamera only). Default is Infinity.

# .minAzimuthAngle : Float

How far you can orbit horizontally, lower limit. Range is -Math.PI to Math.PI (or -Infinity for no limit) and default is -Infinity;

# .minDistance : Float

How far you can dolly in (PerspectiveCamera only). Default is 0.

# .minPolarAngle : Float

How far you can orbit vertically, lower limit. Range is 0 to Math.PI radians, and default is 0.

# .minZoom : Float

How far you can zoom in (OrthographicCamera only). Default is 0.

# .mouseButtons : Object

This object contains references to the mouse buttons used for the controls.


    controls.mouseButtons = {
        ROTATE: v3d.MOUSE.LEFT,
        ZOOM: v3d.MOUSE.MIDDLE,
        PAN: v3d.MOUSE.RIGHT
    }

# .object : Camera

The camera (or other object) that is being controlled.

# .panInertia : Float

The panning damping inertia used if .enableDamping is set to true. Note that for this to work, you must call .update() in your animation loop. Default is 0.05.

# .panSpeed : Float

Speed of panning. Default is 1.3.

# .panSpeedKey : Float

Speed of panning (pixels moved) when using keyboard arrow keys. Default is 15.0.

# .position0 : Vector3

Used internally by the .saveState and .reset methods.

# .rotateInertia : Float

The rotation damping inertia used if .enableDamping is set to true. Note that for this to work, you must call .update() in your animation loop. Default is 0.05.

# .rotateInertiaTouch : Float

Same as .rotateInertia, but for the touch-based controls used on mobile devices. Default value is 0.05.

# .rotateSpeed : Float

Speed of rotation. Default is 1.2.

# .rotateSpeedTouch : Float

Speed of rotation on touch-based devices. Default is 0.7.

# .screenSpacePanning : Boolean

Defines how the camera's position is translated when panning. If true, the camera pans in screen space. Otherwise, the camera pans in the plane orthogonal to the camera's up direction. Default is true.

# .target0 : Vector3

Used internally by the .saveState and .reset methods.

# .targetObj : Object3D

An object which position in the world space acts as the focus point of the controls, the .object orbits around this. It can be updated manually at any point to change the focus of the controls.

# .zoom0 : Float

Used internally by the .saveState and .reset methods.

# .zoomSpeed : Float

Speed of zooming / dollying. Default is 5.0.

# .zoomSpeedTouch : Float

Speed of rotation on touch-based devices. Default is 1.0.

# .zoomInertia : Float

The zoom damping inertia used if .enableDamping is set to true. Note that for this to work, you must call .update() in your animation loop. Default is 0.05.

# .zoomInertiaTouch : Float

Same as .zoomInertia, but for the touch-based controls used on mobile devices. Default is 0.05.

Methods

# .dispose()

Remove all the event listeners.

# .getAzimuthalAngle() → Float

Get the current horizontal rotation, in radians.

# .getDistance() → Float

Get the current distance between the camera and the target.

# .getPolarAngle() → Float

Get the current vertical rotation, in radians.

# .reset()

Reset the controls to their state from either the last time the .saveState was called, or the initial state.

# .saveState()

Save the current state of the controls. This can later be recovered with .reset.

# .tween(toPosition : Vector3, toTarget : Vector3, time : Float, finishCb : Function, movementType : Constant)

toPosition: The new position of the camera.
toTarget: The new target point.
time: The length of the tween animation.
finishCb: A callback to be called after the tween animation ends.
movementType: The movement interpolation. Can be v3d.TweenLinear (default) or v3d.TweenSpherical.

Change the camera's current position and target point to the specified new position and target smoothly over the specified time.

# .tweenZoomTo(toTarget : Vector3, toZoom : Float, time : Float, finishCb : Function)

toTarget: The new target point.
toZoom: The new zoom factor.
time: The length of the tween animation.
finishCb: A callback to be called after the tween animation ends.

Change the orthographic camera target point and zoom factor smoothly over the specified period of time.

# .update() → Boolean

Update the controls. Must be called after any manual changes to the camera's transform, or in the update loop if .autoRotate or .enableDamping are set.

Source

For more info on how to obtain the source code of this module see this page.