source: trunk/documents/UserDoc/DocBookUsersGuides/ForApplicationDeveloper/xml/Detector/geomTouch.xml @ 905

<!-- ******************************************************** -->
<!--                                                          -->
<!--  [History]                                               -->
<!--    Converted to DocBook: Katsuya Amako, Aug-2006         -->
<!--    Changed by: Gabriele Cosmo, 18-Apr-2005               -->
<!--                                                          -->
<!-- ******************************************************** -->


<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.Geom.Touch">
<title>
Touchables: Uniquely Identifying a Volume
</title>


<!-- ******************* Section (Level#3) ****************** -->
<sect3 id="sect.Geom.Touch.Intro">
<title>
Introduction to Touchables
</title>

<para>
A <emphasis>touchable</emphasis> for a volume serves the purpose of providing
a unique identification for a detector element. This can be useful
for description of the geometry alternative to the one used by the
Geant4 tracking system, such as a Sensitive Detectors based
read-out geometry, or a parameterised geometry for fast Monte
Carlo. In order to create a <emphasis>touchable volume</emphasis>, several
techniques can be implemented: for example, in Geant4 touchables
are implemented as solids associated to a transformation-matrix in
the global reference system, or as a hierarchy of physical volumes
up to the root of the geometrical tree.
</para>

<para>
A touchable is a geometrical entity (volume or solid) which has
a unique placement in a detector description. It is represented by
an abstract base class which can be implemented in a variety of
ways. Each way must provide the capabilities of obtaining the
transformation and solid that is described by the touchable.
</para>

</sect3>

<!-- ******************* Section (Level#3) ****************** -->
<sect3 id="sect.Geom.Touch.WhatCan">
<title>
What can a Touchable do?
</title>

<para>
All <literal>G4VTouchable</literal> implementations must respond to the
two following "requests", where in all cases, by <literal>depth</literal> it
is meant the number of levels <emphasis>up</emphasis> in the tree to be
considered (the default and current one is <literal>0</literal>):

<orderedlist spacing="compact">
  <listitem><para>
    <literal>GetTranslation(depth)</literal>
  </para></listitem>
  <listitem><para>
    <literal>GetRotation(depth)</literal>
  </para></listitem>
</orderedlist>

that return the components of the volume's transformation.
</para>

<para>
Additional capabilities are available from implementations with
more information. These have a default implementation that causes
an exception.
</para>

<para>
Several capabilities are available from touchables with physical
volumes:

<orderedlist continuation="continues" >
  <listitem><para>
    <literal>GetSolid(depth)</literal> gives the solid associated to the
    touchable.
  </para></listitem>
  <listitem><para>
    <literal>GetVolume(depth)</literal> gives the physical volume.
  </para></listitem>
  <listitem><para>
    <literal>GetReplicaNumber(depth)</literal> or
    <literal>GetCopyNumber(depth)</literal> which return the copy number of the
    physical volume (replicated or not).
  </para></listitem>
</orderedlist>
</para>

<para>
Touchables that store volume hierarchy (history) have the whole
stack of parent volumes available. Thus it is possible to add a
little more state in order to extend its functionality. We add a
"pointer" to a level and a member function to move the level in
this stack. Then calling the above member functions for another
level the information for that level can be retrieved.
</para>

<para>
The top of the history tree is, by convention, the world
volume.

<orderedlist continuation="continues" >
  <listitem><para>
    <literal>GetHistoryDepth()</literal> gives the depth of the history
    tree.
  </para></listitem>
  <listitem><para>
    <para>
    <literal>MoveUpHistory(num)</literal> moves the current pointer inside
    the touchable to point <literal>num</literal> levels up the history tree.
    Thus, e.g., calling it with <literal>num=1</literal> will cause the internal
    pointer to move to the mother of the current volume.
    </para>
    <para>
    WARNING: this function changes the state of the touchable and can
    cause errors in tracking if applied to Pre/Post step
    touchables.
    </para>
  </para></listitem>
</orderedlist>
</para>

<para>
These methods are valid only for the <emphasis>touchable-history</emphasis> type,
as specified also below.
</para>

<para>
An update method, with different arguments is available, so that
the information in a touchable can be updated:

<orderedlist continuation="continues" >
  <listitem><para>
    <literal>UpdateYourself(vol, history)</literal> takes a physical volume
    pointer and can additionally take a <literal>NavigationHistory</literal>
    pointer.
  </para></listitem>
</orderedlist>
</para>

</sect3>

<!-- ******************* Section (Level#3) ****************** -->
<sect3 id="sect.Geom.Touch.History">
<title>
Touchable history holds stack of geometry data
</title>

<para>
As shown in Sections 
<xref linkend="sect.Geom.LogVol" /> and <xref linkend="sect.Geom.PhysVol" />, 
a logical volume represents unpositioned detector elements, and a physical 
volume can represent multiple detector elements. On the other hand,
touchables provide a unique identification for a detector element.
In particular, the Geant4 transportation process and the tracking
system exploit touchables as implemented in
<literal>G4TouchableHistory</literal>. The touchable history is the minimal
set of information required to specify the full genealogy of a
given physical volume (up to the root of the geometrical tree).
These touchable volumes are made available to the user at every
step of the Geant4 tracking in <literal>G4VUserSteppingAction</literal>.
</para>

<para>
To create/access a <literal>G4TouchableHistory</literal> the user must
message <literal>G4Navigator</literal> which provides the method
<literal>CreateTouchableHistoryHandle()</literal>:

<informalexample>
<programlisting>
  G4TouchableHistoryHandle CreateTouchableHistoryHandle() const;
</programlisting>
</informalexample>

this will return a handle to the touchable.
</para>

<para>
The methods that differentiate the touchable-history from other
touchables (since they have meaning only for this type...),
are:

<informalexample>
<programlisting>
  G4int GetHistoryDepth()  const;
  G4int MoveUpHistory( G4int num_levels = 1 );
</programlisting>
</informalexample>
</para>

<para>
The first method is used to find out how many levels deep in the
geometry tree the current volume is. The second method asks the
touchable to eliminate its deepest level.
</para>

<para>
As mentioned above, <literal>MoveUpHistory(num)</literal> significantly
modifies the state of a touchable.
</para>


</sect3>
</sect2>