API Docs

Class: ViewController

PD. ViewController

A view controller inspired by THREE.OrbitControls and THREE.FirstPersonControls.

This class converts mouse, pen, pointer and touch events into 2D and 3D view manipulations such as pan, zoom and rotation. It also smoothly handles switching from orbital to first-person navigation.

new ViewController(sceneViewer)

Creates a new view controller,

Parameters:
Name Type Description
sceneViewer PD.SceneViewer

The scene viewer to control.
Author:
  • drajmarsh

Extends

Members

:boolean

autoRotate

Whether or not to continuously rotate the view, defaults to false.

If auto-rotate is enabled, you must call update() in your animation loop.

Type
  • boolean
:number

autoRotateSpeed

The auto-rotation speed in rotations per minute, defaults to 2.0.

Type
  • number
:number

avatarRadius

The radius of the virtual avatar during WASD movements, defaults to 150mm.

Type
  • number
:THREE.Camera

camera

Stores the scene viewer camera instance.

Type
  • THREE.Camera
:HTMLElement

canvas

Stores the scene viewer canvas element.

Type
  • HTMLElement
:number

dampingFactor

The amount of inertial damping applied to the view, defaults to 0.05.

Type
  • number
:boolean

enableDamping

Whether or not the apply inertia to view manipulations, defaults to false.

If damping is enabled, you must call update() within your animation loop,

Type
  • boolean
:boolean

enableFOV

Whether or not the allow adjusting the field of view in the canvas, defaults to true.

Type
  • boolean
:boolean

enablePan

Whether or not the allow panning within the canvas, defaults to true.

Type
  • boolean
:boolean

enableRotate

Whether or not the allow orbital rotation within the canvas, defaults to true.

Type
  • boolean
:boolean

enableWASD

Whether or not the allow first-person WASD movements, defaults to true.

Type
  • boolean
:boolean

enableZoom

Whether or not the allow dolly-based zooming within the canvas, defaults to true.

Type
  • boolean
:boolean

enabled

Whether or not the controller is active.

Type
  • boolean

isActualCtrlKeyDown

The state of the control key at document level.

:number

keyPanSpeed

The number of canvas pixels to pan per ary key press, defaults to 7.0.

Type
  • number

keys

The key code names of the four arrow keys.

Properties:
Name Type Default Description
LEFT ArrowLeft
UP ArrowUp
RIGHT ArrowRight
DOWN ArrowDown
MOVE_FORWARD KeyW
MOVE_BACKWARD KeyS
MOVE_LEFT KeyA
MOVE_RIGHT KeyD
MOVE_UP KeyQ
MOVE_DOWN KeyZ
:number

maxAltitudeAngle

The maximum view altitude angle in radians, defaults to PI.

Type
  • number
:number

maxAzimuthAngle

The maximum view azimuth angle in radians, defaults to +Infinity.

Type
  • number
:number

maxDistance

The maximum zoom/dolly distance, defaults to Infinity.

Type
  • number
:number

minAltitudeAngle

The minimum view altitude angle in radians, defaults to zero.

Type
  • number
:number

minAzimuthAngle

The minimum view azimuth angle in radians, defaults to -Infinity.

Type
  • number
:number

minDistance

The minimum zoom/dolly distance, defaults to 50mm.

Type
  • number
:boolean

moving

Is the view being moved around using WASD/Arrow keys.

Type
  • boolean
:THREE.Vector3

orbitLocus

The position of the orbit locus point in model space.

Type
  • THREE.Vector3
:number

panSpeed

The relative speed of panning, defaults to 1.0.

Type
  • number
:number

rotateSpeed

The relative speed of orbital view rotations, defaults to 1.0.

Type
  • number
:PD.SceneViewer

sceneViewer

Stores the scene viewer whose view is being controlled.

Type
:boolean

screenSpacePanning

Whether or not panning should be screen-based rather than cartesian, defaults to true.

Type
  • boolean
:THREE.Vector3

target

The model point the camera always faces and rotates around.

Type
  • THREE.Vector3

touches

The actions associated with the number of touch points.

Properties:
Name Type Default Description
ONE THREE.TOUCH.ROTATE
TWO THREE.TOUCH.DOLLY_PAN
THREE THREE.TOUCH.PAN
:number

wasdMaxSpeed

The maximum relative speed of WASD movements, defaults to 1.0.

Type
  • number
:number

zoomSpeed

The relative speed of dolly-based zooms, defaults to 1.0.

Type
  • number
:number

dragThreshold <static, constant>

The number of pixels a click/tap action can move before becoming a drag action.

Type
  • number

Methods

addEventListener(type, listener)

Adds or replaces a listener function.

This method returns the listener function which allows a caller to use an unnamed or arrow function defined within the call and still store it for later removal.

Parameters:
Name Type Description
type string

The type of event to listen to.
listener function

The function that gets called when the event is fired.
Inherited From:
Overrides:
Returns:

Returns the listener function so it can be stored for later removal.

Type
function
Example
let event_listener;

onMounted() {
    event_listener = PD.GlobalEvents.addEventListener(PD.EVENT.SITE_LOCATION, (location) => {
        this.doSomethingWithTheLocation(location);
    });
};

onUnmounted() {
    if (event_listener) {
        PD.GlobalEvents.removeEventListener(PD.EVENT.SITE_LOCATION, event_listener);
        event_listener = null;
    }
};

dispatch(type, args)

Invokes all the listeners for the given event type with the given arguments.

NOTE: This method is different to the standard dispatchEvent() method on THREE.EventDispatcher that you may be used to. The THREE.js method requires a bespoke event object with the event arguments as properties of that object. It also modifies that object by adding an additional target property prior to sending, and creates a copy of the listener array on every call.

In our case, events may be generated many times a second as the view, location and/or sun-position are changed dynamically. The listener methods are all called in a tight loop and, given the nature of framework events, they do not remove themselves when called, so changes to the listener array during iteration are unlikely enough for the risk to be tolerable. Also, the dispatching object is typically static and globally available, so there is no need to send a reference to each listener. Whilst having to create a transitory event object, modify it and then copy the array may be a relatively small overhead, it is still an unnecessary one.

As a result, this method simply passes on the given event arguments to each listener without requiring a custom object, modifying it or copying the listener array each time.

Parameters:
Name Type Argument Description
type string

The event type identifier.
args any <repeatable>

The additional arguments that correspond to the given event type.
Inherited From:
Overrides:
Returns:

Returns true if at least one event listener was invoked, otherwise false.

Type
boolean

dispose()

Removes all listeners and frees any allocated resources.

getAltitudeAngle()

Retrieve the current view altitude angle, in radians (-PI/2 to PI/2).

Returns:

Returns the altitude angle in radians.

Type
number

getAzimuthalAngle()

Retrieve the current view azimuth angle, in radians (-PI to PI).

Returns:

Returns the azimuth angle in radians.

Type
number

getDistance()

Retrieve the current distance between camera and target, in model units.

Returns:

Returns the view distance in model units.

Type
number

handleExternalTouchMove(event)

Allows a host application to pass in pointer move events.

Parameters:
Name Type Description
event Event

The touch event.

handleExternalTouchUp(event)

Allows a host application to pass in pointer release events.

Parameters:
Name Type Description
event Event

The touch event.

handleKeyDown(event)

Handle an external key down event.

If the host application has keyboard event handlers on the same canvas, rather that risk double-handling of key events, you can simply call this method from that handler for any keys that the host does not handle.

When handling key events in this way, make sure you DO NOT call the optional listenToKeyEvents() method as this will install an additional set of internal handlers.

Parameters:
Name Type Description
event KeyboardEvent

The key down event to be handled.

handleKeyUp(event)

Handle an external key up event.

If the host application has keyboard event handlers on the same canvas, rather that risk double-handling of key events, you can simply call this method from that handler for any keys that the host does not handle.

When handling key events in this way, make sure you DO NOT call the optional listenToKeyEvents() method as this will install an additional set of internal handlers.

Parameters:
Name Type Description
event KeyboardEvent

The key up event to be handled.

handleSimulatedMouseEvent(event)

Allows a host application to simulate mouse events.

Parameters:
Name Type Description
event Event

The mouse event.

hasEventListener(type, listener)

Determines if the given listener function is associated with the given event type.

Parameters:
Name Type Description
type string

The type of event to listen to.
listener function

The function that gets called when the event is fired.
Inherited From:
Overrides:
Returns:

Returns true if the listener function exists.

Type
boolean

hasEventListeners(type)

Determines if an event has any registered listeners.

Parameters:
Name Type Description
type string

The type of event to check.
Inherited From:
Overrides:
Returns:

Returns true if there is more than one listener for the given event.

Type
boolean

isActiveAction()

Checks if there is an active state in the view.

An active state means that there is an ongoing drag operation in effect.

Returns:

Returns true if there is an active state.

Type
boolean

isInAvatarMode()

Retrieve whether or not the current view is in WASD walking mode.

Walking mode differs from orbit mode in that user interactions generate view direction changes rather than view rotation changes. Also, zoom/dolly moves both the camera and target positions together rather than moving the camera closer to or further away from the target.

Returns:

Returns whether or not the view is in walking mode.

Type
boolean

listenToKeyEvents(canvas)

Start listening and responding to canvas key events using internal handlers.

Call this method to install a set of internal key event handlers on the given canvas to provide direct view manipulations. Use the enableWASD flag to set whether or not the view will support first-person navigation (walking mode) using the WASD and ARROW keys.

Parameters:
Name Type Description
canvas HTMLCanvasElement

The canvas element to listen to events on.

needsUpdate()

Determines whether or not the view has changed or is changing.

This method is typically polled by the host application and, whenever it returns true, the update() method should then be called by the host.

Updates are required whenever the user interacts with the view by clicking/touching and dragging a pointer within the view canvas, when movement is still above a set threshold when dampening a previous move, or when auto-rotate is set.

Returns:

Returns true if the view is moving or damping is active.

Type
boolean

pan(dx, dy)

Begins panning the model at the given rates in the relative X and Y directions.

The X direction refers to lateral movement to the left or right sides, whilst the Y direction refers to relative up and down movements.

The amount of movement in each direction is given as fractions between -1 and 1, which are multiplied by the current wasdMaxSpeed value.

To clear the pan movement, call this method with zero values.

Parameters:
Name Type Description
dx number

The amount of X direction pan as a fraction (-1 to 1).
dy number

The amount of Y direction pan as a fraction (-1 to 1).

removeEventListener(type, listener)

Removes the given listener function from the given event type.

Parameters:
Name Type Description
type string

The type of event to listen to.
listener function

The function that gets called when the event is fired.
Inherited From:
Overrides:
Returns:

Returns true if the listener function was found and removed.

Type
boolean

restoreState()

Restores the last saved camera and target positions as well as zoom.

rotate(dx, dy)

Begins rotating the model at the given rates in the relative X and Y directions.

The X direction refers to lateral rotations to the left or right sides, whilst the Y direction refers to relative up and down rotations.

The amount of rotation in each direction is given as fractions between -1 and 1, which are multiplied by the current wasdMaxSpeed value.

To clear the rotation, call this method with zero values.

Parameters:
Name Type Description
dx number

The amount of horizontal rotation as a fraction (-1 to 1).
dy number

The amount of vertical rotation as a fraction (-1 to 1).

saveState()

Stores the current camera and target positions as well as zoom.

setDragAction()

Sets whether or not the current view is in WASD walking mode.

Walking mode differs from orbit mode in that user interactions generate view direction changes rather than view rotation changes. Also, zoom/dolly moves both the camera and target positions together rather than moving the camera closer to or further away from the target.

Returns:

Returns whether or not the view was set to walking mode.

Type
boolean

stop()

Stop moving in the model.

Call this method to discontinue walking in any direction within the model. If damping is enabled, the motion will continue for a short period whilst the damping value slows the movement to zero.

If you wish to come to an abrupt halt, call the walk() method instead with a speed value of zero.

update()

Updates the view after any changes.

This method does all the work required to apply any current pan, zoom and/or rotations to the current camera and target positions, and apply damping to each value.

This is typically called by the host application after polling the PD.ViewController#needsUpdate method and receiving a true result.

Returns:

Returns true if the view was changed.

Type
boolean

walk(speed, angle)

Start walking forwards or backwards in the model.

This method will only respond when the enableWASD flag is true and the current view is not an axially-aligned orthographic view.

If the given speed is positive, the camera walks forwards. If negative, it walks backwards. If zero, the camera is not moved and the angle is set to zero.

If the relative sideways turn angle is positive, the camera rotates to the left. If negative, it rotates to the right. If zero, no rotation is applied.

If the speed value is zero, the camera movement will come to an abrupt halt. If damping is enabled and you want to let damping slow the movement, use the stop() method instead.

The values for speed and angle are each given as fractions between -1 and 1, which are multiplied by the current wasdMaxSpeed value.

Parameters:
Name Type Description
speed number

The walking speed as a fraction of the maximum speed (-1 to 1).
angle number

The relative sideways turn angle as a fraction (-1 to 1).