Reference Source
public class | source

CameraFlightAnimation

Extends:

Component → CameraFlightAnimation

Jumps or flies the Scene's Camera to a given target.

  • Located at Viewer#cameraFlight
  • Can fly or jump to its target.
  • While flying, can be stopped, or redirected to a different target.
  • Can also smoothly transition between ortho and perspective projections.

A CameraFlightAnimation's target can be:

  • specific eye, look and up positions,
  • an axis-aligned World-space bounding box (AABB), or
  • an instance or ID of any Component subtype that provides a World-space AABB.

A target can also contain a projection type to transition into. For example, if your Camera#projection is currently "perspective" and you supply CameraFlightAnimation#flyTo with a projection property equal to "ortho", then CameraFlightAnimation will smoothly transition the Camera into an orthographic projection.

Configure CameraFlightAnimation#fit and CameraFlightAnimation#fitFOV to make it stop at the point where the target occupies a certain amount of the field-of-view.

Flying to an Entity

Flying to an Entity:

var entity = new Mesh(viewer.scene);

// Fly to the Entity's World-space AABB
viewer.cameraFlight.flyTo(entity);

Flying to a Position

Flying the CameraFlightAnimation from the previous example to specified eye, look and up positions:

viewer.cameraFlight.flyTo({
   eye: [-5,-5,-5],
   look: [0,0,0]
   up: [0,1,0],
   duration: 1 // Default, seconds
},() => {
     // Done
});

Flying to an AABB

Flying the CameraFlightAnimation from the previous two examples explicitly to the {@link Boundary3D"}}Boundary3D's{{/crossLink}} axis-aligned bounding box:

viewer.cameraFlight.flyTo(entity.aabb);

Transitioning Between Projections

CameraFlightAnimation also allows us to smoothly transition between Camera projections. We can do that by itself, or in addition to flying the Camera to a target.

Let's transition the Camera to orthographic projection:

[Run example]

viewer.cameraFlight.flyTo({ projection: "ortho", () => {
     // Done
});

Now let's transition the Camera back to perspective projection:

viewer.cameraFlight.flyTo({ projection: "perspective"}, () => {
     // Done
});

Fly Camera to a position, while transitioning to orthographic projection:

viewer.cameraFlight.flyTo({
    eye: [-100,20,2],
    look: [0,0,-40],
    up: [0,1,0],
    projection: "ortho", () => {
       // Done
});

Member Summary

Public Members
public set

duration(value: Number)

Sets the flight duration, in seconds, when calling CameraFlightAnimation#flyTo.

public get

Gets the flight duration, in seconds, when calling CameraFlightAnimation#flyTo.

public

easing: *

public set

fit(value: Boolean)

Sets if, when CameraFlightAnimation is flying to a boundary, it will always adjust the distance between the Camera#eye and Camera#look so as to ensure that the target boundary is always filling the view volume.

public get

fit: Boolean: *

Gets if, when CameraFlightAnimation is flying to a boundary, it will always adjust the distance between the Camera#eye and Camera#look so as to ensure that the target boundary is always filling the view volume.

public set

fitFOV(value: Number)

Sets how much of the perspective field-of-view, in degrees, that a target Entity#aabb should fill the canvas when calling CameraFlightAnimation#flyTo or CameraFlightAnimation#jumpTo.

public get

Gets how much of the perspective field-of-view, in degrees, that a target Entity#aabb should fill the canvas when calling CameraFlightAnimation#flyTo or CameraFlightAnimation#jumpTo.

public set

trail(value: Boolean)

Sets if this CameraFlightAnimation to point the Camera in the direction that it is travelling when flying to a target after calling CameraFlightAnimation#flyTo.

public get

Gets if this CameraFlightAnimation points the Camera in the direction that it is travelling when flying to a target after calling CameraFlightAnimation#flyTo.

Method Summary

Public Methods
public

cancel()

Cancels an earlier flyTo without calling the arrival callback.

public

flyTo(params: Object | Component, callback: Function, scope: Object)

Flies the Camera to a target.

public

jumpTo(params: * | Component)

Jumps the Scene's Camera to the given target.

  • When the target is a boundary, this CameraFlightAnimation will position the Camera at where the target fills most of the canvas.
  • When the target is an explicit Camera position, given as eye, look and up vectors, then this CameraFlightAnimation will jump the Camera to that target.
public

stop()

Stops an earlier flyTo, fires arrival callback.

Inherited Summary

From class Component
public get

The Component that owns the lifecycle of this Component, if any.

public

True as soon as this Component has been destroyed

public

ID of this Component, unique within the Scene.

public

meta: *

Arbitrary, user-defined metadata on this component.

public

The parent Scene that contains this Component.

public

The viewer that contains this Scene.

public

clear()

Destroys all Components that are owned by this.

public

Destroys this component.

public

error(message: String)

Logs an error for this component to the JavaScript console.

public

fire(event: String, value: Object, forget: Boolean)

Fires an event on this component.

public

Returns true if there are any subscribers to the given event on this component.

public

isType(type: *): *: Boolean

Tests if this component is of the given type, or is a subclass of the given type.

public

log(message: String)

Logs a console debugging message for this component.

public

off(subId: String)

Cancels an event subscription that was previously made with Component#on or Component#once.

public

on(event: String, callback: Function, scope: Object): String

Subscribes to an event on this component.

public

once(event: String, callback: Function, scope: Object)

Subscribes to the next occurrence of the given event, then un-subscribes as soon as the event is subIdd.

public

scheduleTask(task: *)

Schedule a task to perform on the next browser interval

public

warn(message: String)

Logs a warning for this component to the JavaScript console.

Public Members

public set duration(value: Number) source

Sets the flight duration, in seconds, when calling CameraFlightAnimation#flyTo.

Stops any flight currently in progress.

default value is 0.5.

public get duration: Number: * source

Gets the flight duration, in seconds, when calling CameraFlightAnimation#flyTo.

default value is 0.5.

Return:

Number

New duration value.

public easing: * source

public set fit(value: Boolean) source

Sets if, when CameraFlightAnimation is flying to a boundary, it will always adjust the distance between the Camera#eye and Camera#look so as to ensure that the target boundary is always filling the view volume.

When false, the eye will remain at its current distance from the look position.

Default value is true.

public get fit: Boolean: * source

Gets if, when CameraFlightAnimation is flying to a boundary, it will always adjust the distance between the Camera#eye and Camera#look so as to ensure that the target boundary is always filling the view volume.

When false, the eye will remain at its current distance from the look position.

Default value is true.

Return:

Boolean

value Set true to activate this behaviour.

public set fitFOV(value: Number) source

Sets how much of the perspective field-of-view, in degrees, that a target Entity#aabb should fill the canvas when calling CameraFlightAnimation#flyTo or CameraFlightAnimation#jumpTo.

Default value is 45.

public get fitFOV: Number: * source

Gets how much of the perspective field-of-view, in degrees, that a target Entity#aabb should fill the canvas when calling CameraFlightAnimation#flyTo or CameraFlightAnimation#jumpTo.

Default value is 45.

Return:

Number

Current FOV value.

public set trail(value: Boolean) source

Sets if this CameraFlightAnimation to point the Camera in the direction that it is travelling when flying to a target after calling CameraFlightAnimation#flyTo.

Default value is true.

public get trail: Boolean: * source

Gets if this CameraFlightAnimation points the Camera in the direction that it is travelling when flying to a target after calling CameraFlightAnimation#flyTo.

Default value is true.

Return:

Boolean

True if trailing behaviour is active.

Public Methods

public cancel() source

Cancels an earlier flyTo without calling the arrival callback.

public flyTo(params: Object | Component, callback: Function, scope: Object) source

Flies the Camera to a target.

  • When the target is a boundary, the Camera will fly towards the target and stop when the target fills most of the canvas.
  • When the target is an explicit Camera position, given as eye, look and up, then CameraFlightAnimation will interpolate the Camera to that target and stop there.

Params:

NameTypeAttributeDescription
params Object | Component
  • optional
  • default: Scene

Either a parameters object or a Component subtype that has an AABB. Defaults to the Scene, which causes the Camera to fit the Scene in view.

params.arc Number
  • optional
  • default: 0

Factor in range [0..1] indicating how much the Camera#eye position will swing away from its Camera#look position as it flies to the target.

params.component Number | String | Component
  • optional

ID or instance of a component to fly to. Defaults to the entire Scene.

params.aabb Number[]
  • optional

World-space axis-aligned bounding box (AABB) target to fly to.

params.eye Number[]
  • optional

Position to fly the eye position to.

params.look Number[]
  • optional

Position to fly the look position to.

params.up Number[]
  • optional

Position to fly the up vector to.

params.projection String
  • optional

Projection type to transition into as we fly. Can be any of the values of Camera.projection.

params.fit Boolean
  • optional
  • default: true

Whether to fit the target to the view volume. Overrides CameraFlightAnimation#fit.

params.fitFOV Number
  • optional

How much of field-of-view, in degrees, that a target Entity or its AABB should fill the canvas on arrival. Overrides CameraFlightAnimation#fitFOV.

params.duration Number
  • optional

Flight duration in seconds. Overrides CameraFlightAnimation#duration.

params.orthoScale Number
  • optional

Animate the Camera's orthographic scale to this target value. See Ortho#scale.

callback Function
  • optional

Callback fired on arrival.

scope Object
  • optional

Optional scope for callback.

public jumpTo(params: * | Component) source

Jumps the Scene's Camera to the given target.

  • When the target is a boundary, this CameraFlightAnimation will position the Camera at where the target fills most of the canvas.
  • When the target is an explicit Camera position, given as eye, look and up vectors, then this CameraFlightAnimation will jump the Camera to that target.

Params:

NameTypeAttributeDescription
params * | Component

Either a parameters object or a Component subtype that has a World-space AABB.

params.arc Number
  • optional
  • default: 0

Factor in range [0..1] indicating how much the Camera#eye will swing away from its Camera#look as it flies to the target.

params.component Number | String | Component
  • optional

ID or instance of a component to fly to.

params.aabb Number[]
  • optional

World-space axis-aligned bounding box (AABB) target to fly to.

params.eye Number[]
  • optional

Position to fly the eye position to.

params.look Number[]
  • optional

Position to fly the look position to.

params.up Number[]
  • optional

Position to fly the up vector to.

params.projection String
  • optional

Projection type to transition into. Can be any of the values of Camera.projection.

params.fitFOV Number
  • optional

How much of field-of-view, in degrees, that a target Entity or its AABB should fill the canvas on arrival. Overrides CameraFlightAnimation#fitFOV.

params.fit Boolean
  • optional

Whether to fit the target to the view volume. Overrides CameraFlightAnimation#fit.

public stop() source

Stops an earlier flyTo, fires arrival callback.