Add/update documentation and add example of RenderableTravelSpeed (#3224)

* Add/update documentation and add example of `RenderableTravelSpeed`

* Update description based on review comments

---------

Co-authored-by: Alexander Bock <alexander.bock@liu.se>
Co-authored-by: Ylva Selling <ylva.selling@gmail.com>

modules/space/rendering/renderabletravelspeed.cpp

@@ -41,23 +41,24 @@ namespace {
 
     constexpr openspace::properties::Property::PropertyInfo SpeedInfo = {
         "TravelSpeed",
-        "Speed of travel",
-        "The speed of light is the default value.",
+        "Speed of Travel",
+        "A value for how fast the speed indicator should travel, in meters per second. "
+        "The default value is the speed of light.",
         openspace::properties::Property::Visibility::NoviceUser
     };
 
     constexpr openspace::properties::Property::PropertyInfo TargetInfo = {
         "TargetNode",
-        "Target object",
-        "This value sets which scene graph node to target with the light speed "
-        "indicator.",
+        "Target Object",
+        "The identifier of the scene graph node to target with the speed indicator. The "
+        "speed indicator will travel from the parent node to this scene graph node.",
         openspace::properties::Property::Visibility::AdvancedUser
     };
 
     constexpr openspace::properties::Property::PropertyInfo LineColorInfo = {
         "Color",
         "Color",
-        "This value determines the RGB color for the line.",
+        "An RGB color for the line.",
         openspace::properties::Property::Visibility::NoviceUser
     };
 
@@ -71,36 +72,50 @@ namespace {
     constexpr openspace::properties::Property::PropertyInfo IndicatorLengthInfo = {
         "IndicatorLength",
         "Indicator Length",
-        "This value specifies the length of the light indicator set in light seconds.",
+        "The length of the speed indicator line, given in seconds. The length will be "
+        "computed as the speed times this value. For example, a value of 1 will make it "
+        "as long as the distance it would travel over one second with the specified speed.",
         openspace::properties::Property::Visibility::User
     };
 
     constexpr openspace::properties::Property::PropertyInfo FadeLengthInfo = {
         "FadeLength",
         "Fade Length",
-        "This value specifies the length of the faded tail of the light indicator "
-        "set in light seconds.",
+        "The length of the faded tail of the speed indicator, given in seconds. The "
+        "length of the tail will be computed as the speed times this value. For example, "
+        "a value of 1 will make it as long as the distance it would travel over one "
+        "second. A linear fade will be applied over this distance to create the tail.",
         openspace::properties::Property::Visibility::User
     };
 
+    // This renderable can be used to visualize a certain travel speed using a line that
+    // moves at the provided speed from a start object to a target. The start position
+    // will be set from the `Parent` of this scene graph node, and the end position is
+    // set from the provided `Target` scene graph node. Per default, the speed is set to
+    // the speed of light.
+    //
+    // The length of the traveling line is set based on the travel speed and can be used
+    // to show more information related to the distance traveled. For example, a length
+    // of 1 shows how far an object would move over a duration of one second based on the
+    // selected speed.
     struct [[codegen::Dictionary(RenderableTravelSpeed)]] Parameters {
         // [[codegen::verbatim(TargetInfo.description)]]
-        std::string target;
+        std::string target [[codegen::identifier()]];;
 
         // [[codegen::verbatim(SpeedInfo.description)]]
-        std::optional<double> travelSpeed;
+        std::optional<double> travelSpeed [[codegen::greater(0.f)]];
 
         // [[codegen::verbatim(LineColorInfo.description)]]
-        std::optional<glm::vec3> color;
+        std::optional<glm::vec3> color [[codegen::color()]];
 
         // [[codegen::verbatim(LineWidthInfo.description)]]
-        std::optional<float> lineWidth;
+        std::optional<float> lineWidth [[codegen::greater(0.f)]];
 
         // [[codegen::verbatim(IndicatorLengthInfo.description)]]
-        std::optional<float> indicatorLength;
+        std::optional<float> indicatorLength [[codegen::greater(0.f)]];
 
         // [[codegen::verbatim(FadeLengthInfo.description)]]
-        std::optional<float> fadeLength;
+        std::optional<float> fadeLength [[codegen::greater(0.f)]];
     };
 #include "renderabletravelspeed_codegen.cpp"
 } // namespace
@@ -121,7 +136,7 @@ RenderableTravelSpeed::RenderableTravelSpeed(const ghoul::Dictionary& dictionary
         distanceconstants::LightSecond
       )
     , _indicatorLength(IndicatorLengthInfo, 1.f, 0.f, 360.f)
-    , _fadeLength(FadeLengthInfo, 1.f, 0.f, 360.f)
+    , _fadeLength(FadeLengthInfo, 0.f, 0.f, 360.f)
     , _lineWidth(LineWidthInfo, 2.f, 1.f, 20.f)
     , _lineColor(LineColorInfo, glm::vec3(1.f), glm::vec3(0.f), glm::vec3(1.f))
 {
@@ -134,7 +149,6 @@ RenderableTravelSpeed::RenderableTravelSpeed(const ghoul::Dictionary& dictionary
     _lineColor.setViewOption(properties::Property::ViewOptions::Color);
     addProperty(_lineColor);
 
-
     _lineWidth = p.lineWidth.value_or(_lineWidth);
     addProperty(_lineWidth);
 
@@ -150,8 +164,7 @@ RenderableTravelSpeed::RenderableTravelSpeed(const ghoul::Dictionary& dictionary
         if (SceneGraphNode* n = sceneGraphNode(_targetName);  n) {
             _targetNode = n;
             _targetPosition = _targetNode->worldPosition();
-            _lightTravelTime =
-                glm::distance(_targetPosition, _sourcePosition) / _travelSpeed;
+            _travelTime = glm::distance(_targetPosition, _sourcePosition) / _travelSpeed;
             calculateDirectionVector();
             reinitiateTravel();
         }
@@ -165,7 +178,7 @@ RenderableTravelSpeed::RenderableTravelSpeed(const ghoul::Dictionary& dictionary
 void RenderableTravelSpeed::initialize() {
     _targetNode = sceneGraphNode(_targetName);
     if (_targetNode == nullptr) {
-        throw ghoul::RuntimeError("Could not find targetNode");
+        throw ghoul::RuntimeError("Could not find Target Node");
     }
 }
 
@@ -243,7 +256,7 @@ void RenderableTravelSpeed::updateVertexData() {
 
 void RenderableTravelSpeed::reinitiateTravel() {
     _initiationTime = global::timeManager->time().j2000Seconds();
-    _arrivalTime = _initiationTime + _lightTravelTime;
+    _arrivalTime = _initiationTime + _travelTime;
 }
 
 bool RenderableTravelSpeed::isReady() const{
@@ -253,7 +266,7 @@ bool RenderableTravelSpeed::isReady() const{
 void RenderableTravelSpeed::update(const UpdateData& data) {
     if (_initiationTime == -1.0) {
         _initiationTime = data.time.j2000Seconds();
-        _arrivalTime = _initiationTime + _lightTravelTime;
+        _arrivalTime = _initiationTime + _travelTime;
     }
 
     _targetPosition = _targetNode->worldPosition();
@@ -261,7 +274,7 @@ void RenderableTravelSpeed::update(const UpdateData& data) {
     ghoul_assert(mySGNPointer, "Renderable have to be owned by scene graph node");
     _sourcePosition = mySGNPointer->worldPosition();
 
-    _lightTravelTime = glm::distance(_targetPosition, _sourcePosition) / _travelSpeed;
+    _travelTime = glm::distance(_targetPosition, _sourcePosition) / _travelSpeed;
 
     const double currentTime = data.time.j2000Seconds();
     // Unless we've reached the target

modules/space/rendering/renderabletravelspeed.h

@@ -76,7 +76,7 @@ private:
 
     glm::dvec3 _sourcePosition;
     glm::dvec3 _targetPosition;
-    double _lightTravelTime;
+    double _travelTime = 0.0;
     glm::dvec3 _directionVector;
     double _initiationTime = -1.0;
     double _arrivalTime;