Constructor + *
Default constructor - creates uninitialized canvas. + * + *
Initializes all member variables to safe default values. This + * constructor produces an invalid canvas (IsValid() returns false). + * Use full constructors with Fourier data for functional canvases. + * + *
State after construction: + * - No timeout, no batch mode + * - All view flags disabled + * - Empty title and axis labels + * - Zero phase offset + * - Null GUI pointers + * + *
Primarily used internally or for two-stage initialization patterns. */ PFourierCanvas::PFourierCanvas() { @@ -76,19 +89,39 @@ PFourierCanvas::PFourierCanvas() //--------------------------------------------------------------------------- /** - *
Constructor + *
Full constructor with automatic marker/color generation. * - * \param fourier - * \param title - * \param showAverage - * \param fourierPlotOpt - * \param fourierXrange - * \param phase - * \param wtopx - * \param wtopy - * \param ww - * \param wh - * \param batch + *
Creates a complete, functional Fourier canvas ready for display. + * Automatically generates random but consistent markers (styles 20-29) + * and colors for each dataset based on seeded random numbers. + * + *
Initialization sequence: + * 1. Store configuration parameters + * 2. Generate random markers/colors (reproducible from dataset index) + * 3. Create axis titles based on unit type + * 4. Set up ROOT plotting style + * 5. Generate all Fourier histograms (Re/Im/Pwr/Phase/PhaseOpt) + * 6. Create ROOT canvas with menus and pads + * 7. Connect signals/slots for interactivity + * + * @param fourier Vector of PFourier objects (must be already transformed) + * @param dataSetTag Dataset group identifiers for averaging + * @param title Window title string + * @param showAverage Start in all-data averaged view + * @param showAveragePerDataSet Start in per-dataset averaged view + * @param fourierPlotOpt Initial view mode (FOURIER_PLOT_*) + * @param fourierXrange X-axis display range [min, max] + * @param phase Initial phase offset in degrees (for Re/Im views) + * @param wtopx Canvas window x-position in pixels + * @param wtopy Canvas window y-position in pixels + * @param ww Canvas width in pixels + * @param wh Canvas height in pixels + * @param batch If true, suppress GUI (for automated plotting) + * + *
Check IsValid() after construction to verify success.
+ *
+ * @see InitFourierDataSets()
+ * @see InitFourierCanvas()
*/
PFourierCanvas::PFourierCanvas(std::vector Constructor
+ * Full constructor with explicit marker/color specification.
*
- * \param fourier
- * \param title
- * \param showAverage
- * \param fourierPlotOpt
- * \param fourierXrange
- * \param phase
- * \param wtopx
- * \param wtopy
- * \param ww
- * \param wh
- * \param markerList
- * \param colorList
- * \param batch
+ * Creates a complete Fourier canvas with user-defined plot styling.
+ * Provides full control over visual appearance by specifying ROOT marker
+ * styles and color indices for each dataset.
+ *
+ * Marker styles: ROOT marker codes (typically 20-34):
+ * - 20: filled circle
+ * - 21: filled square
+ * - 22: filled triangle up
+ * - 23: filled triangle down
+ * - etc.
+ *
+ * Colors: ROOT color palette indices or RGB-defined colors
+ * via TColor::GetColor(r,g,b).
+ *
+ * Partial lists: If markerList or colorList contain fewer
+ * entries than datasets, remaining entries are auto-generated randomly.
+ *
+ * @param fourier Vector of PFourier objects (must be already transformed)
+ * @param dataSetTag Dataset group identifiers for averaging
+ * @param title Window title string
+ * @param showAverage Start in all-data averaged view
+ * @param showAveragePerDataSet Start in per-dataset averaged view
+ * @param fourierPlotOpt Initial view mode (FOURIER_PLOT_*)
+ * @param fourierXrange X-axis display range [min, max]
+ * @param phase Initial phase offset in degrees (for Re/Im views)
+ * @param wtopx Canvas window x-position in pixels
+ * @param wtopy Canvas window y-position in pixels
+ * @param ww Canvas width in pixels
+ * @param wh Canvas height in pixels
+ * @param markerList ROOT marker style codes for each dataset
+ * @param colorList ROOT color indices for each dataset
+ * @param batch If true, suppress GUI (for automated plotting)
+ *
+ * Check IsValid() after construction to verify success.
+ *
+ * @see InitFourierDataSets()
+ * @see InitFourierCanvas()
*/
PFourierCanvas::PFourierCanvas(std::vector Signal emitted that the user wants to terminate the application.
+ * Emits Done signal to notify parent application of canvas closure.
*
- * \param status Status info
+ * This ROOT signal mechanism allows parent objects to connect cleanup
+ * handlers or application flow logic. Typically called when:
+ * - User closes canvas window
+ * - User presses 'q' to quit
+ * - Timeout expires
+ * - SaveGraphicsAndQuit() completes
+ *
+ * @param status Exit status: 0=normal, non-zero=error/abort
+ *
+ * Example connection:
+ * @code
+ * PFourierCanvas *canvas = new PFourierCanvas(...);
+ * QObject::connect(canvas, SIGNAL(Done(Int_t)), app, SLOT(Quit()));
+ * @endcode
+ *
+ * @see LastCanvasClosed()
+ * @see SaveGraphicsAndQuit()
*/
void PFourierCanvas::Done(Int_t status)
{
@@ -198,19 +271,37 @@ void PFourierCanvas::Done(Int_t status)
// HandleCmdKey (SLOT)
//--------------------------------------------------------------------------
/**
- * Filters keyboard events, and if they are a command key (see below) carries out the
- * necessary actions.
- * Currently implemented command keys:
- * - 'q' quit musrview
- * - 'u' unzoom to the original plot range given in the msr-file.
- * - 'a' toggle between average view and single Fourier histo view.
- * - '+' increment the phase (real/imaginary Fourier). The phase step is defined in the musrfit_startup.xml
- * - '-' decrement the phase (real/imaginary Fourier). The phase step is defined in the musrfit_startup.xml
+ * Processes keyboard shortcuts for canvas control.
*
- * \param event event type
- * \param x character key
- * \param y not used
- * \param selected not used
+ * This slot receives keyboard events from ROOT and dispatches
+ * appropriate actions. Ignored in batch mode.
+ *
+ * Keyboard shortcuts:
+ * - 'q': Quit - emits Done(0) signal to close canvas
+ * - 'u': Unzoom - reset view to initial X/Y range
+ * - 'a': Toggle all-data average view on/off
+ * - 'd': Toggle per-dataset average view on/off
+ * - 'c': Toggle crosshair cursor on/off
+ * - '+': Increment phase by 5° (Re/Im views only)
+ * - '-': Decrement phase by 5° (Re/Im views only)
+ *
+ * Phase adjustment: Only affects Real and Imaginary Fourier
+ * views. Phase value is displayed as text overlay on canvas.
+ *
+ * Average toggling: 'a' and 'd' are mutually exclusive.
+ * Activating one deactivates the other. Switching triggers histogram
+ * recomputation via HandleAverage().
+ *
+ * @param event ROOT event type (must be kKeyPress to process)
+ * @param x ASCII code of pressed key
+ * @param y Mouse y-coordinate (unused)
+ * @param selected Object under cursor (unused)
+ *
+ * @see IncrementFourierPhase()
+ * @see DecrementFourierPhase()
+ * @see HandleAverage()
+ * @see PlotFourier()
+ * @see PlotAverage()
*/
void PFourierCanvas::HandleCmdKey(Int_t event, Int_t x, Int_t y, TObject *selected)
{
@@ -282,9 +373,33 @@ void PFourierCanvas::HandleCmdKey(Int_t event, Int_t x, Int_t y, TObject *select
// HandleMenuPopup (SLOT)
//--------------------------------------------------------------------------
/**
- * Handles the MusrFT menu.
+ * Processes menu selection events from the MusrFT menu bar.
*
- * \param id identification key of the selected menu
+ * Handles all menu item clicks including:
+ * - Fourier view mode selection (Real/Imag/Power/Phase/etc.)
+ * - Averaging mode toggles (All/Per-dataset/Off)
+ * - Phase adjustment (±5°)
+ * - Data export
+ *
+ * Menu structure:
+ * - MusrFT/Fourier: View mode submenu
+ * - Real, Imaginary, Real+Imag, Power, Phase, Phase-Optimized
+ * - Phase +/- adjustments
+ * - MusrFT/Average: All-data average toggle
+ * - MusrFT/Average Per Data Set: Per-dataset average toggle
+ * - MusrFT/Export Data: Save to ASCII file
+ *
+ * View changes trigger canvas redraw with new histogram type.
+ * Averaging changes recompute histograms via HandleAverage().
+ *
+ * Ignored in batch mode.
+ *
+ * @param id Menu item identifier (P_MENU_ID_* constants)
+ *
+ * @see HandleAverage()
+ * @see PlotFourier()
+ * @see PlotAverage()
+ * @see ExportData()
*/
void PFourierCanvas::HandleMenuPopup(Int_t id)
{
@@ -473,9 +588,26 @@ void PFourierCanvas::UpdateInfoPad()
// SetTimeout (public)
//--------------------------------------------------------------------------
/**
- * sets the timeout after which the program shall terminate.
+ * Configures automatic canvas closure after specified timeout.
*
- * \param timeout after which the done signal shall be emitted. Given in seconds
+ * Creates and starts a ROOT TTimer that emits Done() signal after
+ * the timeout expires. Useful for:
+ * - Batch processing with timed display
+ * - Automated testing and screenshot capture
+ * - Slideshow-style data review
+ *
+ * If timeout ≤ 0, no timer is created (infinite display time).
+ *
+ * Timer behavior: Single-shot (kTRUE flag), fires once then stops.
+ *
+ * @param timeout Duration in seconds before auto-close (≤0 = disabled)
+ *
+ * Example:
+ * @code
+ * canvas->SetTimeout(30); // Close after 30 seconds
+ * @endcode
+ *
+ * @see Done()
*/
void PFourierCanvas::SetTimeout(Int_t timeout)
{
@@ -495,9 +627,32 @@ void PFourierCanvas::SetTimeout(Int_t timeout)
// SaveGraphicsAndQuit
//--------------------------------------------------------------------------
/**
- * Will save the canvas as graphics output. Needed in the batch mode of musrview.
+ * Exports canvas to graphics file and terminates.
*
- * \param fileName file name under which the canvas shall be saved.
+ * Saves current canvas view to image file, then emits Done(0) signal
+ * to trigger cleanup. Primary use: batch mode automated plotting.
+ *
+ * Supported formats (determined by file extension):
+ * - .pdf: Vector PDF (best for publications)
+ * - .eps: Encapsulated PostScript (vector)
+ * - .png: Raster PNG (good for web/presentations)
+ * - .jpg/.jpeg: Raster JPEG (compressed)
+ * - .svg: Scalable Vector Graphics
+ * - .root: ROOT file (preserves interactive features)
+ * - .C: ROOT macro (for programmatic recreation)
+ *
+ * ROOT's TCanvas::SaveAs() handles format detection automatically.
+ *
+ * @param fileName Output file path with extension indicating format
+ *
+ * Batch mode workflow:
+ * @code
+ * PFourierCanvas *canvas = new PFourierCanvas(..., batch=true);
+ * canvas->SaveGraphicsAndQuit("output.pdf");
+ * // Canvas closes automatically after saving
+ * @endcode
+ *
+ * @see Done()
*/
void PFourierCanvas::SaveGraphicsAndQuit(const Char_t *fileName)
{
@@ -512,7 +667,44 @@ void PFourierCanvas::SaveGraphicsAndQuit(const Char_t *fileName)
// ExportData
//--------------------------------------------------------------------------
/**
- * Exports the currently displayed Fourier data set in ascii column format.
+ * Exports currently displayed Fourier spectrum to ASCII data file.
+ *
+ * Writes frequency/field values and corresponding spectrum amplitudes
+ * in columnar text format suitable for:
+ * - External plotting tools (Origin, MATLAB, Gnuplot, etc.)
+ * - Statistical analysis packages (R, Python, etc.)
+ * - Spreadsheet applications (Excel, LibreOffice)
+ * - Archival data storage
+ *
+ * File format:
+ * - Header: Column labels (X-axis, dataset names)
+ * - Data: Space-separated columns
+ * - Column 1: Frequency/field values
+ * - Columns 2+: Spectrum values for each dataset
+ *
+ * Exported spectrum: Depends on current view mode:
+ * - Real view → Real parts
+ * - Imaginary view → Imaginary parts
+ * - Power view → Power spectra
+ * - Phase view → Phase spectra
+ * - Phase-optimized → Phase-corrected real parts
+ * - Real+Imag view → Both real and imaginary columns
+ *
+ * Averaging: If average mode active, exports averaged data
+ * instead of individual runs.
+ *
+ * X-range: Only exports visible X-axis range (honors zoom).
+ *
+ * @param pathFileName Output file path (typically .dat extension).
+ * Must not be nullptr.
+ *
+ * Example output format:
+ * @code
+ * # Field(G) Run1_Real Run2_Real Run3_Real
+ * 100.5 0.234 0.221 0.245
+ * 101.0 0.198 0.187 0.203
+ * ...
+ * @endcode
*/
void PFourierCanvas::ExportData(const Char_t *pathFileName)
{
diff --git a/src/include/PFourierCanvas.h b/src/include/PFourierCanvas.h
index b7c186bc4..c82c12631 100644
--- a/src/include/PFourierCanvas.h
+++ b/src/include/PFourierCanvas.h
@@ -66,54 +66,236 @@
//------------------------------------------------------------------------
/**
- * Structure holding all necessary Fourier histograms.
+ * Structure holding all Fourier transform histograms for one data set.
+ *
+ * This structure bundles all different representations of a single
+ * Fourier transform, including real, imaginary, power, phase, and
+ * phase-optimized spectra. Each μSR run or dataset gets one instance.
+ *
+ * Purpose: Provides complete Fourier analysis results in one
+ * container for easy access and visualization switching.
+ *
+ * @see PFourierCanvas
+ * @see PFourier
*/
struct PFourierCanvasDataSet {
- TH1F *dataFourierRe; ///< real part of the Fourier transform of the data histogram
- TH1F *dataFourierIm; ///< imaginary part of the Fourier transform of the data histogram
- TH1F *dataFourierPwr; ///< power spectrum of the Fourier transform of the data histogram
- TH1F *dataFourierPhase; ///< phase spectrum of the Fourier transform of the data histogram
- TH1F *dataFourierPhaseOptReal; ///< phase otpimized real Fourier transform of the data histogram
- std::vector typedef to make to code more readable: list of histogram data sets.
+ * Type alias for a collection of Fourier data sets.
+ *
+ * Represents multiple μSR runs or datasets, each with complete
+ * Fourier transform results. Used for multi-run visualization and
+ * averaging operations.
+ *
+ * @see PFourierCanvasDataSet
*/
typedef std::vector
+ * Interactive ROOT canvas for visualizing μSR Fourier transform spectra.
+ *
+ * PFourierCanvas provides a sophisticated GUI for displaying and analyzing
+ * Fourier-transformed μSR data with multiple viewing modes:
+ * - Real spectrum (absorption mode)
+ * - Imaginary spectrum (dispersion mode)
+ * - Real + Imaginary overlay
+ * - Power spectrum (magnitude)
+ * - Phase spectrum
+ * - Phase-optimized real spectrum
+ *
+ * Key features:
+ * - Multi-run visualization with color/marker coding
+ * - Interactive phase adjustment (±5° increments)
+ * - Automatic averaging across all runs or per dataset
+ * - Export to data files
+ * - Batch mode for non-interactive operation
+ * - Customizable markers and colors
+ * - Menu-driven interface with keyboard shortcuts
+ *
+ * Usage modes:
+ * - Interactive: Full GUI with menus for exploring spectra
+ * - Batch: Automated plot generation for scripts
+ * - Individual: Display each run separately
+ * - Averaged: Show ensemble average across all data
+ * - Per-dataset average: Average within grouped datasets
+ *
+ * Architecture: Uses ROOT TQObject for signal/slot mechanism,
+ * enabling clean event handling and timeout functionality.
+ *
+ * @see PFourier
+ * @see PFourierCanvasDataSet
*/
class PFourierCanvas : public TObject, public TQObject
{
public:
+ /**
+ * Default constructor - creates empty canvas.
+ *
+ * Initializes internal state with default values. Not typically
+ * used directly; prefer constructors with data parameters.
+ */
PFourierCanvas();
+
+ /**
+ * Constructor with automatic marker/color generation.
+ *
+ * Creates interactive Fourier canvas with randomly generated
+ * markers and colors for each data set.
+ *
+ * @param fourier Vector of PFourier objects containing transformed data
+ * @param dataSetTag Vector of dataset identifiers for grouping runs
+ * @param title Canvas window title
+ * @param showAverage If true, display average across all runs
+ * @param showAveragePerDataSet If true, average within each dataset group
+ * @param fourierPlotOpt Initial plot mode (real/imag/power/phase/etc.)
+ * @param fourierXrange X-axis range [min, max] in output units (G/T/MHz)
+ * @param phase Initial phase offset in degrees for Re/Im display
+ * @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 interaction)
+ */
PFourierCanvas(std::vector Constructor with explicit marker/color specification.
+ *
+ * Creates interactive Fourier canvas with user-defined visual
+ * styling for each data set. Provides full control over plot appearance.
+ *
+ * @param fourier Vector of PFourier objects containing transformed data
+ * @param dataSetTag Vector of dataset identifiers for grouping runs
+ * @param title Canvas window title
+ * @param showAverage If true, display average across all runs
+ * @param showAveragePerDataSet If true, average within each dataset group
+ * @param fourierPlotOpt Initial plot mode (real/imag/power/phase/etc.)
+ * @param fourierXrange X-axis range [min, max] in output units (G/T/MHz)
+ * @param phase Initial phase offset in degrees for Re/Im display
+ * @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 markerList ROOT marker styles (20-30) for each dataset
+ * @param colorList ROOT color indices for each dataset
+ * @param batch If true, run in batch mode (no GUI interaction)
+ */
PFourierCanvas(std::vector Signal emitted when user closes canvas or timeout expires.
+ *
+ * This signal notifies parent applications that the canvas
+ * is terminating. Used for cleanup and application flow control.
+ *
+ * @param status Exit status code (0 = normal, non-zero = error)
+ */
virtual void Done(Int_t status=0); // *SIGNAL*
+
+ /**
+ * Slot for handling keyboard events in the canvas.
+ *
+ * Processes keyboard shortcuts:
+ * - '+': Increment phase by 5°
+ * - '-': Decrement phase by 5°
+ * - Other keys: Reserved for future use
+ *
+ * @param event ROOT event type identifier
+ * @param x Mouse x-coordinate at event time
+ * @param y Mouse y-coordinate at event time
+ * @param selected ROOT object under cursor (if any)
+ */
virtual void HandleCmdKey(Int_t event, Int_t x, Int_t y, TObject *selected); // SLOT
+
+ /**
+ * Slot for handling menu selection events.
+ *
+ * Processes menu item selections:
+ * - View mode changes (Real/Imag/Power/Phase/etc.)
+ * - Averaging toggles (All/Per-dataset/Off)
+ * - Data export
+ * - Phase adjustments
+ *
+ * @param id Menu item identifier (P_MENU_ID_* constants)
+ */
virtual void HandleMenuPopup(Int_t id); // SLOT
+
+ /**
+ * Slot called when canvas window is closed by user.
+ *
+ * Triggers cleanup and emits Done() signal. Part of ROOT's
+ * window management system.
+ */
virtual void LastCanvasClosed(); // SLOT
+ /**
+ * Redraws the Fourier spectrum pad with current settings.
+ *
+ * Updates the main plotting area with current view mode,
+ * phase settings, and averaging options. Called automatically
+ * after parameter changes.
+ */
virtual void UpdateFourierPad();
+
+ /**
+ * Redraws the legend/info pad with current dataset information.
+ *
+ * Updates the legend showing which datasets are displayed,
+ * with appropriate markers and colors.
+ */
virtual void UpdateInfoPad();
+ /**
+ * Checks if canvas initialized successfully.
+ *
+ * @return True if canvas is ready for display, false on initialization errors
+ */
virtual Bool_t IsValid() { return fValid; }
+ /**
+ * Sets automatic timeout for canvas closure.
+ *
+ * Useful for batch processing or automated testing. Canvas
+ * emits Done() signal after timeout expires.
+ *
+ * @param ival Timeout in milliseconds (≤0 = no timeout)
+ */
virtual void SetTimeout(Int_t ival);
+ /**
+ * Saves canvas to graphics file and exits.
+ *
+ * Exports current canvas view to image file (format determined
+ * by extension: .pdf, .png, .eps, .root, etc.) and closes canvas.
+ *
+ * @param fileName Output file path with extension
+ */
virtual void SaveGraphicsAndQuit(const Char_t *fileName);
+
+ /**
+ * Exports Fourier spectrum data to ASCII file.
+ *
+ * Writes frequency/field values and corresponding spectrum
+ * amplitudes in columnar format for external analysis.
+ *
+ * @param pathFileName Output data file path (typically .dat extension)
+ */
virtual void ExportData(const Char_t *pathFileName);
private:
@@ -155,23 +337,70 @@ class PFourierCanvas : public TObject, public TQObject
std::unique_ptr