source: trunk/documents/UserDoc/DocBookUsersGuides/ForToolkitDeveloper/xml/GuideToExtendFunctionality/Geometry/geometry.xml@ 1345

<!-- ******************************************************** -->
<!--  Docbook Version:  For Toolkit Developers Guide          -->
<!-- ******************************************************** -->

<!-- ******************* Section (Level#1) ****************** -->
<sect1 id="sect.ExtdFuncGeom">
<title>
Geometry
</title>

<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.ExtdFuncGeom.WhtCan">
<title>
What can be extended ?
</title>

<para>
Geant4 already allows a user to describe any desired solid,
and to use it in a detector description, in some cases, however,
the user may want or need to extend Geant4's geometry.
One reason can be that some methods and types in the geometry
are general and the user can utilise specialised knowledge about
his or her geometry to gain a speedup. The most evident case where
this can happen is when a particular type of solid is a key
element for a specific detector geometry and an investment in
improving its runtime performance may be worthwhile.
</para>

<para>
To extend the functionality of the Geometry in this way,
a toolkit developer must write a small number of methods for
the new solid.
We will document below these methods and their specifications.
Note that the implementation details for some methods are not a
trivial matter: these methods must provide the functionality of
finding whether a point is inside a solid, finding the
intersection of a line with it, and finding the distance to the
solid along any direction. However once the solid class has been
created with all its specifications fulfilled, it can be used like
any Geant4 solid, as it implements the abstract interface of G4VSolid.
</para>

<para>
Other additions can also potentially be achieved. For example, 
an advanced user could add a new way of creating physical volumes.
However, because each type of volume has a corresponding navigator
helper, this would require to create a new Navigator as well.
To do this the user would have to inherit from G4Navigator and
modify the new Navigator to handle this type of volumes.
This can certainly be done, but will probably be made easier to
achieve in the future versions of the Geant4 toolkit. 
</para>

</sect2>

<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.ExtdFuncGeom.AddSld">
<title>
Adding a new type of Solid
</title>

<para>
We list below the required methods for integrating a new type
of solid in Geant4. Note that Geant4's specifications for a
solid pay significant attention to what happens at points that
are within a small distance (tolerance, 
<emphasis role="bold">kCarTolerance</emphasis> 
in the code) of the surface. So special care must be taken to
handle these cases in considering all different possible
scenarios, in order to respect the specifications and allow
the solid to be used correctly by the other components of the
geometry module.
</para>

<!-- ******* Bridgehead ******* -->
<bridgehead renderas='sect4'>
Creating a derived class of G4VSolid
</bridgehead>

<para>
The solid must inherit from G4VSolid or one of its 
derived classes and implement its virtual functions. 
</para>

<para>
Mandatory member functions you must define are the following 
pure virtual of G4VSolid: 

<informalexample><programlisting>
 EInside Inside(const G4ThreeVector&amp; p)
 G4double DistanceToIn(const G4ThreeVector&amp; p)
 G4double DistanceToIn(const G4ThreeVector&amp; p, const G4ThreeVector&amp; v)
 G4ThreeVector SurfaceNormal(const G4ThreeVector&amp; p)
 G4double DistanceToOut(const G4ThreeVector&amp; p)
 G4double DistanceToOut(const G4ThreeVector&amp; p, const G4ThreeVector&amp; v,
                        const G4bool calcNorm=false,
                              G4bool *validNorm=0, G4ThreeVector *n)
 G4bool CalculateExtent(const EAxis pAxis,
                        const G4VoxelLimits&amp; pVoxelLimit,
                        const G4AffineTransform&amp; pTransform,
                              G4double&amp; pMin,
                              G4double&amp; pMax) const
 G4GeometryType GetEntityType() const
 std::ostream&amp; StreamInfo(std::ostream&amp; os) const
</programlisting></informalexample>
</para>

<para>
They must perform the following functions 

<informalexample><programlisting>
  EInside Inside(const G4ThreeVector&amp; p)
</programlisting></informalexample>

This method must return: 

<itemizedlist spacing="compact">
  <listitem><para>
    kOutside if the point at offset p is outside the shape 
    boundaries plus Tolerance/2, 
  </para></listitem>
  <listitem><para>
    kSurface if the point is &lt;= Tolerance/2 from a surface, or 
  </para></listitem>
  <listitem><para>
    kInside otherwise. 
  </para></listitem>
</itemizedlist>
</para>

<para>
<informalexample><programlisting>
G4ThreeVector SurfaceNormal(const G4ThreeVector&amp; p)
</programlisting></informalexample>

Return the outwards pointing unit normal of the shape for the 
surface closest to the point at offset p.

<informalexample><programlisting>
G4double DistanceToIn(const G4ThreeVector&amp; p)
</programlisting></informalexample>

Calculate distance to nearest surface of shape from an outside 
point p. The distance can be an underestimate. 

<informalexample><programlisting>
G4double DistanceToIn(const G4ThreeVector&amp; p, const G4ThreeVector&amp; v)
</programlisting></informalexample>

Return the distance along the normalised vector v to the shape, 
from the point at offset p. If there is no intersection, return
kInfinity. The first intersection resulting from `leaving' 
a surface/volume is discarded. Hence, this is tolerant of points on
surface of shape.

<informalexample><programlisting>
G4double DistanceToOut(const G4ThreeVector&amp; p)
</programlisting></informalexample>

Calculate distance to nearest surface of shape from an inside 
point. The distance can be an underestimate. 

<informalexample><programlisting>
G4double DistanceToOut(const G4ThreeVector&amp; p, const G4ThreeVector&amp; v,
                        const G4bool calcNorm=false,
                        G4bool *validNorm=0, G4ThreeVector *n=0);
</programlisting></informalexample>

Return distance along the normalised vector v to the shape, from 
a point at an offset p inside or on the surface of the shape.
Intersections with surfaces, when the point is not greater than 
kCarTolerance/2 from a surface, must be ignored. 
</para>

<para>
If calcNorm is true, then it must also set validNorm to either 
<itemizedlist spacing="compact">
<listitem><para></para></listitem>true, if the solid lies entirely behind or on the exiting 
      surface. Then it must set n to the outwards normal vector (the
      Magnitude of the vector is not defined). 
<listitem><para></para></listitem>false, if the solid does not lie entirely behind or on the 
      exiting surface. 
</itemizedlist>
</para>

<para>
If calcNorm is false, then validNorm and n are unused. 

<informalexample><programlisting>
G4bool CalculateExtent(const EAxis pAxis,
                        const G4VoxelLimits&amp; pVoxelLimit,
                        const G4AffineTransform&amp; pTransform,
                              G4double&amp; pMin,
                              G4double&amp; pMax) const
</programlisting></informalexample>

Calculate the minimum and maximum extent of the solid, when under the
specified transform, and within the specified limits. If the solid
is not intersected by the region, return false, else return true.

<informalexample><programlisting>
G4GeometryType GetEntityType() const;
</programlisting></informalexample>

Provide identification of the class of an object (required for
persistency and STEP interface).

<informalexample><programlisting>
std::ostream&amp; StreamInfo(std::ostream&amp; os) const
</programlisting></informalexample>

Should dump the contents of the solid to an output stream.
</para>

<para>
The method:

<informalexample><programlisting>
G4double GetCubicVolume()
</programlisting></informalexample>

should be implemented for every solid in order to cache the computed
value (and therefore reuse it for future calls to the method) and to
eventually implement a precise computation of the solid's volume. If
the method will not be overloaded, the default implementation from the
base class will be used (estimation through a Monte Carlo algorithm)
and the computed value will not be stored.
</para>

<para>
There are a few member functions to be defined for the purpose of 
visualisation. The first method is mandatory, and the next four are not. 

<informalexample><programlisting>
  // Mandatory
  virtual void DescribeYourselfTo (G4VGraphicsScene&amp; scene) const = 0;

  // Not mandatory
  virtual G4VisExtent GetExtent() const;
  virtual G4Polyhedron* CreatePolyhedron () const;
  virtual G4NURBS*      CreateNURBS      () const;
  virtual G4Polyhedron* GetPolyhedron    () const;
</programlisting></informalexample>

What these methods should do and how they should be implemented is
described here. 

<informalexample><programlisting>
 void DescribeYourselfTo (G4VGraphicsScene&amp; scene) const;
</programlisting></informalexample>

This method is required in order to identify the solid to the graphics scene. 
It is used for the purposes of ``double dispatch''. All implementations 
should be similar to the one for G4Box: 

<informalexample><programlisting>
void G4Box::DescribeYourselfTo (G4VGraphicsScene&amp; scene) const
{
  scene.AddSolid (*this);
}
</programlisting></informalexample>

The method:

<informalexample><programlisting>
 G4VisExtent GetExtent() const;
</programlisting></informalexample>

provides extent (bounding box) as a possible hint to the graphics view. 
You must create it by finding a box that encloses your solid, and returning 
a VisExtent that is created from this. 
The G4VisExtent must presumably be given the minus x, plus x,
minus y, plus y, minus z and plus z extents of this ``box''. 
For example a cylinder can say 

<informalexample><programlisting>
G4VisExtent G4Tubs::GetExtent() const
{
  // Define the sides of the box into which the G4Tubs instance would fit.
  return G4VisExtent (-fRMax, fRMax, -fRMax, fRMax, -fDz, fDz);
}
</programlisting></informalexample>

The method:

<informalexample><programlisting>
 G4Polyhedron* CreatePolyhedron () const;
</programlisting></informalexample>

is required by the visualisation system, in order to create a 
realistic rendering of your solid. To create a G4Polyhedron for
your solid, consult G4Polyhedron.
</para>

<para>
While the method:

<informalexample><programlisting>
 G4Polyhedron* GetPolyhedron () const;
</programlisting></informalexample>

is a ``smart'' access function that creates on requests a polyhedron
and stores it for future access and should be customised for every solid.
</para>

<para>
The method:

<informalexample><programlisting>
 G4NURBS* CreateNURBS () const;
</programlisting></informalexample>

is not currently utilised, so you do not have to implement it. 
</para>

</sect2>

<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.ExtdFuncGeom.ModNav">
<title>
Modifying the Navigator
</title>

<para>
For the vast majority of use-cases, it is not indeed necessary
(and definitely not advised) to extend or modify the existing
classes for navigation in the geometry.
A possible use-case for which this may apply, is for the
description of a new kind of physical volume to be integrated.
We believe that our set of choices for creating physical volumes
is varied enough for nearly all needs.
Future extensions of the Geant4 toolkit will probably make
easier exchanging or extending the G4Navigator, by introducing an
abstraction level simplifying the customisation. At this time,
a simple abstraction level of the navigator is provided by allowing
overloading of the relevant functionalities.
</para>

<!-- ******* Bridgehead ******* -->
<bridgehead renderas='sect4'>
Extending the Navigator
</bridgehead>

<para>
The main responsibilities of the Navigator are: 

<itemizedlist spacing="compact">
  <listitem><para>
    locate a point in the tree of the geometrical volumes; 
  </para></listitem>
  <listitem><para>
    compute the length a particle can travel from a point
    in a certain direction before encountering a volume
      boundary. 
  </para></listitem>
</itemizedlist>
</para>

<para>
The Navigator utilises one helper class for each type of physical 
volume that exists. You will have to reuse the helper classes provided
in the base Navigator or create new ones for the new type of physical volume. 
</para>

<para>
To extend G4Navigator you will have then to inherit from it 
and modify these functions in your ModifiedNavigator to
request the answers for your new physical volume type from the
new helper class. The ModifiedNavigator should delegate other
cases to the Geant4's standard Navigator. 
</para>


<!-- ******* Bridgehead ******* -->
<bridgehead renderas='sect4'>
Replacing the Navigator
</bridgehead>

<para>
Replacing the Navigator is another possible operation. It is 
similar to extending the Navigator, in that any types of physical
volume that will be allowed must be handled by it. The same 
functionality is required as described in the previous section. 
</para>

<para>
However the amount of work is probably potentially larger, if 
support for all the current types of physical volumes is required.
</para>

<para>
The Navigator utilises one helper class for each type of 
physical volume that exists. These could also potentially be 
replaced, allowing a simpler way to create a new navigation
system. 
</para>

</sect2>
</sect1>