Calorimetery/ExtractIndicesFromCellID/README.md

0001 # Extracting Indices From CellIDs
0002
0003 A short ROOT macro illustrating how to extract the value of individual
0004 fields from a `CellID`.  The `CellID` is a bit field that stores all
0005 of the various indices and IDs, referred to as _fields_ in DD4hep,
0006 that define a unique volume.  The no. of bits in the bit field
0007 allocated to each field is defined in the `readouts` element in each
0008 detector's compact (xml) file.
0009
0010 Really, there are 2 parts to unpacking a CellID. First is to
0011 initialize necessary DD4hep interfaces:
0012
0013 ```c++
0014 // 1) entry point into DD4hep interface
0015 static std::unique_ptr<dd4hep::Detector> detector = dd4hep::Detector::make_unique("");
0016 detector->fromCompact("/path/to/my/epic.xml");
0017
0018 // 2) interface for working with readout fields/cell IDs
0019 //   --> argument should be name of readouts element
0020 //       in your xml file
0021 dd4hep::IDDescriptor descriptor = detector->readout("HcalBarrelHits");
0022
0023 // 3) utility for unpacking cell IDs
0024 dd4hep::DDSegmentation::BitFieldCoder* decoder = descriptor.decoder();
0025 ```
0026
0027 Then field values can be extracted from a cell ID like so:
0028
0029 ```c++
0030 value = decoder -> get(hit.getCellID(), "field");
0031 ```
0032
0033 Note that while calorimter hits are used as the example, the same
0034 process applies to any object that has a CellID.
0035
0036
0037 ## Inputs/Outputs
0038
0039 Processes `.edm4eic.root` output from EICrecon.
0040
0041
0042 ## Dependencies
0043
0044 Needs `PODIO` and `edm4eic`. If you're running in the eic-shell,
0045 then it can be run out-of-the-box with the command below.
0046
0047
0048 ## Usage
0049
0050 To run, do:
0051 ```
0052 root -b -q ExtractCellIndices.cxx
0053 ```