Usage ===== SCOPE-XR provides two main interfaces designed for different user workflows. The program supports configurable execution via YAML configuration files. You can find an example of these files in the ``examples`` folder, along with some simulated images to test the package. Supported Image Formats ----------------------- The supported input image formats are: * ``.png`` * ``.tif`` / ``.tiff`` * ``.raw`` (must be accompanied by a corresponding ``.xml`` metadata file) * ``.dcm`` (DICOM) GUI Execution ------------- The recommended way for routine analysis. It features live image previews and interactive parameter tuning. To run the GUI, simply type: .. code-block:: bash scopexr-gui **GUI Features:** * **Easy Mode Selection**: Separate tabs for "Focal Spot (FS)" and "PSF" analysis. * **Automatic Configuration**: The GUI automatically loads all default parameters from ``fs_args.yaml`` or ``psf_args.yaml`` on startup. * **Image Preview**: Load .png, .tif/.tiff, or .dcm images to see a preview directly in the app. * **Full Parameter Control**: All CLI flags are editable via interactive widgets. * **Edit Config Files**: A button allows you to directly open and edit the default .yaml config file for the active tab. * **Live Output**: All console output from the analysis script is printed directly to a text box within the GUI. CLI Execution ------------- Ideal for batch processing and integration into automated research pipelines. To run the program with the default settings (as defined in ``fs_args.yaml`` or ``psf_args.yaml``), use the following commands: * **Focal Spot:** .. code-block:: bash scopexr-fs --f "path/to/img.png" * **PSF:** .. code-block:: bash scopexr-psf --f "path/to/img.png" Use the ``--help`` flag with any command to see all available parameters. Overriding Configuration Parameters ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ You can override any configuration value directly from the command line by adding the corresponding flag. For example: .. code-block:: bash scopexr-fs --f "path/to/img.png" --p 0.2 Available CLI Flags ~~~~~~~~~~~~~~~~~~~ Focal Spot CLI ^^^^^^^^^^^^^^ +-------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------+ | **Flag** | **Description** | +=========================+===============================================================================================================================================+ | ``--config`` (str) | Path to the YAML configuration file. | +-------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------+ | ``--f`` (str) | **Required.** Path to the input image file (``.raw``, ``.png``, ``.tif``/``.tiff``, ``.dcm``). | +-------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------+ | ``--o`` (str) | Output directory to store results. | +-------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------+ | ``--p`` (float) | Pixel size in mm. | +-------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------+ | ``--d`` (float) | Physical diameter of the circular object in mm. | +-------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------+ | ``--no_hough`` | Skip Hough Transform for automatic circle detection. | +-------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------+ | ``--m`` (float) | Image magnification. If not provided, estimated automatically. | +-------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------+ | ``--n`` (int) | Minimum number of pixels required to achieve a reasonable focal spot size. | +-------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------+ | ``--nangles`` (int) | Number of angular projections for profile extraction. | +-------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------+ | ``--hl`` (int) | Half length of the extracted radial profiles. | +-------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------+ | ``--ds`` (int) | Step size used for numerical derivative calculations. | +-------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------+ | ``--axis_shifts`` (int) | Number of steps to shift the sinogram axis. | +-------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------+ | ``--filter`` (str) | Filter used. Options: ``ramp``, ``shepp-logan``, ``cosine``, ``hamming``, ``hann``. Use ``None`` for no filter. | +-------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------+ | ``--avg_number`` (int) | Number of profiles to average (must be odd). Only used if ``--avg`` is true. | +-------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------+ | ``--sym`` | Symmetrize the sinogram before reconstruction. | +-------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------+ | ``--shift`` | Enable automatic sinogram shifting. | +-------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------+ | ``--no_shift`` | Disable automatic sinogram shifting. (*Mutually exclusive with* ``--shift``) | +-------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------+ | ``--avg`` | Average neighboring sinogram profiles to improve FWHM estimation. | +-------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------+ | ``--no_avg`` | Do not average neighboring profiles. (*Mutually exclusive with* ``--avg``) | +-------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------+ | ``--show`` | Display plots during processing (matplotlib windows). | +-------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------+ PSF CLI ^^^^^^^ +--------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | **Flag** | **Description** | +==========================+========================================================================================================================================================================+ | ``--config`` (str) | Path to the YAML configuration file. | +--------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | ``--f`` (str) | **Required.** Path to the input image file (``.raw``, ``.png``, ``.tif``/``.tiff``, ``.dcm``). | +--------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | ``--o`` (str) | Output directory to store results. | +--------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | ``--p`` (float) | Pixel size in mm. | +--------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | ``--d`` (float) | Physical diameter of the circular object in mm. | +--------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | ``--no_hough`` | Skip Hough Transform for automatic circle detection. | +--------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | ``--nangles`` (int) | Number of angular projections for profile extraction. | +--------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | ``--hl`` (int) | Half length of the extracted radial profiles. | +--------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | ``--ds`` (int) | Step size used for numerical derivative calculations. | +--------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | ``--axis_shifts`` (int) | Number of steps to shift the sinogram axis. | +--------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | ``--filter`` (str) | Filter used. Options: ``ramp``, ``shepp-logan``, ``cosine``, ``hamming``, ``hann``. Use ``None`` for no filter. | +--------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | ``--avg_number`` (int) | Number of profiles to average (must be odd). Only used if ``--avg`` is true. | +--------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | ``--sym`` | Symmetrize the sinogram before reconstruction. | +--------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | ``--dtheta`` (float) | Angle of the circular sector for oversampling (in degrees). | +--------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | ``--resample2`` (int) | Radial sampling density for the coarse grid when oversampling is enabled. | +--------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | ``--gaussian_sigma`` | Controls oversampling mode: ``0``/``None`` uses direct binned statistics; ``>0`` applies fine-grid resample + Gaussian blur before coarse binning. | +--------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | ``--shift`` | Enable automatic sinogram shifting. | +--------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | ``--no_shift`` | Disable automatic sinogram shifting. (*Mutually exclusive with* ``--shift``) | +--------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | ``--avg`` | Average neighboring sinogram profiles to improve FWHM estimation. | +--------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | ``--no_avg`` | Do not average neighboring profiles. (*Mutually exclusive with* ``--avg``) | +--------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | ``--oversample`` | Perform oversampling. | +--------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | ``--no_oversample`` | Disable oversampling. (*Mutually exclusive with* ``--oversample``) | +--------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | ``--show`` | Display plots during processing (matplotlib windows). | +--------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+