refactor: Move parameter transform helpers out of detail:: (acts-pr…

…oject#3070)

These helpers are extensively used outside Acts.

Core/include/Acts/EventData/GenericBoundTrackParameters.hpp

@@ -9,8 +9,8 @@
 #pragma once
 
 #include "Acts/Definitions/Tolerance.hpp"
+#include "Acts/EventData/TransformationHelpers.hpp"
 #include "Acts/EventData/detail/PrintParameters.hpp"
-#include "Acts/EventData/detail/TransformationFreeToBound.hpp"
 #include "Acts/Surfaces/Surface.hpp"
 #include "Acts/Utilities/UnitVectors.hpp"
 #include "Acts/Utilities/detail/periodic.hpp"
@@ -93,9 +93,9 @@ class GenericBoundTrackParameters {
       std::optional<CovarianceMatrix> cov,
       ParticleHypothesis particleHypothesis,
       ActsScalar tolerance = s_onSurfaceTolerance) {
-    Result<BoundVector> bound = detail::transformFreeToBoundParameters(
-        pos4.segment<3>(ePos0), pos4[eTime], dir, qOverP, *surface, geoCtx,
-        tolerance);
+    Result<BoundVector> bound =
+        transformFreeToBoundParameters(pos4.segment<3>(ePos0), pos4[eTime], dir,
+                                       qOverP, *surface, geoCtx, tolerance);
 
     if (!bound.ok()) {
       return bound.error();

Core/include/Acts/EventData/GenericCurvilinearTrackParameters.hpp

@@ -47,8 +47,7 @@ class GenericCurvilinearTrackParameters
                                     std::optional<CovarianceMatrix> cov,
                                     ParticleHypothesis particleHypothesis)
       : Base(Surface::makeShared<PlaneSurface>(pos4.segment<3>(ePos0), dir),
-             detail::transformFreeToCurvilinearParameters(pos4[eTime], dir,
-                                                          qOverP),
+             transformFreeToCurvilinearParameters(pos4[eTime], dir, qOverP),
              std::move(cov), std::move(particleHypothesis)) {}
 
   /// Construct from four-position, angles, and qOverP.
@@ -65,8 +64,8 @@ class GenericCurvilinearTrackParameters
                                     ParticleHypothesis particleHypothesis)
       : Base(Surface::makeShared<PlaneSurface>(
                  pos4.segment<3>(ePos0), makeDirectionFromPhiTheta(phi, theta)),
-             detail::transformFreeToCurvilinearParameters(pos4[eTime], phi,
-                                                          theta, qOverP),
+             transformFreeToCurvilinearParameters(pos4[eTime], phi, theta,
+                                                  qOverP),
              std::move(cov), std::move(particleHypothesis)) {}
 
   /// Converts a bound track parameter with a different hypothesis.

Core/include/Acts/EventData/MultiComponentTrackParameters.hpp

@@ -275,7 +275,7 @@ class MultiComponentCurvilinearTrackParameters
                            .position();
 
       BoundVector bv =
-          detail::transformFreeToCurvilinearParameters(pos4[eTime], dir, qop);
+          transformFreeToCurvilinearParameters(pos4[eTime], dir, qop);
 
       // Because of the projection this should never fail
       bv.template segment<2>(eBoundLoc0) =

Core/include/Acts/EventData/MultiTrajectoryHelpers.hpp

@@ -9,7 +9,7 @@
 #pragma once
 #include "Acts/EventData/MultiTrajectory.hpp"
 #include "Acts/EventData/TrackContainer.hpp"
-#include "Acts/EventData/detail/TransformationBoundToFree.hpp"
+#include "Acts/EventData/TransformationHelpers.hpp"
 #include "Acts/Geometry/Layer.hpp"
 #include "Acts/Geometry/TrackingVolume.hpp"
 #include "Acts/Surfaces/Surface.hpp"
@@ -146,8 +146,8 @@ VolumeTrajectoryStateContainer trajectoryState(
 template <typename track_state_proxy_t>
 FreeVector freeFiltered(const GeometryContext& gctx,
                         const track_state_proxy_t& trackStateProxy) {
-  return detail::transformBoundToFreeParameters(
-      trackStateProxy.referenceSurface(), gctx, trackStateProxy.filtered());
+  return transformBoundToFreeParameters(trackStateProxy.referenceSurface(),
+                                        gctx, trackStateProxy.filtered());
 }
 
 /// @brief Transforms the smoothed parameters from a @c TrackStateProxy to free
@@ -161,8 +161,8 @@ FreeVector freeFiltered(const GeometryContext& gctx,
 template <typename track_state_proxy_t>
 FreeVector freeSmoothed(const GeometryContext& gctx,
                         const track_state_proxy_t& trackStateProxy) {
-  return detail::transformBoundToFreeParameters(
-      trackStateProxy.referenceSurface(), gctx, trackStateProxy.smoothed());
+  return transformBoundToFreeParameters(trackStateProxy.referenceSurface(),
+                                        gctx, trackStateProxy.smoothed());
 }
 }  // namespace MultiTrajectoryHelpers
 

Core/include/Acts/EventData/detail/TransformationFreeToBound.hpp → Core/include/Acts/EventData/TransformationHelpers.hpp

@@ -1,6 +1,6 @@
 // This file is part of the Acts project.
 //
-// Copyright (C) 2016-2020 CERN for the benefit of the Acts project
+// Copyright (C) 2024 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
@@ -18,7 +18,15 @@ namespace Acts {
 
 class Surface;
 
-namespace detail {
+/// Transform bound track parameters into equivalent free track parameters.
+///
+/// @param surface Surface onto which the input parameters are bound
+/// @param geoCtx Geometry context for the local-to-global transformation
+/// @param boundParams Bound track parameters vector
+/// @return Equivalent free trackparameters vector
+FreeVector transformBoundToFreeParameters(const Surface& surface,
+                                          const GeometryContext& geoCtx,
+                                          const BoundVector& boundParams);
 
 /// Convert free track parameters to bound track parameters.
 ///
@@ -78,5 +86,4 @@ BoundVector transformFreeToCurvilinearParameters(ActsScalar time,
                                                  ActsScalar theta,
                                                  ActsScalar qOverP);
 
-}  // namespace detail
 }  // namespace Acts

Core/include/Acts/EventData/detail/CorrectedTransformationFreeToBound.hpp

@@ -11,7 +11,6 @@
 #include "Acts/Definitions/Algebra.hpp"
 #include "Acts/Definitions/Direction.hpp"
 #include "Acts/Definitions/TrackParametrization.hpp"
-#include "Acts/EventData/detail/TransformationFreeToBound.hpp"
 #include "Acts/Geometry/GeometryContext.hpp"
 #include "Acts/Surfaces/Surface.hpp"
 #include "Acts/Utilities/Logger.hpp"

Core/include/Acts/Propagator/AtlasStepper.hpp

@@ -14,8 +14,8 @@
 #include "Acts/Definitions/Algebra.hpp"
 #include "Acts/Definitions/Units.hpp"
 #include "Acts/EventData/TrackParameters.hpp"
+#include "Acts/EventData/TransformationHelpers.hpp"
 #include "Acts/EventData/detail/CorrectedTransformationFreeToBound.hpp"
-#include "Acts/EventData/detail/TransformationBoundToFree.hpp"
 #include "Acts/Geometry/GeometryContext.hpp"
 #include "Acts/MagneticField/MagneticFieldContext.hpp"
 #include "Acts/MagneticField/MagneticFieldProvider.hpp"
@@ -313,10 +313,10 @@ class AtlasStepper {
       const BoundSquareMatrix& cov, const Surface& surface,
       const double stepSize = std::numeric_limits<double>::max()) const {
     // Update the stepping state
-    update(state,
-           detail::transformBoundToFreeParameters(surface, state.geoContext,
-                                                  boundParams),
-           boundParams, cov, surface);
+    update(
+        state,
+        transformBoundToFreeParameters(surface, state.geoContext, boundParams),
+        boundParams, cov, surface);
     state.stepSize = ConstrainedStep(stepSize);
     state.pathAccumulated = 0.;
 

Core/include/Acts/Propagator/EigenStepper.ipp

@@ -6,7 +6,7 @@
 // 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/.
 
-#include "Acts/EventData/detail/TransformationBoundToFree.hpp"
+#include "Acts/EventData/TransformationHelpers.hpp"
 #include "Acts/Propagator/ConstrainedStep.hpp"
 #include "Acts/Propagator/detail/CovarianceEngine.hpp"
 
@@ -29,8 +29,8 @@ void Acts::EigenStepper<E, A>::resetState(State& state,
                                           const BoundSquareMatrix& cov,
                                           const Surface& surface,
                                           const double stepSize) const {
-  FreeVector freeParams = detail::transformBoundToFreeParameters(
-      surface, state.geoContext, boundParams);
+  FreeVector freeParams =
+      transformBoundToFreeParameters(surface, state.geoContext, boundParams);
 
   // Update the stepping state
   state.pars = freeParams;

Core/src/EventData/CMakeLists.txt

@@ -3,8 +3,7 @@ target_sources(
   PRIVATE
     PrintParameters.cpp
     TrackParameters.cpp
-    TransformationBoundToFree.cpp
-    TransformationFreeToBound.cpp
+    TransformationHelpers.cpp
     CorrectedTransformationFreeToBound.cpp
     TrackStatePropMask.cpp
     VectorMultiTrajectory.cpp

Core/src/EventData/CorrectedTransformationFreeToBound.cpp

@@ -9,7 +9,7 @@
 #include "Acts/EventData/detail/CorrectedTransformationFreeToBound.hpp"
 
 #include "Acts/Definitions/TrackParametrization.hpp"
-#include "Acts/EventData/detail/TransformationFreeToBound.hpp"
+#include "Acts/EventData/TransformationHelpers.hpp"
 #include "Acts/Surfaces/RegularSurface.hpp"
 #include "Acts/Surfaces/Surface.hpp"
 #include "Acts/Utilities/Intersection.hpp"
@@ -133,7 +133,7 @@ Acts::detail::CorrectedFreeToBoundTransformer::operator()(
   const auto& [paramsNom, mweightNom, cweightNom] = sampledFreeParams[0];
   // Transform the free to bound
   auto nominalRes =
-      detail::transformFreeToBoundParameters(paramsNom, surface, geoContext);
+      transformFreeToBoundParameters(paramsNom, surface, geoContext);
   // Not successful, fall back to nominal free to bound transformation
   if (!nominalRes.ok()) {
     ACTS_WARNING(
@@ -160,8 +160,8 @@ Acts::detail::CorrectedFreeToBoundTransformer::operator()(
     correctedFreeParams.segment<3>(eFreePos0) = intersection.position();
 
     // Transform the free to bound
-    auto result = detail::transformFreeToBoundParameters(correctedFreeParams,
-                                                         surface, geoContext);
+    auto result = transformFreeToBoundParameters(correctedFreeParams, surface,
+                                                 geoContext);
     // Not successful, fall back to nominal free to bound transformation
     if (!result.ok()) {
       ACTS_WARNING(

Core/src/EventData/TransformationFreeToBound.cpp → Core/src/EventData/TransformationHelpers.cpp

@@ -1,20 +1,46 @@
 // This file is part of the Acts project.
 //
-// Copyright (C) 2020 CERN for the benefit of the Acts project
+// Copyright (C) 2016-2020 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/.
 
-#include "Acts/EventData/detail/TransformationFreeToBound.hpp"
+#include "Acts/EventData/TransformationHelpers.hpp"
 
+#include "Acts/Definitions/Algebra.hpp"
 #include "Acts/Definitions/Common.hpp"
 #include "Acts/Surfaces/Surface.hpp"
 #include "Acts/Utilities/Result.hpp"
+#include "Acts/Utilities/UnitVectors.hpp"
 
 #include <algorithm>
 
-Acts::Result<Acts::BoundVector> Acts::detail::transformFreeToBoundParameters(
+Acts::FreeVector Acts::transformBoundToFreeParameters(
+    const Acts::Surface& surface, const GeometryContext& geoCtx,
+    const Acts::BoundVector& boundParams) {
+  // convert angles to global unit direction vector
+  Vector3 direction = makeDirectionFromPhiTheta(boundParams[eBoundPhi],
+                                                boundParams[eBoundTheta]);
+
+  // convert local position to global position vector
+  Vector2 local(boundParams[eBoundLoc0], boundParams[eBoundLoc1]);
+  Vector3 position = surface.localToGlobal(geoCtx, local, direction);
+
+  // construct full free-vector. time and q/p stay as-is.
+  FreeVector freeParams = FreeVector::Zero();
+  freeParams[eFreePos0] = position[ePos0];
+  freeParams[eFreePos1] = position[ePos1];
+  freeParams[eFreePos2] = position[ePos2];
+  freeParams[eFreeTime] = boundParams[eBoundTime];
+  freeParams[eFreeDir0] = direction[eMom0];
+  freeParams[eFreeDir1] = direction[eMom1];
+  freeParams[eFreeDir2] = direction[eMom2];
+  freeParams[eFreeQOverP] = boundParams[eBoundQOverP];
+  return freeParams;
+}
+
+Acts::Result<Acts::BoundVector> Acts::transformFreeToBoundParameters(
     const FreeVector& freeParams, const Surface& surface,
     const GeometryContext& geoCtx, ActsScalar tolerance) {
   // initialize the bound vector
@@ -38,7 +64,7 @@ Acts::Result<Acts::BoundVector> Acts::detail::transformFreeToBoundParameters(
   return Result<Acts::BoundVector>::success(bp);
 }
 
-Acts::Result<Acts::BoundVector> Acts::detail::transformFreeToBoundParameters(
+Acts::Result<Acts::BoundVector> Acts::transformFreeToBoundParameters(
     const Acts::Vector3& position, ActsScalar time,
     const Acts::Vector3& direction, ActsScalar qOverP,
     const Acts::Surface& surface, const Acts::GeometryContext& geoCtx,
@@ -62,7 +88,7 @@ Acts::Result<Acts::BoundVector> Acts::detail::transformFreeToBoundParameters(
   return Result<Acts::BoundVector>::success(bp);
 }
 
-Acts::BoundVector Acts::detail::transformFreeToCurvilinearParameters(
+Acts::BoundVector Acts::transformFreeToCurvilinearParameters(
     ActsScalar time, ActsScalar phi, ActsScalar theta, ActsScalar qOverP) {
   BoundVector bp = BoundVector::Zero();
   // local coordinates are zero by construction
@@ -73,7 +99,7 @@ Acts::BoundVector Acts::detail::transformFreeToCurvilinearParameters(
   return bp;
 }
 
-Acts::BoundVector Acts::detail::transformFreeToCurvilinearParameters(
+Acts::BoundVector Acts::transformFreeToCurvilinearParameters(
     ActsScalar time, const Vector3& direction, ActsScalar qOverP) {
   BoundVector bp = BoundVector::Zero();
   // local coordinates are zero by construction

Core/src/Propagator/StraightLineStepper.cpp

@@ -8,7 +8,7 @@
 
 #include "Acts/Propagator/StraightLineStepper.hpp"
 
-#include "Acts/EventData/detail/TransformationBoundToFree.hpp"
+#include "Acts/EventData/TransformationHelpers.hpp"
 #include "Acts/Propagator/detail/CovarianceEngine.hpp"
 
 namespace Acts {
@@ -71,8 +71,8 @@ void StraightLineStepper::resetState(State& state,
                                      const BoundSquareMatrix& cov,
                                      const Surface& surface,
                                      const double stepSize) const {
-  FreeVector freeParams = detail::transformBoundToFreeParameters(
-      surface, state.geoContext, boundParams);
+  FreeVector freeParams =
+      transformBoundToFreeParameters(surface, state.geoContext, boundParams);
 
   // Update the stepping state
   state.pars = freeParams;