Acts/Utilities/Frustum.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/Visualization/IVisualization3D.hpp"
0013
0014 #include <ostream>
0015
0016 namespace Acts {
0017
0018 /// Class representing a frustum shape. The frustum is defined using an origin,
0019 /// a direction and an opening angle. These parameters are then used to
0020 /// calculate a number of side planes, each having a position and a normal
0021 /// vector. The "near plane" is assumed to coincide with the origin point, and
0022 /// the normal with the "direction" of the frustum. No far plane is defined.
0023 /// @tparam value_t The floating point value to use
0024 /// @tparam DIM The number of dimensions of ambient space
0025 /// @tparam SIDES The number of sides (= side planes) the frustum has (exactly 2
0026 /// in 2D, minimum 3 in 3D)
0027 template <typename value_t, std::size_t DIM, std::size_t SIDES>
0028 class Frustum {
0029   using translation_t = Eigen::Translation<value_t, DIM>;
0030
0031   static constexpr std::size_t n_normals = SIDES + 1;
0032
0033  public:
0034   /// Re expose the value type
0035   using value_type = value_t;
0036   /// Vertex type based on the value type and dimension
0037   using VertexType = Eigen::Matrix<value_t, DIM, 1>;
0038   /// Vertex array type corresponding to the vertex type
0039   using vertex_array_type = Eigen::Array<value_t, DIM, 1>;
0040   /// Associated transform type
0041   using transform_type = Eigen::Transform<value_t, DIM, Eigen::Affine>;
0042
0043   /// Re expose the number of dimensions
0044   static constexpr std::size_t dim = DIM;
0045   /// Re expose the number of sides
0046   static constexpr std::size_t sides = SIDES;
0047
0048   /// Constructor for the 2D case.
0049   /// @param origin The origin of the frustum
0050   /// @param dir The direction of the frustum
0051   /// @param opening_angle The opening angle
0052   /// @note The @p opening_angle is defined as the angle between opposing side
0053   /// planes. The opening angle needs to be < pi.
0054   Frustum(const VertexType& origin, const VertexType& dir,
0055           value_type opening_angle)
0056     requires(DIM == 2);
0057
0058   /// Constructor for the 3D case.
0059   /// @param origin The origin of the frustum
0060   /// @param dir The direction of the frustum
0061   /// @param opening_angle The opening angle
0062   /// @note The @p opening_angle is defined as the angle between opposing side
0063   /// planes. The opening angle needs to be < pi.
0064   Frustum(const VertexType& origin, const VertexType& dir,
0065           value_type opening_angle)
0066     requires(DIM == 3);
0067
0068   /// Draw a representation of this frustum using a visualization helper
0069   /// @note This is only available for the 3D case.
0070   /// @param helper The visualization helper
0071   /// @param far_distance The distance to the virtual "far plane" at which point
0072   /// the side planes terminate visually.
0073   void draw(IVisualization3D& helper, value_type far_distance = 10) const
0074     requires(DIM == 3);
0075
0076   /// Draw a representation of this frustum as an SVG string to an outstream
0077   /// @note This is only available for the 2D case.
0078   /// @param os The out stream to write to
0079   /// @param w The width of the output SVG
0080   /// @param h The height of the output SVG
0081   /// @param far_distance The distance to the virtual "far line" at which point
0082   /// the side lines terminate visually.
0083   /// @param unit Multiplicative factor to apply to internal distances
0084   std::ostream& svg(std::ostream& os, value_type w, value_type h,
0085                     value_type far_distance = 1, value_type unit = 20.) const
0086     requires(DIM == 2);
0087
0088   /// Getter for the oriogin of the frustum
0089   /// @return The origin of the frustum
0090   const VertexType& origin() const { return m_origin; }
0091
0092   /// Getter for the direction of the frustum
0093   /// @return The direction of the frustum
0094   const VertexType& dir() const { return m_normals[0]; }
0095
0096   /// Getter for the normal vectors of the planes defining this frustum.
0097   /// @return Array containing the normal vectors for all planes.
0098   /// @note The size of the array that is returned is fixed to `number of sides + 1`
0099   const std::array<VertexType, SIDES + 1>& normals() const { return m_normals; }
0100
0101   /// Transforms this frustum using a given transform and returns a new instance
0102   /// @param trf The transform to apply
0103   /// @return A copy of this frustum with the transform @p trf applied.
0104   Frustum<value_t, DIM, SIDES> transformed(const transform_type& trf) const;
0105
0106  private:
0107   // private constructor with pre-calculated normals
0108   Frustum(const VertexType& origin, std::array<VertexType, SIDES + 1> normals)
0109       : m_origin(origin), m_normals(std::move(normals)) {}
0110
0111   VertexType m_origin;
0112   // need one more for direction we're facing
0113   std::array<VertexType, SIDES + 1> m_normals;
0114 };
0115
0116 }  // namespace Acts
0117
0118 #include "Acts/Utilities/Frustum.ipp"