diff --git a/src/classes/PMusrCanvas.cpp b/src/classes/PMusrCanvas.cpp index de7aa4bbb..124e14f3f 100644 --- a/src/classes/PMusrCanvas.cpp +++ b/src/classes/PMusrCanvas.cpp @@ -50,7 +50,10 @@ ClassImp(PMusrCanvasPlotRange) // Constructor //-------------------------------------------------------------------------- /** - *

Constructor + * \brief Constructor initializing plot range to undefined state. + * + * Sets both X and Y ranges as not present and initializes all range + * values to zero. Ranges must be explicitly set via SetXRange/SetYRange. */ PMusrCanvasPlotRange::PMusrCanvasPlotRange() { @@ -67,10 +70,13 @@ PMusrCanvasPlotRange::PMusrCanvasPlotRange() // SetXRange (public) //-------------------------------------------------------------------------- /** - *

Sets the x-range values. + * \brief Sets the X-axis range and marks it as present. * - * \param xmin minimum range value - * \param xmax maximum range value + * Automatically swaps values if xmin > xmax to ensure proper ordering. + * Outputs a warning to stderr when swapping occurs. + * + * \param xmin Minimum X value + * \param xmax Maximum X value */ void PMusrCanvasPlotRange::SetXRange(Double_t xmin, Double_t xmax) { @@ -89,10 +95,13 @@ void PMusrCanvasPlotRange::SetXRange(Double_t xmin, Double_t xmax) // SetYRange (public) //-------------------------------------------------------------------------- /** - *

Sets the y-range values. + * \brief Sets the Y-axis range and marks it as present. * - * \param ymin minimum range value - * \param ymax maximum range value + * Automatically swaps values if ymin > ymax to ensure proper ordering. + * Outputs a warning to stderr when swapping occurs. + * + * \param ymin Minimum Y value + * \param ymax Maximum Y value */ void PMusrCanvasPlotRange::SetYRange(Double_t ymin, Double_t ymax) { @@ -114,7 +123,19 @@ ClassImpQ(PMusrCanvas) // Constructor //-------------------------------------------------------------------------- /** - *

Constructor + * \brief Default constructor initializing canvas to undefined state. + * + * Initializes all member variables to default values: + * - No timeout + * - N0 and background scaling enabled + * - Not valid (requires proper initialization via other constructors) + * - Data view mode + * - All pointers set to nullptr + * - Fourier and average structures initialized + * - No explicit ranges set + * + * This constructor creates an invalid canvas that cannot be used directly. + * Use one of the full constructors to create a functional canvas. */ PMusrCanvas::PMusrCanvas() { @@ -158,18 +179,30 @@ PMusrCanvas::PMusrCanvas() // Constructor //-------------------------------------------------------------------------- /** - *

Constructor. + * \brief Basic constructor creating canvas with default Fourier settings. * - * \param number The plot number of the msr-file PLOT block - * \param title Title to be displayed - * \param wtopx top x coordinate (in pixels) to place the canvas. - * \param wtopy top y coordinate (in pixels) to place the canvas. - * \param ww width (in pixels) of the canvas. - * \param wh height (in pixels) of the canvas. - * \param batch flag: if set true, the canvas will not be displayed. This is used when just dumping of a - * graphical output file is wished. - * \param fourier flag: if set true, the canvas will present the Fourier view. - * \param avg flag: if set true, the canvas will present the averages data/Fourier view. + * Creates a functional PMusrCanvas with standard Fourier transform settings + * and default markers/colors. This is the simpler constructor for cases where + * custom Fourier parameters or plot styling are not needed. + * + * Initialization sequence: + * 1. Initializes member variables + * 2. Sets up default Fourier parameters (via InitFourier) + * 3. Initializes average data structures (via InitAverage) + * 4. Creates ROOT graphics style (via CreateStyle) + * 5. Creates canvas pads and menus (via InitMusrCanvas) + * 6. Sets histogram minimum to zero for proper bar chart display + * + * \param number Plot number from MSR file PLOT block + * \param title Canvas title to display + * \param wtopx Top-left X coordinate of canvas window (pixels) + * \param wtopy Top-left Y coordinate of canvas window (pixels) + * \param ww Canvas width (pixels) + * \param wh Canvas height (pixels) + * \param batch If true, run in batch mode without GUI display (for file export) + * \param fourier If true, start with Fourier view instead of time domain + * \param avg If true, start with averaged data view + * \param theoAsData If true, calculate theory only at data points (faster) */ PMusrCanvas::PMusrCanvas(const Int_t number, const Char_t* title, Int_t wtopx, Int_t wtopy, Int_t ww, Int_t wh, @@ -205,21 +238,37 @@ PMusrCanvas::PMusrCanvas(const Int_t number, const Char_t* title, // Constructor //-------------------------------------------------------------------------- /** - *

Constructor. + * \brief Full constructor with custom Fourier settings and plot styling. * - * \param number The plot number of the msr-file PLOT block - * \param title Title to be displayed - * \param wtopx top x coordinate (in pixels) to place the canvas. - * \param wtopy top y coordinate (in pixels) to place the canvas. - * \param ww width (in pixels) of the canvas. - * \param wh height (in pixels) of the canvas. - * \param fourierDefault structure holding the pre-defined settings for a Fourier transform - * \param markerList pre-defined list of markers - * \param colorList pre-defined list of colors - * \param batch flag: if set true, the canvas will not be displayed. This is used when just dumping of a - * graphical output file is wished. - * \param fourier flag: if set true, the canvas will present the Fourier view. - * \param avg flag: if set true, the canvas will present the averages data/Fourier view. + * Creates a PMusrCanvas with user-specified Fourier transform parameters, + * custom marker styles, and color schemes. This constructor provides maximum + * control over canvas appearance and behavior. + * + * The marker and color lists allow customization of how multiple datasets + * appear in plots. Each dataset uses the marker/color at the corresponding + * index in the provided vectors. + * + * Initialization sequence: + * 1. Initializes member variables with custom settings + * 2. Copies Fourier parameters, marker list, and color list + * 3. Initializes average data structures + * 4. Creates ROOT graphics style + * 5. Creates canvas pads and menus + * 6. Sets histogram minimum to zero for proper bar chart display + * + * \param number Plot number from MSR file PLOT block + * \param title Canvas title to display + * \param wtopx Top-left X coordinate of canvas window (pixels) + * \param wtopy Top-left Y coordinate of canvas window (pixels) + * \param ww Canvas width (pixels) + * \param wh Canvas height (pixels) + * \param fourierDefault Fourier transform parameters (ranges, apodization, etc.) + * \param markerList Vector of ROOT marker style indices (e.g., 20=circle, 21=square) + * \param colorList Vector of ROOT color indices (e.g., 1=black, 2=red, 4=blue) + * \param batch If true, run in batch mode without GUI display + * \param fourier If true, start with Fourier view + * \param avg If true, start with averaged data view + * \param theoAsData If true, calculate theory only at data points */ PMusrCanvas::PMusrCanvas(const Int_t number, const Char_t* title, Int_t wtopx, Int_t wtopy, Int_t ww, Int_t wh, diff --git a/src/include/PMusrCanvas.h b/src/include/PMusrCanvas.h index afd4f7f2b..6c1a84204 100644 --- a/src/include/PMusrCanvas.h +++ b/src/include/PMusrCanvas.h @@ -50,65 +50,89 @@ #include "PRunListCollection.h" #endif // __MAKECLING__ -#define YINFO 0.1 -#define YTITLE 0.95 -#define XTHEO 0.75 +//-------------------------------------------------------------------------- +// Layout constants +//-------------------------------------------------------------------------- +#define YINFO 0.1 ///< Y-position of info/legend pad +#define YTITLE 0.95 ///< Y-position of title pad +#define XTHEO 0.75 ///< X-position of theory pad +//-------------------------------------------------------------------------- // Current Plot Views -#define PV_DATA 1 -#define PV_FOURIER_REAL 2 -#define PV_FOURIER_IMAG 3 -#define PV_FOURIER_REAL_AND_IMAG 4 -#define PV_FOURIER_PWR 5 -#define PV_FOURIER_PHASE 6 -#define PV_FOURIER_PHASE_OPT_REAL 7 +//-------------------------------------------------------------------------- +#define PV_DATA 1 ///< Plot view: time-domain data +#define PV_FOURIER_REAL 2 ///< Plot view: real part of Fourier transform +#define PV_FOURIER_IMAG 3 ///< Plot view: imaginary part of Fourier transform +#define PV_FOURIER_REAL_AND_IMAG 4 ///< Plot view: real and imaginary parts simultaneously +#define PV_FOURIER_PWR 5 ///< Plot view: power spectrum +#define PV_FOURIER_PHASE 6 ///< Plot view: phase spectrum +#define PV_FOURIER_PHASE_OPT_REAL 7 ///< Plot view: phase-optimized real part -// Canvas menu id's -#define P_MENU_ID_DATA 10001 -#define P_MENU_ID_FOURIER 10002 -#define P_MENU_ID_DIFFERENCE 10003 -#define P_MENU_ID_AVERAGE 10004 -#define P_MENU_ID_EXPORT_DATA 10005 +//-------------------------------------------------------------------------- +// Canvas menu IDs +//-------------------------------------------------------------------------- +#define P_MENU_ID_DATA 10001 ///< Menu ID for Data view +#define P_MENU_ID_FOURIER 10002 ///< Menu ID for Fourier submenu +#define P_MENU_ID_DIFFERENCE 10003 ///< Menu ID for Difference view (data-theory) +#define P_MENU_ID_AVERAGE 10004 ///< Menu ID for Average view +#define P_MENU_ID_EXPORT_DATA 10005 ///< Menu ID for Export Data function -#define P_MENU_PLOT_OFFSET 1000 +#define P_MENU_PLOT_OFFSET 1000 ///< Offset for plot-specific menu IDs -#define P_MENU_ID_FOURIER_REAL 100 -#define P_MENU_ID_FOURIER_IMAG 101 -#define P_MENU_ID_FOURIER_REAL_AND_IMAG 102 -#define P_MENU_ID_FOURIER_PWR 103 -#define P_MENU_ID_FOURIER_PHASE 104 -#define P_MENU_ID_FOURIER_PHASE_OPT_REAL 105 -#define P_MENU_ID_FOURIER_PHASE_PLUS 106 -#define P_MENU_ID_FOURIER_PHASE_MINUS 107 +//-------------------------------------------------------------------------- +// Fourier submenu IDs +//-------------------------------------------------------------------------- +#define P_MENU_ID_FOURIER_REAL 100 ///< Fourier menu: real part +#define P_MENU_ID_FOURIER_IMAG 101 ///< Fourier menu: imaginary part +#define P_MENU_ID_FOURIER_REAL_AND_IMAG 102 ///< Fourier menu: real and imaginary +#define P_MENU_ID_FOURIER_PWR 103 ///< Fourier menu: power spectrum +#define P_MENU_ID_FOURIER_PHASE 104 ///< Fourier menu: phase spectrum +#define P_MENU_ID_FOURIER_PHASE_OPT_REAL 105 ///< Fourier menu: phase-optimized real +#define P_MENU_ID_FOURIER_PHASE_PLUS 106 ///< Fourier menu: increment phase +#define P_MENU_ID_FOURIER_PHASE_MINUS 107 ///< Fourier menu: decrement phase //------------------------------------------------------------------------ /** - *

+ * \brief Helper class for managing plot axis ranges. + * + * Stores and manages X and Y axis ranges for plots, allowing explicit + * range specification from MSR file PLOT blocks or automatic range + * determination based on data. */ class PMusrCanvasPlotRange : public TObject { public: + /// Default constructor PMusrCanvasPlotRange(); + /// Destructor virtual ~PMusrCanvasPlotRange() {} + /// Sets X-axis range and marks it as present virtual void SetXRange(Double_t xmin, Double_t xmax); + /// Sets Y-axis range and marks it as present virtual void SetYRange(Double_t ymin, Double_t ymax); + /// Returns true if X-axis range has been explicitly set virtual Bool_t IsXRangePresent() { return fXRangePresent; } + /// Returns true if Y-axis range has been explicitly set virtual Bool_t IsYRangePresent() { return fYRangePresent; } + /// Returns minimum X value virtual Double_t GetXmin() { return fXmin; } + /// Returns maximum X value virtual Double_t GetXmax() { return fXmax; } + /// Returns minimum Y value virtual Double_t GetYmin() { return fYmin; } + /// Returns maximum Y value virtual Double_t GetYmax() { return fYmax; } private: - Bool_t fXRangePresent; - Bool_t fYRangePresent; - Double_t fXmin; - Double_t fXmax; - Double_t fYmin; - Double_t fYmax; + Bool_t fXRangePresent; ///< Flag: true if X-range explicitly set + Bool_t fYRangePresent; ///< Flag: true if Y-range explicitly set + Double_t fXmin; ///< Minimum X value + Double_t fXmax; ///< Maximum X value + Double_t fYmin; ///< Minimum Y value + Double_t fYmax; ///< Maximum Y value ClassDef(PMusrCanvasPlotRange, 1) }; @@ -197,44 +221,139 @@ typedef std::vector PMusrCanvasAsciiDumpVector; //-------------------------------------------------------------------------- /** - *

The preprocessor tag __MAKECLING__ is used to hide away from rootcling - * the overly complex spirit header files. + * \brief ROOT-based canvas for interactive visualization of muSR data and fits. + * + * PMusrCanvas provides comprehensive visualization capabilities for muSR data analysis: + * + * **Display Modes:** + * - Time-domain data with fitted theory curves + * - Difference plots (data - theory) + * - Fourier transforms (real, imaginary, power, phase) + * - Phase-optimized real Fourier spectra + * - Averaged data across multiple runs + * + * **Supported Fit Types:** + * - Single histogram fits + * - Asymmetry fits (forward-backward, alpha-beta-LR) + * - Beta-NMR asymmetry + * - Non-muSR data (generic X-Y plots with errors) + * + * **Interactive Features:** + * - Menu-driven view switching (Data/Fourier/Difference/Average) + * - Keyboard shortcuts for quick navigation + * - Phase adjustment for Fourier transforms + * - Data export to ASCII format + * - Graphics export (EPS, PDF, PNG, etc.) + * - Automatic timeout for batch processing + * + * **Canvas Layout:** + * The canvas is divided into several pads: + * - Title pad: Displays MSR file title + * - Data/Theory pad: Main plotting area for histograms/graphs + * - Parameter pad: Shows fitted parameter values + * - Theory pad: Lists theory functions used in fit + * - Info/Legend pad: Displays run information and legend + * + * **Integration:** + * - Reads MSR files via PMsrHandler + * - Accesses fit results via PRunListCollection + * - Uses ROOT's TCanvas and graphics primitives + * - Supports both interactive and batch modes + * + * \note The preprocessor tag __MAKECLING__ is used to hide complex + * Boost Spirit headers from rootcling during dictionary generation + * + * \see PMsrHandler for MSR file management + * \see PRunListCollection for fit results + * \see PMsrFourierStructure for Fourier transform parameters */ class PMusrCanvas : public TObject, public TQObject { public: + /// Default constructor PMusrCanvas(); + + //---------------------------------------------------------------------- + /** + * \brief Basic constructor for canvas without custom markers/colors. + * + * \param number Plot number from MSR file PLOT block + * \param title Canvas title + * \param wtopx X-position of canvas window (pixels) + * \param wtopy Y-position of canvas window (pixels) + * \param ww Canvas width (pixels) + * \param wh Canvas height (pixels) + * \param batch If true, run in batch mode (no GUI) + * \param fourier If true, start with Fourier view instead of time domain + * \param avg If true, start with averaged view + * \param theoAsData If true, calculate theory only at data points + */ PMusrCanvas(const Int_t number, const Char_t* title, Int_t wtopx, Int_t wtopy, Int_t ww, Int_t wh, const Bool_t batch, const Bool_t fourier=false, const Bool_t avg=false, const Bool_t theoAsData=false, const Bool_t useDKS=false); + + //---------------------------------------------------------------------- + /** + * \brief Full constructor with Fourier defaults and custom markers/colors. + * + * \param number Plot number from MSR file PLOT block + * \param title Canvas title + * \param wtopx X-position of canvas window (pixels) + * \param wtopy Y-position of canvas window (pixels) + * \param ww Canvas width (pixels) + * \param wh Canvas height (pixels) + * \param fourierDefault Default Fourier transform parameters + * \param markerList Vector of ROOT marker styles for plots + * \param colorList Vector of ROOT color indices for plots + * \param batch If true, run in batch mode (no GUI) + * \param fourier If true, start with Fourier view instead of time domain + * \param avg If true, start with averaged view + * \param theoAsData If true, calculate theory only at data points + */ PMusrCanvas(const Int_t number, const Char_t* title, Int_t wtopx, Int_t wtopy, Int_t ww, Int_t wh, PMsrFourierStructure fourierDefault, const PIntVector markerList, const PIntVector colorList, const Bool_t batch, const Bool_t fourier=false, const Bool_t avg=false, const Bool_t theoAsData=false, const Bool_t useDKS=false); + + /// Destructor - cleans up all histograms, graphs, and ROOT objects virtual ~PMusrCanvas(); + /// Returns true if canvas initialized successfully virtual Bool_t IsValid() { return fValid; } #ifndef __MAKECLING__ + /// Sets the MSR file handler for accessing fit parameters and configuration virtual void SetMsrHandler(PMsrHandler *msrHandler); + /// Sets the run list collection for accessing fit data and results virtual void SetRunListCollection(PRunListCollection *runList) { fRunList = runList; } #endif // __MAKECLING__ + /// Sets timeout in seconds after which Done signal is emitted (0=no timeout) virtual void SetTimeout(Int_t ival); + /// Updates parameter and theory display pads with current fit results virtual void UpdateParamTheoryPad(); + /// Updates main data/theory plotting pad virtual void UpdateDataTheoryPad(); + /// Updates info/legend pad with run information virtual void UpdateInfoPad(); + /// ROOT signal emitted when canvas is closed or timeout occurs virtual void Done(Int_t status=0); // *SIGNAL* + /// ROOT slot handling keyboard commands (e.g., 'f' for Fourier, 'd' for data) virtual void HandleCmdKey(Int_t event, Int_t x, Int_t y, TObject *selected); // SLOT + /// ROOT slot handling menu selections virtual void HandleMenuPopup(Int_t id); // SLOT + /// ROOT slot called when this is the last canvas being closed virtual void LastCanvasClosed(); // SLOT + /// ROOT slot called when canvas window is closed virtual void WindowClosed(); // SLOT + /// Saves canvas to graphics file and emits Done signal virtual void SaveGraphicsAndQuit(Char_t *fileName, Char_t *graphicsFormat); + /// Exports displayed data to ASCII file virtual void ExportData(const Char_t *fileName); private: