API Docs

Class: ViewOrbital

PD. ViewOrbital

Manages a camera using spherical coordinates and field of view around a target.

This class encapsulated the data required to smoothly transition between views of a model. It uses spherical coordinates to maintain a consistent view distance from the model by interpolating rotation angles, rather than moving linearly between view points which could potentially pass the camera through the model.

new ViewOrbital( [camera] [, controller])

Creates a new camera view.

If the camera parameter is given, its position and field of view will be automatically set whenever the view changes.

Parameters:
Name Type Argument Description
camera THREE.Camera <optional>

The camera to keep updated.
controller PD.ViewController <optional>

The view controller to keep updated.
Author:
  • drajmarsh

Extends

Members

:THREE.Vector3

_tempVec

A temporary vector used in some methods.

Type
  • THREE.Vector3
:number

altitude

The altitude angle of the camera relative to the view target, in degrees (-90 to 90).

The altitude angle is measure vertically above the horizontal plane.

Type
  • number
Inherited From:
Overrides:
:number

azimuth

The azimuth angle of the camera relative to the view target, in degrees (-180 to 180).

The azimuth angle is measured in an anti-clockwise direction from the positive X axis.

Type
  • number
Inherited From:
Overrides:
:THREE.Camera|null

camera

The camera to keep updated.

Type
  • THREE.Camera | null
:THREE.Vector3

cameraPos

The position of the camera in model space.

Type
  • THREE.Vector3
Inherited From:
Overrides:
:PD.ViewController|null

controller

The view controller to keep updated.

Type
:number

distance

The distance between the camera and view target, in model units.

Type
  • number
:function

easing

A PD.Easing function to use when interpolating between views.

Type
  • function
:number

fov

The field of view angle of the camera, in degrees (0.1 to 160).

Type
  • number
Inherited From:
Overrides:
:number

fovFactor

The calculated field of view compensation factor.

Type
  • number
:boolean

isTransitioning <readonly>

Determines whether or not the view transition needs to be updated.

Type
  • boolean
:boolean

isViewAngles <readonly>

A flag identifying this object as a view angles instance.

Type
  • boolean
Inherited From:
Overrides:
:boolean

isViewOrbital <readonly>

A flag identifying this object as an orbital view.

Type
  • boolean
:boolean

lockCamera

Maintain relative camera/target vector when moving the target position.

Type
  • boolean
Inherited From:
Overrides:
:number

minDistance

The minimum allowable distance between camera and target.

Type
  • number
:number

referenceViewDist

Stores the reference distance between camera and target.

This is the actual distance with the fovFactor multiplier applied.

Type
  • number
:THREE.Vector3

targetPos

The position of the look-at point in model space.

Type
  • THREE.Vector3
Inherited From:
Overrides:
:THREE.Vector3

vectorToCamera

The normalised view vector from the target to the camera.

Type
  • THREE.Vector3
:number

zoom

Stores the relative view zoom as a multiplier factor.

Type
  • number
Inherited From:
Overrides:

Methods

copyViewAnglesFrom(data)

Copies data from the given instance to this instance.

Parameters:
Name Type Description
data PD.ViewAngles | object

The view state instance to copy data from.
Inherited From:
Overrides:
Returns:

Returns this view angles instance to support method chaining.

Type
PD.ViewAngles

copyViewAnglesTo(data)

Copies data from this instance to another given instance.

Parameters:
Name Type Description
data PD.ViewAngles | object

The object instance to copy data to.
Inherited From:
Overrides:
Returns:

Returns this view angles instance to support method chaining.

Type
PD.ViewAngles

fromJSON(data)

Safely copy properties from a source object.

See the PD.Base#fromJSON method for more details.

Parameters:
Name Type Description
data object

The source object containing data to copy.
Inherited From:
Overrides:
Returns:

Returns this instance to support method chaining.

Type
PD.View

moveView(direction, distance)

Instantly change the view by the distance in the given direction.

Parameters:
Name Type Description
direction THREE.Vector3

The vector direction to travel in.
distance number

The zoom factor to apply to the view distance.
Returns:

Returns this camera controller to support method chaining.

Type
PD.ViewOrbital

setFOV(fov)

Sets the field of view of the camera.

Parameters:
Name Type Description
fov number

The new camera field of view, in decimal degrees (0.1 to 160).
Returns:

Returns this scene manager to support method chaining.

Type
PD.SceneManager

setFromPositions(cameraPos [, targetPos])

Instantly change the view to the given camera and target positions.

Parameters:
Name Type Argument Description
cameraPos THREE.Vector3

The new position of the camera.
targetPos THREE.Vector3 <optional>

The new position of the view center.
Returns:

Returns this camera controller to support method chaining.

Type
PD.ViewOrbital

setViewFromAngles(azimuth, altitude)

Instantly change the view to the given view angles.

Parameters:
Name Type Description
azimuth number

The new camera azimuth angle in degrees.
altitude number

The new camera altitude angle in degrees.
Returns:

Returns this camera controller to support method chaining.

Type
PD.ViewOrbital

setViewFromVector(vector)

Instantly change the view to the given vector.

Parameters:
Name Type Description
vector THREE.Vector3

The new camera view vector.
Returns:

Returns this camera controller to support method chaining.

Type
PD.ViewOrbital

toJSON( [data])

Converts the object instance to a simple POJO for JSON storage.

This method is used to copy, store and save the data for ths object, so the returned object must have all the properties required be able to rebuild this instance in its entirety when passed to the class constructor.

See the PD.Base#toJSON method for more details.

Parameters:
Name Type Argument Description
data object <optional>

An optional parent object to append this data to.
Inherited From:
Returns:

Returns a JSON object.

Type
object

transition( [fraction])

Smoothly interpolate between the stored views.

If no fractional value is given, the transition attempts to complete within the number of milliseconds in the PD.GlobalState.transitionSpeed property.

Parameters:
Name Type Argument Description
fraction number <optional>

The fractional value between 'from' and 'to' (0 to 1).
Returns:

Returns this camera controller to support method chaining.

Type
PD.ViewOrbital

transitionFieldOfView(fov)

Initialises a transition to a new field of view angle.

Parameters:
Name Type Description
fov number

The new field of view angle, in degrees (0.1 to 160.0).
Returns:

Returns this camera controller to support method chaining.

Type
PD.ViewOrbital

transitionHeight(dz [, animate])

Moves the camera and target position by the given height.

Parameters:
Name Type Argument Default Description
dz number

The height difference.
animate boolean <optional>
 true

Whether to animate the transition, defaults to true.
Returns:

Returns this camera controller to support method chaining.

Type
PD.ViewOrbital

transitionToAngles(azimuth, altitude [, distance] [, targetPos] [, fov])

Initialises a transition to a new set of spherical coordinates.

Parameters:
Name Type Argument Description
azimuth number

The new azimuth angle in degrees.
altitude number

The new altitude angle in degrees.
distance number <optional>

The new view distance in model units.
targetPos THREE.Vector3 <optional>

The new position of the view center.
fov number <optional>

The new field of view angle, in degrees (0.01 to 160.0).
Returns:

Returns this camera controller to support method chaining.

Type
PD.ViewOrbital

transitionToFit(distance [, targetPos] [, callback])

Initialises a transition to a new target distance.

Parameters:
Name Type Argument Description
distance number

The new view distance in model units.
targetPos THREE.Vector3 <optional>

The new position of the view center.
callback function <optional>

An optional callback function to invoke when transition is complete.
Returns:

Returns this camera controller to support method chaining.

Type
PD.ViewOrbital

transitionToHorizontal()

Initialises a transition to a horizontal view at the default eye height.

Returns:

Returns this camera controller to support method chaining.

Type
PD.ViewOrbital

transitionToPosition(cameraPos [, targetPos] [, fov])

Initialises a transition to a new camera and target position.

Parameters:
Name Type Argument Description
cameraPos THREE.Vector3

The new position of the camera.
targetPos THREE.Vector3 <optional>

The new position of the view center.
fov number <optional>

The new field of view angle, in degrees (0.01 to 160.0).
Returns:

Returns this camera controller to support method chaining.

Type
PD.ViewOrbital

transitionToSelection(extents [, normal] [, center] [, fov])

Initialises a transition to straight-on at the given selection.

Parameters:
Name Type Argument Description
extents number

The bounding box defining the view area.
normal THREE.Vector3 <optional>

An optional surface normal to align with.
center THREE.Vector3 <optional>

An optional new look-at target position.
fov number <optional>

An optional new field of view angle, in degrees (0.01 to 160.0).
Returns:

Returns this camera controller to support method chaining.

Type
PD.ViewOrbital

transitionToVector(vector [, distance] [, targetPos] [, fov])

Initialises a transition to a new camera vector.

Parameters:
Name Type Argument Description
vector THREE.Vector3

The new camera view vector.
distance number <optional>

The new view distance in model units.
targetPos THREE.Vector3 <optional>

The new position of the view center.
fov number <optional>

The new field of view angle, in degrees (0.1 to 160.0).
Returns:

Returns this camera controller to support method chaining.

Type
PD.ViewOrbital

transitionToView(view)

Switches towards the given view.

Parameters:
Name Type Description
view PD.View

The target view to interpolate towards.
Returns:

Returns this camera controller to support method chaining.

Type
PD.ViewOrbital

updateView()

Compute the camera position relative to target using spherical coordinates.

Returns:

Returns this camera controller to support method chaining.

Type
PD.ViewOrbital

zoomByRay(ray, factor)

Instantly change the view by the distance in the given direction.

Parameters:
Name Type Description
ray THREE.Ray

The ray direction to travel in.
factor number

The zoom factor to apply to the view distance.
Returns:

Returns this camera controller to support method chaining.

Type
PD.ViewOrbital