refactor(geo): Geometry visualization update (acts-project#3681)

Blocked by:
- acts-project#3675

Related to acts-project#3502

---

The most significant changes include adding visualization methods to `TrackingGeometry` and `TrackingVolume`, updating the `Surface` class, and enhancing the `IVisualization3D` interface. Additionally, the `ObjVisualization3D` class has been refactored, and new default view configurations have been defined.

### Visualization Enhancements:
* [`TrackingGeometry.hpp`](diffhunk://#diff-cc497a4ee5032615db90ef065e9466279a0fde38fbd201840a32d783d3d6ec4aR148-R158): Added a `visualize` method to enable visualization of tracking geometry, including substructures. (`[Core/include/Acts/Geometry/TrackingGeometry.hppR148-R158](diffhunk://#diff-cc497a4ee5032615db90ef065e9466279a0fde38fbd201840a32d783d3d6ec4aR148-R158)`)
* [`TrackingVolume.hpp`](diffhunk://#diff-835fb549fb77cdaa632a4e2131c8dc17ad4973ab3f1600a4608582b706a3f68eR326-R344): Added methods to visualize tracking volumes and manage surfaces, including `visualize`, `surfaces`, and `addSurface`. (`[[1]](diffhunk://#diff-835fb549fb77cdaa632a4e2131c8dc17ad4973ab3f1600a4608582b706a3f68eR326-R344)`, `[[2]](diffhunk://#diff-835fb549fb77cdaa632a4e2131c8dc17ad4973ab3f1600a4608582b706a3f68eR477-R487)`, `[[3]](diffhunk://#diff-835fb549fb77cdaa632a4e2131c8dc17ad4973ab3f1600a4608582b706a3f68eR550)`)

### Interface Updates:
* [`IVisualization3D.hpp`](diffhunk://#diff-c56ccee98d351daf6ac595cd265d30716a594ceb74030138411595aca66fdc39R75-R80): Introduced a destructor and a new `object` method to start a new object context. (`[Core/include/Acts/Visualization/IVisualization3D.hppR75-R80](diffhunk://#diff-c56ccee98d351daf6ac595cd265d30716a594ceb74030138411595aca66fdc39R75-R80)`)
* [`ObjVisualization3D.hpp`](diffhunk://#diff-fab69ace861a3e5d8fc173e8627732777a5fdd52703e9e162a14db563ea56a2aL29-R32): Refactored to use `double` as the value type and added support for object contexts. (`[[1]](diffhunk://#diff-fab69ace861a3e5d8fc173e8627732777a5fdd52703e9e162a14db563ea56a2aL29-R32)`, `[[2]](diffhunk://#diff-fab69ace861a3e5d8fc173e8627732777a5fdd52703e9e162a14db563ea56a2aR76-R102)`)

### Configuration and Defaults:
* [`ViewConfig.hpp`](diffhunk://#diff-e403e98244e75d6b7d32864417c37619de6becee73f53415b733073f655f0929R114-R117): Defined new default view configurations for surfaces, portals, volumes, and other elements. (`[[1]](diffhunk://#diff-e403e98244e75d6b7d32864417c37619de6becee73f53415b733073f655f0929R114-R117)`, `[[2]](diffhunk://#diff-e403e98244e75d6b7d32864417c37619de6becee73f53415b733073f655f0929R139-R146)`)

### Codebase Cleanup:
* Removed obsolete and redundant code from `ObjVisualization3D.ipp`. (`[Core/include/Acts/Visualization/detail/ObjVisualization3D.ippL1-L179](diffhunk://#diff-29bbb6e8cfcb388c51d1e88237dd0c7d582762d7e05a0ec12278bdc336b0aaa1L1-L179)`)

Core/include/Acts/Geometry/TrackingGeometry.hpp

@@ -145,6 +145,17 @@ class TrackingGeometry {
   const std::unordered_map<GeometryIdentifier, const Surface*>&
   geoIdSurfaceMap() const;
 
+  /// Visualize a tracking geometry including substructure
+  /// @param helper The visualization helper that implement the output
+  /// @param gctx The geometry context
+  /// @param viewConfig Global view config
+  /// @param portalViewConfig View config for portals
+  /// @param sensitiveViewConfig View configuration for sensitive surfaces
+  void visualize(IVisualization3D& helper, const GeometryContext& gctx,
+                 const ViewConfig& viewConfig = s_viewVolume,
+                 const ViewConfig& portalViewConfig = s_viewPortal,
+                 const ViewConfig& sensitiveViewConfig = s_viewSensitive) const;
+
  private:
   // the known world
   std::shared_ptr<TrackingVolume> m_world;

Core/include/Acts/Geometry/TrackingVolume.hpp

@@ -26,6 +26,7 @@
 #include "Acts/Utilities/BinnedArray.hpp"
 #include "Acts/Utilities/Logger.hpp"
 #include "Acts/Utilities/TransformRange.hpp"
+#include "Acts/Visualization/ViewConfig.hpp"
 
 #include <cstddef>
 #include <memory>
@@ -486,6 +487,17 @@ class TrackingVolume : public Volume {
   ///  - positiveFaceXY
   GlueVolumesDescriptor& glueVolumesDescriptor();
 
+  /// Produces a 3D visualization of this tracking volume
+  /// @param helper The visualization helper describing the output format
+  /// @param gctx The geometry context
+  /// @param viewConfig The view configuration
+  /// @param portalViewConfig View configuration for portals
+  /// @param sensitiveViewConfig View configuration for sensitive surfaces
+  void visualize(IVisualization3D& helper, const GeometryContext& gctx,
+                 const ViewConfig& viewConfig,
+                 const ViewConfig& portalViewConfig,
+                 const ViewConfig& sensitiveViewConfig) const;
+
  private:
   void connectDenseBoundarySurfaces(
       MutableTrackingVolumeVector& confinedDenseVolumes);

Core/include/Acts/Geometry/Volume.hpp

@@ -122,7 +122,7 @@ class Volume : public GeometryObject {
   /// @param gctx The geometry context
   /// @param viewConfig The view configuration
   void visualize(IVisualization3D& helper, const GeometryContext& gctx,
-                 const ViewConfig& viewConfig = {}) const;
+                 const ViewConfig& viewConfig) const;
 
  protected:
   Transform3 m_transform;

Core/include/Acts/Surfaces/Surface.hpp

@@ -482,7 +482,7 @@ class Surface : public virtual GeometryObject,
       const GeometryContext& gctx, const Vector3& position) const = 0;
 
   void visualize(IVisualization3D& helper, const GeometryContext& gctx,
-                 const ViewConfig& viewConfig = {}) const;
+                 const ViewConfig& viewConfig = s_viewSurface) const;
 
  protected:
   /// Output Method for std::ostream, to be overloaded by child classes

Core/include/Acts/Visualization/GeometryView3D.hpp

@@ -31,12 +31,6 @@ class DetectorVolume;
 class Portal;
 }  // namespace Experimental
 
-static const ViewConfig s_viewSensitive;
-static const ViewConfig s_viewPassive;
-static const ViewConfig s_viewVolume;
-static const ViewConfig s_viewGrid;
-static const ViewConfig s_viewLine;
-
 struct GeometryView3D {
   /// Helper method to draw Polyhedron objects
   ///

Core/include/Acts/Visualization/IVisualization3D.hpp

@@ -72,6 +72,12 @@ class IVisualization3D {
   /// Remove all contents of this helper
   ///
   virtual void clear() = 0;
+
+  virtual ~IVisualization3D() = default;
+
+  /// Start a new object context
+  /// @param name The name of the object
+  virtual void object(const std::string& name) = 0;
 };
 
 /// Overload of the << operator to facilitate writing to streams.

Core/include/Acts/Visualization/ObjVisualization3D.hpp

@@ -12,12 +12,8 @@
 #include "Acts/Visualization/IVisualization3D.hpp"
 #include "Acts/Visualization/ViewConfig.hpp"
 
-#include <array>
 #include <filesystem>
-#include <fstream>
-#include <iomanip>
 #include <map>
-#include <sstream>
 #include <string>
 #include <vector>
 
@@ -26,14 +22,10 @@ namespace Acts {
 /// This helper produces output in the OBJ format. Note that colors are not
 /// supported in this implementation.
 ///
-template <typename T = double>
 class ObjVisualization3D : public IVisualization3D {
  public:
-  static_assert(std::is_same_v<T, double> || std::is_same_v<T, float>,
-                "Use either double or float");
-
   /// Stored value type, should be double or float
-  using ValueType = T;
+  using ValueType = double;
 
   /// Type of a vertex based on the value type
   using VertexType = Eigen::Matrix<ValueType, 3, 1>;
@@ -77,22 +69,32 @@ class ObjVisualization3D : public IVisualization3D {
   ///  @copydoc Acts::IVisualization3D::clear()
   void clear() final;
 
+  /// Start a new object context with a name
+  /// @param name The name of the object
+  void object(const std::string& name) final;
+
  private:
+  struct Object {
+    std::string name;
+    std::vector<VertexType> vertices{};
+    std::vector<FaceType> faces{};
+    std::vector<LineType> lines{};
+
+    /// The object data to be written
+    /// Map of colors to be written at given index position
+    std::map<std::size_t, Color> lineColors{};
+    std::map<std::size_t, Color> vertexColors{};
+    std::map<std::size_t, Color> faceColors{};
+  };
+
+  Object& object();
+  const Object& object() const;
+
   /// The output parameters
   unsigned int m_outputPrecision = 4;
   double m_outputScalor = 1.;
-  /// The object data to be written
-  std::vector<VertexType> m_vertices;
-  std::vector<FaceType> m_faces;
-  std::vector<LineType> m_lines;
-  /// Map of colors to be written at given index position
-  std::map<std::size_t, Color> m_lineColors;
-  std::map<std::size_t, Color> m_vertexColors;
-  std::map<std::size_t, Color> m_faceColors;
-};
 
-#ifndef DOXYGEN
-#include "detail/ObjVisualization3D.ipp"
-#endif
+  std::vector<Object> m_objects;
+};
 
 }  // namespace Acts

Core/include/Acts/Visualization/PlyVisualization3D.hpp

@@ -60,6 +60,10 @@ class PlyVisualization3D : public IVisualization3D {
   /// @copydoc Acts::IVisualization3D::clear()
   void clear() final;
 
+  void object(const std::string& /*name*/) final {
+    // Unimplemented
+  }
+
  private:
   std::vector<std::pair<VertexType, Color>> m_vertices;
   std::vector<FaceType> m_faces;

Core/include/Acts/Visualization/ViewConfig.hpp

@@ -10,7 +10,7 @@
 
 #include <array>
 #include <filesystem>
-#include <string>
+#include <string_view>
 
 namespace Acts {
 
@@ -49,17 +49,31 @@ struct Color {
   constexpr Color(double r, double g, double b)
       : Color{std::array<double, 3>{r, g, b}} {}
 
+ private:
+  constexpr static int hexToInt(std::string_view hex) {
+    constexpr auto hexCharToInt = [](char c) {
+      if (c >= '0' && c <= '9') {
+        return c - '0';
+      } else if (c >= 'a' && c <= 'f') {
+        return c - 'a' + 10;
+      } else if (c >= 'A' && c <= 'F') {
+        return c - 'A' + 10;
+      } else {
+        throw std::invalid_argument("Invalid hex character");
+      }
+    };
+
+    int value = 0;
+    for (char c : hex) {
+      value = (value << 4) + hexCharToInt(c);
+    }
+    return value;
+  };
+
+ public:
   /// Constructor from hex string. The expected format is `#RRGGBB`
   /// @param hex The hex string
   constexpr explicit Color(std::string_view hex) {
-    auto hexToInt = [](std::string_view hexStr) {
-      int value = 0;
-      std::stringstream ss;
-      ss << std::hex << hexStr;
-      ss >> value;
-      return value;
-    };
-
     if (hex[0] == '#' && hex.size() == 7) {
       rgb[0] = hexToInt(hex.substr(1, 2));  // Extract R component
       rgb[1] = hexToInt(hex.substr(3, 2));  // Extract G component
@@ -85,7 +99,6 @@ struct Color {
   /// @param rhs The second color
   /// @return True if the colors are equal
   friend bool operator==(const Color& lhs, const Color& rhs) = default;
-
   /// Output stream operator
   /// @param os The output stream
   /// @param color The color to be printed
@@ -99,6 +112,10 @@ struct Color {
   std::array<int, 3> rgb{};
 };
 
+constexpr Color s_defaultSurfaceColor{"#0000aa"};
+constexpr Color s_defaultPortalColor{"#308c48"};
+constexpr Color s_defaultVolumColor{"#ffaa00"};
+
 /// @brief Struct to concentrate all visualization configurations
 /// in order to harmonize visualization interfaces
 struct ViewConfig {
@@ -120,4 +137,12 @@ struct ViewConfig {
   std::filesystem::path outputName = std::filesystem::path("");
 };
 
+static const ViewConfig s_viewSurface = {.color = {170, 170, 170}};
+static const ViewConfig s_viewPortal = {.color = Color{"#308c48"}};
+static const ViewConfig s_viewSensitive = {.color = {0, 180, 240}};
+static const ViewConfig s_viewPassive = {.color = {240, 280, 0}};
+static const ViewConfig s_viewVolume = {.color = {220, 220, 0}};
+static const ViewConfig s_viewGrid = {.color = {220, 0, 0}};
+static const ViewConfig s_viewLine = {.color = {0, 0, 220}};
+
 }  // namespace Acts