chore!: rename BinningValue to AxisDirection (acts-project#4005)

This PR supersede acts-project#3826 by encapsulating only the move of `BinningValue`
to `AxisDirection` and move it into the renamed `AxisDefinitions.hpp`.

This will allow to keep the same enums once the `BinUtility`
infrastructure is gone.

For Json files, a legacy reading mode is implemented.

--- END COMMIT MESSAGE ---

Any further description goes here, @-mentions are ok here!

- Use a *conventional commits* prefix: [quick
summary](https://www.conventionalcommits.org/en/v1.0.0/#summary)
- We mostly use `feat`, `fix`, `refactor`, `docs`, `chore` and `build`
types.
- A milestone will be assigned by one of the maintainers

Author: asalzburger

Core/include/Acts/Detector/Blueprint.hpp

@@ -13,7 +13,7 @@
 #include "Acts/Detector/ProtoBinning.hpp"
 #include "Acts/Geometry/Extent.hpp"
 #include "Acts/Geometry/VolumeBounds.hpp"
-#include "Acts/Utilities/BinningData.hpp"
+#include "Acts/Utilities/AxisDefinitions.hpp"
 #include "Acts/Utilities/StringHelpers.hpp"
 
 #include <map>
@@ -47,11 +47,11 @@ struct Node final {
   /// @param t the transform
   /// @param bt the boundary type
   /// @param bv the boundary values
-  /// @param bss the binning values
+  /// @param bss the axis directions for the binning
   /// @param cs the children of the node
   /// @param e the estimated extent of the node (optional)
   Node(const std::string& n, const Transform3& t, VolumeBounds::BoundsType bt,
-       const std::vector<double>& bv, const std::vector<BinningValue>& bss,
+       const std::vector<double>& bv, const std::vector<AxisDirection>& bss,
        std::vector<std::unique_ptr<Node>> cs = {}, const Extent& e = Extent())
       : name(n),
         transform(t),
@@ -96,7 +96,7 @@ struct Node final {
   /// Branch definitions: children
   std::vector<std::unique_ptr<Node>> children = {};
   /// Branch definition binning
-  std::vector<BinningValue> binning = {};
+  std::vector<AxisDirection> binning = {};
 
   /// Portal proto material binning
   std::map<unsigned int, BinningDescription> portalMaterialBinning = {};

Core/include/Acts/Detector/CuboidalContainerBuilder.hpp

@@ -12,7 +12,7 @@
 #include "Acts/Detector/DetectorComponents.hpp"
 #include "Acts/Detector/interface/IDetectorComponentBuilder.hpp"
 #include "Acts/Geometry/GeometryContext.hpp"
-#include "Acts/Utilities/BinningType.hpp"
+#include "Acts/Utilities/AxisDefinitions.hpp"
 #include "Acts/Utilities/Logger.hpp"
 
 #include <memory>
@@ -36,8 +36,8 @@ class IGeometryIdGenerator;
 /// @note the builder expects a fully consistent set of sub volume builders
 /// that will be executed in a chain
 ///
-/// @note allowed BinningValue(s) for the cuboid container builder are
-/// {binX}, {binY}, {binZ}.
+/// @note allowed AxisDirection(s) for the cuboid container builder are
+/// {AxisX}, {AxisY}, {AxisZ}.
 ///
 /// @note Connecting containers isn't functional yet due to the underlying
 /// issues in the CuboidDetectorHelper
@@ -48,8 +48,8 @@ class CuboidalContainerBuilder : public IDetectorComponentBuilder {
   struct Config {
     /// The configured volume builders
     std::vector<std::shared_ptr<const IDetectorComponentBuilder>> builders = {};
-    /// Binning prescription of attachment
-    BinningValue binning{};
+    /// Axis direction for the binning
+    AxisDirection binning{};
     /// The root volume finder
     std::shared_ptr<const IRootVolumeFinderBuilder> rootVolumeFinderBuilder =
         nullptr;

Core/include/Acts/Detector/CylindricalContainerBuilder.hpp

@@ -13,7 +13,7 @@
 #include "Acts/Detector/ProtoBinning.hpp"
 #include "Acts/Detector/interface/IDetectorComponentBuilder.hpp"
 #include "Acts/Geometry/GeometryContext.hpp"
-#include "Acts/Utilities/BinningType.hpp"
+#include "Acts/Utilities/AxisDefinitions.hpp"
 #include "Acts/Utilities/Logger.hpp"
 
 #include <map>
@@ -39,17 +39,17 @@ class IGeometryIdGenerator;
 /// @note the builder expects a fully consistent set of sub volume builders
 /// that will be executed in a chain
 ///
-/// @note allowed BinningValue(s) for the cylindrical container builder are
-/// {binZ}, {binR}, {binPhi}, {binZ, binR}, whereas the last option indicates
-/// a wrapping setup.
+/// @note allowed AxisDirection(s) for the cylindrical container builder are
+/// {AxisZ}, {AxisR}, {AxisPhi}, {AxisZ, AxisR}, whereas the last option
+/// indicates a wrapping setup.
 class CylindricalContainerBuilder : public IDetectorComponentBuilder {
  public:
   /// Nested configuration object
   struct Config {
     /// The configured volume builders
     std::vector<std::shared_ptr<const IDetectorComponentBuilder>> builders = {};
-    /// Binning prescription of attachment
-    std::vector<BinningValue> binning = {};
+    /// The axis direction for the binning
+    std::vector<AxisDirection> binning = {};
     /// The root volume finder
     std::shared_ptr<const IRootVolumeFinderBuilder> rootVolumeFinderBuilder =
         nullptr;

Core/include/Acts/Detector/IndexedRootVolumeFinderBuilder.hpp

@@ -11,7 +11,7 @@
 #include "Acts/Detector/interface/IRootVolumeFinderBuilder.hpp"
 #include "Acts/Geometry/GeometryContext.hpp"
 #include "Acts/Navigation/PortalNavigation.hpp"
-#include "Acts/Utilities/BinningData.hpp"
+#include "Acts/Utilities/AxisDefinitions.hpp"
 
 #include <memory>
 #include <vector>
@@ -26,7 +26,7 @@ class IndexedRootVolumeFinderBuilder final : public IRootVolumeFinderBuilder {
  public:
   /// @brief Constructor with binning casts
   /// @param binning the cast values for the grid binning
-  IndexedRootVolumeFinderBuilder(std::vector<Acts::BinningValue> binning);
+  IndexedRootVolumeFinderBuilder(std::vector<Acts::AxisDirection> binning);
 
   /// The virtual interface definition for root volume finder builders
   ///
@@ -40,7 +40,7 @@ class IndexedRootVolumeFinderBuilder final : public IRootVolumeFinderBuilder {
       const final;
 
  private:
-  std::vector<Acts::BinningValue> m_casts;
+  std::vector<Acts::AxisDirection> m_casts;
 };
 
 }  // namespace Acts::Experimental

Core/include/Acts/Detector/KdtSurfacesProvider.hpp

@@ -12,7 +12,7 @@
 #include "Acts/Detector/detail/ReferenceGenerators.hpp"
 #include "Acts/Detector/interface/ISurfacesProvider.hpp"
 #include "Acts/Surfaces/Surface.hpp"
-#include "Acts/Utilities/BinningData.hpp"
+#include "Acts/Utilities/AxisDefinitions.hpp"
 #include "Acts/Utilities/KDTree.hpp"
 
 #include <array>
@@ -50,7 +50,7 @@ class KdtSurfaces {
   /// @param rgen the reference point generator
   KdtSurfaces(const GeometryContext& gctx,
               const std::vector<std::shared_ptr<Surface>>& surfaces,
-              const std::array<BinningValue, kDIM>& casts,
+              const std::array<AxisDirection, kDIM>& casts,
               const reference_generator& rgen =
                   detail::PolyhedronReferenceGenerator<1u, false>{})
       : m_kdt(nullptr), m_casts(casts), m_rGenerator(rgen) {
@@ -113,7 +113,7 @@ class KdtSurfaces {
   std::unique_ptr<KDTS> m_kdt = nullptr;
 
   /// Cast values that turn a global position to lookup position
-  std::array<BinningValue, kDIM> m_casts = {};
+  std::array<AxisDirection, kDIM> m_casts = {};
 
   /// Helper to generate reference points for filling
   reference_generator m_rGenerator;

Core/include/Acts/Detector/ProtoBinning.hpp

@@ -10,9 +10,8 @@
 
 #include "Acts/Definitions/Algebra.hpp"
 #include "Acts/Definitions/Common.hpp"
-#include "Acts/Utilities/AxisFwd.hpp"
+#include "Acts/Utilities/AxisDefinitions.hpp"
 #include "Acts/Utilities/BinUtility.hpp"
-#include "Acts/Utilities/BinningType.hpp"
 
 #include <sstream>
 #include <stdexcept>
@@ -27,8 +26,8 @@ namespace Acts::Experimental {
 /// only for convenience that the binning can be defined and then
 /// translated into concrete axis types
 struct ProtoBinning {
-  /// The binning value of this
-  BinningValue binValue;
+  /// The axis direction
+  AxisDirection axisDir;
   /// The axis type: equidistant or variable
   Acts::AxisType axisType = Acts::AxisType::Equidistant;
   /// The axis boundary type: Open, Bound or Closed
@@ -42,13 +41,13 @@ struct ProtoBinning {
 
   /// Convenience constructors - for variable binning
   ///
-  /// @param bValue the value/cast in which this is binned
+  /// @param aDir the value/cast in which this is binned
   /// @param bType the axis boundary type
   /// @param e the bin edges (variable binning)
   /// @param exp the expansion (in bins)
-  ProtoBinning(BinningValue bValue, Acts::AxisBoundaryType bType,
+  ProtoBinning(AxisDirection aDir, Acts::AxisBoundaryType bType,
                const std::vector<double>& e, std::size_t exp = 0u)
-      : binValue(bValue),
+      : axisDir(aDir),
         axisType(Acts::AxisType::Variable),
         boundaryType(bType),
         edges(e),
@@ -61,18 +60,18 @@ struct ProtoBinning {
 
   /// Convenience constructors - for equidistant binning
   ///
-  /// @param bValue the value/cast in which this is binned
+  /// @param aDir the value/cast in which this is binned
   /// @param bType the axis boundary type
   /// @param minE the lowest edge of the binning
   /// @param maxE the highest edge of the binning
   /// @param nbins the number of bins
   /// @param exp the expansion (in bins)
-  ProtoBinning(BinningValue bValue, Acts::AxisBoundaryType bType, double minE,
+  ProtoBinning(AxisDirection aDir, Acts::AxisBoundaryType bType, double minE,
                double maxE, std::size_t nbins, std::size_t exp = 0u)
-      : binValue(bValue), boundaryType(bType), expansion(exp) {
+      : axisDir(aDir), boundaryType(bType), expansion(exp) {
     if (minE >= maxE) {
-      std::string msg = "ProtoBinning: Invalid binning for value '";
-      msg += binningValueName(bValue);
+      std::string msg = "ProtoBinning: Invalid axis range for direction '";
+      msg += axisDirectionName(axisDir);
       msg += "', min edge (" + std::to_string(minE) + ") ";
       msg += " needs to be smaller than max edge (";
       msg += std::to_string(maxE) + ").";
@@ -96,13 +95,13 @@ struct ProtoBinning {
   /// when the actual extent is not yet evaluated, only works
   /// for equidistant binning obviously
   ///
-  /// @param bValue the value/cast in which this is binned
+  /// @param aDir the value/cast in which this is binned
   /// @param bType the axis boundary type
   /// @param nbins the number of bins
   /// @param exp the expansion (in bins)
-  ProtoBinning(BinningValue bValue, Acts::AxisBoundaryType bType,
+  ProtoBinning(AxisDirection aDir, Acts::AxisBoundaryType bType,
                std::size_t nbins, std::size_t exp = 0u)
-      : binValue(bValue),
+      : axisDir(aDir),
         boundaryType(bType),
         edges(nbins + 1, 0.),
         expansion(exp),
@@ -115,7 +114,7 @@ struct ProtoBinning {
   std::string toString() const {
     std::stringstream ss;
     ss << "ProtoBinning: " << bins() << " bins in "
-       << binningValueName(binValue);
+       << axisDirectionName(axisDir);
     ss << (axisType == Acts::AxisType::Variable ? ", variable "
                                                 : ", equidistant ");
     if (!autorange) {
@@ -165,12 +164,12 @@ struct BinningDescription {
                                                           : Acts::closed;
       if (b.axisType == Acts::AxisType::Equidistant) {
         binUtility += BinUtility(b.bins(), b.edges.front(), b.edges.back(),
-                                 bOption, b.binValue);
+                                 bOption, b.axisDir);
       } else {
         std::vector<float> edges;
         std::for_each(b.edges.begin(), b.edges.end(),
                       [&](double edge) { edges.push_back(edge); });
-        binUtility += BinUtility(edges, bOption, b.binValue);
+        binUtility += BinUtility(edges, bOption, b.axisDir);
       }
     }
     return binUtility;

Core/include/Acts/Detector/ProtoDetector.hpp

@@ -98,12 +98,12 @@ struct 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);
+  /// @param aDir the axis direction that is propagated
+  void propagateMinDown(AxisDirection aDir);
 
   /// Extend the tracking volume with its own constituents
-  /// @param bValue the binning value that is propagated
-  void propagateMaxDown(BinningValue bValue);
+  /// @param aDir the axis direction that is propagated
+  void propagateMaxDown(AxisDirection aDir);
 
   /// Constrain the daughter volumes with this volume
   ///

Core/include/Acts/Detector/ProtoSupport.hpp

@@ -12,7 +12,7 @@
 #include "Acts/Definitions/Common.hpp"
 #include "Acts/Detector/ProtoBinning.hpp"
 #include "Acts/Surfaces/Surface.hpp"
-#include "Acts/Utilities/AxisFwd.hpp"
+#include "Acts/Utilities/AxisDefinitions.hpp"
 #include "Acts/Utilities/BinningData.hpp"
 
 #include <optional>
@@ -55,7 +55,7 @@ struct ProtoSupport {
   /// The internal constraint would overwrite the volume one in order to allow
   /// support surfaces to be fitted from global volume extensions to the
   /// actually contained internal objects.
-  std::vector<BinningValue> internalConstraints = {};
+  std::vector<AxisDirection> internalConstraints = {};
 
   // Building instructions 2 (surface is provided):
 
@@ -69,7 +69,7 @@ struct ProtoSupport {
   unsigned int splits = 1u;
 
   /// Planar placement (only valid for planar support surfaces)
-  BinningValue pPlacement = BinningValue::binZ;
+  AxisDirection pPlacement = AxisDirection::AxisZ;
 
   /// Indicate if the support surface(s) should always be addressed in
   /// navigation

Core/include/Acts/Detector/detail/CuboidalDetectorHelper.hpp

@@ -33,7 +33,7 @@ namespace detail::CuboidalDetectorHelper {
 ///
 /// @param gctx The geometry context
 /// @param volumes the volumes
-/// @param bValue the binning value  (allowed are binX, binY, binZ)
+/// @param bValue the binning value  (allowed are AxisX, AxisY, AxisZ)
 /// @param selectedOnly switch only selected boundaries
 /// @param logLevel is the screen logging level
 ///
@@ -43,15 +43,15 @@ namespace detail::CuboidalDetectorHelper {
 /// @return a proto container with the outside portals
 DetectorComponent::PortalContainer connect(
     const GeometryContext& gctx,
-    std::vector<std::shared_ptr<DetectorVolume>>& volumes, BinningValue bValue,
+    std::vector<std::shared_ptr<DetectorVolume>>& volumes, AxisDirection bValue,
     const std::vector<unsigned int>& selectedOnly = {},
     Acts::Logging::Level logLevel = Acts::Logging::INFO);
 
 /// @brief Connect containers given a binning value
 ///
 /// @param gctx The geometry context
 /// @param containers the containers
-/// @param bValue the binning value  (allowed are binX, binY, binZ)
+/// @param bValue the binning value  (allowed are AxisX, AxisY, AxisZ)
 /// @param selectedOnly switch only selected boundaries
 /// @param logLevel is the screen logging level
 ///
@@ -62,7 +62,7 @@ DetectorComponent::PortalContainer connect(
 DetectorComponent::PortalContainer connect(
     const GeometryContext& gctx,
     const std::vector<DetectorComponent::PortalContainer>& containers,
-    BinningValue bValue, const std::vector<unsigned int>& selectedOnly = {},
+    AxisDirection bValue, const std::vector<unsigned int>& selectedOnly = {},
     Acts::Logging::Level logLevel = Acts::Logging::INFO);
 
 /// @brief Helper method to extract r,z,phi boundaries for

Core/include/Acts/Detector/detail/DetectorVolumeConsistency.hpp

@@ -48,7 +48,7 @@ void checkRotationAlignment(
 std::vector<double> checkCenterAlignment(
     const GeometryContext& gctx,
     const std::vector<std::shared_ptr<Experimental::DetectorVolume>>& volumes,
-    BinningValue axisValue);
+    AxisDirection axisValue);
 
 }  // namespace detail::DetectorVolumeConsistency
 }  // namespace Acts::Experimental