- added short section on IDDecoder

doc/LaTex/DDRecManual.tex

@@ -121,10 +121,10 @@ The \DDR API provides the following functionality:
   to positions of readout cells and vice versa
 \item access to a list of materials between any two points inside the world
   volume of the detector
-\item average material properties between two points
+\item access to the materials at any given point or along a straight line between two points
+\item averaged material properties for a list of materials
 \item computation of radiation and interaction lenghts for detector layers, modules
   or arbitrary sections through the detector
-\item ...
 \end{itemize}
 
 \noindent
@@ -540,6 +540,86 @@ of a reconstruction program for caching material properties !}
 
 
 
+%=============================================================================
+\section{IDDecoder}
+\label{sec:ddrec-manual-iddecoder}
+%=============================================================================
+Sensitive volumes in a \DDH geometry model are assigned a unique volume-ID. 
+This ID is then used by the corresponding {\em DDSegmentation} object
+to create a unique cellID for tracker and calorimeter hits, allowing
+to uniquely match hits to their sensitive volumes and also to their
+{\em DetElements} if they have been defined appropriately.
+During reconstruction tasks, including digitization of simulated hits,
+one often needs to convert between a cellID assigned to the hit and 
+the position of the corresponding detector cell. 
+For example one could write out simulated calorimeter hits without position
+information in order to save disk space and retrieve the position information
+based on the cellID. Another application might be a clustering algorithm
+where one looks for hits in the neighbor cells of a given hit.
+
+\noindent
+The functionality to do this is provided by the {\em IDDecoder} class with
+the following interface:
+
+\begin{code}
+  class IDDecoder {
+  public:
+     /// Default constructor using the name of the corresponding readout collection
+    IDDecoder(const std::string& collectionName);
+    
+     /// Default constructor using a readout object
+    IDDecoder(const Geometry::Readout& readout);
+    
+     /// Destructor
+    virtual ~IDDecoder();
+    
+     /// Returns the cell ID from the local position in the given volume ID.
+    CellID cellIDFromLocal(const Geometry::Position& local, const VolumeID volumeID) const;
+    
+     /// Returns the global cell ID from a given global position
+    CellID cellID(const Geometry::Position& global) const;
+    
+     /// Returns the global position from a given cell ID
+    Geometry::Position position(const CellID& cellID) const;
+    
+     /// Returns the local position from a given cell ID
+    Geometry::Position localPosition(const CellID& cellID) const;
+    
+     /// Returns the volume ID of a given cell ID
+    VolumeID volumeID(const CellID& cellID) const;
+    
+     /// Returns the volume ID of a given global position
+    VolumeID volumeID(const Geometry::Position& global) const;
+    
+     /// Returns the placement for a given cell ID
+    Geometry::PlacedVolume placement(const CellID& cellID) const;
+    
+     /// Returns the placement for a given global position
+    Geometry::PlacedVolume placement(const Geometry::Position& global) const;
+    
+     /// Returns the subdetector for a given cell ID
+    Geometry::DetElement subDetector(const CellID& cellID) const;
+    
+     /// Returns the subdetector for a given global position
+    Geometry::DetElement subDetector(const Geometry::Position& global) const;
+    
+     /// Returns the closest detector element in the hierarchy for a given cell ID
+    Geometry::DetElement detectorElement(const CellID& cellID) const;
+    
+     /// Returns the closest detector element in the hierarchy for a given global position
+    Geometry::DetElement detectorElement(const Geometry::Position& global) const;
+    
+     /// Calculates the neighbours of the given cell ID and adds them to the list of neighbours
+    void neighbours(const CellID& cellID, std::set<CellID>& neighbours) const;
+    
+     /// Checks if the given cell IDs are neighbours
+    bool areNeighbours(const CellID& cellID, const CellID& otherCellID) const;
+}
+\end{code}
+
+
+
+
 %=============================================================================
 \section{Detectors}
 \label{sec:ddrec-manual-detectors}