[1208] | 1 | \chapter{Geometry} |
---|
| 2 | |
---|
| 3 | \section{What can be extended ?} |
---|
| 4 | {\sc Geant4} already allows a user to describe any desired solid, |
---|
| 5 | and to use it in a detector description, in some cases, however, |
---|
| 6 | the user may want or need to extend {\sc Geant4}'s geometry. |
---|
| 7 | One reason can be that some methods and types in the geometry |
---|
| 8 | are general and the user can utilise specialised knowledge about |
---|
| 9 | his or her geometry to gain a speedup. The most evident case where |
---|
| 10 | this can happen is when a particular type of solid is a key |
---|
| 11 | element for a specific detector geometry and an investment in |
---|
| 12 | improving its runtime performance may be worthwhile. |
---|
| 13 | |
---|
| 14 | To extend the functionality of the Geometry in this way, |
---|
| 15 | a toolkit developer must write a small number of methods for |
---|
| 16 | the new solid. |
---|
| 17 | We will document below these methods and their specifications. |
---|
| 18 | Note that the implementation details for some methods are not a |
---|
| 19 | trivial matter: these methods must provide the functionality of |
---|
| 20 | finding whether a point is inside a solid, finding the |
---|
| 21 | intersection of a line with it, and finding the distance to the |
---|
| 22 | solid along any direction. However once the solid class has been |
---|
| 23 | created with all its specifications fulfilled, it can be used like |
---|
| 24 | any {\sc Geant4} solid, as it implements the abstract interface of G4VSolid. |
---|
| 25 | |
---|
| 26 | Other additions can also potentially be achieved. For example, |
---|
| 27 | an advanced user could add a new way of creating physical volumes. |
---|
| 28 | However, because each type of volume has a corresponding navigator |
---|
| 29 | helper, this would require to create a new Navigator as well. |
---|
| 30 | To do this the user would have to inherit from G4Navigator and |
---|
| 31 | modify the new Navigator to handle this type of volumes. |
---|
| 32 | This can certainly be done, but will probably be made easier to |
---|
| 33 | achieve in the future versions of the {\sc Geant4} toolkit. |
---|
| 34 | |
---|
| 35 | \section{Adding a new type of Solid} |
---|
| 36 | We list below the required methods for integrating a new type |
---|
| 37 | of solid in {\sc Geant4}. Note that {\sc Geant4}'s specifications for a |
---|
| 38 | solid pay significant attention to what happens at points that |
---|
| 39 | are within a small distance (tolerance, {\em kCarTolerance} in |
---|
| 40 | the code) of the surface. So special care must be taken to |
---|
| 41 | handle these cases in considering all different possible |
---|
| 42 | scenarios, in order to respect the specifications and allow |
---|
| 43 | the solid to be used correctly by the other components of the |
---|
| 44 | geometry module. |
---|
| 45 | |
---|
| 46 | \paragraph{Creating a derived class of G4VSolid} |
---|
| 47 | The solid must inherit from G4VSolid or one of its |
---|
| 48 | derived classes and implement its virtual functions. |
---|
| 49 | |
---|
| 50 | Mandatory member functions you must define are the following |
---|
| 51 | pure virtual of G4VSolid: |
---|
| 52 | \begin{verbatim} |
---|
| 53 | EInside Inside(const G4ThreeVector& p) |
---|
| 54 | G4double DistanceToIn(const G4ThreeVector& p) |
---|
| 55 | G4double DistanceToIn(const G4ThreeVector& p, const G4ThreeVector& v) |
---|
| 56 | G4ThreeVector SurfaceNormal(const G4ThreeVector& p) |
---|
| 57 | G4double DistanceToOut(const G4ThreeVector& p) |
---|
| 58 | G4double DistanceToOut(const G4ThreeVector& p, const G4ThreeVector& v, |
---|
| 59 | const G4bool calcNorm=false, |
---|
| 60 | G4bool *validNorm=0, G4ThreeVector *n) |
---|
| 61 | G4bool CalculateExtent(const EAxis pAxis, |
---|
| 62 | const G4VoxelLimits& pVoxelLimit, |
---|
| 63 | const G4AffineTransform& pTransform, |
---|
| 64 | G4double& pMin, |
---|
| 65 | G4double& pMax) const |
---|
| 66 | G4GeometryType GetEntityType() const |
---|
| 67 | std::ostream& StreamInfo(std::ostream& os) const |
---|
| 68 | \end{verbatim} |
---|
| 69 | They must perform the following functions |
---|
| 70 | |
---|
| 71 | \begin{verbatim} |
---|
| 72 | EInside Inside(const G4ThreeVector& p) |
---|
| 73 | \end{verbatim} |
---|
| 74 | This method must return: |
---|
| 75 | \begin{itemize} |
---|
| 76 | \item kOutside if the point at offset p is outside the shape |
---|
| 77 | boundaries plus Tolerance/2, |
---|
| 78 | \item kSurface if the point is $<=$ Tolerance/2 from a surface, or |
---|
| 79 | \item kInside otherwise. |
---|
| 80 | \end{itemize} |
---|
| 81 | |
---|
| 82 | \begin{verbatim} |
---|
| 83 | G4ThreeVector SurfaceNormal(const G4ThreeVector& p) |
---|
| 84 | \end{verbatim} |
---|
| 85 | Return the outwards pointing unit normal of the shape for the |
---|
| 86 | surface closest to the point at offset p. |
---|
| 87 | |
---|
| 88 | \begin{verbatim} |
---|
| 89 | G4double DistanceToIn(const G4ThreeVector& p) |
---|
| 90 | \end{verbatim} |
---|
| 91 | Calculate distance to nearest surface of shape from an outside |
---|
| 92 | point p. The distance can be an underestimate. |
---|
| 93 | |
---|
| 94 | \begin{verbatim} |
---|
| 95 | G4double DistanceToIn(const G4ThreeVector& p, const G4ThreeVector& v) |
---|
| 96 | \end{verbatim} |
---|
| 97 | Return the distance along the normalised vector v to the shape, |
---|
| 98 | from the point at offset p. If there is no intersection, return |
---|
| 99 | kInfinity. The first intersection resulting from `leaving' |
---|
| 100 | a surface/volume is discarded. Hence, this is tolerant of points on |
---|
| 101 | surface of shape. |
---|
| 102 | |
---|
| 103 | \begin{verbatim} |
---|
| 104 | G4double DistanceToOut(const G4ThreeVector& p) |
---|
| 105 | \end{verbatim} |
---|
| 106 | Calculate distance to nearest surface of shape from an inside |
---|
| 107 | point. The distance can be an underestimate. |
---|
| 108 | |
---|
| 109 | \begin{verbatim} |
---|
| 110 | G4double DistanceToOut(const G4ThreeVector& p, const G4ThreeVector& v, |
---|
| 111 | const G4bool calcNorm=false, |
---|
| 112 | G4bool *validNorm=0, G4ThreeVector *n=0); |
---|
| 113 | \end{verbatim} |
---|
| 114 | Return distance along the normalised vector v to the shape, from |
---|
| 115 | a point at an offset p inside or on the surface of the shape. |
---|
| 116 | Intersections with surfaces, when the point is not greater than |
---|
| 117 | kCarTolerance/2 from a surface, must be ignored. |
---|
| 118 | |
---|
| 119 | If calcNorm is true, then it must also set validNorm to either |
---|
| 120 | \begin{itemize} |
---|
| 121 | \item true, if the solid lies entirely behind or on the exiting |
---|
| 122 | surface. Then it must set n to the outwards normal vector (the |
---|
| 123 | Magnitude of the vector is not defined). |
---|
| 124 | \item false, if the solid does not lie entirely behind or on the |
---|
| 125 | exiting surface. |
---|
| 126 | \end{itemize} |
---|
| 127 | If calcNorm is false, then validNorm and n are unused. |
---|
| 128 | \begin{verbatim} |
---|
| 129 | G4bool CalculateExtent(const EAxis pAxis, |
---|
| 130 | const G4VoxelLimits& pVoxelLimit, |
---|
| 131 | const G4AffineTransform& pTransform, |
---|
| 132 | G4double& pMin, |
---|
| 133 | G4double& pMax) const |
---|
| 134 | \end{verbatim} |
---|
| 135 | Calculate the minimum and maximum extent of the solid, when under the |
---|
| 136 | specified transform, and within the specified limits. If the solid |
---|
| 137 | is not intersected by the region, return false, else return true. |
---|
| 138 | |
---|
| 139 | \begin{verbatim} |
---|
| 140 | G4GeometryType GetEntityType() const; |
---|
| 141 | \end{verbatim} |
---|
| 142 | Provide identification of the class of an object (required for |
---|
| 143 | persistency and STEP interface). |
---|
| 144 | |
---|
| 145 | \begin{verbatim} |
---|
| 146 | std::ostream& StreamInfo(std::ostream& os) const |
---|
| 147 | \end{verbatim} |
---|
| 148 | Should dump the contents of the solid to an output stream. |
---|
| 149 | |
---|
| 150 | The method: |
---|
| 151 | |
---|
| 152 | \begin{verbatim} |
---|
| 153 | G4double GetCubicVolume() |
---|
| 154 | \end{verbatim} |
---|
| 155 | should be implemented for every solid in order to cache the computed |
---|
| 156 | value (and therefore reuse it for future calls to the method) and to |
---|
| 157 | eventually implement a precise computation of the solid's volume. If |
---|
| 158 | the method will not be overloaded, the default implementation from the |
---|
| 159 | base class will be used (estimation through a Monte Carlo algorithm) |
---|
| 160 | and the computed value will not be stored. |
---|
| 161 | |
---|
| 162 | There are a few member functions to be defined for the purpose of |
---|
| 163 | visualisation. The first method is mandatory, and the next four are not. |
---|
| 164 | |
---|
| 165 | \begin{verbatim} |
---|
| 166 | // Mandatory |
---|
| 167 | virtual void DescribeYourselfTo (G4VGraphicsScene& scene) const = 0; |
---|
| 168 | |
---|
| 169 | // Not mandatory |
---|
| 170 | virtual G4VisExtent GetExtent() const; |
---|
| 171 | virtual G4Polyhedron* CreatePolyhedron () const; |
---|
| 172 | virtual G4NURBS* CreateNURBS () const; |
---|
| 173 | virtual G4Polyhedron* GetPolyhedron () const; |
---|
| 174 | \end{verbatim} |
---|
| 175 | What these methods should do and how they should be implemented is |
---|
| 176 | described here. |
---|
| 177 | |
---|
| 178 | \begin{verbatim} |
---|
| 179 | void DescribeYourselfTo (G4VGraphicsScene& scene) const; |
---|
| 180 | \end{verbatim} |
---|
| 181 | This method is required in order to identify the solid to the graphics scene. |
---|
| 182 | It is used for the purposes of ``double dispatch''. All implementations |
---|
| 183 | should be similar to the one for G4Box: |
---|
| 184 | |
---|
| 185 | \begin{verbatim} |
---|
| 186 | void G4Box::DescribeYourselfTo (G4VGraphicsScene& scene) const |
---|
| 187 | { |
---|
| 188 | scene.AddSolid (*this); |
---|
| 189 | } |
---|
| 190 | \end{verbatim} |
---|
| 191 | The method: |
---|
| 192 | |
---|
| 193 | \begin{verbatim} |
---|
| 194 | G4VisExtent GetExtent() const; |
---|
| 195 | \end{verbatim} |
---|
| 196 | provides extent (bounding box) as a possible hint to the graphics view. |
---|
| 197 | You must create it by finding a box that encloses your solid, and returning |
---|
| 198 | a VisExtent that is created from this. |
---|
| 199 | The G4VisExtent must presumably be given the minus x, plus x, |
---|
| 200 | minus y, plus y, minus z and plus z extents of this ``box''. |
---|
| 201 | For example a cylinder can say |
---|
| 202 | |
---|
| 203 | \begin{verbatim} |
---|
| 204 | G4VisExtent G4Tubs::GetExtent() const |
---|
| 205 | { |
---|
| 206 | // Define the sides of the box into which the G4Tubs instance would fit. |
---|
| 207 | return G4VisExtent (-fRMax, fRMax, -fRMax, fRMax, -fDz, fDz); |
---|
| 208 | } |
---|
| 209 | \end{verbatim} |
---|
| 210 | The method: |
---|
| 211 | |
---|
| 212 | \begin{verbatim} |
---|
| 213 | G4Polyhedron* CreatePolyhedron () const; |
---|
| 214 | \end{verbatim} |
---|
| 215 | is required by the visualisation system, in order to create a |
---|
| 216 | realistic rendering of your solid. To create a G4Polyhedron for |
---|
| 217 | your solid, consult G4Polyhedron. |
---|
| 218 | |
---|
| 219 | While the method: |
---|
| 220 | |
---|
| 221 | \begin{verbatim} |
---|
| 222 | G4Polyhedron* GetPolyhedron () const; |
---|
| 223 | \end{verbatim} |
---|
| 224 | is a ``smart'' access function that creates on requests a polyhedron |
---|
| 225 | and stores it for future access and should be customised for every solid. |
---|
| 226 | |
---|
| 227 | The method: |
---|
| 228 | |
---|
| 229 | \begin{verbatim} |
---|
| 230 | G4NURBS* CreateNURBS () const; |
---|
| 231 | \end{verbatim} |
---|
| 232 | is not currently utilised, so you do not have to implement it. |
---|
| 233 | |
---|
| 234 | \section{Modifying the Navigator} |
---|
| 235 | For the vast majority of use-cases, it is not indeed necessary |
---|
| 236 | (and definitely not advised) to extend or modify the existing |
---|
| 237 | classes for navigation in the geometry. |
---|
| 238 | A possible use-case for which this may apply, is for the |
---|
| 239 | description of a new kind of physical volume to be integrated. |
---|
| 240 | We believe that our set of choices for creating physical volumes |
---|
| 241 | is varied enough for nearly all needs.\newline |
---|
| 242 | Future extensions of the {\sc Geant4} toolkit will probably make |
---|
| 243 | easier exchanging or extending the G4Navigator, by introducing an |
---|
| 244 | abstraction level simplifying the customisation. At this time, |
---|
| 245 | a simple abstraction level of the navigator is provided by allowing |
---|
| 246 | overloading of the relevant functionalities. |
---|
| 247 | |
---|
| 248 | \paragraph{Extending the Navigator} |
---|
| 249 | The main responsibilities of the Navigator are: |
---|
| 250 | \begin{itemize} |
---|
| 251 | \item locate a point in the tree of the geometrical volumes; |
---|
| 252 | \item compute the length a particle can travel from a point |
---|
| 253 | in a certain direction before encountering a volume |
---|
| 254 | boundary. |
---|
| 255 | \end{itemize} |
---|
| 256 | The Navigator utilises one helper class for each type of physical |
---|
| 257 | volume that exists. You will have to reuse the helper classes provided |
---|
| 258 | in the base Navigator or create new ones for the new type of physical volume. |
---|
| 259 | |
---|
| 260 | To extend G4Navigator you will have then to inherit from it |
---|
| 261 | and modify these functions in your ModifiedNavigator to |
---|
| 262 | request the answers for your new physical volume type from the |
---|
| 263 | new helper class. The ModifiedNavigator should delegate other |
---|
| 264 | cases to the {\sc Geant4}'s standard Navigator. |
---|
| 265 | |
---|
| 266 | \paragraph{Replacing the Navigator} |
---|
| 267 | Replacing the Navigator is another possible operation. It is |
---|
| 268 | similar to extending the Navigator, in that any types of physical |
---|
| 269 | volume that will be allowed must be handled by it. The same |
---|
| 270 | functionality is required as described in the previous section. |
---|
| 271 | |
---|
| 272 | However the amount of work is probably potentially larger, if |
---|
| 273 | support for all the current types of physical volumes is required. |
---|
| 274 | |
---|
| 275 | The Navigator utilises one helper class for each type of |
---|
| 276 | physical volume that exists. These could also potentially be |
---|
| 277 | replaced, allowing a simpler way to create a new navigation |
---|
| 278 | system. |
---|