scopexr package

Submodules

scopexr.arg_parser_fs module

scopexr.arg_parser_fs.get_merged_config() → dict

Parse command-line arguments and YAML configuration file, merging them with the following priority:

1. Code defaults (lowest priority)

2. YAML config file

3. Command-line arguments (highest priority)

Returns:

dict – Merged configuration dictionary

scopexr.arg_parser_fs.validate_args(args: dict) → None

Validate the merged configuration arguments. :param args: Merged configuration dictionary

Raises:

ValueError – If any argument is invalid

scopexr.arg_parser_psf module

scopexr.arg_parser_psf.get_merged_config() → dict

Parse command-line arguments and YAML configuration file, merging them with the following priority:

1. Code defaults (lowest priority)

2. YAML config file

3. Command-line arguments (highest priority)

Returns:

dict – Merged configuration dictionary

scopexr.arg_parser_psf.validate_args(args: dict) → None

Validate the merged configuration arguments. :param args: Merged configuration dictionary

Raises:

ValueError – If any argument is invalid

scopexr.circle_detection module

scopexr.circle_detection.detect_circle_hough(img: ndarray, dp: float, min_dist: float, param1: int, param2: int, min_radius: int, max_radius: int, output_path: str | None = None, debug: bool = False) → tuple[float, float, float] | None

Detect a single circle in a grayscale image using the Hough Circle Transform.

Parameters:

• img – 2D array representing the input grayscale image.

• dp – Inverse ratio of the accumulator resolution to the image resolution. For example, dp=1 means the accumulator has the same resolution as the image.

• min_dist – Minimum distance between the centers of detected circles (in pixels).

• param1 – Higher threshold for the internal Canny edge detector (lower is half).

• param2 – Accumulator threshold for the circle centers at the detection stage. Smaller values will detect more circles (including false ones).

• min_radius – Minimum circle radius (in pixels) to search for.

• max_radius – Maximum circle radius (in pixels) to search for. If <= 0, no upper limit is applied.

• debug – If True, display the detected circle overlaid on the image in a pop-up window. Defaults to False.

Returns:

• x (float) – x coordinate of the detected circle center.

• y (float) – y coordinate of the detected circle center.

• r (float) – radius of the detected circle.

• None – If no circle is found.

Raises:

FileNotFoundError – If the input img is None.

scopexr.circle_detection.estimate_circle(cropped: ndarray) → tuple[float, float, float]

Estimate circle parameters using Center of Mass and Equivalent Area.

Methods: - Center (cx, cy): Calculated via center_of_mass on the binary mask. - Radius: Calculated from the area (Area = pi * r^2).

scopexr.circle_detection.is_circle_centered(cropped: ndarray, cx: float, cy: float, margin: float = 0.1) → bool

Check if the estimated circle center is within margin of the cropped image center in both the x- and y-directions. Returns True if it is, False otherwise.

Parameters:

• cropped – cropped image containing the circle

• cx – x coordinate of the estimated circle center

• cy – y coordinate of the estimated circle center

• margin – allowable fraction of width/height (default 0.1)

Returns:

bool – True if the circle center is within the margin from the image center

scopexr.fs_main module

scopexr.fs_main.main()

scopexr.fs_runner module

scopexr.fs_runner.run_pipeline_fs()

scopexr.gui module

GUI module for SCOPE-XR.

Provides a PyQt6-based graphical user interface for configuring and running focal spot and PSF analysis on X-ray images. The interface allows users to load images, adjust analysis parameters, and execute SCOPE-XR algorithms with real-time output feedback.

class scopexr.gui.PathSelector(is_directory: bool = False)

Bases: QWidget

Custom widget for selecting file or directory paths.

Combines a text field (QLineEdit) with a “Browse” button to allow users to manually enter or interactively select file/directory paths.

is_directory

If True, opens directory dialog; if False, file dialog

Type:

bool

line_edit

Text field displaying the selected path

Type:

QLineEdit

browse() → None

Open file or directory browser dialog and update the text field.

Opens either a directory selection dialog or a file selection dialog based on the is_directory attribute. Updates the line_edit widget with the selected path.

setText(text: str) → None

Set the path text programmatically.

Parameters:

text – Path string to display in the input field

text() → str

Get the current path text.

Returns:

str – Current text in the path input field

class scopexr.gui.RunThread(cmd_list: list)

Bases: QThread

Background thread for running SCOPE-XR analysis commands.

This thread executes subprocess commands asynchronously to prevent the GUI from freezing during long-running analyses. Emits output signals that can be connected to GUI elements for real-time feedback.

output

int = …, arguments: Sequence = …) -> PYQT_SIGNAL

types is normally a sequence of individual types. Each type is either a type object or a string that is the name of a C++ type. Alternatively each type could itself be a sequence of types each describing a different overloaded signal. name is the optional C++ name of the signal. If it is not specified then the name of the class attribute that is bound to the signal is used. revision is the optional revision of the signal that is exported to QML. If it is not specified then 0 is used. arguments is the optional sequence of the names of the signal’s arguments.

Type:

pyqtSignal(*types, name

Type:

str = …, revision

run() → None

Execute the command in a subprocess and emit output.

Runs the configured command list, captures stdout/stderr, and emits output via the output signal. Handles platform-specific encoding (cp1252 for Windows, utf-8 for others) and provides detailed error messages on failure.

class scopexr.gui.ScopeXRApp

Bases: QMainWindow

Main application window for the SCOPE-XR GUI.

Provides a two-pane interface with:

• Left pane: Image preview and loading controls

• Right pane: Tabbed parameter configuration (Focal Spot and PSF), control buttons, and output console

The GUI allows users to configure analysis parameters either through widgets or by loading YAML configuration files, then executes the analysis in a background thread.

image_path

Path to the currently loaded image file

Type:

str or None

run_thread

Background thread for running analysis

Type:

RunThread or None

fs_config_data

Loaded focal spot configuration

Type:

dict

psf_config_data

Loaded PSF configuration

Type:

dict

append_output(text: str) → None

Append text to the output console.

Parameters:

text – Output text to append to the console

create_advanced_tab(fs_config_data: dict, psf_config_data: dict) → QWidget

Create the Advanced tab for Hough transform parameters.

Creates a scrollable tab containing separate sections for FS and PSF Hough circle detection parameters. These parameters control the circle detection algorithm used to locate the focal spot or pinhole in the image.

Parameters:

• fs_config_data (dict) – Configuration data for focal spot including hough_params

• psf_config_data (dict) – Configuration data for PSF including hough_params

Returns:

QWidget – The advanced tab widget containing all Hough parameter controls

create_fs_tab(config_data: dict) → QWidget

Create the Focal Spot analysis configuration tab.

Parameters:

config_data – Initial configuration values for focal spot parameters

Returns:

QWidget – The constructed focal spot tab widget with all parameter controls

create_psf_tab(config_data: dict) → QWidget

Create the PSF analysis configuration tab.

Parameters:

config_data – Initial configuration values for PSF parameters

Returns:

QWidget – The constructed PSF tab widget with all parameter controls

edit_config() → None

Open the default configuration file in the system’s default editor.

Opens either fs_args.yaml or psf_args.yaml depending on the currently active tab. Shows a warning dialog if the file is not found.

on_run_finished() → None

Handle completion of the analysis thread.

Re-enables the run button and updates its text to indicate the analysis has finished.

open_image_file() → None

Open file dialog to select and load an image.

Allows selection of PNG, TIF, RAW, or DICOM image files. Updates the image display with a preview (except for RAW files) and stores the file path for analysis.

resizeEvent(event: QResizeEvent) → None

Handle window resize events and update image display accordingly.

Parameters:

event – The resize event

run_script() → None

Construct and execute the SCOPE-XR analysis command.

Collects all parameter values from the active tab (FS or PSF), constructs the appropriate command line arguments, and launches the analysis in a background thread. Updates the GUI to show the analysis is running and disables the run button.

set_app_icon(filename: str) → None

Set the application window icon from package resources.

Parameters:

filename – Name of the icon file within the scopexr package

Notes

Fails silently if the icon file is not found.

update_fs_gui() → None

Update all focal spot GUI widgets from a loaded configuration file.

Reads the file path from the FS config selector, loads the YAML file, and updates all focal spot parameter widgets with the loaded values. Shows warning dialogs if the file is not found or cannot be loaded.

update_image_display(pixmap: QPixmap) → None

Update the image display label with a scaled pixmap.

Parameters:

pixmap – Image to display in the preview area

update_psf_gui() → None

Update all PSF GUI widgets from a loaded configuration file.

Reads the file path from the PSF config selector, loads the YAML file, and updates all PSF parameter widgets with the loaded values. Shows warning dialogs if the file is not found or cannot be loaded.

update_psf_oversample_controls() → None

Enable/disable PSF oversampling controls based on checkbox state.

scopexr.gui.create_radio_group(title: str, options: dict, default_key: str = 'default') → tuple

Create a radio button group within a QGroupBox.

Parameters:

• title – Title for the group box

• options – Dictionary mapping option keys to display labels

• default_key – Key of the option to be checked by default, by default ‘default’

Returns:

tuple – (QGroupBox, dict) where the dict maps option keys to QRadioButton objects

scopexr.gui.load_config(filename: str) → dict

Load a YAML configuration file and return its contents as a dictionary.

Parameters:

filename – Path to the YAML configuration file

Returns:

dict – Configuration parameters loaded from the file, or an empty dict if the file cannot be loaded

scopexr.gui.main() → None

Main entry point for the SCOPE-XR GUI application.

Creates and displays the main application window.

scopexr.image_opening module

scopexr.image_opening.load_dicom_as_ndarray(img_path: str) → ndarray

Load a DICOM image using pydicom and convert it to a numpy array.

Parameters:

img_path – Path to the DICOM image file (.dcm)

Returns:

np.ndarray – 2D numpy ndarray representing the image.

scopexr.image_opening.load_image(img_path: str) → ndarray

Load an image and dispatch to the correct loader based on file extension.

Parameters:

img_path – Path to the image file.

Returns:

np.ndarray – 2D numpy ndarray representing the image.

Notes

Supported formats: .raw (with matching .xml), .tif/.tiff, .png, and .dcm.

scopexr.image_opening.load_png_as_ndarray(img_path: str) → ndarray

Load a PNG image using PIL and convert it to a numpy array.

Parameters:

img_path – Path to the PNG image file (.png)

Returns:

np.ndarray – 2D numpy ndarray representing the image.

scopexr.image_opening.load_raw_as_ndarray(img_path: str) → ndarray

Load a RAW image as a numpy ndarray using metadata from the corresponding XML file.

Parameters:

img_path – Path to the raw image file (.raw).

Returns:

np.ndarray – 2D numpy ndarray representing the image.

Raises:

FileNotFoundError – If the XML metadata file is not found.

scopexr.image_opening.load_tiff_as_ndarray(img_path: str) → ndarray

Load a TIFF image using PIL and convert it to a numpy array.

Parameters:

img_path – Path to the TIFF image file (.tif or .tiff)

Returns:

np.ndarray – 2D numpy ndarray representing the image.

scopexr.mtf_calc module

scopexr.mtf_calc.compute_1d_mtf(lsf: ndarray, pixel_size: float) → tuple[ndarray, ndarray, float]

Compute 1D MTF from LSF.

Parameters:

• lsf – 1D array representing the line spread function (LSF).

• pixel_size – Pixel size in mm.

Returns:

• freq (np.ndarray) – Frequencies in cycles/mm.

• mtf_1d (np.ndarray) – 1D MTF array normalized to 1 at zero frequency.

• mtf10 (float) – Frequency at which MTF drops to 10% (cycles/mm).

scopexr.mtf_calc.compute_1d_mtf_from_sino(sinogram: ndarray, pixel_size: float, angle: int) → tuple[ndarray, ndarray, float]

Compute 1D MTF from sinogram

Parameters:

• sinogram – 2D array representing the sinogram.

• pixel_size – Pixel size in mm.

• angle – Angle index along which to extract the profile.

Returns:

• freq (np.ndarray) – Frequencies in cycles/mm.

• mtf_1d (np.ndarray) – 1D MTF array normalized to 1 at zero frequency.

• mtf10 (float) – Frequency at which MTF drops to 10% (cycles/mm).

scopexr.mtf_calc.get_mtf_at_freq(target_freq: float, freq_array: ndarray, mtf_array: ndarray) → float

Finds the MTF value at a specific frequency using linear interpolation.

Parameters:

• target_freq – The frequency on which to evaluate the MTF.

• freq_array – The array of frequency values.

• mtf_array – The array of MTF values.

Returns:

float – The interpolated MTF value at the target frequency.

scopexr.plotters module

scopexr.plotters.plot_1d_mtf(freq: ndarray, mtf: ndarray, pixel_size: float, out_path: str, mtf10_freq: float | None = None, show_plots: bool = False) → None

Plot 1D MTF with Nyquist and MTF10 reference lines.

Parameters:

• freq – Array of frequencies in cycles/mm.

• mtf – MTF values (same length as freq).

• pixel_size – Pixel size in mm (system pixel size!).

• out_path – Path to save the figure.

• mtf10_freq – Frequency at which MTF drops to 10% (cycles/mm).

• show_plots – If True, also display plot on screen.

Returns:

None – This function saves a file and does not return a value.

scopexr.plotters.plot_circle_on_crop(cropped: ndarray, cx: float, cy: float, radius: float, output_path: str, show: bool = False) → None

Plot the cropped ROI with the detected circle overlay.

Parameters:

• cropped – The 2D image array of the crop.

• cx – Center x-coordinate relative to the crop.

• cy – Center y-coordinate relative to the crop.

• radius – Radius of the circle in pixels.

• output_path – Directory to save the image.

• show – If True, display the plot.

Returns:

None – This function saves a file and does not return a value.

scopexr.plotters.plot_profile_with_gaussian(radial: ndarray, intensity_profile: ndarray, popt: tuple[float, float, float, float], out_path: str, show_plots: bool = False, pixel_size: float | None = None, magnification: float | None = None) → None

Plot an intensity profile (from sinogram or projection) with its Gaussian fit.

scopexr.plotters.plot_profiles_and_reconstruction(profiles: ndarray, sinogram: ndarray, reconstruction: ndarray, out_dir: str, show_plots: bool, reconstruction_type: str, suffix: str = '') → None

Plot aligned profiles, sinogram, and reconstruction side-by-side.

Parameters:

• profiles – The aligned profiles image/array.

• sinogram – The sinogram image/array.

• reconstruction – The reconstructed image/array.

• out_dir – Directory to save the plot.

• show_plots – If True, display the plot.

• reconstruction_type – Type string (‘psf’, ‘fs’, or other) to determine the title.

• suffix – Optional suffix for the output filename.

Returns:

None – This function saves a file and does not return a value.

scopexr.plotters.plot_profiles_with_fwhm(radial: ndarray, prof_horizontal_sino: ndarray, prof_vertical_sino: ndarray, horizontal_idx: int, vertical_idx: int, height: float, fh: float, lh: float, rh: float, fv: float, lv: float, rv: float, out_path: str, show_plots: bool = False, pixel_size: float | None = None, magnification: float | None = None) → None

Plot the horizontal and vertical sinogram profiles with FWHM/FW15M lines.

Parameters:

• radial – Radial coordinates array (in pixels).

• prof_horizontal_sino – Intensity array of the horizontal profile.

• prof_vertical_sino – Intensity array of the vertical profile.

• horizontal_idx – Index of the horizontal profile.

• vertical_idx – Index of the vertical profile.

• height – Relative height for the width measurement (e.g., 0.5 for FWHM).

• fh – Width of the horizontal profile (in pixels).

• lh – Left coordinate of the horizontal profile width.

• rh – Right coordinate of the horizontal profile width.

• fv – Width of the vertical profile (in pixels).

• lv – Left coordinate of the vertical profile width.

• rv – Right coordinate of the vertical profile width.

• out_path – Path to save the figure.

• show_plots – If True, display the plot.

• pixel_size – Pixel size in mm. If provided with magnification, x-axis will be in mm.

• magnification – Magnification factor. If provided with pixel_size, x-axis will be in mm.

Returns:

None – This function saves a file and does not return a value.

scopexr.plotters.plot_recon_with_lines(recon: ndarray, angle_horizontal: float, angle_vertical: float, out_path: str, show_plots: bool = False, reconstruction_type: str = 'fs') → None

Plot the reconstruction with lines indicating the profile angles.

Parameters:

• recon – 2D reconstruction image.

• angle_horizontal – Angle in degrees for the horizontal profile.

• angle_vertical – Angle in degrees for the vertical profile.

• out_path – Path to save the figure.

• show_plots – If True, display the plot.

• reconstruction_type – ‘psf’ or ‘fs’ to determine title and labels.

Returns:

None – This function saves a file and does not return a value.

scopexr.plotters.plot_sinogram_with_traced_profiles(sinogram: ndarray, horizontal_idx: int, vertical_idx: int, out_path: str, reconstruction_type: str, show_plots: bool) → None

Plot the sinogram with vertical lines indicating the selected profiles.

Parameters:

• sinogram – The sinogram image/array.

• horizontal_idx – Index of the horizontal profile.

• vertical_idx – Index of the vertical profile.

• out_path – Path to save the figure.

• reconstruction_type – ‘psf’ or ‘fs’ to determine label text.

• show_plots – If True, display the plot.

Returns:

None – This function saves a file and does not return a value.

scopexr.psf_main module

scopexr.psf_main.main()

scopexr.psf_runner module

scopexr.psf_runner.run_pipeline_psf()

scopexr.sinogram_recon module

scopexr.utils module

scopexr.utils.background_percentile(profile: ndarray, low_frac: float = 0.15) → float

Estimate background intensity from the lower percentile of a profile.

Parameters:

• profile – 1D array representing a profile.

• low_frac – Fraction (0-1) to use for percentile calculation. Default is 0.5 (50th percentile).

Returns:

float – Mean intensity of values below the percentile threshold.

scopexr.utils.crop_square_roi(img: ndarray, center: tuple[float, float], radius: float, width_factor: float = 1.5, output_path: str | None = None) → ndarray

Crop a square region of interest (ROI) around the specified center.

Parameters:

• img – Input image array.

• center – (x, y) coordinates of the center.

• radius – Radius of the feature to crop around.

• width_factor – Factor to determine the crop size relative to the radius.

• output_path – If provided, saves the cropped image to this directory.

Returns:

np.ndarray – The cropped image array.

scopexr.utils.eval_minimum_magnification(a: float, n: int, p: float) → float

Evaluate the minimum magnification required to obtain a focal spot image involving a reasonable number n of pixels.

Parameters:

• a – Focal spot size (dimension).

• n – Number of pixels desired.

• p – Pixel size/pitch.

Returns:

float – The calculated minimum magnification.

scopexr.utils.eval_minimum_radius(n: int, p: float, m: float) → float

Evaluate the minimum disk radius required to obtain a focal spot image involving a reasonable number n of pixels.

Parameters:

• n – Number of pixels desired.

• p – Pixel size/pitch.

• m – Magnification factor.

Returns:

float – The calculated minimum radius.

scopexr.utils.interpolate_nans_1d(y: ndarray) → ndarray

Linearly interpolate NaNs in a 1D array.

Parameters:

y – 1D input array possibly containing NaNs.

Returns:

np.ndarray – Array with NaNs filled by linear interpolation.

scopexr.utils.save_16bit_tiff(data: ndarray, path: str) → None

Scales and saves a NumPy array as a 16-bit grayscale TIFF.

Parameters:

• data – Input image data.

• path – Output file path.

Returns:

None – This function saves a file and does not return a value.

scopexr.utils.save_and_plot(name: str, arr: ndarray, out_dir: str, plot_func: Callable | None = None, suffix: str = '', show_plots: bool = False) → str

Save a 2D array as a 16-bit TIFF and optionally plot it using a provided plotting function.

Parameters:

• name – Base name for the file.

• arr – Image array to save.

• out_dir – Output directory.

• plot_func – Optional function to generate a plot.

• suffix – Suffix to append to the filename.

• show_plots – If True, show the plot interactively.

Returns:

str – Path to the saved TIFF file.

scopexr.utils.suggest_os_angle(p: float, n: int, r: float) → float

Suggest the optimal oversampling angle to ensure negligible cross-talk.

Parameters:

• p – Pixel size.

• n – Oversampling factor (or similar parameter depending on strategy).

• r – Radius.

Returns:

float – Suggested oversampling angle in degrees.

scopexr.widths_calculator module

scopexr.widths_calculator.average_neighbors(sinogram: ndarray, angle_idx: int, line_width: int) → ndarray

Compute the vertical profile at a given angle index, averaging across multiple adjacent rows.

Parameters:

• sinogram – 2D sinogram array of shape (rows/pixels, angles).

• angle_idx – The angle (column index) to extract the profile from.

• line_width – Number of adjacent rows to average (must be odd).

Returns:

np.ndarray – A 1D profile averaged across multiple rows.

scopexr.widths_calculator.compute_fs_width(fwhm_px: float, pixel_size: float, fs_magnification: float) → float

Compute the focal spot width in micrometers from the FWHM in pixels.

Parameters:

• fwhm_px – Full width at half maximum in pixels.

• pixel_size – Size of a pixel in micrometers.

• fs_magnification – Magnification factor of the focal spot.

Returns:

float – Focal spot width in micrometers.

scopexr.widths_calculator.compute_lsf_from_projection(reconstruction: ndarray) → tuple[ndarray, ndarray]

Compute LSF by projecting the focal spot reconstruction along each axis.

This method sums all horizontal profiles across the 2D distribution to compute the vertical profile, and sums all vertical profiles to compute the horizontal profile.

Parameters:

reconstruction – 2D array representing the reconstructed focal spot.

Returns:

• horizontal_lsf (np.ndarray) – 1D profile along horizontal axis (sum along vertical direction, axis=0).

• vertical_lsf (np.ndarray) – 1D profile along vertical axis (sum along horizontal direction, axis=1).

scopexr.widths_calculator.erf_step(x: ndarray, a: float, x0: float, sigma: float, b: float) → ndarray

Error function step model for fitting profile edges.

Parameters:

• x – Independent variable (e.g., pixel positions).

• A – Amplitude of the step.

• x0 – Center position of the transition.

• sigma – Width of the transition (standard deviation).

• B – Background offset.

Returns:

np.ndarray – Model values evaluated at x.

scopexr.widths_calculator.find_extreme_profiles_erf(profiles: ndarray) → tuple[int, int, ndarray]

Fit each angular profile to an error function step and find extreme slopes.

Parameters:

profiles – 2D array of shape [n_rays, n_angles] containing line profiles.

Returns:

• wide_idx (int) – Index of the profile with the steepest (widest) slope.

• narrow_idx (int) – Index of the profile with the shallowest (narrowest) slope.

• sigmas (np.ndarray) – 1D array of computed sigmas for each profile.

scopexr.widths_calculator.find_extreme_profiles_gaussian(sinogram: ndarray) → tuple[int, int, ndarray, list[ndarray]]

Fit each sinogram profile (column) to a Gaussian curve and extract the extreme profiles.

Parameters:

sinogram – 2D array of shape (n_rays, n_angles) containing line profiles.

Returns:

• wide_idx (int) – Index of the profile with the largest sigma (widest).

• narrow_idx (int) – Index of the profile with the smallest sigma (narrowest).

• sigmas (np.ndarray) – 1D array of sigma values for each profile.

• popts (list[np.ndarray]) – List of optimal fit parameters [A, mu, sigma, B] for each profile; entries are np.array([nan, nan, nan, nan]) on fit failure.

scopexr.widths_calculator.fw_at_percent_max(profile: ndarray, percent: float) → tuple[float, float, float]

Compute the Full Width at a specified percentage of the maximum (FWxM) of a 1D profile using linear interpolation.

Parameters:

• profile – 1D array representing a single profile (e.g. from a sinogram).

• percent – Percentage of the maximum to compute the width at (e.g., 0.15 for 15%).

Returns:

• width (float) – Width in pixels between crossings at the specified percentage of maximum (interpolated).

• left_idx (float) – Fractional index of left crossing.

• right_idx (float) – Fractional index of right crossing.

scopexr.widths_calculator.fwhm_from_sigma(sigma: float) → float

Compute the FWHM from the standard deviation of an error function step.

Parameters:

sigma – Standard deviation of the error function step.

Returns:

float – FWHM value.

scopexr.widths_calculator.gaussian(x: ndarray, a: float, mu: float, sigma: float, b: float) → ndarray

Gaussian model for fitting sinusoidal profiles.

Parameters:

• x – Independent variable (e.g., pixel positions).

• A – Amplitude of the Gaussian.

• mu – Mean (center) of the Gaussian.

• sigma – Standard deviation of the Gaussian.

• B – Baseline offset.

Returns:

np.ndarray – Gaussian curve evaluated at x.

Module contents