Center finding

COSEDA estimates the per-frame beam center without indexing using Friedel symmetry and temporal trends. This chapter focuses on the Beamstop pipeline; see Center refinement for the follow-up smoothing stage.

This stage requires peak finding to have run first (nPeaks, peakXPosRaw, peakYPosRaw must exist in the HDF5).

Inputs

  • COSEDA working file (<dataset>.h5) with:

    • entry/data/images (frames)

    • entry/data/peakXPosRaw, peakYPosRaw, nPeaks (from peak finding)

    • optional entry/data/index (mapping raw → kept frames, written by Strip HDF5)

  • Dataset .ini with center-finding parameters (see below)

How it works

  1. Batching. Split usable frames into ≥4 contiguous batches (size configurable).

  2. Per batch, iterate:

    • Select frames with at least min_peaks; keep peaks within resolution_limit (px) from the current center.

    • Detect Friedel pairs: peak pairs whose vectors about the center almost cancel, [ \left|(\mathbf{p}_i-\mathbf{c}) + (\mathbf{p}_j-\mathbf{c})\right| < \tau. ]

    • Collect deviation vectors (\boldsymbol{\delta} = (\delta_x,\delta_y)) from accepted pairs.

    • Robustly cluster deviations (DBSCAN) to reject outliers; fit a single-component Gaussian to the main cluster.

    • Update the batch center by half the fitted mean. Stop when the mean step is small or no stable cluster forms.

  3. Drift model. Anchor each batch center to the batch’s mean original frame index. Fit a linear drift for X and Y vs. frame index. If the fit passes a quality threshold (or forced), interpolate per-frame centers; otherwise, use piecewise constants per batch. You can also skip the linear fit entirely (centerfinding_skip_linear_fit) to always keep per-batch means.

  4. Write out. Store per-frame center_x, center_y in HDF5. Export diagnostics (NPZ) for the GUI.

Parallelism. Batches run independently via Dask; if Dask fails, COSEDA automatically falls back to sequential processing.

Parameters (INI [Parameters])

Beamstop method

Key

Description

centerfinding_tolerance (px)

Friedel pairing threshold τ

centerfinding_min_peaks

Discard frames with fewer peaks than this

centerfinding_resolution_limit (px)

Radial cutoff; only peaks within this radius are considered

centerfinding_min_samples_fraction (0–1)

Inlier fraction for DBSCAN clustering

centerfinding_dbscan_eps (px)

DBSCAN neighborhood radius for clustering Friedel-pair deviations. Falls back to 5.0 if absent

centerfinding_x0, centerfinding_y0 (px)

Optional initial center guess; defaults to frame centre if absent

centerfinding_force_linear_fit

Accept linear drift regardless of R² (ignored when skip is true)

centerfinding_skip_linear_fit

Bypass linear drift fitting entirely; use per-batch means (takes precedence over force)

centerfinding_max_pairs_per_frame

Cap on Friedel pairs collected per frame (default 10000)

batch_size

Frames per batch; auto-raised to ensure ≥4 batches

Required keys check: the runner hard-fails if any of centerfinding_tolerance, centerfinding_min_peaks, centerfinding_min_samples_fraction, centerfinding_resolution_limit is missing.

centerfinding_dbscan_eps only affects the clustering of Friedel-pair deviations. It does not change the Friedel-pair search radius; that is controlled by centerfinding_tolerance.

Using the GUI

Open the Find Centers window from the toolbar or menu.

  1. Select the method (Beamstop or Direct) from the drop-down.

  2. Set the required parameters. Hover over any field for a tooltip explanation.

  3. Optionally enter initial center guesses (Center guess x/y). If left empty, the frame centre is used as the starting point. You can also click directly on the main viewer to pick coordinates.

  4. Set the Batch Size (default 3000 frames per batch).

  5. Click Save Current (or Save All) under Save Settings to persist settings into the .ini.

  6. Click Find Current (one dataset) or Find All (all workspace datasets) under Find Centers to run.

  7. After completion, review the preview panel: batch deviation clouds, mean batch centers, and the fitted drift lines are shown. Use the run selector dropdown to switch between past runs.

A Stop button is available during processing to cancel after the currently submitted Dask batches complete.

After this stage completes, proceed to the Refine Centers window (documented in the next chapter).

CLI

from coseda.centerfinding.findcenters_beamstop import quartering_batch

ini = "/path/to/dataset.ini"

# Beamstop stage (batched; uses Dask if configured)
quartering_batch(input_path=ini, usedask=True, batch_size=1000)

# Refinement stage: see docs/howto/workflow/6_centerrefinement.md

Outputs

  • HDF5:

    • entry/data/center_x, center_y (px, per frame)

    • entry/data/det_shift_x_mm, det_shift_y_mm (mm, per frame)

  • Diagnostics (per run; used by the GUI):

    • findcenters_*/*.npz (deviation clouds, batch centers, drift fit)

Refinement outputs (LOWESS NPZ, detector shifts) are described in docs/howto/workflow/6_centerrefinement.md.