Tracking/TrkDetDescr/TrkSurfaces/TrkSurfaces/Surface.h

Go to the documentation of this file.

/*
  Copyright (C) 2002-2024 CERN for the benefit of the ATLAS collaboration
*/

// Surface.h, (c) ATLAS Detector software
 
#ifndef TRKSURFACES_SURFACE_H
#define TRKSURFACES_SURFACE_H
 
// Amg
// Ensure Eigen plugin comes first
#include "EventPrimitives/EventPrimitives.h"
#include "GeoPrimitives/GeoPrimitives.h"
 
// Trk
#include "TrkDetDescrUtils/GeometryStatics.h"
#include "TrkDetDescrUtils/Intersection.h"
#include "TrkDetElementBase/TrkDetElementBase.h"
//
#include "TrkEventPrimitives/LocalParameters.h"
#include "TrkEventPrimitives/ParamDefs.h"
#include "TrkEventPrimitives/PropDirection.h"
#include "TrkEventPrimitives/SurfaceTypes.h"
#include "TrkEventPrimitives/SurfaceUniquePtrT.h"
#include "TrkEventPrimitives/TrkObjectCounter.h"
//
#include "TrkParametersBase/Charged.h"
#include "TrkParametersBase/Neutral.h"
#include "TrkParametersBase/ParametersBase.h"
#include "TrkSurfaces/BoundaryCheck.h"
#include "TrkSurfaces/DistanceSolution.h"
// Identifier
#include "Identifier/Identifier.h"
//
#include "CxxUtils/CachedUniquePtr.h"
#include "CxxUtils/checker_macros.h"
#include <atomic>
#include <memory>
#include <optional>
 
class MsgStream;
class SurfaceCnv_p1;
 
namespace Trk {
 
class TrkDetElementBase;
class SurfaceBounds;
class Layer;
class MaterialLayer;
 
/* enum that affects how this surface is to be managed.
 * See TrkEventPrimitives/SurfaceHolderImpl.
 */
enum SurfaceOwner {
  noOwn = 0,     // Surface is free can be deleted at will.
  TGOwn = 1,     // Surface is owned by the Geometry and will be deleted by it.
  DetElOwn = 2,  // Surface is associated with a detector element. So can not be
                 // deleted as long this is active.
  userOwn = 3  // Surface is owned by the user. e.g could be "static"
};

 
class Surface: public Trk::ObjectCounter<Trk::Surface>
{
 
public:
  /*
   * struct holding the transform, center, normal,
   * needed by surfaces when not delegating
   * to a detector element
   */
  struct Transforms
  {
    // constructor with just a Amg::Transform3D input
    inline Transforms(const Amg::Transform3D& atransform)
      : transform(atransform)
      , center(transform.translation())
      , normal(transform.linear().col(2))
    {
    }
 
    // constructor with  Amg::Transform3D and center input
    inline Transforms(const Amg::Transform3D& atransform,
                      const Amg::Vector3D& acenter)
      : transform(atransform)
      , center(acenter)
      , normal(transform.linear().col(2))
    {
    }
 
    // constructor with  Amg::Transform3D , center and normal input
    inline Transforms(const Amg::Transform3D& atransform,
                      const Amg::Vector3D& acenter,
                      const Amg::Vector3D& anormal)
      : transform(atransform)
      , center(acenter)
      , normal(anormal)
    {
    }
    Transforms(const Transforms&) = default;
    Transforms(Transforms&&) = default;
    Transforms& operator=(const Transforms&) = default;
    Transforms& operator=(Transforms&&) = default;
    ~Transforms() = default;
    Amg::Transform3D transform;
    Amg::Vector3D center;
    Amg::Vector3D normal;
  };

  using ChargedTrackParametersUniquePtr =
    std::unique_ptr<ParametersBase<5, Trk::Charged>>;
  using NeutralTrackParametersUniquePtr =
    std::unique_ptr<ParametersBase<5, Trk::Neutral>>;

  Surface();

  virtual ~Surface();

  Surface(const Amg::Transform3D& htrans);

  Surface(const TrkDetElementBase& detelement);

  Surface(const TrkDetElementBase& detelement, const Identifier& id);

  virtual bool operator==(const Surface& sf) const = 0;

  bool operator!=(const Surface& sf) const;

  virtual Surface* clone() const = 0;

  std::unique_ptr<Surface> uniqueClone() const;

  constexpr virtual SurfaceType type() const = 0;

  const Amg::Transform3D* cachedTransform() const;

  const Amg::Transform3D& transform() const;

  const Amg::Vector3D& center() const;

  virtual const Amg::Vector3D& normal() const;

  virtual Amg::Vector3D normal(const Amg::Vector2D& lp) const;

  virtual const Amg::Vector3D& globalReferencePoint() const;

  const TrkDetElementBase* associatedDetectorElement() const;

  Identifier associatedDetectorElementIdentifier() const;

  const Trk::Layer* associatedLayer() const;

  const Trk::MaterialLayer* materialLayer() const;
  Trk::MaterialLayer* materialLayer();

  virtual const Trk::Surface* baseSurface() const;

  virtual ChargedTrackParametersUniquePtr createUniqueTrackParameters(
    double l1,
    double l2,
    double phi,
    double theat,
    double qop,
    std::optional<AmgSymMatrix(5)> cov = std::nullopt) const = 0;

  virtual ChargedTrackParametersUniquePtr createUniqueTrackParameters(
    const Amg::Vector3D&,
    const Amg::Vector3D&,
    double,
    std::optional<AmgSymMatrix(5)> cov = std::nullopt) const = 0;

  virtual NeutralTrackParametersUniquePtr createUniqueNeutralParameters(
    double l1,
    double l2,
    double phi,
    double theat,
    double qop,
    std::optional<AmgSymMatrix(5)> cov = std::nullopt) const = 0;

  virtual NeutralTrackParametersUniquePtr createUniqueNeutralParameters(
    const Amg::Vector3D&,
    const Amg::Vector3D&,
    double charge = 0.,
    std::optional<AmgSymMatrix(5)> cov = std::nullopt) const = 0;

  std::optional<Amg::Vector2D> positionOnSurface(
    const Amg::Vector3D& glopo,
    const BoundaryCheck& bchk = true,
    double tol1 = 0.,
    double tol2 = 0.) const;

  template<class T>
  bool onSurface(const T& parameters,
                 const BoundaryCheck& bchk = BoundaryCheck(true)) const;

  virtual bool isOnSurface(const Amg::Vector3D& glopo,
                           const BoundaryCheck& bchk = true,
                           double tol1 = 0.,
                           double tol2 = 0.) const;

  virtual bool insideBounds(const Amg::Vector2D& locpos,
                            double tol1 = 0.,
                            double tol2 = 0.) const = 0;
 
  virtual bool insideBoundsCheck(const Amg::Vector2D& locpos,
                                 const BoundaryCheck& bchk) const = 0;

  virtual void localToGlobal(const Amg::Vector2D& locp,
                             const Amg::Vector3D& mom,
                             Amg::Vector3D& glob) const = 0;

  Amg::Vector3D localToGlobal(const Amg::Vector2D& locpos) const;

  Amg::Vector3D localToGlobal(const Amg::Vector2D& locpos,
                              const Amg::Vector3D& glomom) const;

  Amg::Vector3D localToGlobal(const LocalParameters& locpars) const;

  Amg::Vector3D localToGlobal(const LocalParameters& locpars,
                              const Amg::Vector3D& glomom) const;

  virtual bool globalToLocal(const Amg::Vector3D& glob,
                             const Amg::Vector3D& mom,
                             Amg::Vector2D& loc) const = 0;

  std::optional<Amg::Vector2D> globalToLocal(const Amg::Vector3D& glopos,
                                             double tol = 0.) const;

  std::optional<Amg::Vector2D> globalToLocal(const Amg::Vector3D& glopos,
                                             const Amg::Vector3D& glomom) const;

  virtual Amg::Vector2D localParametersToPosition(
    const LocalParameters& locpars) const;

  virtual double pathCorrection(const Amg::Vector3D& pos,
                                const Amg::Vector3D& mom) const;

  virtual Amg::RotationMatrix3D measurementFrame(
    const Amg::Vector3D& glopos,
    const Amg::Vector3D& glomom) const;

  template<typename T>
  Intersection straightLineIntersection(
    const T& pars,
    bool forceDir = false,
    const Trk::BoundaryCheck& bchk = false) const
  {
    return straightLineIntersection(
      pars.position(), pars.momentum().unit(), forceDir, bchk);
  }

  virtual Intersection straightLineIntersection(
    const Amg::Vector3D& pos,
    const Amg::Vector3D& dir,
    bool forceDir = false,
    Trk::BoundaryCheck bchk = false) const = 0;

  virtual DistanceSolution straightLineDistanceEstimate(
    const Amg::Vector3D& pos,
    const Amg::Vector3D& dir) const = 0;

  virtual DistanceSolution straightLineDistanceEstimate(
    const Amg::Vector3D& pos,
    const Amg::Vector3D& dir,
    bool Bound) const = 0;

  virtual const SurfaceBounds& bounds() const = 0;

  bool isFree() const;

  bool isActive() const;

  void setTransform(const Amg::Transform3D& trans);

  void setOwner(SurfaceOwner x);

  SurfaceOwner owner() const;

  void setMaterialLayer(std::shared_ptr<Trk::MaterialLayer> mlay);

  virtual MsgStream& dump(MsgStream& sl) const;

  virtual std::ostream& dump(std::ostream& sl) const;

  virtual std::string name() const = 0;

  void associateLayer(const Layer& lay);
 
protected:
 Surface(const Surface& sf);
 Surface& operator=(const Surface& sf);
 Surface(const Surface& sf, const Amg::Transform3D& transf);
 // Move operators for inheriting classes
 Surface(Surface&& sf) noexcept = default;
 Surface& operator=(Surface&& sf) noexcept = default;

 Amg::Transform3D inverseTransformHelper() const;
 Amg::Vector3D inverseTransformMultHelper(const Amg::Vector3D& glopos) const;
 
 friend class ::SurfaceCnv_p1;

 std::unique_ptr<Transforms> m_transforms{};
 const TrkDetElementBase* m_associatedDetElement{};
 Identifier m_associatedDetElementId{};
 const Layer* m_associatedLayer{};
 std::shared_ptr<MaterialLayer> m_materialLayer{};
 SurfaceOwner m_owner{SurfaceOwner::noOwn};

 static constexpr double s_onSurfaceTolerance = 10e-5;  // 0.1 * micron
};

MsgStream&
operator<<(MsgStream& sl, const Surface& sf);
std::ostream&
operator<<(std::ostream& sl, const Surface& sf);
 
typedef SurfaceUniquePtrT<Trk::Surface> SurfaceUniquePtr;
typedef SurfaceUniquePtrT<const Trk::Surface> ConstSurfaceUniquePtr;
} //
#include "Surface.icc"
#endif // TRKSURFACES_SURFACE_H