Acts/Visualization/EventDataView3D.hpp

0001 // This file is part of the Acts project.
0002 //
0003 // Copyright (C) 2020-2023 CERN for the benefit of the Acts project
0004 //
0005 // This Source Code Form is subject to the terms of the Mozilla Public
0006 // License, v. 2.0. If a copy of the MPL was not distributed with this
0007 // file, You can obtain one at http://mozilla.org/MPL/2.0/.
0008
0009 #pragma once
0010
0011 #include "Acts/Definitions/Algebra.hpp"
0012 #include "Acts/Definitions/TrackParametrization.hpp"
0013 #include "Acts/EventData/MultiTrajectory.hpp"
0014 #include "Acts/EventData/TrackParameters.hpp"
0015 #include "Acts/Geometry/GeometryContext.hpp"
0016 #include "Acts/Geometry/Polyhedron.hpp"
0017 #include "Acts/Surfaces/CylinderBounds.hpp"
0018 #include "Acts/Surfaces/CylinderSurface.hpp"
0019 #include "Acts/Surfaces/Surface.hpp"
0020 #include "Acts/Surfaces/detail/FacesHelper.hpp"
0021 #include "Acts/Utilities/UnitVectors.hpp"
0022 #include "Acts/Visualization/GeometryView3D.hpp"
0023 #include "Acts/Visualization/IVisualization3D.hpp"
0024 #include "Acts/Visualization/ViewConfig.hpp"
0025
0026 #include <array>
0027 #include <cmath>
0028 #include <cstddef>
0029 #include <optional>
0030 #include <vector>
0031
0032 namespace Acts {
0033 class IVisualization3D;
0034
0035 static ViewConfig s_viewParameter = ViewConfig({0, 0, 255});
0036 static ViewConfig s_viewMeasurement = ViewConfig({255, 102, 0});
0037 static ViewConfig s_viewPredicted = ViewConfig({51, 204, 51});
0038 static ViewConfig s_viewFiltered = ViewConfig({255, 255, 0});
0039 static ViewConfig s_viewSmoothed = ViewConfig({0, 102, 255});
0040
0041 struct EventDataView3D {
0042   /// Helper to find the eigen values and corr angle
0043   ///
0044   /// @param covariance The covariance matrix
0045   static inline std::array<double, 3> decomposeCovariance(
0046       const ActsSquareMatrix<2>& covariance) {
0047     double c00 = covariance(eBoundLoc0, eBoundLoc0);
0048     double c01 = covariance(eBoundLoc0, eBoundLoc1);
0049     double c11 = covariance(eBoundLoc1, eBoundLoc1);
0050
0051     double cdsq = std::pow((c00 - c11), 2) / 4.;
0052     double cosq = c01 * c01;
0053
0054     // Calculate the eigen values w.r.t reference frame
0055     double lambda0 = (c00 + c11) / 2. + std::sqrt(cdsq + cosq);
0056     double lambda1 = (c00 + c11) / 2. - std::sqrt(cdsq + cosq);
0057     double theta = atan2(lambda0 - c00, c01);
0058
0059     return {lambda0, lambda1, theta};
0060   }
0061
0062   /// Helper method to draw the ellipse points
0063   ///
0064   /// @param lambda0 The Eigenvalue in 0
0065   /// @param lambda1 The Eigenvalue in 1
0066   /// @param theta The angle between the x/y frame and EV frame
0067   /// @param lseg The number of segments
0068   /// @param offset The out of plane offset for visibility
0069   /// @param lposition The local anker point of the ellipse
0070   /// @param transform The transform to global
0071   static inline std::vector<Vector3> createEllipse(
0072       double lambda0, double lambda1, double theta, std::size_t lseg,
0073       double offset, const Vector2& lposition = Vector2(0., 0.),
0074       const Transform3& transform = Transform3::Identity()) {
0075     double ctheta = std::cos(theta);
0076     double stheta = std::sin(theta);
0077
0078     double l1sq = std::sqrt(lambda0);
0079     double l2sq = std::sqrt(lambda1);
0080
0081     // Now generate the ellipse points
0082     std::vector<Vector3> ellipse;
0083     ellipse.reserve(lseg);
0084     double thetaStep = 2 * M_PI / lseg;
0085     for (std::size_t it = 0; it < lseg; ++it) {
0086       double phi = -M_PI + it * thetaStep;
0087       double cphi = std::cos(phi);
0088       double sphi = std::sin(phi);
0089       double x = lposition.x() + (l1sq * ctheta * cphi - l2sq * stheta * sphi);
0090       double y = lposition.y() + (l1sq * stheta * cphi + l2sq * ctheta * sphi);
0091       ellipse.push_back(transform * Vector3(x, y, offset));
0092     }
0093     return ellipse;
0094   }
0095
0096   /// Helper method to draw error ellipse
0097   ///
0098   /// @param helper [in, out] The visualization helper
0099   /// @param lposition The local position
0100   /// @param covariance The covariance matrix
0101   /// @param transform The reference Frame transform
0102   /// @param locErrorScale The local Error scale
0103   /// @param viewConfig The visualization parameters
0104   static void drawCovarianceCartesian(
0105       IVisualization3D& helper, const Vector2& lposition,
0106       const SquareMatrix2& covariance, const Transform3& transform,
0107       double locErrorScale = 1, const ViewConfig& viewConfig = s_viewParameter);
0108
0109   /// Helper method to draw error cone of a direction
0110   ///
0111   /// @param helper [in, out] The visualization helper
0112   /// @param position Where the cone originates from
0113   /// @param direction The direction parameters
0114   /// @param covariance The 2x2 covariance matrix for phi/theta
0115   /// @param directionScale The direction arrow length
0116   /// @param angularErrorScale The local Error scale
0117   /// @param viewConfig The visualization parameters
0118   static void drawCovarianceAngular(
0119       IVisualization3D& helper, const Vector3& position,
0120       const Vector3& direction, const ActsSquareMatrix<2>& covariance,
0121       double directionScale = 1, double angularErrorScale = 1,
0122       const ViewConfig& viewConfig = s_viewParameter);
0123
0124   /// Helper method to draw bound parameters object
0125   ///
0126   /// @param helper [in, out] The visualization helper
0127   /// @param parameters The bound parameters to be drawn
0128   /// @param gctx The geometry context for which it is drawn
0129   /// @param momentumScale The scale of the momentum
0130   /// @param locErrorScale  The scale of the local error
0131   /// @param angularErrorScale The scale of the angular error
0132   /// @param parConfig The visualization options for the parameter
0133   /// @param covConfig The visualization option for the covariance
0134   /// @param surfConfig The visualization option for the surface
0135   template <typename parameters_t>
0136   static inline void drawBoundTrackParameters(
0137       IVisualization3D& helper, const parameters_t& parameters,
0138       const GeometryContext& gctx = GeometryContext(),
0139       double momentumScale = 1., double locErrorScale = 1.,
0140       double angularErrorScale = 1.,
0141       const ViewConfig& parConfig = s_viewParameter,
0142       const ViewConfig& covConfig = s_viewParameter,
0143       const ViewConfig& surfConfig = s_viewSensitive) {
0144     if (surfConfig.visible) {
0145       GeometryView3D::drawSurface(helper, parameters.referenceSurface(), gctx,
0146                                   Transform3::Identity(), surfConfig);
0147     }
0148
0149     // Draw the parameter shaft and cone
0150     auto position = parameters.position(gctx);
0151     auto direction = parameters.direction();
0152     double p = parameters.absoluteMomentum();
0153
0154     ViewConfig lparConfig = parConfig;
0155     lparConfig.lineThickness = 0.05;
0156     Vector3 parLength = p * momentumScale * direction;
0157
0158     GeometryView3D::drawArrowBackward(
0159         helper, position, position + 0.5 * parLength, 100., 1.0, lparConfig);
0160
0161     GeometryView3D::drawArrowForward(helper, position + 0.5 * parLength,
0162                                      position + parLength, 4., 2.5, lparConfig);
0163
0164     if (parameters.covariance().has_value()) {
0165       auto paramVec = parameters.parameters();
0166       auto lposition = paramVec.template block<2, 1>(0, 0);
0167
0168       // Draw the local covariance
0169       const auto& covariance = *parameters.covariance();
0170       drawCovarianceCartesian(helper, lposition,
0171                               covariance.template block<2, 2>(0, 0),
0172                               parameters.referenceSurface().transform(gctx),
0173                               locErrorScale, covConfig);
0174
0175       drawCovarianceAngular(
0176           helper, position, direction, covariance.template block<2, 2>(2, 2),
0177           0.9 * p * momentumScale, angularErrorScale, covConfig);
0178     }
0179   }
0180
0181   /// Helper method to draw a single measurement
0182   ///
0183   /// @param helper [in, out] The visualization helper
0184   /// @param lposition calibrated measurement
0185   /// @param covariance calibrated covariance
0186   /// @param transform reference surface transformed with the geometry context
0187   /// @param locErrorScale  The scale of the local error
0188   /// @param measurementConfig The visualization options for the measurement
0189   ///
0190   /// TODO: Expand to 1D measurements
0191   static void drawMeasurement(
0192       IVisualization3D& helper, const Vector2& lposition,
0193       const SquareMatrix2& covariance, const Transform3& transform,
0194       const double locErrorScale = 1.,
0195       const ViewConfig& measurementConfig = s_viewMeasurement) {
0196     if (locErrorScale <= 0) {
0197       throw std::invalid_argument("locErrorScale must be > 0");
0198     }
0199     if (measurementConfig.visible) {
0200       drawCovarianceCartesian(helper, lposition, covariance, transform,
0201                               locErrorScale, measurementConfig);
0202     }
0203   }
0204
0205   /// Helper method to draw one trajectory stored in a MultiTrajectory object
0206   ///
0207   /// @param helper [in, out] The visualization helper
0208   /// @param multiTraj The MultiTrajectory storing the trajectory to be drawn
0209   /// @param entryIndex The trajectory entry index
0210   /// @param gctx The geometry context for which it is drawn
0211   /// @param momentumScale The scale of the momentum
0212   /// @param locErrorScale  The scale of the local error
0213   /// @param angularErrorScale The scale of the angular error
0214   /// @param surfaceConfig The visualization options for the surface
0215   /// @param measurementConfig The visualization options for the measurement
0216   /// @param predictedConfig The visualization options for the predicted
0217   /// measurement
0218   /// @param filteredConfig The visualization options for the filtered
0219   /// parameters
0220   /// @param smoothedConfig The visualization options for the smoothed
0221   /// parameters
0222   template <typename traj_t>
0223   static void drawMultiTrajectory(
0224       IVisualization3D& helper, const traj_t& multiTraj,
0225       const std::size_t& entryIndex,
0226       const GeometryContext& gctx = GeometryContext(),
0227       double momentumScale = 1., double locErrorScale = 1.,
0228       double angularErrorScale = 1.,
0229       const ViewConfig& surfaceConfig = s_viewSensitive,
0230       const ViewConfig& measurementConfig = s_viewMeasurement,
0231       const ViewConfig& predictedConfig = s_viewPredicted,
0232       const ViewConfig& filteredConfig = s_viewFiltered,
0233       const ViewConfig& smoothedConfig = s_viewSmoothed) {
0234     // @TODO: Refactor based on Track class
0235
0236     // TODO get particle hypothesis from track
0237     ParticleHypothesis particleHypothesis = ParticleHypothesis::pion();
0238
0239     // Visit the track states on the trajectory
0240     multiTraj.visitBackwards(entryIndex, [&](const auto& state) {
0241       // Only draw the measurement states
0242       if (!state.typeFlags().test(Acts::TrackStateFlag::MeasurementFlag)) {
0243         return true;
0244       }
0245
0246       // Use smaller scaling factors for the first state
0247       // @Todo: add parameter for the first state error scaling
0248       if (state.index() == 0) {
0249         locErrorScale = locErrorScale * 0.1;
0250         angularErrorScale = angularErrorScale * 0.1;
0251       }
0252
0253       // First, if necessary, draw the surface
0254       if (surfaceConfig.visible) {
0255         GeometryView3D::drawSurface(helper, state.referenceSurface(), gctx,
0256                                     Transform3::Identity(), surfaceConfig);
0257       }
0258
0259       // Second, if necessary and present, draw the calibrated measurement (only
0260       // draw 2D measurement here)
0261       // @Todo: how to draw 1D measurement?
0262       if (state.hasCalibrated() && state.calibratedSize() == 2) {
0263         const Vector2& lposition = state.template calibrated<2>();
0264         const SquareMatrix2 covariance =
0265             state.template calibratedCovariance<2>();
0266         drawMeasurement(helper, lposition, covariance,
0267                         state.referenceSurface().transform(gctx), locErrorScale,
0268                         measurementConfig);
0269       }
0270
0271       // Last, if necessary and present, draw the track parameters
0272       // (a) predicted track parameters
0273       if (predictedConfig.visible && state.hasPredicted()) {
0274         drawBoundTrackParameters(
0275             helper,
0276             BoundTrackParameters(state.referenceSurface().getSharedPtr(),
0277                                  state.predicted(), state.predictedCovariance(),
0278                                  particleHypothesis),
0279             gctx, momentumScale, locErrorScale, angularErrorScale,
0280             predictedConfig, predictedConfig, ViewConfig(false));
0281       }
0282       // (b) filtered track parameters
0283       if (filteredConfig.visible && state.hasFiltered()) {
0284         drawBoundTrackParameters(
0285             helper,
0286             BoundTrackParameters(state.referenceSurface().getSharedPtr(),
0287                                  state.filtered(), state.filteredCovariance(),
0288                                  particleHypothesis),
0289             gctx, momentumScale, locErrorScale, angularErrorScale,
0290             filteredConfig, filteredConfig, ViewConfig(false));
0291       }
0292       // (c) smoothed track parameters
0293       if (smoothedConfig.visible && state.hasSmoothed()) {
0294         drawBoundTrackParameters(
0295             helper,
0296             BoundTrackParameters(state.referenceSurface().getSharedPtr(),
0297                                  state.smoothed(), state.smoothedCovariance(),
0298                                  particleHypothesis),
0299             gctx, momentumScale, locErrorScale, angularErrorScale,
0300             smoothedConfig, smoothedConfig, ViewConfig(false));
0301       }
0302       return true;
0303     });
0304   }
0305 };
0306
0307 }  // namespace Acts