From 6dd497d38c431e91a004703cbb72a2cd81f68ead Mon Sep 17 00:00:00 2001 From: Emma Broman Date: Thu, 4 Jan 2024 13:55:21 +0100 Subject: [PATCH] Feature/add some docs (#2961) * Add docs for PathInstruction * Add docs for renderablecartesianaxes and navigationstate * Write docs for ExoplanetDataPreparationTask * Add some kind of documentation for the task base class Was already showing in the list, but the property or decription was not included * Apply suggestions from code review * Address review comments * Clarify confusing sentence * Slight rephrasing --- .../rendering/renderablecartesianaxes.cpp | 13 +++++++++- .../tasks/exoplanetsdatapreparationtask.cpp | 21 ++++++++++++++++ src/documentation/core_registration.cpp | 2 ++ src/navigation/navigationstate.cpp | 18 +++++++++++++ src/navigation/path.cpp | 25 +++++++++++++++---- src/util/task.cpp | 9 +++++++ 6 files changed, 82 insertions(+), 6 deletions(-) diff --git a/modules/base/rendering/renderablecartesianaxes.cpp b/modules/base/rendering/renderablecartesianaxes.cpp index 841a6b032e..a0f01d6c74 100644 --- a/modules/base/rendering/renderablecartesianaxes.cpp +++ b/modules/base/rendering/renderablecartesianaxes.cpp @@ -61,6 +61,18 @@ namespace { openspace::properties::Property::Visibility::NoviceUser }; + // The RenderableCartesianAxes can be used to render the local Cartesian coordinate + // system, or reference frame, of another scene graph node. The colors of the axes + // can be customized but are per default set to Red, Green and Blue, for the X-, Y- + // and Z-axis, respectively. + // + // To add the axes, create a scene graph node with the RenderableCartesianAxes + // renderable and add it as a child to the other scene graph node, i.e. specify the + // other node as the Parent of the node with this renderable. Also, the axes have to + // be scaled to match the parent object for the axes to be visible in the scene, for + // example using a StaticScale. + // + // See example asset (@TODO: link to asset file). struct [[codegen::Dictionary(RenderableCartesianAxes)]] Parameters { // [[codegen::verbatim(XColorInfo.description)]] std::optional xColor [[codegen::color()]]; @@ -70,7 +82,6 @@ namespace { // [[codegen::verbatim(ZColorInfo.description)]] std::optional zColor [[codegen::color()]]; - }; #include "renderablecartesianaxes_codegen.cpp" } // namespace diff --git a/modules/exoplanets/tasks/exoplanetsdatapreparationtask.cpp b/modules/exoplanets/tasks/exoplanetsdatapreparationtask.cpp index 98fe89286f..c160e8e473 100644 --- a/modules/exoplanets/tasks/exoplanetsdatapreparationtask.cpp +++ b/modules/exoplanets/tasks/exoplanetsdatapreparationtask.cpp @@ -40,6 +40,27 @@ namespace { constexpr std::string_view _loggerCat = "ExoplanetsDataPreparationTask"; + // This task is used for generating the binary data files that are used for the + // exoplanet system loading in OpenSpace. Using this binary file allows efficient + // data loading of an arbitrary exoplanet system during runtime, without keeping all + // data in memory. + // + // Two output files are generated, whose paths have to be specified: One binary with + // the data for the exoplanets (OutputBIN) and one look-up table that is used to + // find where in the binary file a particular system is located (OutputLUT). + // + // Additionally, the task uses three different files as input: 1) a CSV file with the + // data from the NASA Exoplanet Archive, 2) A SPECK file that contains star positions, + // and 3) a TXT file that is used for the conversion from the stars' effective + // temperature to a B-V color index. The paths for all these paths have to be + // specified. The SPECK file (2) will be used for the positions of the host stars, to + // make sure that they line up with the stars in that dataset. The cross-matching is + // done by star name, as given by the comment in the SPECK file and the host star + // column in the exoplanet dataset. + // + // Note that the CSV (1) has to include a certain set of columns for the rendering to + // be correct. Use the accompanying python script to download the datafile, or make + // sure to include all columns in your download. struct [[codegen::Dictionary(ExoplanetsDataPreparationTask)]] Parameters { // The csv file to extract data from std::string inputDataFile; diff --git a/src/documentation/core_registration.cpp b/src/documentation/core_registration.cpp index bdec3fa0a9..e1c9f03438 100644 --- a/src/documentation/core_registration.cpp +++ b/src/documentation/core_registration.cpp @@ -57,6 +57,7 @@ #include #include #include +#include #include #include @@ -74,6 +75,7 @@ void registerCoreClasses(documentation::DocumentationEngine& engine) { engine.addDocumentation(Scale::Documentation()); engine.addDocumentation(SceneGraphNode::Documentation()); engine.addDocumentation(ScreenSpaceRenderable::Documentation()); + engine.addDocumentation(Task::documentation()); engine.addDocumentation(TimeRange::Documentation()); engine.addDocumentation(Translation::Documentation()); engine.addDocumentation(TimeFrame::Documentation()); diff --git a/src/navigation/navigationstate.cpp b/src/navigation/navigationstate.cpp index a1f11ba337..b995b9ebf9 100644 --- a/src/navigation/navigationstate.cpp +++ b/src/navigation/navigationstate.cpp @@ -33,6 +33,24 @@ namespace { constexpr double Epsilon = 1E-7; + // A NavigationState is an object describing an exact camera position and rotation, + // in a certain reference frame (per default, the one of the specified Anchor node). + // It can be used to set the same camera position at a later point in time, or + // navigating to a specific camera position using the pathnavigation system. + // + // The camera rotation is specified using Euler angles, in radians. It is also + // possible to specify a node to be used as Aim, but note that this will not affect + // 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. + // + // Note that a NavigationState does not include information about what timestamp + // within OpenSpace that the NavigationState was generated. When laoding a + // NavigationState, the visuals may be different depending on what the simulation + // timestamp is, as the relative positions of objects in the scene may have changed. + // The get the exact same visuals as when the NavigationState was saved, make sure + // to also set the time to be the same as on save. struct [[codegen::Dictionary(NavigationState)]] Parameters { // The identifier of the anchor node std::string anchor; diff --git a/src/navigation/path.cpp b/src/navigation/path.cpp index abeb9ec85c..8b827009b6 100644 --- a/src/navigation/path.cpp +++ b/src/navigation/path.cpp @@ -45,9 +45,24 @@ namespace { constexpr std::string_view _loggerCat = "Path"; constexpr float LengthEpsilon = 1e-5f; - // TODO: where should this documentation be? - // It's nice to have these to interpret the dictionary when creating the path, but - // maybe it's not really necessary + // A PathInstruction is a table describing the specification for a camera path. + // It is used as an input to the `openspace.pathnavigation.createPath` function. + // + // There are two types of paths that can be created, as specified by the required + // TargetType parameter: 'Node' or 'NavigationState'. The difference is what kind + // of target the path is created for, a scene graph node or a specific navigation + // state for the camera. + // + // Depending on the type, the parameters that can be specified are a bit different. + // A 'NavigationState' already contains all details for the camera position, so no + // other details may be specified. For a 'Node' instruction, only a 'Target' node is + // required, but a 'Height' or 'Position' may also be specified. If both a position + // and height is specified, the height value will be ignored. + // + // For 'Node' paths it is also possible to specify whether the target camera state + // at the end of the flight should take the up direction of the target node into + // account. Note that for this to give an effect on the path, rolling motions have + // to be enabled. struct [[codegen::Dictionary(PathInstruction)]] Parameters { // The type of the instruction. Decides what other parameters are // handled/available @@ -61,7 +76,7 @@ namespace { std::optional duration; // (Node): The target node of the camera path. Not optional for 'Node' - // instructions + // type instructions std::optional target; // (Node): An optional position in relation to the target node, in model @@ -76,7 +91,7 @@ namespace { std::optional useTargetUpDirection; // (NavigationState): A navigation state that will be the target - // of this path segment + // of the resulting path std::optional navigationState [[codegen::reference("core_navigation_state")]]; diff --git a/src/util/task.cpp b/src/util/task.cpp index 40e1c0fa60..2eb1ce6185 100644 --- a/src/util/task.cpp +++ b/src/util/task.cpp @@ -31,6 +31,15 @@ #include namespace { + + // The base class of all tasks. Specify the Type property to create one of the + // available task types. This property should be included in the same table object + // as the properties of the specific task. + // + // Tasks can be executed using the separate TaskRunner application. When starting the + // application, just enter the path to the file describing the task you want to run + // as input in the command line to initiate the run. All tasks should live in the task + // folder in the data folder of the OpenSpace installation. struct [[codegen::Dictionary(Task)]] Parameters { // This key specifies the type of Task that gets created. It has to be one of the // valid Tasks that are available for creation (see the FactoryDocumentation for a