Acts/Visualization/EventDataView3D.hpp

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