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