From d4c4c92a5eead01ea1f8403144b614ad70c99330 Mon Sep 17 00:00:00 2001 From: Emma Broman Date: Mon, 20 Jan 2025 15:58:37 +0100 Subject: [PATCH] Docs for `RenderableConstellationLines` and `RenderableConstellationBounds` (#3481) * Update some of the base documentation to make more sense on the docs page * Add description for `RenderableConstellationBounds` * Add description for `RenderableConstellationLines` and names file and labels details * Remove redundant info from description * Apply suggestions from code review Co-authored-by: Ylva Selling Co-authored-by: Malin E * Update constellation bound documentation based on review comments * Update docs about labels for constellation lines as well --------- Co-authored-by: Ylva Selling Co-authored-by: Malin E --- .../renderableconstellationbounds.cpp | 31 +++++++++++++++++-- .../renderableconstellationlines.cpp | 22 +++++++++++++ .../renderableconstellationsbase.cpp | 7 +++-- 3 files changed, 55 insertions(+), 5 deletions(-) diff --git a/modules/space/rendering/renderableconstellationbounds.cpp b/modules/space/rendering/renderableconstellationbounds.cpp index 9a5cde6bad..a0ae97a33a 100644 --- a/modules/space/rendering/renderableconstellationbounds.cpp +++ b/modules/space/rendering/renderableconstellationbounds.cpp @@ -47,7 +47,8 @@ namespace { constexpr openspace::properties::Property::PropertyInfo VertexInfo = { "File", "Vertex File Path", - "A file that contains the vertex locations of the constellations bounds.", + "A file that contains the vertex locations of the constellations bounds, as RA " + "Dec coordinates on the celestial sphere.", openspace::properties::Property::Visibility::AdvancedUser }; @@ -58,6 +59,32 @@ namespace { openspace::properties::Property::Visibility::NoviceUser }; + // This `Renderable` type can be used to draw bounding shapes on the night sky, where + // each shape encapsulates a group of night sky objects, such as the stars of a + // constellation. + // + // The shapes are defined in a file where each line specifies a vertex location in RA + // Dec coordinates on the celestial sphere. Each coordinate must also be marked with + // an abbreviation for the corresponding constellation that the shapes encapsulates. + // This gives each line the following order: `RA Dec Abbreviation`. The units for the + // coordinate values are hours for RA, and degrees for Dec. An example of a line + // corresponding to a vertex location may look like this: + // `23.5357132 +35.1897736 AND`, where `AND` is the identifier of the constellation. + // In this case it is short for Andromeda. + // + // The abbreviations act as identifiers of the individual constellations and can + // be mapped to full names in the optional `NamesFile`. The names in this file are + // then the ones that will show in the user interface, for example. A line in the + // file should first include the abbreviation and then the full name. For example, + // for the `AND` abbreviation in the example above, the line would look like this: + // `AND Andromeda`. + // + // If labels were added, the full names in the `NamesFile` may also be used for the + // text of the labels. Note that labels are added using a different file, where each + // line may or may not include an identifier for that specific label, marked by `id` + // in the file. If a row in the label file has an `id` that matches the abbreviation + // of the constellation, the text of that label is replaced with the full name from + // the `NamesFile`. struct [[codegen::Dictionary(RenderableConstellationBounds)]] Parameters { // [[codegen::verbatim(VertexInfo.description)]] std::filesystem::path file; @@ -289,7 +316,7 @@ bool RenderableConstellationBounds::loadVertexFile() { // Likewise, the declination is stored in degrees and needs to be converted dec = glm::radians(dec); - // Convert the (right ascension, declination) to rectangular coordinates) + // Convert the (right ascension, declination) to rectangular coordinates. // The 1.0 is the distance of the celestial sphere, we will scale that in the // render function std::array rectangularValues; diff --git a/modules/space/rendering/renderableconstellationlines.cpp b/modules/space/rendering/renderableconstellationlines.cpp index ccd483266d..0714fa8b73 100644 --- a/modules/space/rendering/renderableconstellationlines.cpp +++ b/modules/space/rendering/renderableconstellationlines.cpp @@ -78,6 +78,28 @@ namespace { openspace::properties::Property::Visibility::User }; + // @TODO (2025-01-07, emmbr) I did not add any description of the file format below, + // since we intend for this to be changed in a relatively near future. When that is + // done, update the description. + // @TODO (2025-01-07, emmbr) Also need to update description of names file and labels + // as part of the labels rewrite + + // This renderable can be used to draw constellations using lines. Each constellation + // corresponds to a group of lines between 3D positions that represent the star + // positions. + // + // Each constellation is given an abbreviation that acts as the identifier of the + // constellation. These abbreviations can be mapped to full names in the + // optional `NamesFile`. The names in this file are then the ones that will show + // in the user interface. A line in the `NamesFile` should first include the + // abbreviation and then the full name. For example: `AND Andromeda`. + // + // If labels were added, the full names in the `NamesFile` may also be used for the + // text of the labels. Note that labels are added using a different file, where each + // line may or may not include an identifier for that specific label, marked by `id` + // in the file. If a row in the label file has an `id` that matches the abbreviation + // of the constellation, the text of that label is replaced with the full name from + // the `NamesFile`. struct [[codegen::Dictionary(RenderableConstellationLines)]] Parameters { // [[codegen::verbatim(FileInfo.description)]] std::filesystem::path file; diff --git a/modules/space/rendering/renderableconstellationsbase.cpp b/modules/space/rendering/renderableconstellationsbase.cpp index cf41c2c873..359fc21eb3 100644 --- a/modules/space/rendering/renderableconstellationsbase.cpp +++ b/modules/space/rendering/renderableconstellationsbase.cpp @@ -51,14 +51,14 @@ namespace { constexpr openspace::properties::Property::PropertyInfo LineWidthInfo = { "LineWidth", "Line Width", - "The line width of the constellation.", + "The line width used for the constellation shape.", openspace::properties::Property::Visibility::NoviceUser }; constexpr openspace::properties::Property::PropertyInfo SelectionInfo = { "ConstellationSelection", "Constellation Selection", - "The constellations that are selected are displayed on the celestial sphere.", + "The selected constellations are displayed on the celestial sphere.", openspace::properties::Property::Visibility::NoviceUser }; @@ -75,7 +75,8 @@ namespace { // [[codegen::verbatim(LineWidthInfo.description)]] std::optional lineWidth; - // [[codegen::verbatim(SelectionInfo.description)]] + // A list of constellations (given as abbreviations) to show. If empty or + // excluded, all constellations will be shown. std::optional> selection; // [[codegen::verbatim(LabelsInfo.description)]]