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

getNavigationState

Return the current NavigationState as a Lua table

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

listAllJoysticks

Return the complete list of connected joysticks

loadNavigationState

Set the camera position by loading a NavigationState from file

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

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

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()

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)

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)

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)

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)

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)