# 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](6_centerrefinement.md) 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

```python
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.*