include/Geant4/G4UAdapter.hh

0001 //
0002 // ********************************************************************
0003 // * License and Disclaimer                                           *
0004 // *                                                                  *
0005 // * The  Geant4 software  is  copyright of the Copyright Holders  of *
0006 // * the Geant4 Collaboration.  It is provided  under  the terms  and *
0007 // * conditions of the Geant4 Software License,  included in the file *
0008 // * LICENSE and available at  http://cern.ch/geant4/license .  These *
0009 // * include a list of copyright holders.                             *
0010 // *                                                                  *
0011 // * Neither the authors of this software system, nor their employing *
0012 // * institutes,nor the agencies providing financial support for this *
0013 // * work  make  any representation or  warranty, express or implied, *
0014 // * regarding  this  software system or assume any liability for its *
0015 // * use.  Please see the license in the file  LICENSE  and URL above *
0016 // * for the full disclaimer and the limitation of liability.         *
0017 // *                                                                  *
0018 // * This  code  implementation is the result of  the  scientific and *
0019 // * technical work of the GEANT4 collaboration.                      *
0020 // * By using,  copying,  modifying or  distributing the software (or *
0021 // * any work based  on the software)  you  agree  to acknowledge its *
0022 // * use  in  resulting  scientific  publications,  and indicate your *
0023 // * acceptance of all terms of the Geant4 Software license.          *
0024 // ********************************************************************
0025 //
0026 // G4UAdapter
0027 //
0028 // Class description:
0029 //
0030 // Utility class for adapting VecGeom solids API to Geant4 solids.
0031 // NOTE: Using protected inheritance since the Adapter is supposed to
0032 // be a G4VSolid "implemented-in-terms-of" the VecGeom UnplacedVolume_t.
0033 // The choice of protected vs private is due to the fact that we want
0034 // to propagate functions further down in the inheritance hierarchy.
0035
0036 // Author: Gabriele Cosmo (CERN), 17.05.2017
0037 //         Adapted for G4VSolid from original G4USolids bridge
0038 //         class and the USolidsAdapter class in VecGeom.
0039 // ------------------------------------------------------------------------
0040 #ifndef G4UADAPTER_HH
0041 #define G4UADAPTER_HH
0042
0043 #include "G4ThreeVector.hh"
0044 #include "G4VSolid.hh"
0045
0046 // Required for inline visualization adapter functions
0047 //
0048 #include "G4AffineTransform.hh"
0049 #include "G4VoxelLimits.hh"
0050 #include "G4VGraphicsScene.hh"
0051 #include "G4Polyhedron.hh"
0052 #include "G4VisExtent.hh"
0053 #include "G4BoundingEnvelope.hh"
0054 #include "G4AutoLock.hh"
0055
0056 #include "G4GeomTypes.hh"
0057
0058 #if ( defined(G4GEOM_USE_USOLIDS) || defined(G4GEOM_USE_PARTIAL_USOLIDS) )
0059
0060 #include <VecGeom/base/Global.h>
0061 #include <VecGeom/base/Vector3D.h>
0062
0063 class G4VPVParameterisation;
0064
0065 /**
0066  * @brief G4UAdapter is a utility class for adapting VecGeom solids API to
0067  * Geant4 solids. The Adapter is supposed to be a G4VSolid
0068  * "implemented-in-terms-of" the VecGeom UnplacedVolume_t.
0069  */
0070
0071 template <class UnplacedVolume_t>
0072 class G4UAdapter : public G4VSolid, protected UnplacedVolume_t
0073 {
0074   public:
0075
0076     using U3Vector = vecgeom::Vector3D<G4double>;
0077
0078     /** VecGeom volumes have special delete/new ("AlignedBase")
0079         and we need to make these functions public again. */
0080     using UnplacedVolume_t::operator delete;
0081     using UnplacedVolume_t::operator new;
0082
0083     /**
0084      * Constructor taking a name.
0085      *  @param[in] name The name of the volume.
0086      */
0087     G4UAdapter(const G4String& name);
0088
0089     /**
0090      * Constructor templated on arguments for UnplacedVolume_t.
0091      *  @param[in] name The name of the volume.
0092      *  @param[in] params Templated arguments for UnplacedVolume_t.
0093      */
0094     template <typename... T>
0095     G4UAdapter(const G4String& name, const T &... params);
0096
0097     /**
0098      * Virtual destructor.
0099      */
0100     virtual ~G4UAdapter();
0101
0102     /**
0103      * Copy constructor and assignment operator.
0104      */
0105     G4UAdapter(const G4UAdapter& rhs);
0106     G4UAdapter& operator=(const G4UAdapter& rhs);
0107
0108     /**
0109      * Equality operator. Returns true only if addresses are the same.
0110      */
0111     G4bool operator==(const G4UAdapter& s) const;
0112
0113     /**
0114      * Calculates the minimum and maximum extent of the solid, when under the
0115      * specified transform, and within the specified limits.
0116      *  @param[in] pAxis The axis along which compute the extent.
0117      *  @param[in] pVoxelLimit The limiting space dictated by voxels.
0118      *  @param[in] pTransform The internal transformation applied to the solid.
0119      *  @param[out] pMin The minimum extent value.
0120      *  @param[out] pMax The maximum extent value.
0121      *  @returns True if the solid is intersected by the extent region.
0122      */
0123     virtual G4bool CalculateExtent(const EAxis pAxis,
0124                                    const G4VoxelLimits& pVoxelLimit,
0125                                    const G4AffineTransform& pTransform,
0126                                G4double& pMin, G4double& pMax) const override;
0127
0128     /**
0129      * Returns the characterisation of a point at offset 'p' respect
0130      * to the shape.
0131      *  @param[in] p The point at offset p.
0132      *  @returns kOutside if the point is outside the shapes boundaries
0133      *           plus Tolerance/2; kSurface if the point is less than
0134      *           Tolerance/2 from a surface; kInside otherwise.
0135      */
0136     virtual EInside Inside(const G4ThreeVector& p) const override;
0137
0138     /**
0139      * Returns the outwards pointing unit normal of the shape for the
0140      * surface closest to the point at offset 'p'.
0141      *  @param[in] p The point at offset p.
0142      *  @returns The outwards pointing unit normal.
0143      */
0144     virtual G4ThreeVector SurfaceNormal(const G4ThreeVector& p) const override;
0145
0146     /**
0147      * Returns the distance along the normalised vector 'v' to the shape,
0148      * from the point at offset 'p'. If there is no intersection, returns
0149      * kInfinity. The first intersection resulting from 'leaving' a
0150      * surface/volume is discarded. Hence, it is tolerant of points on
0151      * the surface of the shape.
0152      *  @param[in] p The point at offset p.
0153      *  @param[in] v The normalised direction vector.
0154      *  @returns The distance to enter the shape.
0155      */
0156     virtual G4double DistanceToIn(const G4ThreeVector& p,
0157                                   const G4ThreeVector& v) const override;
0158
0159     /**
0160      * Calculates the distance to the nearest surface of a shape from an
0161      * outside point. The distance can be an underestimate.
0162      *  @param[in] p The point at offset p.
0163      *  @returns The safety distance to enter the shape.
0164      */
0165     virtual G4double DistanceToIn(const G4ThreeVector& p) const override;
0166
0167     /**
0168      * Returns the distance along the normalised vector 'v' to the shape,
0169      * from a point at an offset 'p' inside or on the surface of the shape.
0170      * Intersections with surfaces, when the point is less than Tolerance/2
0171      * from a surface must be ignored.
0172      *  @param[in] p The point at offset p.
0173      *  @param[in] v The normalised direction vector.
0174      *  @param[in] calcNorm Flag to indicate if to calculate the normal or not.
0175      *  @param[out] validNorm Flag set to true if the solid lies entirely
0176      *              behind or on the exiting surface. It is set false if the
0177      *              solid does not lie entirely behind or on the exiting surface.
0178      *              'calcNorm' must be true, otherwise it is unused.
0179      *  @param[out] n The exiting outwards normal vector (undefined Magnitude).
0180      *              'calcNorm' must be true, otherwise it is unused.
0181      *  @returns The distance to exit the shape.
0182      */
0183     virtual G4double DistanceToOut(const G4ThreeVector& p,
0184                                    const G4ThreeVector& v,
0185                                    const G4bool calcNorm = false,
0186                                    G4bool* validNorm = 0,
0187                                    G4ThreeVector* n = 0) const override;
0188
0189     /**
0190      * Calculates the distance to the nearest surface of a shape from an
0191      * inside point 'p'. The distance can be an underestimate.
0192      *  @param[in] p The point at offset p.
0193      *  @returns The safety distance to exit the shape.
0194      */
0195     virtual G4double DistanceToOut(const G4ThreeVector& p) const override;
0196
0197     /**
0198      * Dispatch method for parameterisation replication mechanism and
0199      * dimension computation. Throws exception if ComputeDimensions() is
0200      * called from an illegal derived class.
0201      */
0202     virtual void ComputeDimensions(G4VPVParameterisation* p,
0203                                    const G4int n,
0204                                    const G4VPhysicalVolume* pRep) override;
0205
0206     /**
0207      * Returns an estimation of the solid volume in internal units.
0208      * This method may be overloaded by derived classes to compute the
0209      * exact geometrical quantity for solids where this is possible,
0210      * or anyway to cache the computed value.
0211      * Note: the computed value is NOT cached.
0212      */
0213     virtual G4double GetCubicVolume() override;
0214
0215     /**
0216      * Returns an estimation of the solid surface area in internal units.
0217      * This method may be overloaded by derived classes to compute the
0218      * exact geometrical quantity for solids where this is possible,
0219      * or anyway to cache the computed value.
0220      * Note: the computed value is NOT cached.
0221      */
0222     virtual G4double GetSurfaceArea() override;
0223
0224     /**
0225      * Returns a random point located on the surface of the solid.
0226      */
0227     virtual G4ThreeVector GetPointOnSurface() const override;
0228
0229     /**
0230      * Returns the number of constituents used for construction of the solid.
0231      * For non-Boolean solids the return value is one.
0232      */
0233     virtual G4int GetNumOfConstituents() const override;
0234
0235     /**
0236      * Returns true if the solid has only planar faces, false otherwise.
0237      */
0238     virtual G4bool IsFaceted() const override;
0239
0240     /**
0241      * Provides identification of the class of an object
0242      * (required for persistency).
0243      */
0244     virtual G4GeometryType GetEntityType() const override;
0245
0246     /**
0247      * Returns a pointer of a dynamically allocated copy of the solid.
0248      * Returns a null pointer with warning in case the concrete solid does not
0249      * implement this method. The caller has responsibility for ownership.
0250      */
0251     virtual G4VSolid* Clone() const override;
0252
0253     /**
0254      * Dumps contents of the solid to a stream.
0255      */
0256     virtual std::ostream& StreamInfo(std::ostream& os) const override;
0257
0258     /**
0259      * A "double dispatch" function which identifies the solid
0260      * to the graphics scene for visualization.
0261      */
0262     virtual void DescribeYourselfTo(G4VGraphicsScene& scene) const override;
0263
0264     /**
0265      * Provides extent (bounding box) as possible hint to the graphics view.
0266      */
0267     virtual G4VisExtent GetExtent()  const override;
0268
0269     /**
0270      * Creates a Polyhedron used for Visualisation.
0271      */
0272     virtual G4Polyhedron* CreatePolyhedron() const override;
0273
0274     /**
0275      * Smart access function - creates on request and stores for future
0276      * access. A null pointer means "not available".
0277      */
0278     virtual G4Polyhedron* GetPolyhedron() const override;
0279
0280
0281     // VecGeom overridden methods ---------------------------------------------
0282
0283     vecgeom::Precision
0284     DistanceToOut(U3Vector const& position, U3Vector const& direction,
0285                   vecgeom::Precision stepMax = kInfinity) const override
0286     {
0287       return UnplacedVolume_t::DistanceToOut(position, direction, stepMax);
0288     }
0289
0290     vecgeom::EnumInside
0291     Inside(U3Vector const& aPoint) const override
0292     {
0293       return UnplacedVolume_t::Inside(aPoint);
0294     }
0295
0296     vecgeom::Precision
0297     DistanceToIn(U3Vector const& position, U3Vector const& direction,
0298                  const vecgeom::Precision step_max = kInfinity) const override
0299     {
0300       return UnplacedVolume_t::DistanceToIn(position, direction, step_max);
0301     }
0302
0303     G4bool Normal(U3Vector const& aPoint, U3Vector& aNormal) const override
0304     {
0305       return UnplacedVolume_t::Normal(aPoint, aNormal);
0306     }
0307
0308     void Extent(U3Vector& aMin, U3Vector& aMax) const override
0309     {
0310       return UnplacedVolume_t::Extent(aMin, aMax);
0311     }
0312
0313     U3Vector SamplePointOnSurface() const override
0314     {
0315       return UnplacedVolume_t::SamplePointOnSurface();
0316     }
0317
0318   protected:  // data
0319
0320     mutable G4bool fRebuildPolyhedron = false;
0321     mutable G4Polyhedron* fPolyhedron = nullptr;
0322
0323     /** Cached geometrical tolerance. */
0324     G4double kHalfTolerance;
0325
0326     using UnplacedVolume_t::DistanceToOut;
0327     using UnplacedVolume_t::DistanceToIn;
0328 };
0329
0330 // Inline implementations
0331
0332 #include "G4UAdapter.icc"
0333
0334 #endif  // G4GEOM_USE_USOLIDS
0335
0336 #endif // G4UADAPTER_HH