feat: Geant4 detector plugin, part 1 (#1758)

This PR does some preparation work for the purely Geant4 detectors.

It introduces:
  *  the `KDTreeTrackingGeometryBuilder` as described in the docs
* a `ProtoDetector` description similar to the `ProtoLayer` (the
`TGeoPlugin` should eventually also change to this)
  * adds some output formatting
* changes explicit construction of `CylinderLayer` and `DiscLayer` in
their respective `create(...)` method rather than the base class.

And it harmonises the evelope definitions between the duplicated
`ProtoLayer::envelope` and `Extent::envelope` - they were both the same,
once defined with `std::vector<std::pair<real,real>>` and once with
`std::array<std::array<real, . > .>`.

Core/include/Acts/Geometry/CuboidVolumeBuilder.hpp

@@ -72,11 +72,12 @@ class CuboidVolumeBuilder : public ITrackingVolumeBuilder {
     // Bins in Z direction
     size_t binsZ = 1;
     // Envelope in X (along layer normal)
-    std::pair<double, double> envelopeX{0, 0};
+    std::array<ActsScalar, 2u> envelopeX{0, 0};
     // Envelope in Y
-    std::pair<double, double> envelopeY{0, 0};
+    std::array<ActsScalar, 2u> envelopeY{0, 0};
     // Envelope in Z
-    std::pair<double, double> envelopeZ{0, 0};
+    std::array<ActsScalar, 2u> envelopeZ{0, 0};
+    // An optional rotation fo this
     std::optional<RotationMatrix3> rotation{std::nullopt};
   };
 

Core/include/Acts/Geometry/CylinderLayer.hpp

@@ -40,15 +40,15 @@ class CylinderLayer : public CylinderSurface, public Layer {
   /// @todo ApproachDescriptor to unique_ptr
   ///
   /// @return The return object is a shared poiter to the layer.
-  static MutableLayerPtr create(
+  static std::shared_ptr<CylinderLayer> create(
       const Transform3& transform,
       const std::shared_ptr<const CylinderBounds>& cbounds,
       std::unique_ptr<SurfaceArray> surfaceArray = nullptr,
       double thickness = 0., std::unique_ptr<ApproachDescriptor> ad = nullptr,
       LayerType laytyp = passive) {
-    return MutableLayerPtr(new CylinderLayer(transform, cbounds,
-                                             std::move(surfaceArray), thickness,
-                                             std::move(ad), laytyp));
+    return std::shared_ptr<CylinderLayer>(
+        new CylinderLayer(transform, cbounds, std::move(surfaceArray),
+                          thickness, std::move(ad), laytyp));
   }
 
   CylinderLayer(const CylinderLayer& cla) = delete;

Core/include/Acts/Geometry/DiscLayer.hpp

@@ -40,15 +40,15 @@ class DiscLayer : virtual public DiscSurface, public Layer {
   /// @todo move ApproachDescriptor to unqique_ptr
   ///
   /// @return a sharted pointer to the new layer
-  static MutableLayerPtr create(
+  static std::shared_ptr<DiscLayer> create(
       const Transform3& transform,
       const std::shared_ptr<const DiscBounds>& dbounds,
       std::unique_ptr<SurfaceArray> surfaceArray = nullptr,
       double thickness = 0., std::unique_ptr<ApproachDescriptor> ad = nullptr,
       LayerType laytyp = Acts::passive) {
-    return MutableLayerPtr(new DiscLayer(transform, dbounds,
-                                         std::move(surfaceArray), thickness,
-                                         std::move(ad), laytyp));
+    return std::shared_ptr<DiscLayer>(
+        new DiscLayer(transform, dbounds, std::move(surfaceArray), thickness,
+                      std::move(ad), laytyp));
   }
 
   DiscLayer() = delete;

Core/include/Acts/Geometry/Extent.hpp

@@ -19,6 +19,7 @@
 #include <array>
 #include <bitset>
 #include <ostream>
+#include <string>
 #include <vector>
 
 namespace Acts {
@@ -42,6 +43,12 @@ class Extent {
   /// Constructor with (optional) @param envelope
   Extent(const ExtentEnvelope& envelope = zeroEnvelopes);
 
+  /// Define a comparison operator
+  bool operator==(const Extent& e) const;
+
+  /// Define a comparison operator
+  bool operator!=(const Extent& e) const { return (not operator==(e)); }
+
   /// Extend with a position vertex
   ///
   /// @param vtx the vertex to be used for extending
@@ -88,6 +95,16 @@ class Extent {
               const std::vector<BinningValue>& bValues = s_binningValues,
               bool applyEnv = true);
 
+  /// Constrain an extent by another one, this is
+  /// - values that are already constrained are not touched
+  /// - values not constrained by @param rhs are not touched
+  /// - values that are constrained by the external one, but not
+  /// by the current one, are touched
+  ///
+  /// @param envelope an envelope applied to the constrained value
+  void addConstrain(const Extent& rhs,
+                    const ExtentEnvelope& envelope = zeroEnvelopes);
+
   /// Set a range for a dedicated binning value
   ///
   /// @param bValue the binning identification
@@ -181,8 +198,9 @@ class Extent {
   bool constrains(BinningValue bValue = binValues) const;
 
   /// Convert to output stream for screen output
-  /// @param sl [in,out] The output stream
-  std::ostream& toStream(std::ostream& sl) const;
+  ///
+  /// @param indent indentation for the screen display
+  std::string toString(const std::string& indent = "") const;
 
  private:
   /// A bitset that remembers the constraint values

Core/include/Acts/Geometry/KDTreeTrackingGeometryBuilder.hpp

@@ -0,0 +1,114 @@
+// This file is part of the Acts project.
+//
+// Copyright (C) 2022 CERN for the benefit of the Acts project
+//
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at http://mozilla.org/MPL/2.0/.
+
+#pragma once
+
+#include "Acts/Geometry/GeometryContext.hpp"
+#include "Acts/Geometry/ProtoDetector.hpp"
+#include "Acts/Geometry/TrackingGeometryBuilder.hpp"
+#include "Acts/Utilities/KDTree.hpp"
+#include "Acts/Utilities/Logger.hpp"
+
+#include <array>
+#include <memory>
+
+namespace Acts {
+
+class TrackingGeometry;
+class Layer;
+class LayerCreator;
+class Surface;
+
+/// A Tracking Geometry builder restricted to cylindrical geometries
+///
+/// It takes some helper tools and a vector of surface objects,
+/// together with a ProtoDetector description that is used to query a
+/// KDTree for contained surfaces in structures defined by the proto
+/// volume.
+class KDTreeTrackingGeometryBuilder : public ITrackingGeometryBuilder {
+ public:
+  /// Nested Configuration for this TrackingGeometryBuilder
+  struct Config {
+    /// The tracking volume helper for detector construction
+    std::shared_ptr<const ITrackingVolumeHelper> trackingVolumeHelper = nullptr;
+    /// The layer crator - for sensitives
+    std::shared_ptr<const LayerCreator> layerCreator = nullptr;
+    /// The created surfaces
+    std::vector<std::shared_ptr<Surface>> surfaces = {};
+    /// The proto tracking geometry description
+    ProtoDetector protoDetector;
+    /// Optional geometry identfier hook to be used during closure
+    /// @note Will be @b copied when calling the geometry building
+    GeometryIdentifierHook geometryIdentifierHook;
+    /// For screen output
+    std::string hierarchyIndent = "  ";
+  };
+
+  using SurfaceKDT =
+      KDTree<2u, std::shared_ptr<Surface>, ActsScalar, std::array, 100>;
+
+  /// Constructor
+  ///
+  /// @param [in] cfg is the configuration struct for this builder
+  /// @param [in] logger logging instance
+  KDTreeTrackingGeometryBuilder(
+      const Config& cfg,
+      std::unique_ptr<const Logger> logger =
+          getDefaultLogger("KDTreeTrackingGeometryBuilder", Logging::INFO));
+
+  /// TrackingGeometry Interface method
+  ///
+  /// @param gctx geometry context of that building call
+  ///
+  /// @return a unique pointer to a TrackingGeometry
+  std::unique_ptr<const TrackingGeometry> trackingGeometry(
+      const GeometryContext& gctx) const final;
+
+ private:
+  /// Configuration member
+  Config m_cfg;
+
+  /// Private access method to the logger
+  const Logger& logger() const { return *m_logger; }
+
+  /// the logging instance
+  std::unique_ptr<const Logger> m_logger;
+
+  /// Private construction cache
+  struct Cache {
+    size_t surfaceCounter = 0;
+  };
+
+  /// Translate a proto tracking volume into a Acts::TrackingVolume
+  ///
+  /// @param cCache is a cache used to extract the built detector elements
+  /// @param gctx is the current geometry context at building
+  /// @param kdt is the pre-filled kdt tree for the surface query
+  /// @param ptVolume the proto volume to be translated
+  /// @param indent is a screen output indentation
+  ///
+  /// @return a new tracking volume
+  std::shared_ptr<TrackingVolume> translateVolume(
+      Cache& cCache, const GeometryContext& gctx, const SurfaceKDT& kdt,
+      const ProtoVolume& ptVolume, const std::string& indent = "") const;
+
+  /// Translate a layer volume
+  ///
+  /// @param cCache is a cache used to extract the built detector elements
+  /// @param gctx is the current geometry context at building
+  /// @param kdt is the pre-filled kdt tree for the surface query
+  /// @param plVolume the proto volume representaion a layer to be translated
+  /// @param indent is a screen output indentation
+  ///
+  /// @return a new tracking volume
+  std::shared_ptr<const Layer> translateLayer(
+      Cache& cCache, const GeometryContext& gctx, const SurfaceKDT& kdt,
+      const ProtoVolume& plVolume, const std::string& indent = "") const;
+};
+
+}  // namespace Acts

Core/include/Acts/Geometry/ProtoDetector.hpp

@@ -0,0 +1,114 @@
+// This file is part of the Acts project.
+//
+// Copyright (C) 2022 CERN for the benefit of the Acts project
+//
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at http://mozilla.org/MPL/2.0/.
+
+#pragma once
+
+#include "Acts/Geometry/Extent.hpp"
+#include "Acts/Geometry/GeometryContext.hpp"
+#include "Acts/Surfaces/Surface.hpp"
+#include "Acts/Utilities/BinningData.hpp"
+
+#include <optional>
+#include <string>
+#include <vector>
+
+namespace Acts {
+
+/// A proto volume description being used to define an overall
+/// structure of either a TrackingVolume or Experimental::DetectorVolume
+struct ProtoVolume {
+  // Internal structure information
+  struct InternalStructure {
+    /// Possibility to provide a layer type information
+    Surface::SurfaceType layerType = Surface::SurfaceType::Other;
+    /// Possibility to provide a surface binning
+    std::vector<BinningData> surfaceBinning = {};
+  };
+
+  // Container structure information
+  struct ContainerStructure {
+    /// Internal structure container
+    std::vector<ProtoVolume> constituentVolumes = {};
+    /// The constituent binning if this a container
+    std::vector<BinningData> constituentBinning = {};
+    /// Layer container flag
+    bool layerContainer = false;
+  };
+
+  /// Name of the proto volume
+  std::string name = "";
+  /// The extent of this volume
+  Extent extent;
+
+  /// Information about internal structure
+  std::optional<InternalStructure> internal = std::nullopt;
+
+  /// Information about container structure
+  std::optional<ContainerStructure> container = std::nullopt;
+
+  /// Define an operator==
+  ///
+  /// @param ptVolume the proto volume to be checked
+  bool operator==(const ProtoVolume& ptVolume) const;
+
+  /// Harmonize the detector information, this can run in two
+  /// modes, steered by the @param legacy boolean
+  ///
+  /// The legacy mode prepares everything for `Acts::TrackingVolume`,
+  /// if off it creates a description for `Acts::Detector`.
+  void harmonize(bool legacy = true);
+
+  /// Extend the tracking volume with its own constituents,
+  /// upwards here means that extents are promoted to the mother
+  ///
+  /// @param ptVolume the protoVolume
+  void extendUp(ProtoVolume& ptVolume);
+
+  /// Extend the tracking volume with its own constituents
+  /// @param bValue the binning value that is propagated
+  void propagateMinDown(BinningValue bValue);
+
+  /// Extend the tracking volume with its own constituents
+  /// @param bValue the binning value that is propagated
+  void propagateMaxDown(BinningValue bValue);
+
+  /// Constrain the daughter volumes with this volume
+  ///
+  /// @param ptVolume is the proto volume from which the constrain
+  /// is taken
+  void constrainDown(const ProtoVolume& ptVolume);
+
+  /// Write the tracking volume to screen
+  /// @param indent the current indentation
+  std::string toString(const std::string& indent = "") const;
+};
+
+/// A proto detector description being used to define an overall
+/// structure of either a TrackingGeometry or Experimental::Detector
+struct ProtoDetector {
+  std::string name = "";
+  ProtoVolume worldVolume;
+
+  /// Harmonize the detector information, this can run in two
+  /// modes, steered by the @param legacy boolean
+  ///
+  /// The legacy mode prepares everything for `Acts::TrackingVolume`,
+  /// if off it creates a description for `Acts::Detector`.
+  ///
+  void harmonize(bool legacy = true) {
+    worldVolume.extendUp(worldVolume);
+    worldVolume.constrainDown(worldVolume);
+    worldVolume.harmonize(legacy);
+  }
+
+  /// Write the tracking volume to screen
+  /// @param indent the current indentation
+  std::string toString(const std::string& indent = "") const;
+};
+
+}  // namespace Acts

Core/include/Acts/Geometry/ProtoLayer.hpp

@@ -31,8 +31,7 @@ struct ProtoLayer {
   Extent extent;
 
   /// The envelope parameters
-  using Range = std::pair<double, double>;
-  std::vector<Range> envelope{(int)binValues, {0., 0.}};
+  ExtentEnvelope envelope = zeroEnvelopes;
 
   /// Constructor
   ///

Core/include/Acts/Surfaces/Surface.hpp

@@ -25,6 +25,8 @@
 #include "Acts/Utilities/Result.hpp"
 
 #include <memory>
+#include <ostream>
+#include <string>
 
 namespace Acts {
 
@@ -402,6 +404,11 @@ class Surface : public virtual GeometryObject,
   virtual std::ostream& toStream(const GeometryContext& gctx,
                                  std::ostream& sl) const;
 
+  /// Output into a std::string
+  ///
+  /// @param gctx The current geometry context object, e.g. alignment
+  std::string toString(const GeometryContext& gctx) const;
+
   /// Return properly formatted class name
   virtual std::string name() const = 0;