[Evt display] Add doxygen + howto comment on old event display

core/eventdisplay/CbmTimesliceManager.h

@@ -2,8 +2,6 @@
    SPDX-License-Identifier: GPL-3.0-only
    Authors: Pierre-Alain Loizeau[committer] */
 
-/// PAL 31/05/2023: based on FairEventManager from FairRoot v18.6.7
-
 #ifndef CbmTimesliceManager_H
 #define CbmTimesliceManager_H
 
@@ -33,6 +31,11 @@ class TGeoNode;
 class TGLAnnotation;
 class TGListTreeItem;
 
+/** @class CbmTimesliceManager
+ ** @author Pierre-Alain Loizeau <p.-a.loizeau@gsi.de>
+ ** @brief TBrowser Event display for Timeslices as Tree entry with CbmEvents in container. Function as unique Instance.
+ ** @brief Based on FairEventManager class of FairRoot v18.6.7
+ **/
 class CbmTimesliceManager : public TEveEventManager {
 public:
   static CbmTimesliceManager* Instance();
@@ -42,20 +45,33 @@ public:
   CbmTimesliceManager(const CbmTimesliceManager&) = delete;
   CbmTimesliceManager& operator=(const CbmTimesliceManager&) = delete;
 
+  /**
+   ** @brief Set path to xml configuration file for control of transparency and visibility of individual geometry nodes.
+   ** @param Full path to the xml file (without usage of variables such as ~ or $XXXX)
+   **/
   virtual void SetXMLConfig(TString xml_config) { fXMLConfig = xml_config; }
+  /**
+   ** @brief Select/add default set of views and some Hit and Tracks drawing classes for the CBM SIS100 electron setup.
+   **/
   void SetDisplayCbmElectron();
+  /**
+   ** @brief Select/add default set of views and some Hit and Tracks drawing classes for the CBM SIS100 muon setup.
+   **/
   void SetDisplayCbmMuon();
+  /**
+   ** @brief Select/add default set of views and some Hit and Tracks drawing classes for the mCBM 2022+ setups.
+   **/
   void SetDisplayMcbm();
   /**
-   * set detector's transparency
+   * set detector's transparency, typically called during processing of XML config file
    * @param use_xml  use xml colors if available
    * @param trans    transparency for detector (if xml not used)
    */
   virtual void SetTransparency(Bool_t use_xml, Int_t trans);
   /**
-   * switch background color
-   * @param light use white if true
-   */
+   ** switch background color: to be called by GUI element
+   ** @param light use white if true
+   **/
   virtual void SwitchBackground(Bool_t /*light*/);
 
   virtual void Init(Int_t visopt = 1, Int_t vislvl = 3, Int_t maxvisnds = 10000);
@@ -88,11 +104,10 @@ public:
   Bool_t GetClearHandler() const { return fClearHandler; }   ///< Used to indicate to subtask that they should reset
 
   /**
-   *
-   * @param name name of file with screenshot
-   * @param proj 0 - 3D view, 1 - RPhi, 2 RhoZ, 3 - all
-   * @param def_path - default path to screenshot, if empty -user will be asked
-   */
+   ** @brief Screenshot(s) generation: to be called by GUI element
+   ** @param screenshotType   see CbmTsEveAnimationControl, depends on CBM/mCBM mode
+   ** @param def_path         default path to screenshot, if empty user will be asked with GUI pop-up
+   **/
   void MakeScreenshot(CbmTsEveAnimationControl::eScreenshotType screenshotType, TString def_path = "");
 
 protected:

core/eventdisplay/CbmTimesliceManagerEditor.h

 /* Copyright (C) 2023 Facility for Antiproton and Ion Research in Europe, Darmstadt
    SPDX-License-Identifier: GPL-3.0-only
    Authors: Pierre-Alain Loizeau[committer] */
-/// Based on CbmTimesliceManagerEditor class of FairRoot v18.6.7
 
 #ifndef CbmTimesliceManagerEditor_H
 #define CbmTimesliceManagerEditor_H
@@ -25,6 +24,11 @@ class TGWindow;
 class TMemberInspector;
 class TObject;
 
+/** @class CbmTimesliceManagerEditor
+ ** @author Pierre-Alain Loizeau <p.-a.loizeau@gsi.de>
+ ** @brief GUI elements for CbmTimesliceManager. Automatically loaded by TBrowser. Cannot be used standalone!
+ ** @brief Based on FairEventManagerEditor class of FairRoot v18.6.7
+ **/
 class CbmTimesliceManagerEditor : public TGedFrame {
 public:
   CbmTimesliceManagerEditor(const TGWindow* p = 0, Int_t width = 250, Int_t height = 30, UInt_t options = kChildFrame,
@@ -35,28 +39,56 @@ public:
   CbmTimesliceManagerEditor& operator=(const CbmTimesliceManagerEditor&) = delete;
 
   /**
-    *
-    * @param light_background true if use white background
-    */
+   ** switch background color: to be called by GUI element
+   ** @param light use white if true
+   **/
   void SwitchBackground(Bool_t light_background);
 
   virtual void Init();
 
+  /**
+   ** @brief Select timeslice depending on GUI elements values, after clearing display. RESERVED FOR GUI CALLS!
+   **/
   virtual void SelectSingleTimeslice();
+  /**
+   ** @brief Select timeslice depending on GUI elements values and load its first event. RESERVED FOR GUI CALLS!
+   **/
   virtual void SelectTimeslice();
+  /**
+   ** @brief Select previous timeslice and load its first event. RESERVED FOR GUI CALLS!
+   **/
   virtual void PrevTimeslice();
+  /**
+   ** @brief Select next timeslice and load its first event. RESERVED FOR GUI CALLS!
+   **/
   virtual void NextTimeslice();
+  /**
+   ** @brief Select event in timeslice depending on GUI elements values, after clearing display. RESERVED FOR GUI CALLS!
+   **/
   virtual void SelectSingleEvent();
+  /**
+   ** @brief Select event in timeslice depending on GUI elements values. RESERVED FOR GUI CALLS!
+   **/
   virtual void SelectEvent();
+  /**
+   ** @brief Select previous event in timeslice. RESERVED FOR GUI CALLS!
+   **/
   virtual void PrevEvent();
+  /**
+   ** @brief Select next event in timeslice. RESERVED FOR GUI CALLS!
+   **/
   virtual void NextEvent();
 
   void SetModel(TObject* obj);
+
+  /**
+   ** @brief Start display: to be called by GUI element, see HowTo for description of options
+   **/
   virtual void StartAnimation();
 
   /**
-    * make screenshot
-    */
+    ** @brief Screenshot(s) generation: to be called by GUI element
+    **/
   void MakeScreenshot();
 
 protected:

core/eventdisplay/CbmTimeslicePixelHitSetDraw.h

@@ -16,8 +16,16 @@ class TClonesArray;
 class TObject;
 class TVector3;
 
+/** @class CbmTimesliceRecoTracks
+ ** @author Pierre-Alain Loizeau <p.-a.loizeau@gsi.de>
+ ** @brief Interface class to add Cbm Hits drawing (derived from PixelHit) to CbmTimesliceManager. Cannot be used alone!
+ **/
 class CbmTimeslicePixelHitSetDraw : public FairPointSetDraw {
 public:
+  /**
+   ** @brief Constructor
+   ** @param Name of the container/bramhc, ROOT color of the displayed points, ROOT style of the displayed points
+   **/
   CbmTimeslicePixelHitSetDraw(const char* name, Color_t color, Style_t mstyle, Int_t iVerbose = 1);
   virtual ~CbmTimeslicePixelHitSetDraw() = default;
 
@@ -25,6 +33,9 @@ public:
   virtual void Exec(Option_t* option);
   void Reset();
 
+  /**
+   ** @brief Load hits from selected event in timeslice. RESERVED FOR GUI CALLS!
+   **/
   void GotoEvent(uint32_t uEventIdx);
 
 protected:

core/eventdisplay/CbmTimesliceRecoTracks.h

@@ -29,12 +29,15 @@ class TParticle;
 class CbmTimesliceManager;
 #endif  // CbmTimesliceManager_H
 
+/** @class CbmTimesliceRecoTracks
+ ** @author Pierre-Alain Loizeau <p.-a.loizeau@gsi.de>
+ ** @brief Interface class to add Cbm Reco tracks drawing to CbmTimesliceManager. Cannot be used alone!
+ **/
 class CbmTimesliceRecoTracks : public FairTask {
 public:
   /** Default constructor **/
   CbmTimesliceRecoTracks() : CbmTimesliceRecoTracks("CbmTimesliceRecoTracks", 0) {}
 
-
   /** Standard constructor
     * @param name        Name of task
     * @param iVerbose    Verbosity level
@@ -55,6 +58,9 @@ public:
   virtual void SetParContainers() { ; }
   virtual void Finish() { ; }
 
+  /**
+   ** @brief Load tracks from selected event in timeslice. RESERVED FOR GUI CALLS!
+   **/
   void GotoEvent(uint32_t uEventIdx);
   void Reset();
   TEveTrackList* GetTrGroup(TParticle* P);

core/eventdisplay/CbmTsEveAnimationControl.h

@@ -10,7 +10,6 @@
  *		E-mail: daniel.wielanek@gmail.com
  *		Warsaw University of Technology, Faculty of Physics
  */
-/// PAL 01/06/2023: Heavily based on FairEveAnimationControl from FairRoot v18.6.7, for usage with CbmTimesliceManager
 
 #ifndef CBMTSEVEANIMATIONCONTROL_H_
 #define CBMTSEVEANIMATIONCONTROL_H_
@@ -29,6 +28,11 @@
 
 #include <GuiTypes.h>
 
+/** @class CbmTsEveAnimationControl
+ ** @author Pierre-Alain Loizeau <p.-a.loizeau@gsi.de>
+ ** @brief GUI elements to add animation and screenshot controls to CbmTimesliceManagerEditor. Cannot be used alone!
+ ** @brief PAL 31/05/2023: Heavily based on FairEveAnimationControl (for FairEventManagerEditor) from FairRoot v18.6.7
+ **/
 class CbmTsEveAnimationControl : public TNamed {
 public:
   enum eAnimationType
@@ -50,7 +54,9 @@ public:
 
   virtual ~CbmTsEveAnimationControl();
 
-
+  /**
+   ** @brief Tune list of allowed screenshot types depending on available CBM/mCBM views.
+   **/
   void SetDisplayMcbm(bool bEna) { fbMcbmViewersEna = bEna; }
 
   /**
@@ -92,9 +98,21 @@ public:
   Bool_t GetRunContinuous();
   Bool_t GetClearBuffer();
 
+  /**
+   ** @brief Update GUI elements to enforce options/limits. RESERVED FOR GUI CALLS!
+   **/
   void UpdateEnaScreenshots();
+  /**
+   ** @brief Update GUI elements to enforce options/limits. RESERVED FOR GUI CALLS!
+   **/
   void UpdateEnaDisButtons();
+  /**
+   ** @brief Update GUI elements to enforce options/limits. RESERVED FOR GUI CALLS!
+   **/
   void UpdateEventLimits();
+  /**
+   ** @brief Update GUI elements to enforce options/limits. RESERVED FOR GUI CALLS!
+   **/
   void UpdateTsLimits();
 
 private:

core/eventdisplay/CbmTsEveTransparencyControl.h

@@ -2,8 +2,6 @@
    SPDX-License-Identifier: GPL-3.0-only
    Authors: Pierre-Alain Loizeau [committer] */
 
-/// PAL 31/05/2023: clone of FairEveTransparencyControl from FairRoot v18.6.7 for usage with CbmTimesliceManager
-
 #ifndef CBMTSEVETRANSPARENCYCONTROL_H_
 #define CBMTSEVETRANSPARENCYCONTROL_H_
 
@@ -16,6 +14,11 @@ class TGCheckButton;
 class TGNumberEntry;  // lines 16-16
 class TMemberInspector;
 
+/** @class CbmTsEveTransparencyControl
+ ** @author Pierre-Alain Loizeau <p.-a.loizeau@gsi.de>
+ ** @brief GUI elements to add global transparency control to CbmTimesliceManagerEditor. Cannot be used alone!
+ ** @brief PAL 31/05/2023: clone of FairEveTransparencyControl (for FairEventManagerEditor) from FairRoot v18.6.7
+ **/
 class CbmTsEveTransparencyControl : public TGHorizontalFrame {
   TGCheckButton* fCheck;
   TGNumberEntry* fNumber;
@@ -26,7 +29,13 @@ public:
   TGCheckButton* GetCheck() const { return fCheck; }
   TGNumberEntry* GetNumber() const { return fNumber; }
 
+  /**
+   ** @brief Called when button clicked. RESERVED FOR GUI CALLS!
+   **/
   void Toggled();  // SLOT to receive check button events
+  /**
+   ** @brief Called when transparency value changed. RESERVED FOR GUI CALLS!
+   **/
   void ValueSet();  // SLOT to receive number entry events
 
   virtual ~CbmTsEveTransparencyControl() {};

docs/eventdisplay/HowTo.md

@@ -45,6 +45,13 @@ Source files of CBM specific classes are in `core/eventdisplay`
 
 => **Not maintained: no meaningful change since transition to git (>3 years), no Example macro found in current version
 of repository**
+=> **Not maintained: To be removed at some point?**
+=> **If removed probably some work needed on the Timeslice compatible version, as currently using it on the output of
+the run_s100e_reco_ev_ideal test give the following fatal error when selecting the first "timeslice" (entry with 1 event
+):**
+```
+CbmTimeslicePixelHitSetDraw::GotoEvent() => Failure, more TofHit in event 0 than available in the TS: 1291 VS 913
+```
 
 ### Typical usage pattern(To be completed by somebody really using it)
 1. Run event base reconstruction, whether on simulated or real data

macro/beamtime/mcbm2022/event_display_l1reco.C

@@ -2,8 +2,18 @@
    SPDX-License-Identifier: GPL-3.0-only
    Authors: Pierre-Alain Loizeau[committer] */
 
-/// FIXME: add support for alignment file
-
+/**
+ ** Start "timeslice + event" compatible event display with hits and reco tracks drawing. Need ROOT call w/o batch or
+ ** auto-quit CLI options (no "-b", no "-q"). For more details see HowTo page.
+ ** Parameters:
+ ** - uRunId = Index of the mCBM run, used to auto-detected the corresponding setup tag
+ ** - sRecoFile = full path to ".reco.root" file holding the reconstructed data (Hits and CbmRecoTracks)
+ ** - sGeoFile = full path to ".geo.root" file holding the full geometry
+ ** - sAlignFile = full path to geometry alignment file (FairRoot format)
+ ** - sXmlGeoConfig = full path (no `~`) to an xml config file, allowing for example to set the visibility,
+ **   transparency or color of any geometry node
+ ** - sUnpFile = optional path to file holding the Digi data
+ **/
 void event_display_l1reco(uint32_t uRunId, std::string sRecoFile, std::string sGeoFile, std::string sAlignFile = "",
                           std::string sXmlGeoConfig = "", std::string sUnpFile = "")
 {

macro/run/event_display_reco_ts.C

@@ -2,6 +2,18 @@
    SPDX-License-Identifier: GPL-3.0-only
    Authors: Pierre-Alain Loizeau[committer] */
 
+/**
+ ** Start "timeslice + event" compatible event display with hits and reco tracks drawing. Need ROOT call w/o batch or
+ ** auto-quit CLI options (no "-b", no "-q"). For more details see HowTo page.
+ ** Parameters:
+ ** - geoSetupTag = short name of the setup (same as provided to CbmSetup class)
+ ** - sRecoFile = full path to ".reco.root" file holding the reconstructed data (Hits and CbmRecoTracks)
+ ** - sGeoFile = full path to ".geo.root" file holding the full geometry
+ ** - sAlignFile = full path to geometry alignment file (FairRoot format)
+ ** - sXmlGeoConfig = full path (no `~`) to an xml config file, allowing for example to set the visibility,
+ **   transparency or color of any geometry node
+ ** - sUnpFile = optional path to file holding the Digi data
+ **/
 void event_display_reco_ts(TString geoSetupTag, std::string sRecoFile, std::string sGeoFile,
                            std::string sAlignFile = "", std::string sXmlGeoConfig = "", std::string sUnpFile = "")
 {