Polish and docs for RenderableDistanceLabel and docs for RenderableNodeLine (#3485)

* Update add add documentation for `RenderableDistanceLabel`

* Move distancelabel to `base` module and remove now empty `vislab` module

* Add examples for `RenderableNodeLine` and `RenderableDistanceLabel`

* Fix faultily formatted documentation ID for `RenderableNodeLine`

* Make `RenderableDistanceLabel` unit use units from distanceconversion file

And simplify how the different names for a unit are specified

* Use new distanceUnitList() function for other classes that uses the units

* Change default unit to correct option according to documentation

* Make the text property readonly for `RenderableDistanceLabel`

* Add property to specify the precision of the number

distance label precision to docs

* Add examples with different units and descriptors

* Add docs description to `RenderableNodeLine`

* Update name in one of the examples

* Remove redundant switch cases

* Apply suggestions from code review

Co-authored-by: Ylva Selling <ylva.selling@gmail.com>

---------

Co-authored-by: Ylva Selling <ylva.selling@gmail.com>

modules/base/CMakeLists.txt

@@ -50,6 +50,7 @@ set(HEADER_FILES
   rendering/pointcloud/sizemappingcomponent.h
   rendering/renderablecartesianaxes.h
   rendering/renderabledisc.h
+  rendering/renderabledistancelabel.h
   rendering/renderablelabel.h
   rendering/renderablemodel.h
   rendering/renderablenodearrow.h
@@ -113,6 +114,7 @@ set(SOURCE_FILES
   rendering/pointcloud/sizemappingcomponent.cpp
   rendering/renderablecartesianaxes.cpp
   rendering/renderabledisc.cpp
+  rendering/renderabledistancelabel.cpp
   rendering/renderablelabel.cpp
   rendering/renderablemodel.cpp
   rendering/renderablenodearrow.cpp

modules/base/basemodule.cpp

@@ -49,6 +49,7 @@
 #include <modules/base/rendering/pointcloud/sizemappingcomponent.h>
 #include <modules/base/rendering/renderablecartesianaxes.h>
 #include <modules/base/rendering/renderabledisc.h>
+#include <modules/base/rendering/renderabledistancelabel.h>
 #include <modules/base/rendering/renderablelabel.h>
 #include <modules/base/rendering/renderablemodel.h>
 #include <modules/base/rendering/renderablenodearrow.h>
@@ -138,6 +139,7 @@ void BaseModule::internalInitialize(const ghoul::Dictionary&) {
     fRenderable->registerClass<RenderableBoxGrid>("RenderableBoxGrid");
     fRenderable->registerClass<RenderableCartesianAxes>("RenderableCartesianAxes");
     fRenderable->registerClass<RenderableDisc>("RenderableDisc");
+    fRenderable->registerClass<RenderableDistanceLabel>("RenderableDistanceLabel");
     fRenderable->registerClass<RenderableGrid>("RenderableGrid");
     fRenderable->registerClass<RenderableLabel>("RenderableLabel");
     fRenderable->registerClass<RenderableModel>("RenderableModel");
@@ -230,6 +232,7 @@ std::vector<documentation::Documentation> BaseModule::documentations() const {
         RenderableBoxGrid::Documentation(),
         RenderableCartesianAxes::Documentation(),
         RenderableDisc::Documentation(),
+        RenderableDistanceLabel::Documentation(),
         RenderableGrid::Documentation(),
         RenderableInterpolatedPoints::Documentation(),
         RenderableLabel::Documentation(),

modules/base/dashboard/dashboarditemdistance.cpp

@@ -106,19 +106,6 @@ namespace {
         openspace::properties::Property::Visibility::AdvancedUser
     };
 
-    std::vector<std::string> unitList() {
-        std::vector<std::string> res(openspace::DistanceUnits.size());
-        std::transform(
-            openspace::DistanceUnits.begin(),
-            openspace::DistanceUnits.end(),
-            res.begin(),
-            [](openspace::DistanceUnit unit) {
-                return std::string(nameForDistanceUnit(unit));
-            }
-        );
-        return res;
-    }
-
     struct [[codegen::Dictionary(DashboardItemDistance)]] Parameters {
         enum class [[codegen::map(Type)]] TypeInfo {
             Node,
@@ -143,7 +130,8 @@ namespace {
         std::optional<bool> simplification;
 
         // [[codegen::verbatim(RequestedUnitInfo.description)]]
-        std::optional<std::string> requestedUnit [[codegen::inlist(unitList())]];
+        std::optional<std::string> requestedUnit
+            [[codegen::inlist(openspace::distanceUnitList())]];
 
         // [[codegen::verbatim(FormatStringInfo.description)]]
         std::optional<std::string> formatString;

modules/base/dashboard/dashboarditemvelocity.cpp

@@ -57,25 +57,13 @@ namespace {
         openspace::properties::Property::Visibility::User
     };
 
-    std::vector<std::string> unitList() {
-        std::vector<std::string> res(openspace::DistanceUnits.size());
-        std::transform(
-            openspace::DistanceUnits.begin(),
-            openspace::DistanceUnits.end(),
-            res.begin(),
-            [](openspace::DistanceUnit unit) {
-                return std::string(nameForDistanceUnit(unit));
-            }
-        );
-        return res;
-    }
-
     struct [[codegen::Dictionary(DashboardItemVelocity)]] Parameters {
         // [[codegen::verbatim(SimplificationInfo.description)]]
         std::optional<bool> simplification;
 
         // [[codegen::verbatim(RequestedUnitInfo.description)]]
-        std::optional<std::string> requestedUnit [[codegen::inlist(unitList())]];
+        std::optional<std::string> requestedUnit
+            [[codegen::inlist(openspace::distanceUnitList())]];
     };
 #include "dashboarditemvelocity_codegen.cpp"
 

modules/base/rendering/renderabledistancelabel.cpp

@@ -0,0 +1,201 @@
+/*****************************************************************************************
+ *                                                                                       *
+ * OpenSpace                                                                             *
+ *                                                                                       *
+ * Copyright (c) 2014-2025                                                               *
+ *                                                                                       *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of this  *
+ * software and associated documentation files (the "Software"), to deal in the Software *
+ * without restriction, including without limitation the rights to use, copy, modify,    *
+ * merge, publish, distribute, sublicense, and/or sell copies of the Software, and to    *
+ * permit persons to whom the Software is furnished to do so, subject to the following   *
+ * conditions:                                                                           *
+ *                                                                                       *
+ * The above copyright notice and this permission notice shall be included in all copies *
+ * or substantial portions of the Software.                                              *
+ *                                                                                       *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,   *
+ * INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A         *
+ * PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT    *
+ * HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF  *
+ * CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE  *
+ * OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.                                         *
+ ****************************************************************************************/
+
+#include <modules/base/rendering/renderabledistancelabel.h>
+
+#include <modules/base/rendering/renderablenodeline.h>
+#include <openspace/documentation/documentation.h>
+#include <openspace/documentation/verifier.h>
+#include <openspace/engine/globals.h>
+#include <openspace/rendering/renderengine.h>
+#include <openspace/scene/scene.h>
+#include <openspace/util/distanceconversion.h>
+#include <ghoul/logging/logmanager.h>
+#include <optional>
+#include <string>
+
+namespace {
+    constexpr std::string_view _loggerCat = "RenderableDistanceLabel";
+
+    constexpr openspace::properties::Property::PropertyInfo NodeLineInfo = {
+        "NodeLine",
+        "Node Line",
+        "The identifier of a scene graph node with a RenderableNodeLine that this label "
+        "should track. The label text will be updating based on the distance from the "
+        "node line's start and end.",
+        openspace::properties::Property::Visibility::AdvancedUser
+    };
+
+    constexpr openspace::properties::Property::PropertyInfo DistanceUnitInfo = {
+        "DistanceUnit",
+        "Display Distance Unit",
+        "The unit in which the distance value should be displayed. Defaults to 'km' if "
+        "not specified.",
+        openspace::properties::Property::Visibility::User
+    };
+
+    constexpr openspace::properties::Property::PropertyInfo CustomUnitDescriptorInfo = {
+        "CustomUnitDescriptor",
+        "Custom Unit Descriptor",
+        "Property to define a custom unit descriptor to use to describe the distance "
+        "value. Defaults to the selected unit's SI descriptor if not specified.",
+        openspace::properties::Property::Visibility::AdvancedUser
+    };
+
+    constexpr openspace::properties::Property::PropertyInfo PrecisionInfo = {
+        "Precision",
+        "Precision",
+        "The precision in which to to show the distance number, i.e. the number of "
+        "digits after the decimal point.",
+        openspace::properties::Property::Visibility::User
+    };
+
+    // This `Renderable` creates a label that shows the distance between two nodes, based
+    // on an existing [RenderableNodeLine](#base_renderable_nodeline). The label
+    // will be placed halfway between the two scene graph nodes that the line connects.
+    //
+    // The unit in which the distance is displayed can be customized, as well as the
+    // precision of the number.
+    struct [[codegen::Dictionary(RenderableDistanceLabel)]] Parameters {
+        // The identifier of a scene graph node with a
+        // [RenderableNodeLine](#base_renderable_nodeline) that this label
+        // should track. The label text will be updating based on the distance from the
+        // node line's start and end.
+        std::string nodeLine;
+
+        // [[codegen::verbatim(DistanceUnitInfo.description)]]
+        std::optional<std::string> distanceUnit
+            [[codegen::inlist(openspace::distanceUnitList())]];
+
+        // [[codegen::verbatim(CustomUnitDescriptorInfo.description)]]
+        std::optional<std::string> customUnitDescriptor;
+
+        // [[codegen::verbatim(PrecisionInfo.description)]]
+        std::optional<int> precision [[codegen::greaterequal(0)]];
+    };
+#include "renderabledistancelabel_codegen.cpp"
+} // namespace
+
+namespace openspace {
+
+documentation::Documentation RenderableDistanceLabel::Documentation() {
+    return codegen::doc<Parameters>("base_renderable_distancelabel");
+}
+
+RenderableDistanceLabel::RenderableDistanceLabel(const ghoul::Dictionary& dictionary)
+    : RenderableLabel(dictionary)
+    , _nodelineId(NodeLineInfo)
+    , _distanceUnit(DistanceUnitInfo, properties::OptionProperty::DisplayType::Dropdown)
+    , _customUnitDescriptor(CustomUnitDescriptorInfo)
+    , _precision(PrecisionInfo, 0, 0, 10)
+{
+    const Parameters p = codegen::bake<Parameters>(dictionary);
+
+    _nodelineId = p.nodeLine;
+    addProperty(_nodelineId);
+
+    for (const DistanceUnit u : DistanceUnits) {
+        _distanceUnit.addOption(
+            static_cast<int>(u),
+            std::string(nameForDistanceUnit(u))
+        );
+    }
+    _distanceUnit = static_cast<int>(DistanceUnit::Kilometer);
+    if (p.distanceUnit.has_value()) {
+        const DistanceUnit unit = distanceUnitFromString(*p.distanceUnit);
+        _distanceUnit = static_cast<int>(unit);
+    }
+    addProperty(_distanceUnit);
+
+    _customUnitDescriptor = p.customUnitDescriptor.value_or(_customUnitDescriptor);
+    addProperty(_customUnitDescriptor);
+
+    _precision = p.precision.value_or(_precision);
+    addProperty(_precision);
+
+    // The text will be updated automatically, so set the property to readonly
+    _text.setReadOnly(true);
+}
+
+void RenderableDistanceLabel::update(const UpdateData&) {
+    if (_errorThrown) {
+        return;
+    }
+
+    RenderEngine& RE = *global::renderEngine;
+
+    SceneGraphNode* nodelineNode = RE.scene()->sceneGraphNode(_nodelineId);
+    if (nodelineNode) {
+        RenderableNodeLine* nodeline = dynamic_cast<RenderableNodeLine*>(
+            nodelineNode->renderable()
+        );
+        if (!nodeline) {
+            LERROR("Expected renderable to be of type 'RenderableNodeLine'");
+            _errorThrown = true;
+            return;
+        }
+
+        const DistanceUnit unit = static_cast<DistanceUnit>(_distanceUnit.value());
+
+        // Get unit descriptor text
+        std::string_view unitDescriptor = abbreviationForDistanceUnit(unit);
+        if (!_customUnitDescriptor.value().empty()) {
+            unitDescriptor = _customUnitDescriptor;
+        }
+
+        // Get distance as string
+        const double convertedDistance = convertMeters(nodeline->distance(), unit);
+
+        std::string distanceText = std::format("{:.{}f}", convertedDistance, _precision.value());
+
+        // Create final label text and set it
+        const std::string finalText = std::format("{} {}", distanceText, unitDescriptor);
+        setLabelText(finalText);
+
+        // Update placement of label with transformation matrix
+        SceneGraphNode* startNode = RE.scene()->sceneGraphNode(nodeline->start());
+        SceneGraphNode* endNode = RE.scene()->sceneGraphNode(nodeline->end());
+        if (startNode && endNode) {
+            const glm::dvec3 start = startNode->worldPosition();
+            const glm::dvec3 end = endNode->worldPosition();
+            const glm::dvec3 goalPos = start + (end - start) / 2.0;
+            _transformationMatrix = glm::translate(glm::dmat4(1.0), goalPos);
+        }
+        else {
+            LERROR(std::format(
+                "Could not find scene graph node '{}' or '{}'",
+                nodeline->start(), nodeline->end()
+            ));
+        }
+    }
+    else {
+        LERROR(std::format(
+            "There is no scenegraph node with id {}", _nodelineId.value()
+        ));
+        _errorThrown = true;
+    }
+}
+
+} // namespace openspace
+

modules/base/rendering/renderabledistancelabel.h

@@ -0,0 +1,55 @@
+/*****************************************************************************************
+ *                                                                                       *
+ * OpenSpace                                                                             *
+ *                                                                                       *
+ * Copyright (c) 2014-2025                                                               *
+ *                                                                                       *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of this  *
+ * software and associated documentation files (the "Software"), to deal in the Software *
+ * without restriction, including without limitation the rights to use, copy, modify,    *
+ * merge, publish, distribute, sublicense, and/or sell copies of the Software, and to    *
+ * permit persons to whom the Software is furnished to do so, subject to the following   *
+ * conditions:                                                                           *
+ *                                                                                       *
+ * The above copyright notice and this permission notice shall be included in all copies *
+ * or substantial portions of the Software.                                              *
+ *                                                                                       *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,   *
+ * INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A         *
+ * PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT    *
+ * HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF  *
+ * CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE  *
+ * OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.                                         *
+ ****************************************************************************************/
+
+#ifndef __OPENSPACE_MODULE_BASE___RENDERABLEDISTANCELABEL___H__
+#define __OPENSPACE_MODULE_BASE___RENDERABLEDISTANCELABEL___H__
+
+#include <modules/base/rendering/renderablelabel.h>
+
+#include <openspace/properties/optionproperty.h>
+#include <openspace/properties/scalar/intproperty.h>
+#include <openspace/properties/stringproperty.h>
+
+namespace openspace {
+
+namespace documentation { struct Documentation; }
+
+class RenderableDistanceLabel : public RenderableLabel {
+public:
+     RenderableDistanceLabel(const ghoul::Dictionary& dictionary);
+
+     void update(const UpdateData& data) override;
+     static documentation::Documentation Documentation();
+
+private:
+     properties::StringProperty _nodelineId;
+     properties::OptionProperty _distanceUnit;
+     properties::StringProperty _customUnitDescriptor;
+     properties::IntProperty _precision;
+     bool _errorThrown = false;
+};
+
+} // namespace openspace
+
+#endif // __OPENSPACE_MODULE_BASE___RENDERABLEDISTANCELABEL___H__

modules/base/rendering/renderablelabel.h

@@ -73,6 +73,8 @@ public:
 protected:
     properties::OptionProperty _blendMode;
 
+    properties::StringProperty _text;
+
     float unit(int unit) const;
 
     std::string_view toString(int unit) const;
@@ -92,8 +94,6 @@ private:
     properties::FloatProperty _size;
     properties::IVec2Property _minMaxSize;
 
-    properties::StringProperty _text;
-
     properties::BoolProperty _enableFadingEffect;
     properties::Vec2Property _fadeWidths;
     properties::Vec2Property _fadeDistances;

modules/base/rendering/renderablemodel.cpp

@@ -319,19 +319,11 @@ RenderableModel::RenderableModel(const ghoul::Dictionary& dictionary)
             const std::string stringUnit = std::get<std::string>(*p.modelScale);
 
             // Find matching unit name in list of supported unit names
-            DistanceUnit distanceUnit;
-            bool wasFound = false;
-            for (int i = 0; i < DistanceUnitNamesSingular.size(); ++i) {
-                if (stringUnit == DistanceUnitNamesSingular[i]) {
-                    wasFound = true;
-                    distanceUnit = DistanceUnits[i];
-                }
-            }
-
-            if (wasFound) {
+            try {
+                DistanceUnit distanceUnit = distanceUnitFromString(stringUnit);
                 _modelScale = toMeter(distanceUnit);
             }
-            else {
+            catch (const ghoul::MissingCaseException& e) {
                 std::string message = std::format("The given unit name '{}' does not "
                     "match any currently supported unit names", stringUnit);
                 LERROR(message);

modules/base/rendering/renderablenodeline.cpp

@@ -114,6 +114,13 @@ namespace {
         return diffPos;
     }
 
+    // This `Renderable` connects two scene graph nodes by drawing a line between them.
+    // The line will update dynamically if the position of the nodes change.
+    //
+    // One use case for the `RenderableNodeLine` is to visualize the distance between two
+    // objects. For this, a [RenderableDistanceLabel](#base_renderable_distancelabel) can
+    // also be added to show the distance as a number. That renderable is designed to show
+    // the distance between the start and end node for a given `RenderableNodeLine`.
     struct [[codegen::Dictionary(RenderableNodeLine)]] Parameters {
         // [[codegen::verbatim(StartNodeInfo.description)]]
         std::optional<std::string> startNode [[codegen::identifier()]];
@@ -142,7 +149,7 @@ namespace {
 namespace openspace {
 
 documentation::Documentation RenderableNodeLine::Documentation() {
-    return codegen::doc<Parameters>("base_renderable_renderablenodeline");
+    return codegen::doc<Parameters>("base_renderable_nodeline");
 }
 
 RenderableNodeLine::RenderableNodeLine(const ghoul::Dictionary& dictionary)