ArcballControls class

Arcball controls allow the camera to be controlled by a virtual trackball with full touch support and advanced navigation functionality.

Cursor/finger positions and movements are mapped over a virtual trackball surface represented by a gizmo and mapped in intuitive and consistent camera movements. Dragging cursor/fingers will cause camera to orbit around the center of the trackball in a conservative way (returning to the starting point will make the camera to return to its starting orientation).

In addition to supporting pan, zoom and pinch gestures, Arcball controls provide focus functionality with a double click/tap for intuitively moving the object's point of interest in the center of the virtual trackball. Focus allows a much better inspection and navigation in complex environment. Moreover Arcball controls allow FOV manipulation (in a vertigo-style method) and z-rotation. Saving and restoring of Camera State is supported also through clipboard (use ctrl+c and ctrl+v shortcuts for copy and paste the state).

Unlike OrbitControls and TrackballControls, ArcballControls doesn't require update to be called externally in an animation loop when animations are on.

To use this, as with all files in the /examples directory, you will have to include the file separately in your HTML.

Mixed-in types
  • EventDispatcher

Constructors

ArcballControls(Camera camera, GlobalKey<PeripheralsState> listenableKey, [Scene? scene, double devicePixelRatio = 1.0])
camera - (required) The camera to be controlled. The camera must not be a child of another object, unless that object is the scene itself.

Properties

adjustNearFar ↔ bool
getter/setter pair
camera ↔ Camera
getter/setter pair
cursorZoom ↔ bool
getter/setter pair
dampingFactor ↔ int
getter/setter pair
disposed ↔ bool
getter/setter pair
domElement → PeripheralsState
no setter
enableAnimations ↔ bool
getter/setter pair
enabled ↔ bool
getter/setter pair
enableGizmos ↔ bool
getter/setter pair
enableGrid ↔ bool
getter/setter pair
enablePan ↔ bool
getter/setter pair
enableRotate ↔ bool
getter/setter pair
enableZoom ↔ bool
getter/setter pair
focusAnimationTime → int
final
hashCode → int
The hash code for this object.
no setterinherited
listenableKey ↔ GlobalKey<PeripheralsState>
getter/setter pair
maxDistance ↔ double
getter/setter pair
maxFov ↔ double
getter/setter pair
maxZoom ↔ double
getter/setter pair
minDistance ↔ double
getter/setter pair
minFov ↔ double
getter/setter pair
minZoom ↔ double
getter/setter pair
mouseActions → List
final
radiusFactor ↔ double
getter/setter pair
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
scaleFactor ↔ double
getter/setter pair
scene ↔ Scene?
getter/setter pair
target ↔ Vector3
getter/setter pair
wMax ↔ int
getter/setter pair

Methods

activateGizmos(dynamic isActive) → void
  • Make rotation gizmos more or less visible
  • isActive If true, make gizmos more visible
    • addEventListener(String type, Function listener) → void
    type - The type of event to listen to.
    inherited
    applyTransformMatrix(Map<String, Matrix4>? transformation) → void
  • Apply a transformation matrix, to the camera and gizmos
  • transformation Object containing matrices to apply to camera and gizmos
    • calculateAngularSpeed(dynamic p0, dynamic p1, dynamic t0, dynamic t1) → double
  • Calculate the angular speed
  • p0 Position at t0
  • p1 Position at t1
  • t0 Initial time in milliseconds
  • t1 Ending time in milliseconds
    • calculatePointersDistance(dynamic p0, dynamic p1) → double
  • Calculate the distance between two pointers
  • p0 The first pointer
  • p1 The second pointer
  • returns double The distance between the two pointers
    • calculateRotationAxis(Vector3 vec1, Vector3 vec2) → Vector3
  • Calculate the rotation axis as the vector perpendicular between two vectors
  • vec1 The first vector
  • vec2 The second vector
  • returns Vector3 The normalized rotation axis
    • calculateTbRadius(Camera camera) → double
  • Calculate the trackball radius so that gizmo's diamater will be 2/3 of the minimum side of the camera frustum
  • returns double The trackball radius
    • cancelAnimationFrame(dynamic instance) → int
    clearListeners() → void
    Remove all Listeners.
    inherited
    compareMouseAction(dynamic action1, dynamic action2) → bool
    Compare two mouse actions returns bool True if action1 and action 2 are the same mouse action, false otherwise
    copyState() → void
    disconnect() → void
    dispatchEvent(Event event) → void
    event - The event that gets fired.
    inherited
    dispose() → void
    Remove all listeners, stop animations and clean scene
    override
    disposeGrid() → void
    remove the grid from the scene
    drawGrid() → void
    Draw a grid and add it to the scene
    easeOutCubic(dynamic t) → num
  • Compute the easing out cubic function for ease out effect in animation
  • @param {Number} t The absolute progress of the animation in the bound of 0 (beginning of the) and 1 (ending of animation)
  • @returns {Number} Result of easing out cubic at time t
    • focus(dynamic point, dynamic size, [num amount = 1]) → void
  • Focus operation consist of positioning the point of interest in front of the camera and a slightly zoom in
  • point The point of interest
  • size Scale factor
  • amount amount of operation to be completed (used for focus animations, default is complete full operation)
    • getAngle(dynamic p1, dynamic p2) → double
    Calculate the angle between two pointers returns double The angle between two pointers in degrees
    getCursorNDC(double cursorX, double cursorY) → Vector2
  • Calculate the cursor position in NDC
  • cursorX Cursor horizontal coordinate within the canvas
  • cursorY Cursor vertical coordinate within the canvas
  • @ Vector2 Cursor normalized position inside the canvas
    • getCursorPosition(double cursorX, double cursorY) → Vector2
  • Calculate the cursor position inside the canvas x/y coordinates with the origin being in the center of the canvas
  • cursorX Cursor horizontal coordinate within the canvas
  • cursorY Cursor vertical coordinate within the canvas
  • returns Vector2 Cursor position inside the canvas
    • getOpFromAction(int mouse, String? key) → String?
  • Return the operation associated to a mouse/keyboard combination
  • mouse A mouse button (0, 1, 2, 3) 3 for wheel notches
  • key The keyboard modifier ('CTRL', 'SHIFT') or null if key is not needed
  • returns The operation if it has been found, null otherwise
    • getOpStateFromAction(int mouse, String? key) → int?
  • Get the operation associated to mouse and key combination and returns the corresponding FSA state
  • mouse Mouse button
  • key Keyboard modifier
  • returns The FSA state obtained from the operation associated to mouse/keyboard combination
    • getRaycaster() → Raycaster
    hasEventListener(String type, Function listener) → bool
    type - The type of event to listen to.
    inherited
    initializeMouseActions() → void
    Set default mouse actions
    makeGizmos(dynamic tbCenter, dynamic tbRadius) → void
  • Creates the rotation gizmos matching trackball center and radius
  • tbCenter The trackball center
  • tbRadius The trackball radius
    • noSuchMethod(Invocation invocation) → dynamic
    Invoked when a nonexistent method or property is accessed.
    inherited
    onContextMenu(dynamic event) → void
    onDoublePanEnd(dynamic event) → void
    onDoublePanMove() → void
    onDoublePanStart() → void
    onDoubleTap(dynamic event) → void
    onFocusAnim(dynamic time, dynamic point, dynamic cameraMatrix, dynamic gizmoMatrix) → void
  • Perform animation for focus operation
  • @param {Number} time Instant in which this function is called as performance.now()
  • @param {Vector3} point Point of interest for focus operation
  • @param {Matrix4} cameraMatrix Camera matrix
  • @param {Matrix4} gizmoMatrix Gizmos matrix
  • onPinchEnd(dynamic event) → void
    onPinchMove() → void
    onPinchStart() → dynamic
    onPointerCancel() → void
    onPointerDown(dynamic event) → void
    onPointerMove(dynamic event) → void
    onPointerUp(dynamic event) → void
    onRotateEnd(dynamic event) → dynamic
    onRotateMove() → void
    onRotateStart() → void
    onRotationAnim(dynamic time, dynamic rotationAxis, dynamic w0) → void
  • Perform animation for rotation operation
  • @param {Number} time Instant in which this function is called as performance.now()
  • @param {Vector3} rotationAxis Rotation axis
  • @param {number} w0 Initial angular velocity
  • onSinglePanEnd() → void
    onSinglePanMove(dynamic event, dynamic opState) → void
    onSinglePanStart(dynamic event, dynamic operation) → void
    onTriplePanEnd() → void
    onTriplePanMove(dynamic event) → void
    onTriplePanStart(dynamic event) → void
    onWheel(dynamic event) → void
    onWindowResize() → void
    pan(Vector3 p0, Vector3 p1, [bool adjust = false]) → Map<String, Matrix4>
  • Perform pan operation moving camera between two points
  • @param {Vector3} p0 Initial point
  • @param {Vector3} p1 Ending point
  • @param {Boolean} adjust If movement should be adjusted considering camera distance (Perspective only)
  • pasteState() → void
    removeEventListener(String type, Function listener) → void
    type - The type of the listener that gets removed.
    inherited
    requestAnimationFrame(Function callback) → int
    reset() → void
    Reset trackball
    rotate(Vector3 axis, double angle) → Map<String, Matrix4>
  • Rotate the camera around an axis passing by trackball's center
  • axis Rotation axis
  • angle Angle in radians
  • returns Object Object with 'camera' field containing transformation matrix resulting from the operation to be applied to the camera
    • saveState() → void
    Save the current state of the control. This can later be recover with .reset
    scale(double size, Vector? point, [bool scaleGizmos = true]) → Map<String, Matrix4>?
  • Perform uniform scale operation around a given point
  • size Scale factor
  • point Point around which scale
  • scaleGizmos If gizmos should be scaled (Perspective only)
  • returns Object Object with 'camera' and 'gizmo' fields containing transformation matrices resulting from the operation to be applied to the camera and gizmos
    • setCamera(dynamic camera) → void
  • Set the camera to be controlled
  • camera The virtual camera to be controlled
    • setCenter(double clientX, double clientY) → void
    Set _center's x/y coordinates
    setFov(double value) → void
  • Set camera fov
  • value fov to be setted
    • setGizmosVisible(dynamic value) → void
  • Set gizmos visibility
  • value Value of gizmos visibility
    • setMouseAction(String operation, int mouse, [String? key]) → bool
  • Set a mouse action by specifying the operation to be performed and a mouse/key combination. In case of conflict, replaces the existing one
  • operation The operation to be performed ('pan', 'rotate', 'ZOOM', 'fov)
  • mouse A mouse button (0, 1, 2, 3) or for wheel notches
  • key The keyboard modifier ('CTRL', 'SHIFT') or null if key is not needed
  • returns Boolean True if the mouse action has been successfully added, false otherwise
    • setStateFromJSON(Map<String, dynamic> json) → void
    setTbRadius(dynamic value) → void
  • Set gizmos radius factor and redraws gizmos
  • value Value of radius factor
    • setTransformationMatrices([Matrix4? camera, Matrix4? gizmos]) → void
  • Set values in transformation object
  • camera Transformation to be applied to the camera
  • gizmos Transformation to be applied to gizmos
    • toString() → String
    A string representation of this object.
    inherited
    unprojectOnObj(Vector2 cursor, Camera camera) → Vector3?
  • Unproject the cursor on the 3D object surface
  • cursor Cursor coordinates in NDC
  • camera Virtual camera
  • returns Vector3 The point of intersection with the model, if exist, null otherwise
    • unprojectOnTbPlane(Camera camera, double cursorX, double cursorY, [bool initialDistance = false]) → Vector3
  • Unproject the cursor on the plane passing through the center of the trackball orthogonal to the camera
  • camera The virtual camera
  • cursorX Cursor horizontal coordinate on screen
  • cursorY Cursor vertical coordinate on screen
  • initialDistance If initial distance between camera and gizmos should be used for calculations instead of current (Perspective only)
  • returns Vector3 The unprojected point on the trackball plane
    • unprojectOnTbSurface(Camera camera, double cursorX, double cursorY, double tbRadius) → Vector3
  • Unproject the cursor on the trackball surface
  • camera The virtual camera
  • cursorX Cursor horizontal coordinate on screen
  • cursorY Cursor vertical coordinate on screen
  • tbRadius The trackball radius
  • returns Vector3 The unprojected point on the trackball surface
    • unsetMouseAction(dynamic mouse, [String? key]) → bool
  • Remove a mouse action by specifying its mouse/key combination
  • mouse A mouse button (0, 1, 2, 3) 3 for wheel notches
  • key The keyboard modifier ('CTRL', 'SHIFT') or null if key is not needed
  • returns Boolean True if the operation has been succesfully removed, false otherwise
    • update() → void
    updateMatrixState() → void
    Update camera and gizmos state
    updateTbState(dynamic newState, bool updateMatrices) → void
  • Update the trackball FSA
  • newState New state of the FSA
  • updateMatrices If matriices state should be updated
    • updateTouchEvent(dynamic event) → void
    Update a PointerEvent inside current pointerevents array
    zRotate(Vector3 point, double angle) → Map<String, Matrix4>
  • Rotate camera around its direction axis passing by a given point by a given angle
  • point The point where the rotation axis is passing trough
  • angle Angle in radians
  • returns The computed transormation matix

    • Operators

    operator ==(Object other) → bool
    The equality operator.
    inherited