mirror/OpenSpace
1
0
Fork 0
mirror of https://github.com/OpenSpace/OpenSpace.git synced 2026-03-09 14:58:37 -05:00
Code Issues Packages Projects Releases Wiki Activity

Utilize new docs functionality in API scripts that are defined in Lua files (#3505)

Browse Source 
* Fix a reference to a deprecated and renamed function in navigationstate docs

* Review documentation for scripts defined in .lua files

And utilize new markdown functionality

* Update renderable box grid size specs

So that it can have a size less than 1, and throws a specification error when the size is given as negative

* Fix some issues with the gaia filtering scripts

* Try adding param documentation to the lua script documentation

It works!

* Utiliize mroe markdown features in the updated documentations

* Add function parameter info and make small updated to gaia filtering functions

* Replace a long parameter info in description with `param` description

* Update usage examples

* Add example of how to create debug axes for the current SGN
This commit is contained in:
Emma Broman
2025-02-11 08:59:33 +01:00
committed by GitHub
parent bc4a137040
commit 1fbd5e827d
8 changed files with 150 additions and 56 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
modules/base/rendering/grids/renderableboxgrid.cpp
View File

@@ -84,7 +84,7 @@ RenderableBoxGrid::RenderableBoxGrid(const ghoul::Dictionary& dictionary)
: Renderable(dictionary)
, _color(ColorInfo, glm::vec3(0.5f), glm::vec3(0.f), glm::vec3(1.f))
, _lineWidth(LineWidthInfo, 0.5f, 1.f, 20.f)
, _size(SizeInfo, glm::vec3(1.f), glm::vec3(1.f), glm::vec3(100.f))
, _size(SizeInfo, glm::vec3(1.f), glm::vec3(0.0001f), glm::vec3(100.f))
{
const Parameters p = codegen::bake<Parameters>(dictionary);

21
modules/debugging/scripts/axes.lua
View File

@@ -7,12 +7,21 @@ openspace.debugging.documentation = {
},
Documentation = [[
Creates a new scene graph node that show the coordinate system used for the
currently selected focus node. The first argument specifies the name of the
scene graph node for which the axes should be added. If this parameter is
not specified, the current focus node is used instead. The second argument
provides the length of the coordinate axis in meters. If this value is not
specified 2.5 times the interaction sphere of the selected node is used
instead.
currently selected focus node, or a specified scene graph node.
Usage:
```lua
-- To add coordinate axes for the currently selected focus node, do not specify any
-- parameters
openspace.debugging.createCoordinateAxes()
```
\\param nodeIdentifier The identifier of the scene graph node for which the axes
should be added. If this parameter is not specified, the
current focus node is used instead.
\\param scale An optional parameter that specifies the size of the coordinate axes,
in meters. If not specified, the size is set to 2.5 times the
interaction sphere of the selected node.
]]
}
}

87
modules/gaia/scripts/filtering.lua
View File

@@ -2,28 +2,58 @@ openspace.gaia.documentation = {
{
Name = "addClippingBox",
Arguments = {
{ "name", "String" },
{ "identifier", "String" },
{ "size", "vec3" },
{ "position", "vec3" }
},
Documentation = "Creates a clipping box for the Gaia renderable in the first argument"
Documentation = [[
Creates a clipping box for a specific Gaia dataset, that can be used to filter out
stars that are outside of the box. The box is visualized as a grid in the scene.
Note that only one clipping box can be active at a time. If a new box is added, the
old one will be removed.
\\param identifier The identifier of the scene graph node with a
[RenderableGaiaStars](#gaiamission_renderablegaiastars) to be
filtered
\\param size The size of each dimension of the box, in Kiloparsec
\\param position The position of the center of the box, specified in galactic
coordinates in Kiloparsec
]]
},
{
Name = "removeClippingBox",
Arguments = {},
Documentation = ""
Documentation = "Remove any added clipping box."
},
{
Name = "addClippingSphere",
Arguments = {
{ "name", "String" },
{ "identifier", "String" },
{ "radius", "Number" }
},
Documentation = "Creates a clipping sphere for the Gaia renderable in the first argument"
Documentation = [[
Creates a clipping sphere for a specific Gaia dataset, that can be used to filter
out stars that are outside of the sphere. The sphere is visualized as a grid in the
scene.
Note that only one clipping sphere can be active at a time. If a new one is added,
the old one will be removed.
\\param identifier The identifier of the scene graph node with a
[RenderableGaiaStars](#gaiamission_renderablegaiastars) to be
filtered
\\param radius The desired radius outside of the clipping sphere, in Kiloparsec
]]
},
{
Name = "removeClippingSphere",
Arguments = {},
Documentation = "Remove any added clipping sphere."
}
}
openspace.gaia.addClippingBox = function (name, size, position)
openspace.gaia.addClippingBox = function (identifier, size, position)
local grid_identifier = "Filtering_Box"
local kilo_parsec_in_meter = 30856775814913700000
@@ -41,6 +71,10 @@ openspace.gaia.addClippingBox = function (name, size, position)
position[2] * kilo_parsec_in_meter,
position[3] * kilo_parsec_in_meter
}
},
Scale = {
Type = "StaticScale",
Scale = kilo_parsec_in_meter
}
},
Renderable = {
@@ -48,9 +82,9 @@ openspace.gaia.addClippingBox = function (name, size, position)
Color = { 0.6, 0.5, 0.7 },
LineWidth = 2.0,
Size = {
size[1] * kilo_parsec_in_meter,
size[2] * kilo_parsec_in_meter,
size[3] * kilo_parsec_in_meter
size[1],
size[2],
size[3]
}
},
GUI = {
@@ -60,18 +94,17 @@ openspace.gaia.addClippingBox = function (name, size, position)
}
openspace.addSceneGraphNode(grid)
openspace.setPropertyValue(
"Scene." .. name .. ".renderable.FilterPosX",
{ (position[1] - size[1] / 2) * kilo_parsec_in_meter, (position[1] + size[1] / 2) * kilo_parsec_in_meter }
openspace.setPropertyValueSingle(
"Scene." .. identifier .. ".Renderable.FilterPosX",
{ (position[1] - size[1] / 2), (position[1] + size[1] / 2) }
)
openspace.setPropertyValue(
"Scene." .. name .. ".renderable.FilterPosY",
{ (position[2] - size[2] / 2) * kilo_parsec_in_meter, (position[2] + size[2] / 2) * kilo_parsec_in_meter }
openspace.setPropertyValueSingle(
"Scene." .. identifier .. ".Renderable.FilterPosY",
{ (position[2] - size[2] / 2), (position[2] + size[2] / 2) }
)
openspace.setPropertyValue(
"Scene." .. name .. ".renderable.FilterPosZ",
{ (position[3] - size[3] / 2) * kilo_parsec_in_meter, (position[3] + size[3] / 2) * kilo_parsec_in_meter }
openspace.setPropertyValueSingle(
"Scene." .. identifier .. ".Renderable.FilterPosZ",
{ (position[3] - size[3] / 2), (position[3] + size[3] / 2) }
)
end
@@ -81,14 +114,16 @@ openspace.gaia.removeClippingBox = function()
if openspace.hasSceneGraphNode(grid_identifier) then
openspace.removeSceneGraphNode(grid_identifier)
end
openspace.setPropertyValue("Scene.*.Renderable.FilterPosX", { 0.0, 0.0 })
openspace.setPropertyValue("Scene.*.Renderable.FilterPosY", { 0.0, 0.0 })
openspace.setPropertyValue("Scene.*.Renderable.FilterPosZ", { 0.0, 0.0 })
end
openspace.gaia.addClippingSphere = function (name, radius)
openspace.gaia.addClippingSphere = function (identifier, radius)
local grid_identifier = "Filtering_Sphere"
local kilo_parsec_in_meter = 30856775814913700000
if openspace.hasSceneGraphNode(grid_identifier) then
openspace.removeSceneGraphNode(grid_identifier)
end
@@ -113,8 +148,10 @@ openspace.gaia.addClippingSphere = function (name, radius)
}
openspace.addSceneGraphNode(grid)
openspace.setPropertyValue("Scene." .. name .. ".renderable.FilterDist", radius * kilo_parsec_in_meter)
openspace.setPropertyValueSingle(
"Scene." .. identifier .. ".Renderable.FilterDist",
{ 0.0, radius }
)
end
openspace.gaia.removeClippingSphere = function()
@@ -123,4 +160,6 @@ openspace.gaia.removeClippingSphere = function()
if openspace.hasSceneGraphNode(grid_identifier) then
openspace.removeSceneGraphNode(grid_identifier)
end
openspace.setPropertyValue("Scene.*.Renderable.FilterDist", { 0.0, 0.0 })
end

43
modules/globebrowsing/scripts/layer_support.lua
View File

@@ -6,9 +6,10 @@ openspace.globebrowsing.documentation = {
{ "resolution", "String" },
{ "format", "String" }
},
Return = "String",
Documentation = [[
Creates an XML configuration for a temporal GIBS dataset to be used in a
TemporalTileprovider
TemporalTileprovider.
]]
},
{
@@ -19,13 +20,15 @@ openspace.globebrowsing.documentation = {
{ "resolution", "String" },
{ "format", "String" }
},
Return = "String",
Documentation = [[
Creates an XML configuration for a GIBS dataset.
Arguments are: layerName, date, resolution, format.
For all specifications, see
https://wiki.earthdata.nasa.gov/display/GIBS/GIBS+Available+Imagery+Products
[this page](https://wiki.earthdata.nasa.gov/display/GIBS/GIBS+Available+Imagery+Products).
Usage:
```lua
openspace.globebrowsing.addLayer(
"Earth",
"ColorLayers",
@@ -39,6 +42,7 @@ openspace.globebrowsing.documentation = {
)
}
)
```
]]
},
{
@@ -51,14 +55,17 @@ openspace.globebrowsing.documentation = {
{ "endDate", "String" }
},
Documentation = [[
Adds a new layer from NASA GIBS to the Earth globe. Arguments are: imagery layer
name, imagery resolution, start date, end date, format.
Adds a new layer from NASA GIBS to the Earth globe.
For all specifications, see
https://wiki.earthdata.nasa.gov/display/GIBS/GIBS+Available+Imagery+Products
[this page](https://wiki.earthdata.nasa.gov/display/GIBS/GIBS+Available+Imagery+Products).
Usage:
```lua
openspace.globebrowsing.addGibsLayer(
"AIRS_Temperature_850hPa_Night", "2km", "2013-07-15", "Present", "png"
)
```
]]
},
{
@@ -66,14 +73,20 @@ openspace.globebrowsing.documentation = {
Arguments = {
{ "file", "String" }
},
Return = "Table",
Documentation = [[
Parses the passed info file and return the table with the information provided in
the info file. The return table contains the optional keys:
'Color', 'Height', 'Node', 'Location', 'Identifier'.
the info file.
The return table contains the optional keys: `Color`, `Height`, `Node`, `Location`,
`Identifier`.
Usage:
```lua
local t = openspace.globebrowsing.parseInfoFile(file)
openspace.globebrowsing.addLayer("Earth", "ColorLayers", t.color)
openspace.globebrowsing.addLayer("Earth", "HeightLayers", t.height)
```
]]
},
{
@@ -86,8 +99,11 @@ openspace.globebrowsing.documentation = {
Retrieves all info files recursively in the directory passed as the first argument
to this function. The color and height tables retrieved from these info files are
then added to the RenderableGlobe identified by name passed to the second argument.
Usage:
```lua
openspace.globebrowsing.addBlendingLayersFromDirectory(directory, "Earth")
```
]]
},
{
@@ -100,8 +116,11 @@ openspace.globebrowsing.documentation = {
Retrieves all info files recursively in the directory passed as the first argument
to this function. The name and location retrieved from these info files are then
used to create new SceneGraphNodes that can be used as focus nodes.
Usage:
```lua
openspace.globebrowsing.addFocusNodesFromDirectory(directory, "Mars")
```
]]
},
{
@@ -111,14 +130,18 @@ openspace.globebrowsing.documentation = {
{ "globeIdentifier", "String" },
{ "latitude", "Number" },
{ "longitude", "Number" },
{ "altitude", "Number" }
{ "altitude", "Number?" }
},
Documentation = [[
Creates a new SceneGraphNode that can be used as focus node.
Creates a new SceneGraphNode that can be used as focus node for a specific point on
a globe. If no altitude is specified, an altitude of 0 will be used.
Usage:
```lua
openspace.globebrowsing.addFocusNodeFromLatLong(
"Olympus Mons", "Mars", -18.65, 226.2, optionalAltitude
)
```
]]
},
{

36
modules/globebrowsing/scripts/node_support.lua
View File

@@ -2,34 +2,56 @@ openspace.globebrowsing.documentation = {
{
Name = "setNodePosition",
Arguments = {
{ "nodeIdentifer", "String" },
{ "nodeIdentifier", "String" },
{ "globeIdentifier", "String" },
{ "latitude", "Number" },
{ "longitude", "Number" },
{ "altitude", "Number" }
{ "altitude", "Number?" }
},
Documentation = [[
Sets the position of a SceneGraphNode that has GlobeTranslation/GlobeRotations.
Sets the position of a scene graph node that has a
[GlobeTranslation](#globebrowsing_translation_globetranslation) and/or
[GlobeRotation](#globebrowsing_rotation_globerotation).
Usage:
```lua
openspace.globebrowsing.setNodePosition(
"Scale_StatueOfLiberty", "Earth", 40.000, -117.5, optionalAltitude
)
```
\\param nodeIdentifier The identifier of the scene graph node to move
\\param globeIdentifier The identifier of the [RenderableGlobe](#globebrowsing_renderableglobe)
that the object should be put on
\\param latitude The latitude value for the new position, in degrees
\\param longitude The longitude value for the new position, in degrees
\\param altitude An optional altitude value for the new position, in meters. If
excluded, an altitude of 0 will be used
]]
},
{
Name = "setNodePositionFromCamera",
Arguments = {
{ "nodeIdentifer", "String" },
{ "useAltitude", "Boolean" }
{ "useAltitude", "Boolean?" }
},
Documentation = [[
Sets the position of a SceneGraphNode that has GlobeTranslation/GlobeRotations to
match the camera. Only uses camera position not rotation. If useAltitude is true,
then the position will also be updated to the camera's altitude.
Sets the position of a scene graph node that has a
[GlobeTranslation](#globebrowsing_translation_globetranslation) and/or
[GlobeRotation](#globebrowsing_rotation_globerotation) to match the camera. Only
uses camera position not rotation. If useAltitude is true, then the position
will also be updated to the camera's altitude.
Usage:
```lua
openspace.globebrowsing.setNodePositionFromCamera(
"Scale_StatueOfLiberty", optionalUseAltitude
)
```
\\param nodeIdentifier The identifier of the scene graph node to move
\\param useAltitude If true, the camera's altitude will also be used for the new
positions. Otherwise, it will not.
]]
}
}

2
modules/globebrowsing/src/globetranslation.cpp
View File

@@ -122,7 +122,7 @@ namespace {
namespace openspace::globebrowsing {
documentation::Documentation GlobeTranslation::Documentation() {
return codegen::doc<Parameters>("space_translation_globetranslation");
return codegen::doc<Parameters>("globebrowsing_translation_globetranslation");
}
GlobeTranslation::GlobeTranslation(const ghoul::Dictionary& dictionary)

13
scripts/core_scripts.lua
View File

@@ -4,32 +4,33 @@ openspace.documentation = {
Arguments = {{ "sceneGraphNodes", "String[]" }},
Documentation = [[This function marks the scene graph nodes identified by name as
interesting, which will provide shortcut access to focus buttons and featured
properties]]
properties.]]
},
{
Name = "markInterestingTimes",
Arguments = {{ "times", "Table[]" }},
Documentation = [[This function marks interesting times for the current scene, which
will create shortcuts for a quick access]]
will create shortcuts for a quick access.]]
},
{
Name = "removeInterestingNodes",
Arguments = {{ "sceneGraphNodes", "String[]" }},
Documentation = [[This function removes unmarks the scene graph nodes identified by
name as interesting, thus removing the shortcuts from the features properties list]]
name as interesting, thus removing the shortcuts from the features properties list.
]]
},
{
Name = "setDefaultDashboard",
Arguments = {},
Documentation = [[This function sets the default values for the dashboard consisting
of 'DashboardItemDate', 'DashboardItemSimulationIncrement', 'DashboardItemDistance',
'DashboardItemFramerate', and 'DashboardItemParallelConnection']]
'DashboardItemFramerate', and 'DashboardItemParallelConnection'.]]
},
{
Name = "rebindKey",
Arguments = {{ "oldKey", "String" }, { "newKey", "String" }},
Documentation = [[Rebinds all scripts from the old key (first argument) to the new
key (second argument)]]
key (second argument).]]
},
{
Name = "appendToListProperty",
@@ -48,7 +49,7 @@ openspace.documentation = {
{
Name = "invertBooleanProperty",
Arguments = {{ "identifier", "String" }},
Documentation = "Inverts the value of a boolean property with the given identifier"
Documentation = "Inverts the value of a boolean property with the given identifier."
},
{
Name = "fadeIn",

2
src/navigation/navigationstate.cpp
View File

@@ -44,7 +44,7 @@ namespace {
// the actual camera position or view direction.
//
// To get the current navigation state of the camera, use the
// `openspace.navigation.getNavigationState()` function in the Scripting API.
// `openspace.navigation.navigationState()` function in the Scripting API.
//
// Note that when loading a NavigationState, the visuals may be different depending
// on what the simulation timestamp is, as the relative positions of objects in the