openspace.navigation

Functions overview

Name

Documentation

addGlobalRoll

Directly adds to the global roll of the camera

addGlobalRotation

Directly add to the global rotation of the camera (around the focus node)

addLocalRoll

Directly adds to the local roll of the camera

addLocalRotation

Directly adds to the local rotation of the camera (around the camera’s current position)

addTruckMovement

Directly adds to the truck movement of the camera

axisDeadzone

Returns the deadzone for the desired axis of the provided joystick

bindJoystickAxis

Bind an axis of a joystick to be used as a certain type, and optionally define detailed settings for the axis

bindJoystickAxisProperty

Binds an axis of a joystick to a numerical property value in OpenSpace

bindJoystickButton

Bind a Lua script to one of the buttons for a joystick

clearJoystickButton

Remove all commands that are currently bound to a button of a joystick or game controller

distanceToFocus

Return the distance to the current focus node

distanceToFocusBoundingSphere

Return the distance to the current focus node’s bounding sphere

distanceToFocusInteractionSphere

Return the distance to the current focus node’s interaction sphere

flyTo

Move the camera to the node with the specified identifier

flyToGeo

Fly the camera to a geographic coordinate (latitude, longitude and altitude) on a globe, using the path navigation system

flyToGeo2

Fly the camera to a geographic coordinate (latitude and longitude) on a globe, using the path navigation system

flyToHeight

Move the camera to the node with the specified identifier

flyToNavigationState

Create a path to the navigation state described by the input table

getLocalPositionFromGeo

Returns the position in the local Cartesian coordinate system of the specified globe that corresponds to the given geographic coordinates

getNavigationState

Return the current NavigationState as a Lua table

goToGeo

Immediately move the camera to a geographic coordinate on a globe

isFlying

Returns true if a camera path is currently running, and false otherwise

joystickAxis

Return all the information bound to a certain joystick axis

joystickButton

Get the Lua script that is currently bound to be executed when the provided button is pressed/triggered

jumpTo

Fade rendering to black, jump to the specified navigation state, and then fade in

jumpToGeo

Immediately move the camera to a geographic coordinate on a node by first fading the rendering to black, jump to the specified coordinate, and then fade in

jumpToNavigationState

Fade rendering to black, jump to the specified node, and then fade in

listAllJoysticks

Return the complete list of connected joysticks

loadNavigationState

Set the camera position by loading a NavigationState from file

localPositionFromGeo

Returns the position in the local Cartesian coordinate system of the specified node that corresponds to the given geographic coordinates

retargetAim

Reset the camera direction to point at the aim node

retargetAnchor

Reset the camera direction to point at the anchor node

saveNavigationState

Save the current NavigationState to a file with the path given by the first argument

setAxisDeadZone

Set the deadzone value for a particular joystick axis, which means that any input less than this value is completely ignored

setFocus

Set the current focus node for the navigation, or re-focus on it if it was already the focus node

setNavigationState

Set the camera position from a provided NavigationState

targetNextInterestingAnchor

Picks the next node from the interesting nodes out of the profile and selects that

targetPreviousInterestingAnchor

Picks the previous node from the interesting nodes out of the profile and selects that

triggerIdleBehavior

Immediately start applying the chosen IdleBehavior

zoomToDistance

Fly linearly to a specific distance in relation to the focus node

zoomToDistanceRelative

Fly linearly to a specific distance in relation to the focus node, given as a relative value based on the size of the object rather than in meters

zoomToFocus

Zoom linearly to the current focus node, using the default distance

Functions

addGlobalRoll

Directly adds to the global roll of the camera. This is a rotation around the line between the focus node and the camera (not always the same as the camera view direction)

Parameters

  • value Number

    • the value to add

Return type: void

Signature
openspace.navigation.addGlobalRoll(value)

addGlobalRotation

Directly add to the global rotation of the camera (around the focus node).

Parameters

  • xValue Number

    • the value to add in the x-direction (a positive value rotates to the right and a negative value to the left)

  • yValue Number

    • the value to add in the y-direction (a positive value rotates the focus upwards and a negative value downwards)

Return type: void

Signature
openspace.navigation.addGlobalRotation(xValue, yValue)

addLocalRoll

Directly adds to the local roll of the camera. This is the rotation around the camera’s forward/view direction.

Parameters

  • value Number

    • the value to add

Return type: void

Signature
openspace.navigation.addLocalRoll(value)

addLocalRotation

Directly adds to the local rotation of the camera (around the camera’s current position).

Parameters

  • xValue Number

    • the value to add in the x-direction (a positive value rotates to the left and a negative value to the right)

  • yValue Number

    • the value to add in the y-direction (a positive value rotates the camera upwards and a negative value downwards)

Return type: void

Signature
openspace.navigation.addLocalRotation(xValue, yValue)

addTruckMovement

Directly adds to the truck movement of the camera. This is the movement along the line from the camera to the focus node.

A positive value moves the camera closer to the focus, and a negative value moves the camera further away.

Parameters

  • value Number

    • the value to add

Return type: void

Signature
openspace.navigation.addTruckMovement(value)

axisDeadzone

Returns the deadzone for the desired axis of the provided joystick.

Parameters

  • joystickName String

    • the name for the joystick or game controller which information should be returned

  • axis Integer

    • the joystick axis for which to get the deadzone value

Return type: Number the deadzone value

Signature
openspace.navigation.axisDeadzone(joystickName, axis)

bindJoystickAxis

Bind an axis of a joystick to be used as a certain type, and optionally define detailed settings for the axis.

Parameters

  • joystickName String

    • the name for the joystick or game controller that should be bound

  • axis Integer

    • the axis of the joystick that should be bound

  • axisType String

    • the type of movement that the axis should be mapped to

  • shouldInvert Boolean? - Default value: false

    • decides if the joystick axis movement should be inverted or not

  • joystickType String? - Default value: "JoystickLike"

    • what type of joystick or axis this is. Decides if the joystick behaves more like a joystick or a trigger. Either \"JoystickLike\" or \"TriggerLike\", where \"JoystickLike\" is default

  • isSticky Boolean? - Default value: false

    • if true, the value is calculated relative to the previous value. If false, the value is used as is

  • shouldFlip Boolean? - Default value: false

    • reverses the movement of the camera that the joystick produces

  • sensitivity Number? - Default value: 0.0

    • sensitivity for this axis, in addition to the global sensitivity

Return type: void

Signature
openspace.navigation.bindJoystickAxis(joystickName, axis, axisType, shouldInvert, joystickType, isSticky, shouldFlip, sensitivity)

bindJoystickAxisProperty

Binds an axis of a joystick to a numerical property value in OpenSpace. This means that interacting with the joystick will change the property value, within a given min-max range.

The axis value will be rescaled from [-1, 1] to the provided [min, max] range (default is [0, 1]).

Parameters

  • joystickName String

    • the name for the joystick or game controller that should be bound

  • axis Integer

    • the axis of the joystick that should be bound

  • propertyUri String

    • the identifier (URI) of the property that this joystick axis should modify

  • min Number? - Default value: 0.f

    • the minimum value that this axis can set for the property

  • max Number? - Default value: 1.f

    • the maximum value that this axis can set for the property

  • shouldInvert Boolean? - Default value: false

    • if the joystick movement should be inverted or not

  • isRemote Boolean? - Default value: true

    • if true, the property change will also be executed on connected nodes. If false, the property change will only affect the master node

Return type: void

Signature
openspace.navigation.bindJoystickAxisProperty(joystickName, axis, propertyUri, min, max, shouldInvert, isRemote)

bindJoystickButton

Bind a Lua script to one of the buttons for a joystick.

Parameters

  • joystickName String

    • the name for the joystick or game controller

  • button Integer

    • the button to which to bind the script

  • command String

    • the script that should be executed on button trigger

  • documentation String

    • the documentation for the provided script/command

  • action String? - Default value: "Press"

    • the action for when the script should be executed. This defaults to \"Press\", which means that the script is run when the user presses the button. Alternatives are \"Idle\" (if the button is unpressed and has been unpressed since the last frame), \"Repeat\" (if the button has been pressed since longer than the last frame), and \"Release\" (if the button was released since the last frame)

  • isRemote Boolean? - Default value: true

    • a value saying whether the command is going to be executable locally or remotely, where the latter is the default

Return type: void

Signature
openspace.navigation.bindJoystickButton(joystickName, button, command, documentation, action, isRemote)

clearJoystickButton

Remove all commands that are currently bound to a button of a joystick or game controller

Parameters

  • joystickName String

    • the name for the joystick or game controller

  • button Integer

    • the button for which to clear the commands

Return type: void

Signature
openspace.navigation.clearJoystickButton(joystickName, button)

distanceToFocus

Return the distance to the current focus node.

Return type: Number

Signature
openspace.navigation.distanceToFocus()

distanceToFocusBoundingSphere

Return the distance to the current focus node’s bounding sphere.

Return type: Number

Signature
openspace.navigation.distanceToFocusBoundingSphere()

distanceToFocusInteractionSphere

Return the distance to the current focus node’s interaction sphere.

Return type: Number

Signature
openspace.navigation.distanceToFocusInteractionSphere()

flyTo

Move the camera to the node with the specified identifier. The optional double specifies the duration of the motion, in seconds. If the optional bool is set to true the target up vector for camera is set based on the target node. Either of the optional parameters can be left out.

Parameters

  • nodeIdentifier String

    • The identifier of the node to which we want to fly

  • useUpFromTargetOrDuration Boolean | Number?

    • If this value is a boolean value (true or false), this value determines whether we want to end up with the camera facing along the selected node’s up direction. If this value is a numerical value, refer to the documnentation of the duration parameter

  • duration Number?

    • The duration (in seconds) how long the flying to the selected node should take. If this value is left out, a sensible default value is uses, which can be configured in the engine

Return type: void

Signature
openspace.navigation.flyTo(nodeIdentifier, useUpFromTargetOrDuration, duration)

flyToGeo

Fly the camera to a geographic coordinate (latitude, longitude and altitude) on a globe, using the path navigation system. If the node is a globe, the longitude and latitude is expressed in the body’s native coordinate system. If it is not, the position on the surface of the interaction sphere is used instead.

Parameters

  • node String

    • The identifier of a scene graph node. If an empty string is provided, the current anchor node is used

  • latitude Number

    • The latitude of the target coordinate, in degrees

  • longitude Number

    • The longitude of the target coordinate, in degrees

  • altitude Number

    • The altitude of the target coordinate, in meters

  • duration Number?

    • An optional duration for the motion to take, in seconds. For example, a value of 5 means “fly to this position over a duration of 5 seconds”

  • shouldUseUpVector Boolean?

    • If true, try to use the up-direction when computing the target position for the camera. For globes, this means that North should be up, in relation to the camera’s view direction. Note that for this to take effect, rolling motions must be enabled in the Path Navigator settings.

Return type: void

Signature
openspace.navigation.flyToGeo(node, latitude, longitude, altitude, duration, shouldUseUpVector)

flyToGeo2

Fly the camera to a geographic coordinate (latitude and longitude) on a globe, using the path navigation system. If the node is a globe, the longitude and latitude is expressed in the body’s native coordinate system. If it is not, the position on the surface of the interaction sphere is used instead.

The distance to fly to can either be set to be the current distance of the camera to the target object, or the default distance from the path navigation system.

Parameters

  • node String

    • The identifier of a scene graph node. If an empty string is provided, the current anchor node is used

  • latitude Number

    • The latitude of the target coordinate, in degrees

  • longitude Number

    • The longitude of the target coordinate, in degrees

  • useCurrentDistance Boolean?

    • If true, use the current distance of the camera to the target globe when going to the specified position. If false, or not specified, set the distance based on the bounding sphere and the distance factor setting in Path Navigator

  • duration Number?

    • An optional duration for the motion to take, in seconds. For example, a value of 5 means “fly to this position over a duration of 5 seconds”

  • shouldUseUpVector Boolean?

    • If true, try to use the up-direction when computing the target position for the camera. For globes, this means that North should be up, in relation to the camera’s view direction. Note that for this to take effect, rolling motions must be enabled in the Path Navigator settings.

Return type: void

Signature
openspace.navigation.flyToGeo2(node, latitude, longitude, useCurrentDistance, duration, shouldUseUpVector)

flyToHeight

Move the camera to the node with the specified identifier. The second argument is the desired target height above the target node’s bounding sphere, in meters. The optional double specifies the duration of the motion, in seconds. If the optional bool is set to true, the target up vector for camera is set based on the target node. Either of the optional parameters can be left out.

Parameters

  • nodeIdentifier String

    • The identifier of the node to which we want to fly

  • height Number

    • The height (in meters) to which we want to fly. The way the height is defined specifically determines on the type of node to which the fly-to command is pointed.

  • useUpFromTargetOrDuration Boolean | Number?

    • If this value is a boolean value (true or false), this value determines whether we want to end up with the camera facing along the selected node’s up direction. If this value is a numerical value, refer to the documnentation of the duration parameter

  • duration Number?

    • The duration (in seconds) how long the flying to the selected node should take. If this value is left out, a sensible default value is uses, which can be configured in the engine

Return type: void

Signature
openspace.navigation.flyToHeight(nodeIdentifier, height, useUpFromTargetOrDuration, duration)

flyToNavigationState

Create a path to the navigation state described by the input table. Note that roll must be included for the target up direction in the navigation state to be taken into account.

Parameters

  • navigationState Table

  • duration Number?

    • An optional duration for the motion to take, in seconds. For example, a value of 5 means “fly to this position over a duration of 5 seconds”

Return type: void

Signature
openspace.navigation.flyToNavigationState(navigationState, duration)

getLocalPositionFromGeo

Returns the position in the local Cartesian coordinate system of the specified globe that corresponds to the given geographic coordinates. In the local coordinate system, the position (0,0,0) corresponds to the globe’s center. If the node is a globe, the longitude and latitude is expressed in the body’s native coordinate system. If it is not, the position on the surface of the interaction sphere is used instead.

Deprecated in favor of localPositionFromGeo.

Parameters

  • nodeIdentifier String

  • latitude Number

    • The latitude of the geograpic position, in degrees

  • longitude Number

    • The longitude of the geographic position, in degrees

  • altitude Number

    • The altitude, in meters

Return type: (Number, Number, Number)

Signature
openspace.navigation.getLocalPositionFromGeo(nodeIdentifier, latitude, longitude, altitude)

getNavigationState

Return the current NavigationState as a Lua table.

By default, the reference frame will be picked based on whether the orbital navigator is currently following the anchor node rotation. If it is, the anchor will be chosen as reference frame. If not, the reference frame will be set to the scene graph root.

Parameters

  • frame String?

    • the identifier of an optional scene graph node to use as reference frame for the NavigationState

Return type: Table a Lua table representing the current NavigationState of the camera

Signature
openspace.navigation.getNavigationState(frame)

goToGeo

Immediately move the camera to a geographic coordinate on a globe. If the node is a globe, the longitude and latitude is expressed in the body’s native coordinate system. If it is not, the position on the surface of the interaction sphere is used instead.

Parameters

  • node String

    • The identifier of a scene graph node. If an empty string is provided, the current anchor node is used

  • latitude Number

    • The latitude of the target coordinate, in degrees

  • longitude Number

    • The longitude of the target coordinate, in degrees

  • altitude Number?

    • An optional altitude, given in meters over the reference surface of the globe. If no altitude is provided, the altitude will be kept as the current distance to the reference surface of the specified globe.

Return type: void

Signature
openspace.navigation.goToGeo(node, latitude, longitude, altitude)

isFlying

Returns true if a camera path is currently running, and false otherwise.

Return type: Boolean

Signature
openspace.navigation.isFlying()

joystickAxis

Return all the information bound to a certain joystick axis.

Parameters

  • joystickName String

    • the name for the joystick or game controller with the axis for which to find the information

  • axis Integer

    • the joystick axis for which to find the information

Return type: Table an object with information about the joystick axis

Signature
openspace.navigation.joystickAxis(joystickName, axis)

joystickButton

Get the Lua script that is currently bound to be executed when the provided button is pressed/triggered.

Parameters

  • joystickName String

    • the name for the joystick or game controller

  • button Integer

    • the button for which to get the command

Return type: String the currently bound Lua script

Signature
openspace.navigation.joystickButton(joystickName, button)

jumpTo

Fade rendering to black, jump to the specified navigation state, and then fade in. This is done by triggering another script that handles the logic.

Parameters

  • nodeIdentifier String

    • The identifier of the scene graph node to jump to

  • fadeDuration Number?

    • An optional duration for the fading. If not included, the property in Navigation Handler will be used

Return type: void

Signature
openspace.navigation.jumpTo(nodeIdentifier, fadeDuration)

jumpToGeo

Immediately move the camera to a geographic coordinate on a node by first fading the rendering to black, jump to the specified coordinate, and then fade in. If the node is a globe, the longitude and latitude values are expressed in the body’s native coordinate system. If it is not, the position on the surface of the interaction sphere is used instead.

This is done by triggering another script that handles the logic.

Parameters

  • node String

    • The identifier of a scene graph node. If an empty string is provided, the current anchor node is used

  • latitude Number

    • The latitude of the target coordinate, in degrees

  • longitude Number

    • The longitude of the target coordinate, in degrees

  • altitude Number?

    • An optional altitude, given in meters over the reference surface of the globe. If no altitude is provided, the altitude will be kept as the current distance to the reference surface of the specified node

  • fadeDuration Number?

    • An optional duration for the fading. If not included, the property in Navigation Handler will be used

Return type: void

Signature
openspace.navigation.jumpToGeo(node, latitude, longitude, altitude, fadeDuration)

jumpToNavigationState

Fade rendering to black, jump to the specified node, and then fade in. This is done by triggering another script that handles the logic.

Parameters

  • navigationState Table

  • useTimeStamp Boolean?

    • if true, and the provided NavigationState includes a timestamp, the time will be set as well.

  • fadeDuration Number?

    • An optional duration for the fading. If not included, the property in Navigation Handler will be used.

Return type: void

Signature
openspace.navigation.jumpToNavigationState(navigationState, useTimeStamp, fadeDuration)

listAllJoysticks

Return the complete list of connected joysticks.

Return type: String[]

Signature
openspace.navigation.listAllJoysticks()

loadNavigationState

Set the camera position by loading a NavigationState from file. The file should be in json format, such as the output files of saveNavigationState.

Parameters

  • filePath String

    • the path to the file, including the file name (and extension, if it is anything other than .navstate)

  • useTimeStamp Boolean? - Default value: false

    • if true, and the provided NavigationState includes a timestamp, the time will be set as well.

Return type: void

Signature
openspace.navigation.loadNavigationState(filePath, useTimeStamp)

localPositionFromGeo

Returns the position in the local Cartesian coordinate system of the specified node that corresponds to the given geographic coordinates. In the local coordinate system, the position (0,0,0) corresponds to the globe’s center. If the node is a globe, the longitude and latitude is expressed in the body’s native coordinate system. If it is not, the position on the surface of the interaction sphere is used instead.

Parameters

  • nodeIdentifier String

    • The identifier of the scene graph node

  • latitude Number

    • The latitude of the geograpic position, in degrees

  • longitude Number

    • The longitude of the geographic position, in degrees

  • altitude Number

    • The altitude, in meters

Return type: (Number, Number, Number)

Signature
openspace.navigation.localPositionFromGeo(nodeIdentifier, latitude, longitude, altitude)

retargetAim

Reset the camera direction to point at the aim node.

Return type: void

Signature
openspace.navigation.retargetAim()

retargetAnchor

Reset the camera direction to point at the anchor node.

Return type: void

Signature
openspace.navigation.retargetAnchor()

saveNavigationState

Save the current NavigationState to a file with the path given by the first argument.

By default, the reference frame will be picked based on whether the orbital navigator is currently following the anchor node rotation. If it is, the anchor will be chosen as reference frame. If not, the reference frame will be set to the scene graph root.

Parameters

  • path String

    • the file path for where to save the NavigationState, including the file name. If no extension is added, the file is saved as a .navstate file.

  • frame String? - Default value: ""

    • the identifier of the scene graph node which coordinate system should be used as a reference frame for the NavigationState.

Return type: void

Signature
openspace.navigation.saveNavigationState(path, frame)

setAxisDeadZone

Set the deadzone value for a particular joystick axis, which means that any input less than this value is completely ignored.

Parameters

  • joystickName String

    • the name for the joystick or game controller

  • axis Integer

    • the joystick axis for which to set the deadzone

  • deadzone Number

    • the new deadzone value

Return type: void

Signature
openspace.navigation.setAxisDeadZone(joystickName, axis, deadzone)

setFocus

Set the current focus node for the navigation, or re-focus on it if it was already the focus node.

Per default, the camera will retarget to center the focus node in the view. The velocities will also be reset so that the camera stops moving after any retargeting is done. However, both of these behaviors may be skipped using the optional arguments.

Parameters

  • identifier String

    • The identifier of the scene graph node to focus

  • shouldRetarget Boolean? - Default value: true

    • If true, retarget the camera to look at the focus node

  • shouldResetVelocities Boolean? - Default value: true

    • If true, reset the camera velocities so that the camera stops after its done retargeting (or immediately if retargeting is not done)

Return type: void

Signature
openspace.navigation.setFocus(identifier, shouldRetarget, shouldResetVelocities)

setNavigationState

Set the camera position from a provided NavigationState.

Parameters

  • navigationState Table

    • a table describing the NavigationState to set

  • useTimeStamp Boolean? - Default value: false

    • if true, and the provided NavigationState includes a timestamp, the time will be set as well

Return type: void

Signature
openspace.navigation.setNavigationState(navigationState, useTimeStamp)

targetNextInterestingAnchor

Picks the next node from the interesting nodes out of the profile and selects that. If the current anchor is not an interesting node, the first node in the list will be selected.

Return type: void

Signature
openspace.navigation.targetNextInterestingAnchor()

targetPreviousInterestingAnchor

Picks the previous node from the interesting nodes out of the profile and selects that. If the current anchor is not an interesting node, the first node in the list will be selected.

Return type: void

Signature
openspace.navigation.targetPreviousInterestingAnchor()

triggerIdleBehavior

Immediately start applying the chosen IdleBehavior. If none is specified, use the one set to default in the OrbitalNavigator.

Parameters

  • choice String? - Default value: ""

Return type: void

Signature
openspace.navigation.triggerIdleBehavior(choice)

zoomToDistance

Fly linearly to a specific distance in relation to the focus node.

Parameters

  • distance Number

    • The distance to fly to, in meters above the bounding sphere.

  • duration Number?

    • An optional duration for the motion to take, in seconds.

Return type: void

Signature
openspace.navigation.zoomToDistance(distance, duration)

zoomToDistanceRelative

Fly linearly to a specific distance in relation to the focus node, given as a relative value based on the size of the object rather than in meters.

Parameters

  • distance Number

    • The distance to fly to, given as a multiple of the bounding sphere of the current focus node bounding sphere. A value of 1 will result in a position at a distance of one times the size of the bounding sphere away from the object.

  • duration Number?

    • An optional duration for the motion, in seconds.

Return type: void

Signature
openspace.navigation.zoomToDistanceRelative(distance, duration)

zoomToFocus

Zoom linearly to the current focus node, using the default distance.

Parameters

  • duration Number?

    • An optional duration for the motion to take, in seconds. For example, a value of 5 means “zoom in over 5 seconds”

Return type: void

Signature
openspace.navigation.zoomToFocus(duration)