Command-Line Interface¶

Entry points and command-line utilities for XPCS Viewer.

Entry Points¶

The package provides separate entry points for CLI and GUI usage.

GUI Entry Point¶

Launch the graphical interface with xpcsviewer-gui.

The main_gui() function is the primary GUI entry point that provides interactive XPCS data analysis.

Usage:

# Launch GUI in current directory
xpcsviewer-gui

# Launch with data path
xpcsviewer-gui /path/to/hdf/data

# With debug logging
xpcsviewer-gui --log-level DEBUG

CLI Entry Point¶

Access batch processing commands with xpcsviewer.

The main() function is the CLI entry point for batch processing operations.

Usage:

# Show available commands
xpcsviewer --help

# Run twotime batch processing
xpcsviewer twotime --input /data --output /results --q 0.05

Available Commands¶

Twotime Batch Processing¶

Generate twotime correlation images from HDF5 files.

Batch processing module for twotime correlation data.

xpcsviewer.cli.twotime_batch.parse_q_phi_pair(q_phi_str)[source]¶

Parse q-phi pair string into q and phi values.

Parameters:: q_phi_str (str) – String in format “q,phi” (e.g., “0.05,45”)
Returns:: Tuple of (q_value, phi_value)
Raises:: ValueError – If string format is invalid
Return type:: tuple[float, float]

xpcsviewer.cli.twotime_batch.extract_q_phi_from_label(label)[source]¶

Extract q and phi values from qbin label string.

Parameters:: label (str) – Qbin label string (e.g., “qbin=5, q=0.0532 Å⁻¹, φ=45.2 deg”)
Returns:: Tuple of (q_value, phi_value) or (None, None) if not found
Return type:: tuple[float | None, float | None]

xpcsviewer.cli.twotime_batch.find_qbins_for_q(xfile, target_q)[source]¶

Find all qbins with the closest q-value(s) across all phi angles.

Parameters:

xfile (XpcsFile) – XpcsFile instance
target_q (float) – Target q-value to match

Returns:

List of tuples (qbin_index, label, q_value, phi_value) for closest matching qbins

Return type:

list[tuple[int, str, float, float]]

xpcsviewer.cli.twotime_batch.find_qbins_for_phi(xfile, target_phi)[source]¶

Find all qbins with the closest phi-value(s) across all q values.

Parameters:

xfile (XpcsFile) – XpcsFile instance
target_phi (float) – Target phi-value to match

Returns:

List of tuples (qbin_index, label, q_value, phi_value) for closest matching qbins

Return type:

list[tuple[int, str, float, float]]

xpcsviewer.cli.twotime_batch.find_qbin_for_qphi(xfile, target_q, target_phi)[source]¶

Find single qbin closest to specific q-phi pair.

Parameters:

xfile (XpcsFile) – XpcsFile instance
target_q (float) – Target q-value to match
target_phi (float) – Target phi-value to match

Returns:

Tuple (qbin_index, label, q_value, phi_value) for closest matching qbin or None

Return type:

tuple[int, str, float, float] | None

xpcsviewer.cli.twotime_batch.create_twotime_plot_matplotlib(c2_matrix, delta_t, title, dpi=300)[source]¶

Create twotime correlation plot using matplotlib.

Parameters:

c2_matrix (ndarray) – 2D correlation matrix
delta_t (float) – Time step for axes scaling
title (str) – Plot title
dpi (int) – Image resolution

Returns:

Matplotlib Figure object

Return type:

Figure

xpcsviewer.cli.twotime_batch.generate_output_filename(input_path, q_value, phi_value, output_format='png')[source]¶

Generate standardized output filename.

Parameters:

input_path (str) – Input HDF file path
q_value (float) – Q-value
phi_value (float) – Phi-value
output_format (str) – Image format

Returns:

Generated filename

Return type:

str

xpcsviewer.cli.twotime_batch.process_single_file(file_path, args)[source]¶

Process a single HDF file and generate twotime images.

Parameters:

file_path (str) – Path to HDF file
args – Command line arguments

Returns:

Number of images generated

Return type:

int

xpcsviewer.cli.twotime_batch.find_hdf_files(directory)[source]¶

Find all HDF files in directory recursively.

Parameters:: directory (str) – Directory to search
Returns:: List of HDF file paths
Return type:: list[str]

xpcsviewer.cli.twotime_batch.process_directory(directory, args)[source]¶

Process all HDF files in directory.

Parameters:

directory (str) – Directory containing HDF files
args – Command line arguments

Returns:

Total number of images generated

Return type:

int

xpcsviewer.cli.twotime_batch.run_twotime_batch(args)[source]¶

Main entry point for twotime batch processing.

Parameters:: args – Parsed command line arguments
Returns:: Exit code (0 for success, 1 for failure)
Return type:: int

Command syntax:

xpcsviewer twotime --input INPUT --output OUTPUT (--q Q | --phi PHI | --q-phi Q,PHI)
                  [--dpi DPI] [--format {png,jpg,pdf,svg}]

Options:

--input, -i: HDF file path or directory containing HDF files
--output, -o: Output directory for generated images
--q: Q-value to process (generates all phi angles)
--phi: Phi-value to process (generates all q values)
--q-phi: Specific q-phi pair as ‘q,phi’ (single image)
--dpi: Image resolution in DPI (default: 300)
--format: Image format: png, jpg, pdf, svg (default: png)

Examples:

# Process all phi angles at a specific q-value
xpcsviewer twotime --input /path/to/data --output /results --q 0.05

# Process all q values at a specific phi angle
xpcsviewer twotime --input /path/to/data --output /results --phi 45

# Generate high-resolution PDF plots
xpcsviewer twotime -i /data -o /results --q 0.05 --dpi 300 --format pdf

Utility Functions¶

safe_shutdown¶

Gracefully shuts down the application, cleaning up resources and thread pools. Called automatically on exit or when handling termination signals.

signal_handler¶

Handles termination signals (SIGTERM, SIGINT) for graceful shutdown. Registered automatically when the CLI or GUI starts.