From a527054c462aa5c39ed72192ecb194e5eb7d7685 Mon Sep 17 00:00:00 2001 From: Emma Broman Date: Wed, 2 Sep 2026 17:09:27 +0200 Subject: [PATCH 1/8] Update camera paths page and start working on the page about scripting --- .../navigation/camera-paths-scripting.md | 116 ++++++++++++++++++ using-openspace/navigation/camera-paths.md | 90 ++++++++------ .../navigation/cancel-flight-button.png | Bin 0 -> 5102 bytes 3 files changed, 169 insertions(+), 37 deletions(-) create mode 100644 using-openspace/navigation/camera-paths-scripting.md create mode 100644 using-openspace/navigation/cancel-flight-button.png diff --git a/using-openspace/navigation/camera-paths-scripting.md b/using-openspace/navigation/camera-paths-scripting.md new file mode 100644 index 0000000..b00683f --- /dev/null +++ b/using-openspace/navigation/camera-paths-scripting.md @@ -0,0 +1,116 @@ +# Creating Camera Paths Using Scripting + +The Scripting API includes functions for creating camera paths to specific positions and for providing more detailed fly-to behavior. This page gives an overview of the available functions and som tips on how to use them. + +Before reading this page, we recommend to first read the [Settings](#camera-paths-settings) part of the [Camera Paths](camera-paths) page, which explains the different available path types and settings. + +For the most up-to-date information on available functions and how they work, see the `openspace.navigation` and `openspace.pathnavigation` parts of the [Scripting API Reference](/reference/scripting-api/index). + +## Fly to a Target +To fly to a target using the scripting API, you can use the `openspace.navigation.flyTo` function. This function takes a single parameter, which is the name of the target node in the scene graph. The target node must have a valid bounding sphere for the fly-to to work correctly. + +```lua +openspace.navigation.flyTo("Earth") +``` + +## Flying to a Specific Position or Height + +There are a few available functions for flying to a specific position or height in relation to a scene graph node. + +| Function | Description | +| -------- | ----------- | +| [`openspace.navigation.flyToHeight`](#navigationflytoheight-target) | Fly to a specific height above a scene graph node. | +| [`openspace.navigation.flyToGeo`](#navigationflytogeo-target) | Fly to a latitude/longitude/altitude target relative to a scene graph node. The node is often a globe (for example Earth), but it can also be any other node. | +| [`openspace.navigation.flyToNavigationState`](#navigationflytonavigationstate-target) | Fly to a specific [NavigationState](#core-navigation-state). Note that the timestamp will not be used in the fly-to operation, and you need to make sure that the simulation time is set correctly for the behavior you expect. | + +For all of these, it is also possible to some specify additional parameters such as the duration of the path and the up-direction of the target node. See code examples using Lua below. + +```lua +-- Fly to a specific height above a scene graph node +openspace.navigation.flyToHeight("Earth", 100000) + +-- Fly to a specific height above a scene graph node using the up-direction of the reference node and parameters +openspace.navigation.flyToHeight("Earth", 100000, true) + +-- Fly to a specific height above a scene graph node with a specified duration (5 seconds ) +openspace.navigation.flyToHeight("Earth", 100000, 5.0) +``` + +```lua +-- Fly to a latitude, longitude, altitude position relative to Earth +openspace.navigation.flyToGeo("Earth", 45.0, -120.0, 10000) + +-- Fly to a latitude, longitude, altitude position relative to Earth, using the +-- up-direction of the reference node and a specified duration (5 seconds) +openspace.navigation.flyToGeo("Earth", 45.0, -120.0, 10000, true, 5.0) +``` + +```lua +-- Fly to a specific navigation state +-- Note that the timestamp will not be used in the fly-to, but is included here for context +openspace.navigation.flyToNavigationState({ + Up = { -0.3381334006389302, 0.8719917989296857, 0.35397189997473527 }, + Position = { -1205410.4887627328, 941781.8267593941, -3471506.006929062 }, + Anchor = "Mars", + Timestamp = "2026 SEP 01 14:57:06" +}) +``` + +:::{admonition} Enable roll for correct up-direction +For the up-direction to be correct when using the up-direction of the target or a navigation state, the {menuselection}`Navigation handler -> Path Navigator -> Include roll` setting must be enabled. Otherwise, the camera will not have the correct orientation when reaching the target state. +::: + +## Instant Flight (Jump) +There are also "jump-to" versions for some of the navigation functions. These move the camera instantly, using a fading transition, rather than a continuous motion. Examples are [`openspace.navigation.jumpTo`](#navigationjumpto-target), [`openspace.navigation.jumpToGeo`](#navigationjumptogeo-target), and [`openspace.navigation.jumpToNavigationState`](#navigationjumptonavigationstate-target). + +## More Customized Camera Paths + +The most flexible way to create a camera path is to use the [`openspace.pathnavigation.createPath`](#pathnavigationcreatepath-target) function, which lets you create some paths that the other functions cannot be used for. For context, the other functions are convenience wrappers around `createPath` that use default parameter values. + +In a single call, you can define the target position (with varying level of detail), the desired [path type](#about-path-types), and the duration. You can also provide an optional start position and orientation using a [NavigationState](#core-navigation-state), which can be used to create a path from a specific point in space instead of the current camera position. + +The `createPath` function takes a table of parameters that can be used to customize the path, called a [PathInstruction](#core-path-instruction). This lets you create two different types of paths: a path to a position in relation to a scene graph node, or a path to a specific navigation state. For the node option, the target position can be specified in different ways, depending on the level of detail you want to provide. See the [PathInstruction](#core-path-instruction) docuemtnation for more details. + +### Node Target + +Below are some examples of a path to a position in relation to a scene graph node is shown below: + +```lua +-- Create a path to the Earth node, with a duration of 5 seconds +openspace.pathnavigation.createPath({ + TargetType = "Node", + Target = "Earth", + Duration = 5.0 +}) + +-- Create a path to a position 1,000,000 meters above the Earth node, with North +-- as the up-direction +openspace.pathnavigation.createPath({ + TargetType = "Node", + Target = "Earth", + Height = 1000000, + UseTargetUpDirection = true +}) + +-- Create a path from a given start position, to Earth, using a zoom-out effect, over 5 seconds +openspace.pathnavigation.createPath({ + TargetType = "Node", + Target = "Earth", + StartState = { ... }, -- The navigation state to start from + PathType = "ZoomOutOverview", + Duration = 5.0 +}) +``` + +### Navigation State Target + +When it comes to creating a path to a specific navigation state, most of the functionality is available through `openspace.navigation.flyToNavigationState` function. However, the `createPath` function can for example be used to include a specific start position and orientation, which is not possible with `flyToNavigationState`. An example of this is shown below: + +```lua +openspace.pathnavigation.createPath({ + TargetType = "NavigationState", + NavigationState = { ... }, -- The navigation state to fly to + StartState = { ... }, -- The navigation state to start from + Duration = 5.0 -- Other options, such as duration, can also be specified +}) +``` \ No newline at end of file diff --git a/using-openspace/navigation/camera-paths.md b/using-openspace/navigation/camera-paths.md index b6d987a..e83b877 100644 --- a/using-openspace/navigation/camera-paths.md +++ b/using-openspace/navigation/camera-paths.md @@ -1,61 +1,77 @@ -# PathNavigation - Simplifying navigation in OpenSpace -As of version 0.18.0, OpenSpace includes a system that simplifies navigation by automatically steering the camera to a desired target. Note that the system is *experimental* and will be subject to change in the future, but it is still useful to reduce the amount of manual navigation needed to control OpenSpace. +# Automatic Flight Paths +OpenSpace includes a system that automatically steers the camera to a target object or position. It reduces the amount of manual navigation needed when moving between objects in the scene. -The system is based on a thesis work by Ingela Rossing and Emma Broman, done in 2020. +The system is based on a thesis work by Ingela Rossing and Emma Broman, done in 2020, and has continued to evolve in later OpenSpace releases. -## Flying to a target -The navigation menu in OpenSpace now includes the possibility to fly to a target, by clicking the airplane button that appears when hovering over an item in the list. The camera will move in a smooth motion to a position where the selected target is focused in view. If the Sun is included in the scene, the system will try to find a sunlit position on the object. It will also try to reduce the risk of collisions with other objects in the scene. +## Flying to a Target +The Navigation menu includes a fly-to action for targets in the list. Click one of the icons listed below to start an automatic camera path to that target. The same options are also avialble in the context menu for focusable nodes in the Scene menu. -In addition to the fly-to button, the current focus node also has "refocus" button. This triggers a linear motion and rotation to center the object in view. +| Icon | Name | Description | +| ---- | ------ | ----------- | +| ![Fly-to icon](flyto_icon.png) | Fly-to | Fly to the target using the current default *path type*, see [below](#about-path-types) | +| ![Refocus icon](refocus_icon.png) | Zoom-to / Frame | Linear motion to center the target in view | -![Refocus icon](refocus_icon.png) - Refocus (linear motion to center the target in view) +The path system determines the route based on the current situation and the selected path type (see below). By default, it tries to: -![Refocus icon](flyto_icon.png) - Fly-to (fly using current default path type, see below) + - Move the camera smoothly to a useful viewing position, approaching the target from a reasonable direction + - Avoid collisions with scene objects when relevant + - Prefer a sunlit position if the Sun is part of the scene -When a path is playing, the Focus menu button changes to a button that can be used to cancel the path. The button also indicates which the current anchor node is. This will be the focus if a path is aborted. +## Aborting a Path +:::{image} cancel-flight-button.png +:alt: Cancel button in the toolbar menu +:align: right +::: -## Path types -The shape of the resulting path depends on the currently selected *path type*. The default type, called `AvoidCollision`, avoids collisions with objects in the scene and tries to rotate the camera as little as possible to avoid creating disorienting rotations. It works well when flying between two targets, like planets, where both of the objects are centered in view. However, since it does not rotate the camera more than necessary it does not work very well when the object we're departing from is not centered in view; for example, from a position on a surface where we are looking a the horizon. In these cases, the `ZoomOutOverview` path type might give a better result. That path type tries to keep targetted nodes in view when leaving/approaching the node. As a consequece it gives a better understanding of the spatial relation, but might introduce fast rotations if not used with care - -See Settings section for more details on path types and how to change the default choice. - -### Linear paths -For the "refocus" button, a linear path is used. The camera will then fly in a straight line to the targeted object. This is also the case for any situation that the camera path system might find "troublesome", for example when the path is very long or when the camera starts from a position inside the bounding sphere of the target object. +A camera path can be aborted at any time by clicking the cancel button in the toolbar menu, which appears when a path is playing. This button also shows the current anchor node, which becomes the focus if a path if the path is aborted. +## Caveats +The path system has some limitations that are good to be aware of: + - Simulation time is paused when a path starts and resumed when it finishes. For best results, pause time manually or use a slow simulation speed before starting a path. + - If the distance traveled is very far, or if the camera starts inside the target's bounding sphere, a linear path is often used instead of the default type. An info message is shown in the log when this happens. + - The system assumes that all fly-to targets have a valid bounding sphere. Missing bounding sphere data can lead to unexpected behavior. +(camera-paths-settings)= ## Settings -The `PathNavigator` settings are found under `NavigationHandler` in the settings menu and include some other properties to control how a path is being played/created. Some properties that are good to know about are: +The settings for the gerenated camera paths can be found in the settings menu under {menuselection}`Navigation handler --> Path Navigator`. Some useful settings are: | Property | Description | | -------- | ----------- | -| `DefaultPathType` | The type of path that is going to be created when generating a path (see next table) | -| `SpeedScale` | Can be used to increase or decrease the traversal speed | -| `ArrivalDistanceFactor` | Decides how far away from a target object the camera should stop. The factor will be multiplied with the bounding sphere of the node and the resulting distance is used to compute the target position when a path is created. | -| `ApplyIdleMotionOnFinish` | If checked, the currently chosen [Idle Motion](idle-motion) is triggered when the path is finished. Can be used to automatically start a rotation around the target when arriving. | -| `RelevantNodeTags` | A list of tags of nodes that is relevant for the path generation. Used for example when computing collisions. | -| `IncludeRoll` | If false, any rolling rotation is removed from the rotation interpolation. Useful in situations where rolling motions can be uncomfortable for the user. OBS! Disabled per default, and we do not recommend turning it on for any paths apart from the `AvoidCollision` and `Linear`, since it might cause uncomfortable rotations. | +| {menuselection}`Default path type` | The path type that is used when generating a new fly-to path. | +| {menuselection}`Speed scale` | Can be used to increase or decrease the traversal speed. | +| {menuselection}`Arrival distance factor` | Determines how far from the target the camera should stop. The factor is multiplied by the target's bounding sphere to compute the final arrival distance. | +| {menuselection}`Apply idle motion on finish` | If enabled, the selected [Idle Motion](idle-motion) starts when the path finishes. This can be used to begin a rotation around the target automatically. | +| {menuselection}`Relevant node tags` | Tags used to identify nodes that are relevant for path generation and collision handling. Try changing this if the camera is colliding with objects in your scene. | +| {menuselection}`Include roll` | If false, any roll is removed from the rotation interpolation. This is disabled by default as it might introduce fast rotations that are unconfortable for a viewer. You might however want to enable this if you need the camera to have a specific orientation at the end of the path, such as when flying to a navigation state. | + +### About Path Types +The resulting path depends on the selected *path type*. The default type, `AvoidCollision`, avoids nearby objects and rotates the camera as little as possible. It works well when moving between targets that are already centered in view. -Short description of the different available path types (as of version 0.18.0): +If the starting view is not centered on the object being left, `ZoomOutOverview` can be a better choice. It tries to keep the relevant target in view for as long as possible and gives a better sense of the spatial relation between objects, but it may introduce stronger rotations. + +Here is a short description of the different available path type options: | Path type | Description | | --------- | ----------- | -| AvoidCollision (default) | Does some simple collision avoidance with close scene graph nodes, but otherwise goes reasonably straightly to the target. Linear interpolation (SLERP) of the rotation. That is, does not try to look at the targeted objects. Works well when flying between objects in the scene, as long as the objects are centered in view at the start and end. | -| ZoomOutOverview | First moves the camera out to a point where both targets are in view, before approaching the desired targets. Provides a better sense of how far away the objects are in relation to each other. Tries to look at either of the targets for as long as possible. However, no collision detection is done. | -| Linear | Just a linear path from the start to end point | -| AvoidCollisionWithLookAt | *Temporary* type that is useful when moving to objects on the same surface, but sometimes leads to fast undesired rotations when traveling between objects. Avoids collision, and looks at the targets as much as possible. | - -For now, the desired path type must be chosen using the `PathNavigator.DefaultPathType` property. Down the line, the system should be able to determine what type to use based on the current situation. Please note that the path types will likely change in future releases of the software. +| `AvoidCollision` (default) | Avoids nearby scene graph nodes and follows a mostly direct path to the target. Uses spherical interpolation of rotation and does not actively keep the target centered. Works well when both the start and end views are already reasonable. | +| `ZoomOutOverview` | Moves the camera out to a point where the relevant targets are visible, then approaches the destination. Gives a better overview of the spatial relation between objects. No collision detection is performed. | +| `Linear` | A straight-line path from the start point to the end point. | +| `AvoidCollisionWithLookAt` | A temporary type that avoids collisions while trying to keep the target in view as much as possible. It can produce fast rotations in some situations. | +For now, the desired path type must be chosen using the {menuselection}`Path Navigator -> Default path type` setting. In the future, the system may choose the path type automatically based on the current situation. The available path types may still change in later releases. -## Caveats - - If the distance traveled is very far (such as outside of the solar system), or if the camera starts within the bounding sphere on an object, a linear path will often be used instead of the default type. An info message is shown in the log when this happens. - - The simulation time will be paused when a path is started, and unpaused again when it is finished. This can lead to some weird/unexpected behavior for larger simulation speeds and we recommend to pause the time before starting the path (or at least using a slow simulation speed). - - The system assumes that all objects that we fly to have a valid bounding sphere. If a target does not, it can lead to some weird behavior. +:::{note} +The linear path type is also used as a fallback when the system cannot find a suitable path using the other types. This can happen if the path is very long or if the camera starts inside the target's bounding sphere. In these cases, a linear path is used to ensure that the camera reaches the target without issues related to risks of numerical instability or other issues. +::: +## Scripting +The path system can also be controlled using the scripting API, which also allows for more complex and customized camera movements such as flying to specific positions. The available functions are described in the [Camera Paths Using Scripting](camera-paths-scripting) page. -## Creating paths through Lua Scripting -The Lua API now also includes functions to create camera paths to specific positions, and to provide more details when flying to a target. +:::{toctree} +:maxdepth: 1 +:hidden: -More info on this is coming to another wiki page, soon! (Emma Broman, 2022-04-13) +camera-paths-scripting +::: diff --git a/using-openspace/navigation/cancel-flight-button.png b/using-openspace/navigation/cancel-flight-button.png new file mode 100644 index 0000000000000000000000000000000000000000..79a3499853316e1ca3137f9e5e11d69fc6ec2717 GIT binary patch literal 5102 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 Date: Wed, 2 Sep 2026 17:27:52 +0200 Subject: [PATCH 2/8] Update broken links and add make some more updates --- .../navigation/camera-paths-scripting.md | 47 ++++++++++++++----- 1 file changed, 35 insertions(+), 12 deletions(-) diff --git a/using-openspace/navigation/camera-paths-scripting.md b/using-openspace/navigation/camera-paths-scripting.md index b00683f..38b8d56 100644 --- a/using-openspace/navigation/camera-paths-scripting.md +++ b/using-openspace/navigation/camera-paths-scripting.md @@ -2,10 +2,12 @@ The Scripting API includes functions for creating camera paths to specific positions and for providing more detailed fly-to behavior. This page gives an overview of the available functions and som tips on how to use them. -Before reading this page, we recommend to first read the [Settings](#camera-paths-settings) part of the [Camera Paths](camera-paths) page, which explains the different available path types and settings. - For the most up-to-date information on available functions and how they work, see the `openspace.navigation` and `openspace.pathnavigation` parts of the [Scripting API Reference](/reference/scripting-api/index). +:::{note} +Before reading this page, you should first have a look at the [Settings](#camera-paths-settings) part of the [Camera Paths](camera-paths) page, which explains the different available path types and settings. +::: + ## Fly to a Target To fly to a target using the scripting API, you can use the `openspace.navigation.flyTo` function. This function takes a single parameter, which is the name of the target node in the scene graph. The target node must have a valid bounding sphere for the fly-to to work correctly. @@ -13,26 +15,46 @@ To fly to a target using the scripting API, you can use the `openspace.navigatio openspace.navigation.flyTo("Earth") ``` +It is also possible to specify how long the fly-to should take, and whether the up-direction of the target node should be accounted for when determining the camera orientation at the end of the path. +```lua +-- Fly to a target node with a specified duration (5 seconds) +openspace.navigation.flyTo("Earth", 5.0) + +-- Fly to a target node using the up-direction of the target node computing the +-- target orientation at the end of the path +openspace.navigation.flyTo("Earth", true) + +-- Fly to a target node using the up-direction of the target node, with a +-- specified duration (5 seconds) +openspace.navigation.flyTo("Earth", 5.0, true) +``` + +:::{admonition} Enable roll for correct up-direction +For the up-direction to be correct when using the up-direction of the target, the {menuselection}`Navigation handler -> Path Navigator -> Include roll` setting must be enabled. Otherwise, the camera will not have the correct orientation when reaching the target state. +::: + ## Flying to a Specific Position or Height -There are a few available functions for flying to a specific position or height in relation to a scene graph node. +There are a few available functions for flying to a specific position or height in relation to a scene graph node: | Function | Description | | -------- | ----------- | | [`openspace.navigation.flyToHeight`](#navigationflytoheight-target) | Fly to a specific height above a scene graph node. | | [`openspace.navigation.flyToGeo`](#navigationflytogeo-target) | Fly to a latitude/longitude/altitude target relative to a scene graph node. The node is often a globe (for example Earth), but it can also be any other node. | -| [`openspace.navigation.flyToNavigationState`](#navigationflytonavigationstate-target) | Fly to a specific [NavigationState](#core-navigation-state). Note that the timestamp will not be used in the fly-to operation, and you need to make sure that the simulation time is set correctly for the behavior you expect. | +| [`openspace.navigation.flyToNavigationState`](#navigationflytonavigationstate-target) | Fly to a specific [NavigationState](#core_navigationstate). Note that the timestamp will not be used in the fly-to operation, and you need to make sure that the simulation time is set correctly for the behavior you expect. | -For all of these, it is also possible to some specify additional parameters such as the duration of the path and the up-direction of the target node. See code examples using Lua below. +For all of these, it is also possible to some specify additional parameters such as the duration of the path and the up-direction of the target node. Below are some examples ```lua -- Fly to a specific height above a scene graph node openspace.navigation.flyToHeight("Earth", 100000) --- Fly to a specific height above a scene graph node using the up-direction of the reference node and parameters +-- Fly to a specific height above a scene graph node using the up-direction of +-- the reference node and parameters openspace.navigation.flyToHeight("Earth", 100000, true) --- Fly to a specific height above a scene graph node with a specified duration (5 seconds ) +-- Fly to a specific height above a scene graph node with a specified duration +-- (5 seconds) openspace.navigation.flyToHeight("Earth", 100000, 5.0) ``` @@ -46,8 +68,9 @@ openspace.navigation.flyToGeo("Earth", 45.0, -120.0, 10000, true, 5.0) ``` ```lua --- Fly to a specific navigation state --- Note that the timestamp will not be used in the fly-to, but is included here for context +-- Fly to a specific navigation state. Note that the timestamp will not be used +-- in the fly-to, but is included here for context as it will be saved in the +-- navigation state. openspace.navigation.flyToNavigationState({ Up = { -0.3381334006389302, 0.8719917989296857, 0.35397189997473527 }, Position = { -1205410.4887627328, 941781.8267593941, -3471506.006929062 }, @@ -65,11 +88,11 @@ There are also "jump-to" versions for some of the navigation functions. These mo ## More Customized Camera Paths -The most flexible way to create a camera path is to use the [`openspace.pathnavigation.createPath`](#pathnavigationcreatepath-target) function, which lets you create some paths that the other functions cannot be used for. For context, the other functions are convenience wrappers around `createPath` that use default parameter values. +The most flexible way to create a camera path is to use the [`openspace.pathnavigation.createPath`](#pathnavigationcreatepath-target) function, which lets you create some paths that the other functions cannot be used for. For context, the other functions are convenience wrappers around `createPath` that use default parameter values. Note that the `createPath` function is located in the `openspace.pathnavigation` sublibrary, while the other functions are located in the `openspace.navigation` sublibrary. -In a single call, you can define the target position (with varying level of detail), the desired [path type](#about-path-types), and the duration. You can also provide an optional start position and orientation using a [NavigationState](#core-navigation-state), which can be used to create a path from a specific point in space instead of the current camera position. +In a single call, you can define the target position (with varying level of detail), the desired [path type](./camera-paths.md#about-path-types), and the duration. You can also provide an optional start position and orientation using a [NavigationState](#core_navigationstate), which can be used to create a path from a specific point in space instead of the current camera position. -The `createPath` function takes a table of parameters that can be used to customize the path, called a [PathInstruction](#core-path-instruction). This lets you create two different types of paths: a path to a position in relation to a scene graph node, or a path to a specific navigation state. For the node option, the target position can be specified in different ways, depending on the level of detail you want to provide. See the [PathInstruction](#core-path-instruction) docuemtnation for more details. +The `createPath` function takes a table of parameters that can be used to customize the path, called a [PathInstruction](#core_path_instruction). This lets you create two different types of paths: a path to a position in relation to a scene graph node, or a path to a specific navigation state. For the node option, the target position can be specified in different ways, depending on the level of detail you want to provide. See the [PathInstruction](#core_path_instruction) docuemtnation for more details. ### Node Target From 44462ecd0be2f7eee97d5e274579528434f5c3c5 Mon Sep 17 00:00:00 2001 From: Emma Broman Date: Wed, 2 Sep 2026 17:46:16 +0200 Subject: [PATCH 3/8] Add info on utility function and note that camera paths are under development. Add development to both pages --- .../navigation/camera-paths-scripting.md | 17 ++++++++++++++++- using-openspace/navigation/camera-paths.md | 8 ++++++++ 2 files changed, 24 insertions(+), 1 deletion(-) diff --git a/using-openspace/navigation/camera-paths-scripting.md b/using-openspace/navigation/camera-paths-scripting.md index 38b8d56..ee349d7 100644 --- a/using-openspace/navigation/camera-paths-scripting.md +++ b/using-openspace/navigation/camera-paths-scripting.md @@ -136,4 +136,19 @@ openspace.pathnavigation.createPath({ StartState = { ... }, -- The navigation state to start from Duration = 5.0 -- Other options, such as duration, can also be specified }) -``` \ No newline at end of file +``` + +## Utility Functions +The scripting API also includes some utility functions for working with camera paths when scripting. These can be used to check if a path is currently playing, to cancel a path, or to get the current path progress. + +The most commonly used function lives in the [`openspace.navigation`](/reference/scripting-api/openspace.navigation) sublibrary, and is called [`openspace.navigation.isFlying()`](#navigationisflying-target). It can be used to check if a path is currently playing. + +A number of other functions can be found in the [`openspace.pathnavigation`](/reference/scripting-api/openspace.pathnavigation) sublibrary, including functions for aborting a path or pausing it during playback, for example. + +## The Camera Paths are Under Development + +The camera path system is still under development, and the available functions and their behavior may change in future releases. If you interested in the camera path system and plans for the development, feel free to check the [currently open issues related to camera paths](https://github.com/OpenSpace/OpenSpace/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22Feature%3A%20Camera%20Paths%22) on Github. + +:::{important} +Many of the features described here are also considered experimental, and may not work as expected in all situations. If you encounter any issues, or have ideas for improvement, please report them on Github or contact the OpenSpace team. +::: diff --git a/using-openspace/navigation/camera-paths.md b/using-openspace/navigation/camera-paths.md index e83b877..076c1e1 100644 --- a/using-openspace/navigation/camera-paths.md +++ b/using-openspace/navigation/camera-paths.md @@ -75,3 +75,11 @@ The path system can also be controlled using the scripting API, which also allow camera-paths-scripting ::: + +## The Camera Paths are Under Development + +The camera path system is still under development, and the available functions and their behavior may change in future releases. If you interested in the camera path system and plans for the development, feel free to check the [currently open issues related to camera paths](https://github.com/OpenSpace/OpenSpace/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22Feature%3A%20Camera%20Paths%22) on Github. + +:::{important} +Many of the features described here are also considered experimental, and may not work as expected in all situations. If you encounter any issues, or have ideas for improvement, please report them on Github or contact the OpenSpace team. +::: From b4f0fa7211d89e7ac30437e6aa150c21c0b4f458 Mon Sep 17 00:00:00 2001 From: Emma Broman Date: Wed, 2 Sep 2026 17:54:11 +0200 Subject: [PATCH 4/8] Update the camera path is under development to include common recommendation --- using-openspace/navigation/camera-paths-scripting.md | 6 +++++- using-openspace/navigation/camera-paths.md | 6 +++++- 2 files changed, 10 insertions(+), 2 deletions(-) diff --git a/using-openspace/navigation/camera-paths-scripting.md b/using-openspace/navigation/camera-paths-scripting.md index ee349d7..9753f6a 100644 --- a/using-openspace/navigation/camera-paths-scripting.md +++ b/using-openspace/navigation/camera-paths-scripting.md @@ -150,5 +150,9 @@ A number of other functions can be found in the [`openspace.pathnavigation`](/re The camera path system is still under development, and the available functions and their behavior may change in future releases. If you interested in the camera path system and plans for the development, feel free to check the [currently open issues related to camera paths](https://github.com/OpenSpace/OpenSpace/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22Feature%3A%20Camera%20Paths%22) on Github. :::{important} -Many of the features described here are also considered experimental, and may not work as expected in all situations. If you encounter any issues, or have ideas for improvement, please report them on Github or contact the OpenSpace team. +The generated camera paths are considered experimental and may not work as expected in all situations. They have primarily been calibrated to create nice flights between different scene graph nodes, and may not work as well for more complex camera scenarios such as navigation states, for example. + +If you are relying on camera paths for a specific use case, we recommend testing them thoroughly to ensure that they work as expected. In sensitive situations, it may be better to use the session recording system to create a recorded path that is guaranteed to work as expected. + +If you encounter any issues, or have ideas for improvement, please report them on Github or contact the OpenSpace team. ::: diff --git a/using-openspace/navigation/camera-paths.md b/using-openspace/navigation/camera-paths.md index 076c1e1..92a77dd 100644 --- a/using-openspace/navigation/camera-paths.md +++ b/using-openspace/navigation/camera-paths.md @@ -81,5 +81,9 @@ camera-paths-scripting The camera path system is still under development, and the available functions and their behavior may change in future releases. If you interested in the camera path system and plans for the development, feel free to check the [currently open issues related to camera paths](https://github.com/OpenSpace/OpenSpace/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22Feature%3A%20Camera%20Paths%22) on Github. :::{important} -Many of the features described here are also considered experimental, and may not work as expected in all situations. If you encounter any issues, or have ideas for improvement, please report them on Github or contact the OpenSpace team. +The generated camera paths are considered experimental and may not work as expected in all situations. They have primarily been calibrated to create nice flights between different scene graph nodes, and may not work as well for more complex camera scenarios, such as close to planetary surfaces or for flying between certain navigation states. + +If you are relying on camera paths for a specific use case, we recommend testing them thoroughly to ensure that they work as expected. In sensitive situations, it may be better to use the session recording system to create a recorded path that is guaranteed to work as expected. + +If you encounter any issues, or have ideas for improvement, please report them on Github or contact the OpenSpace team. ::: From 8d7a026273d566950c83482257a449d46b85d11b Mon Sep 17 00:00:00 2001 From: Emma Broman Date: Thu, 3 Sep 2026 08:53:41 +0200 Subject: [PATCH 5/8] Apply batched suggestions from code review Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- using-openspace/navigation/camera-paths-scripting.md | 8 ++++---- using-openspace/navigation/camera-paths.md | 6 +++--- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/using-openspace/navigation/camera-paths-scripting.md b/using-openspace/navigation/camera-paths-scripting.md index 9753f6a..0d4f3b2 100644 --- a/using-openspace/navigation/camera-paths-scripting.md +++ b/using-openspace/navigation/camera-paths-scripting.md @@ -1,6 +1,6 @@ # Creating Camera Paths Using Scripting -The Scripting API includes functions for creating camera paths to specific positions and for providing more detailed fly-to behavior. This page gives an overview of the available functions and som tips on how to use them. +The Scripting API includes functions for creating camera paths to specific positions and for providing more detailed fly-to behavior. This page gives an overview of the available functions and some tips on how to use them. For the most up-to-date information on available functions and how they work, see the `openspace.navigation` and `openspace.pathnavigation` parts of the [Scripting API Reference](/reference/scripting-api/index). @@ -92,11 +92,11 @@ The most flexible way to create a camera path is to use the [`openspace.pathnavi In a single call, you can define the target position (with varying level of detail), the desired [path type](./camera-paths.md#about-path-types), and the duration. You can also provide an optional start position and orientation using a [NavigationState](#core_navigationstate), which can be used to create a path from a specific point in space instead of the current camera position. -The `createPath` function takes a table of parameters that can be used to customize the path, called a [PathInstruction](#core_path_instruction). This lets you create two different types of paths: a path to a position in relation to a scene graph node, or a path to a specific navigation state. For the node option, the target position can be specified in different ways, depending on the level of detail you want to provide. See the [PathInstruction](#core_path_instruction) docuemtnation for more details. +The `createPath` function takes a table of parameters that can be used to customize the path, called a [PathInstruction](#core_path_instruction). This lets you create two different types of paths: a path to a position in relation to a scene graph node, or a path to a specific navigation state. For the node option, the target position can be specified in different ways, depending on the level of detail you want to provide. See the [PathInstruction](#core_path_instruction) documentation for more details. ### Node Target -Below are some examples of a path to a position in relation to a scene graph node is shown below: +Below are some examples of paths to positions in relation to a scene graph node: ```lua -- Create a path to the Earth node, with a duration of 5 seconds @@ -147,7 +147,7 @@ A number of other functions can be found in the [`openspace.pathnavigation`](/re ## The Camera Paths are Under Development -The camera path system is still under development, and the available functions and their behavior may change in future releases. If you interested in the camera path system and plans for the development, feel free to check the [currently open issues related to camera paths](https://github.com/OpenSpace/OpenSpace/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22Feature%3A%20Camera%20Paths%22) on Github. +The camera path system is still under development, and the available functions and their behavior may change in future releases. If you are interested in the camera path system and plans for its development, feel free to check the [currently open issues related to camera paths](https://github.com/OpenSpace/OpenSpace/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22Feature%3A%20Camera%20Paths%22) on GitHub. :::{important} The generated camera paths are considered experimental and may not work as expected in all situations. They have primarily been calibrated to create nice flights between different scene graph nodes, and may not work as well for more complex camera scenarios such as navigation states, for example. diff --git a/using-openspace/navigation/camera-paths.md b/using-openspace/navigation/camera-paths.md index 92a77dd..fc0d8ea 100644 --- a/using-openspace/navigation/camera-paths.md +++ b/using-openspace/navigation/camera-paths.md @@ -5,7 +5,7 @@ The system is based on a thesis work by Ingela Rossing and Emma Broman, done in ## Flying to a Target -The Navigation menu includes a fly-to action for targets in the list. Click one of the icons listed below to start an automatic camera path to that target. The same options are also avialble in the context menu for focusable nodes in the Scene menu. +The Navigation menu includes a fly-to action for targets in the list. Click one of the icons listed below to start an automatic camera path to that target. The same options are also available in the context menu for focusable nodes in the Scene menu. | Icon | Name | Description | | ---- | ------ | ----------- | @@ -25,7 +25,7 @@ The path system determines the route based on the current situation and the sele :align: right ::: -A camera path can be aborted at any time by clicking the cancel button in the toolbar menu, which appears when a path is playing. This button also shows the current anchor node, which becomes the focus if a path if the path is aborted. +A camera path can be aborted at any time by clicking the cancel button in the toolbar menu, which appears when a path is playing. This button also shows the current anchor node, which becomes the focus if a path is aborted. ## Caveats The path system has some limitations that are good to be aware of: @@ -78,7 +78,7 @@ camera-paths-scripting ## The Camera Paths are Under Development -The camera path system is still under development, and the available functions and their behavior may change in future releases. If you interested in the camera path system and plans for the development, feel free to check the [currently open issues related to camera paths](https://github.com/OpenSpace/OpenSpace/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22Feature%3A%20Camera%20Paths%22) on Github. +The camera path system is still under development, and the available functions and their behavior may change in future releases. If you are interested in the camera path system and plans for its development, feel free to check the [currently open issues related to camera paths](https://github.com/OpenSpace/OpenSpace/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22Feature%3A%20Camera%20Paths%22) on GitHub. :::{important} The generated camera paths are considered experimental and may not work as expected in all situations. They have primarily been calibrated to create nice flights between different scene graph nodes, and may not work as well for more complex camera scenarios, such as close to planetary surfaces or for flying between certain navigation states. From 78f97aaafd5126de12631ac5e980e0a93e0ff78a Mon Sep 17 00:00:00 2001 From: Emma Broman Date: Thu, 3 Sep 2026 08:58:18 +0200 Subject: [PATCH 6/8] Remove an id that's not really needed --- using-openspace/navigation/camera-paths-scripting.md | 2 +- using-openspace/navigation/camera-paths.md | 1 - 2 files changed, 1 insertion(+), 2 deletions(-) diff --git a/using-openspace/navigation/camera-paths-scripting.md b/using-openspace/navigation/camera-paths-scripting.md index 0d4f3b2..8b75d36 100644 --- a/using-openspace/navigation/camera-paths-scripting.md +++ b/using-openspace/navigation/camera-paths-scripting.md @@ -5,7 +5,7 @@ The Scripting API includes functions for creating camera paths to specific posit For the most up-to-date information on available functions and how they work, see the `openspace.navigation` and `openspace.pathnavigation` parts of the [Scripting API Reference](/reference/scripting-api/index). :::{note} -Before reading this page, you should first have a look at the [Settings](#camera-paths-settings) part of the [Camera Paths](camera-paths) page, which explains the different available path types and settings. +Before reading this page, you should first have a look at the [Settings](camera-paths.md#settings) part of the [Camera Paths](camera-paths) page, which explains the different available path types and settings. ::: ## Fly to a Target diff --git a/using-openspace/navigation/camera-paths.md b/using-openspace/navigation/camera-paths.md index fc0d8ea..1597362 100644 --- a/using-openspace/navigation/camera-paths.md +++ b/using-openspace/navigation/camera-paths.md @@ -33,7 +33,6 @@ The path system has some limitations that are good to be aware of: - If the distance traveled is very far, or if the camera starts inside the target's bounding sphere, a linear path is often used instead of the default type. An info message is shown in the log when this happens. - The system assumes that all fly-to targets have a valid bounding sphere. Missing bounding sphere data can lead to unexpected behavior. -(camera-paths-settings)= ## Settings The settings for the gerenated camera paths can be found in the settings menu under {menuselection}`Navigation handler --> Path Navigator`. Some useful settings are: From 9d5bb558b92e48b855ffdd2692decbd5959bc091 Mon Sep 17 00:00:00 2001 From: Emma Broman Date: Fri, 4 Sep 2026 09:29:20 +0200 Subject: [PATCH 7/8] Apply batched suggestions from code review Co-authored-by: Alexander Bock --- .../navigation/camera-paths-scripting.md | 56 +++++++++---------- using-openspace/navigation/camera-paths.md | 3 +- 2 files changed, 27 insertions(+), 32 deletions(-) diff --git a/using-openspace/navigation/camera-paths-scripting.md b/using-openspace/navigation/camera-paths-scripting.md index 8b75d36..bddbd01 100644 --- a/using-openspace/navigation/camera-paths-scripting.md +++ b/using-openspace/navigation/camera-paths-scripting.md @@ -1,5 +1,4 @@ # Creating Camera Paths Using Scripting - The Scripting API includes functions for creating camera paths to specific positions and for providing more detailed fly-to behavior. This page gives an overview of the available functions and some tips on how to use them. For the most up-to-date information on available functions and how they work, see the `openspace.navigation` and `openspace.pathnavigation` parts of the [Scripting API Reference](/reference/scripting-api/index). @@ -34,7 +33,6 @@ For the up-direction to be correct when using the up-direction of the target, th ::: ## Flying to a Specific Position or Height - There are a few available functions for flying to a specific position or height in relation to a scene graph node: | Function | Description | @@ -70,12 +68,12 @@ openspace.navigation.flyToGeo("Earth", 45.0, -120.0, 10000, true, 5.0) ```lua -- Fly to a specific navigation state. Note that the timestamp will not be used -- in the fly-to, but is included here for context as it will be saved in the --- navigation state. +-- navigation state openspace.navigation.flyToNavigationState({ - Up = { -0.3381334006389302, 0.8719917989296857, 0.35397189997473527 }, - Position = { -1205410.4887627328, 941781.8267593941, -3471506.006929062 }, - Anchor = "Mars", - Timestamp = "2026 SEP 01 14:57:06" + Up = { -0.3381334006389302, 0.8719917989296857, 0.35397189997473527 }, + Position = { -1205410.4887627328, 941781.8267593941, -3471506.006929062 }, + Anchor = "Mars", + Timestamp = "2026 SEP 01 14:57:06" }) ``` @@ -87,66 +85,62 @@ For the up-direction to be correct when using the up-direction of the target or There are also "jump-to" versions for some of the navigation functions. These move the camera instantly, using a fading transition, rather than a continuous motion. Examples are [`openspace.navigation.jumpTo`](#navigationjumpto-target), [`openspace.navigation.jumpToGeo`](#navigationjumptogeo-target), and [`openspace.navigation.jumpToNavigationState`](#navigationjumptonavigationstate-target). ## More Customized Camera Paths - -The most flexible way to create a camera path is to use the [`openspace.pathnavigation.createPath`](#pathnavigationcreatepath-target) function, which lets you create some paths that the other functions cannot be used for. For context, the other functions are convenience wrappers around `createPath` that use default parameter values. Note that the `createPath` function is located in the `openspace.pathnavigation` sublibrary, while the other functions are located in the `openspace.navigation` sublibrary. +The most flexible way to create a camera path is to use the [`openspace.pathnavigation.createPath`](#pathnavigationcreatepath-target) function, which lets you create some paths that the other functions cannot be used for. For context, the other functions are convenience wrappers around `createPath` that use default parameter values. Note that the `createPath` function is located in the `openspace.pathnavigation` library, while the other functions are located in the `openspace.navigation` library. In a single call, you can define the target position (with varying level of detail), the desired [path type](./camera-paths.md#about-path-types), and the duration. You can also provide an optional start position and orientation using a [NavigationState](#core_navigationstate), which can be used to create a path from a specific point in space instead of the current camera position. The `createPath` function takes a table of parameters that can be used to customize the path, called a [PathInstruction](#core_path_instruction). This lets you create two different types of paths: a path to a position in relation to a scene graph node, or a path to a specific navigation state. For the node option, the target position can be specified in different ways, depending on the level of detail you want to provide. See the [PathInstruction](#core_path_instruction) documentation for more details. ### Node Target - Below are some examples of paths to positions in relation to a scene graph node: ```lua -- Create a path to the Earth node, with a duration of 5 seconds openspace.pathnavigation.createPath({ - TargetType = "Node", - Target = "Earth", - Duration = 5.0 + TargetType = "Node", + Target = "Earth", + Duration = 5.0 }) -- Create a path to a position 1,000,000 meters above the Earth node, with North -- as the up-direction openspace.pathnavigation.createPath({ - TargetType = "Node", - Target = "Earth", - Height = 1000000, - UseTargetUpDirection = true + TargetType = "Node", + Target = "Earth", + Height = 1000000, + UseTargetUpDirection = true }) -- Create a path from a given start position, to Earth, using a zoom-out effect, over 5 seconds openspace.pathnavigation.createPath({ - TargetType = "Node", - Target = "Earth", - StartState = { ... }, -- The navigation state to start from - PathType = "ZoomOutOverview", - Duration = 5.0 + TargetType = "Node", + Target = "Earth", + StartState = { ... }, -- The navigation state to start from + PathType = "ZoomOutOverview", + Duration = 5.0 }) ``` ### Navigation State Target - When it comes to creating a path to a specific navigation state, most of the functionality is available through `openspace.navigation.flyToNavigationState` function. However, the `createPath` function can for example be used to include a specific start position and orientation, which is not possible with `flyToNavigationState`. An example of this is shown below: ```lua openspace.pathnavigation.createPath({ - TargetType = "NavigationState", - NavigationState = { ... }, -- The navigation state to fly to - StartState = { ... }, -- The navigation state to start from - Duration = 5.0 -- Other options, such as duration, can also be specified + TargetType = "NavigationState", + NavigationState = { ... }, -- The navigation state to fly to + StartState = { ... }, -- The navigation state to start from + Duration = 5.0 -- Other options, such as duration, can also be specified }) ``` ## Utility Functions The scripting API also includes some utility functions for working with camera paths when scripting. These can be used to check if a path is currently playing, to cancel a path, or to get the current path progress. -The most commonly used function lives in the [`openspace.navigation`](/reference/scripting-api/openspace.navigation) sublibrary, and is called [`openspace.navigation.isFlying()`](#navigationisflying-target). It can be used to check if a path is currently playing. +The most commonly used function lives in the [`openspace.navigation`](/reference/scripting-api/openspace.navigation) library, and is called [`openspace.navigation.isFlying()`](#navigationisflying-target). It can be used to check if a path is currently playing. -A number of other functions can be found in the [`openspace.pathnavigation`](/reference/scripting-api/openspace.pathnavigation) sublibrary, including functions for aborting a path or pausing it during playback, for example. +A number of other functions can be found in the [`openspace.pathnavigation`](/reference/scripting-api/openspace.pathnavigation) library, including functions for aborting a path or pausing it during playback, for example. ## The Camera Paths are Under Development - The camera path system is still under development, and the available functions and their behavior may change in future releases. If you are interested in the camera path system and plans for its development, feel free to check the [currently open issues related to camera paths](https://github.com/OpenSpace/OpenSpace/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22Feature%3A%20Camera%20Paths%22) on GitHub. :::{important} @@ -154,5 +148,5 @@ The generated camera paths are considered experimental and may not work as expec If you are relying on camera paths for a specific use case, we recommend testing them thoroughly to ensure that they work as expected. In sensitive situations, it may be better to use the session recording system to create a recorded path that is guaranteed to work as expected. -If you encounter any issues, or have ideas for improvement, please report them on Github or contact the OpenSpace team. +If you encounter any issues, or have ideas for improvement, please report them on GitHub or contact the OpenSpace team. ::: diff --git a/using-openspace/navigation/camera-paths.md b/using-openspace/navigation/camera-paths.md index 1597362..2dedb42 100644 --- a/using-openspace/navigation/camera-paths.md +++ b/using-openspace/navigation/camera-paths.md @@ -29,6 +29,7 @@ A camera path can be aborted at any time by clicking the cancel button in the to ## Caveats The path system has some limitations that are good to be aware of: + - Simulation time is paused when a path starts and resumed when it finishes. For best results, pause time manually or use a slow simulation speed before starting a path. - If the distance traveled is very far, or if the camera starts inside the target's bounding sphere, a linear path is often used instead of the default type. An info message is shown in the log when this happens. - The system assumes that all fly-to targets have a valid bounding sphere. Missing bounding sphere data can lead to unexpected behavior. @@ -54,7 +55,7 @@ Here is a short description of the different available path type options: | Path type | Description | | --------- | ----------- | -| `AvoidCollision` (default) | Avoids nearby scene graph nodes and follows a mostly direct path to the target. Uses spherical interpolation of rotation and does not actively keep the target centered. Works well when both the start and end views are already reasonable. | +| `AvoidCollision` (default) | Avoids nearby scene graph nodes and follows a mostly direct path to the target. Uses spherical interpolation of rotation and does not actively keep the target centered. Works well when both the start and end views are already valid camera positions. | | `ZoomOutOverview` | Moves the camera out to a point where the relevant targets are visible, then approaches the destination. Gives a better overview of the spatial relation between objects. No collision detection is performed. | | `Linear` | A straight-line path from the start point to the end point. | | `AvoidCollisionWithLookAt` | A temporary type that avoids collisions while trying to keep the target in view as much as possible. It can produce fast rotations in some situations. | From 0ddb59b3da80c9ba0691e9531690779fb420bf17 Mon Sep 17 00:00:00 2001 From: Emma Broman Date: Fri, 4 Sep 2026 09:30:46 +0200 Subject: [PATCH 8/8] Remove extra line under header --- using-openspace/navigation/camera-paths.md | 1 - 1 file changed, 1 deletion(-) diff --git a/using-openspace/navigation/camera-paths.md b/using-openspace/navigation/camera-paths.md index 2dedb42..fbed0af 100644 --- a/using-openspace/navigation/camera-paths.md +++ b/using-openspace/navigation/camera-paths.md @@ -77,7 +77,6 @@ camera-paths-scripting ::: ## The Camera Paths are Under Development - The camera path system is still under development, and the available functions and their behavior may change in future releases. If you are interested in the camera path system and plans for its development, feel free to check the [currently open issues related to camera paths](https://github.com/OpenSpace/OpenSpace/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22Feature%3A%20Camera%20Paths%22) on GitHub. :::{important}