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