include/Geant4/G4VCSGface.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 // G4VCSGface
0027 //
0028 // Class description:
0029 //
0030 // Definition of the virtual base class G4VCSGface, one side (or face)
0031 // of a CSG-like solid. It should be possible to build a CSG entirely
0032 // out of connecting CSG faces.
0033 //
0034 // Each face has an inside and outside surface, the former represents
0035 // the inside of the volume, the latter, the outside.
0036 //
0037 // -------------------------------------------------------------------
0038 //
0039 // Implementation notes:
0040 //   * distance.
0041 //        The meaning of distance includes the boundaries of the face.
0042 //        For example, for a rectangular, planer face:
0043 //
0044 //               A   |  B           | C
0045 //                   |              |
0046 //              -------+--------------+-----
0047 //               D   |  I           | E
0048 //                   |              |
0049 //              -------+--------------+-----
0050 //               F   |  G           | H
0051 //                   |              |
0052 //
0053 //        A, C, F, and H: closest distance is the distance to
0054 //        the adjacent corner.
0055 //
0056 //        B, D, E, and G: closest distance is the distance to
0057 //        the adjacent line.
0058 //
0059 //        I: normal distance to plane
0060 //
0061 //        For non-planer faces, one can use the normal to decide when
0062 //        a point falls off the edge and then act accordingly.
0063 //
0064 //
0065 // Usage:
0066 //
0067 //   A CSG shape can be defined by putting together any number of generic
0068 //   faces, as long as the faces cover the entire surface of the shape
0069 //   without overlapping.
0070 //
0071 //   G4VSolid::CalculateExtent
0072 //
0073 //   Define unit vectors along the specified transform axis.
0074 //   Use the inverse of the specified coordinate transformation to rotate
0075 //   these unit vectors. Loop over each face, call face->Extent, and save
0076 //   the maximum value.
0077 //
0078 //   G4VSolid::Inside
0079 //
0080 //   To decide if a point is inside, outside, or on the surface of the shape,
0081 //   loop through all faces, and find the answer from face->Inside which gives
0082 //   a value of "bestDistance" smaller than any other. While looping, if any
0083 //   face->Inside returns kSurface, this value can be returned immediately.
0084 //
0085 //  EInside answer;
0086 //  G4VCSGface *face = faces;
0087 //  G4double best = kInfinity;
0088 //  do
0089 //  {
0090 //    G4double distance;
0091 //    EInside result = (*face)->Inside( p, kCarTolerance/2, distance );
0092 //    if (result == kSurface) return kSurface;
0093 //    if (distance < best)
0094 //    {
0095 //      best = distance;
0096 //      answer = result;
0097 //    }
0098 //  } while( ++face < faces + numFaces );
0099 //
0100 //  return(answer);
0101 //
0102 //   G4VSolid::SurfaceNormal
0103 //
0104 //   Loop over all faces, call face->Normal, and return the normal to the face
0105 //   that is closest to the point.
0106 //
0107 //   G4VSolid::DistanceToIn(p)
0108 //
0109 //   Loop over all faces, invoking face->Distance with outgoing = false,
0110 //   and save the answer that is smallest.
0111 //
0112 //   G4VSolid::DistanceToIn(p,v)
0113 //
0114 //   Loop over all faces, invoking face->Intersect with outgoing = false,
0115 //   and save the answer that is smallest.
0116 //
0117 //   G4VSolid::DistanceToOut(p)
0118 //
0119 //   Loop over all faces, invoking face->Distance with outgoing = true,
0120 //   and save the answer that is smallest.
0121 //
0122 //   G4VSolid::DistanceToOut(p,v)
0123 //
0124 //   Loop over all faces, invoking face->Intersect with outgoing = true,
0125 //   and save the answer that is smallest. If there is more than one answer,
0126 //   or if allBehind is false for the one answer, return validNorm as false.
0127
0128 // Author: David C. Williams (UCSC), 1998 - Created
0129 // --------------------------------------------------------------------
0130 #ifndef G4VCSGFACE_HH
0131 #define G4VCSGFACE_HH
0132
0133 #include "G4Types.hh"
0134 #include "G4ThreeVector.hh"
0135 #include "geomdefs.hh"
0136 #include "G4VSolid.hh"
0137
0138 class G4VoxelLimits;
0139 class G4AffineTransform;
0140 class G4SolidExtentList;
0141
0142 /**
0143  * @brief G4VCSGface is virtual base class, representing one side (or face)
0144  * of a CSG-like solid. It should be possible to build a CSG entirely
0145  * out of connecting CSG faces. Each face has an inside and outside surface,
0146  * the former represents the inside of the volume, the latter, the outside.
0147  */
0148
0149 class G4VCSGface
0150 {
0151   public:
0152
0153     /**
0154      * Default Constructor and Destructor.
0155      */
0156     G4VCSGface() = default;
0157     virtual ~G4VCSGface() = default;
0158
0159     /**
0160      * Determines the distance along a line to the face.
0161      *  @param[in] p Position.
0162      *  @param[in] v Direction (assumed to be a unit vector).
0163      *  @param[in] outgoing Flag true, to consider only inside surfaces;
0164      *             false, to consider only outside surfaces.
0165      *  @param[in] surfTolerance Minimum distance from the surface.
0166      *  @param[out] distance Distance to intersection.
0167      *  @param[out] distFromSurface Distance from surface (along surface normal),
0168      *              < 0 if the point is in front of the surface.
0169      *  @param[out] normal Normal of surface at intersection point.
0170      *  @param[out] allBehind Flag, true, if entire surface is behind normal.
0171      *  @returns true if there is an intersection, false otherwise.
0172      */
0173     virtual G4bool Intersect( const G4ThreeVector& p, const G4ThreeVector& v,
0174                               G4bool outgoing, G4double surfTolerance,
0175                               G4double& distance, G4double& distFromSurface,
0176                               G4ThreeVector& normal, G4bool& allBehind ) = 0;
0177
0178     /**
0179      * Determines the distance of a point from either the inside or outside
0180      * surfaces of the face.
0181      *  @param[in] p Position.
0182      *  @param[in] outgoing Flag, true, to consider only inside surfaces
0183      *             or false, to consider only outside surfaces.
0184      *  @returns The distance to the closest surface satisfying requirements
0185      *           or kInfinity if no such surface exists.
0186      */
0187     virtual G4double Distance( const G4ThreeVector& p, G4bool outgoing ) = 0;
0188
0189     /**
0190      * Determines whether a point is inside, outside, or on the surface of
0191      * the face.
0192      *  @param[in] p Position.
0193      *  @param[in] tolerance Tolerance defining the bounds of the "kSurface",
0194      *             nominally equal to kCarTolerance/2.
0195      *  @param[out] bestDistance Distance to the closest surface (in or out).
0196      *  @returns kInside if the point is closest to the inside surface;
0197      *           kOutside if the point is closest to the outside surface;
0198      *           kSurface if the point is withing tolerance of the surface.
0199      */
0200     virtual EInside Inside( const G4ThreeVector& p, G4double tolerance,
0201                             G4double* bestDistance ) = 0;
0202
0203     /**
0204      * Returns the normal of surface closest to the point.
0205      *  @param[in] p Position.
0206      *  @param[out] bestDistance Distance to the closest surface (in or out).
0207      *  @returns The normal of the surface nearest the point.
0208      */
0209     virtual G4ThreeVector Normal( const G4ThreeVector& p,
0210                                   G4double* bestDistance ) = 0;
0211
0212     /**
0213      * Returns the face extent along the axis.
0214      *  @param[in] axis Unit vector defining the direction.
0215      *  @returns The largest point along the given axis of the face's extent.
0216      */
0217     virtual G4double Extent( const G4ThreeVector axis ) = 0;
0218
0219     /**
0220      * Calculates the extent of the face for the voxel navigator.
0221      *  @param[in] axis The axis in which to check the shapes 3D extent against.
0222      *  @param[in] voxelLimit Limits along x, y, and/or z axes.
0223      *  @param[in] tranform A coordinate transformation on which to apply to
0224      *             the shape before testing.
0225      *  @param[out] extentList The list of (voxel) extents along the axis.
0226      */
0227     virtual void CalculateExtent( const EAxis axis,
0228                                   const G4VoxelLimits& voxelLimit,
0229                                   const G4AffineTransform& tranform,
0230                                   G4SolidExtentList& extentList       ) = 0;
0231
0232     /**
0233      * Method invoked by the copy constructor or the assignment operator.
0234      * Its purpose is to return a pointer to a duplicate copy of the face.
0235      */
0236     virtual G4VCSGface* Clone() = 0;
0237
0238     /**
0239      * Returning an estimation of the face surface area, in internal units.
0240      */
0241     virtual G4double SurfaceArea() = 0;
0242
0243     /**
0244      * Auxiliary method for GetPointOnSurface().
0245      */
0246     virtual G4ThreeVector GetPointOnFace() = 0;
0247 };
0248
0249 #endif