# Preflight check

**Purpose.** Verify that all essential acquisition metadata were parsed from the raw files and let the user **complete or correct** missing values **before** running peak finding / centering / indexing. All fields are persisted back into the dataset `.ini` under `[AcquisitionDetails]`.

## How it works

- Reads from: `<dataset>.ini` → `[AcquisitionDetails]`
- Writes to: the same section, **immediately** on edit (per-field `textChanged` handlers)
- Also inspects `<dataset>.h5` to detect if a pixel **mask** exists (`/mask`)

## Fields shown

| Label (UI)                      | INI key                       | Unit shown (UI) | Notes |
|---|---|---|---|
| Acceleration Voltage           | `acceleration_voltage`        | **kV**          | UI displays kV, but stores **volts** in INI (auto-converted). |
| Camera Length                  | `camera_length`               | **m**           | Read-only; you can apply a correction factor (see below). |
| Camera Length Correction Factor| `camera_length_correction`     | –               | Editable multiplier, default `1`. Saved to INI immediately. |
| Resolution (width × height)    | `resolution_width/height`     | px              | Read-only. |
| Bin Factor (width × height)    | `binning_width/height`        | –               | Read-only. |
| **Binned Resolution** (computed)| (no INI key; display only)   | px              | Auto-updates from resolution ÷ bin factor. |
| Exposure Time                  | `exposure_time`               | s               | Read-only. |
| ADU                            | `adu_per_photon`              | –               | Detector gain factor used in CrystFEL geometry (`adu_per_photon`). |
| Pixels per Meter               | `pixels_per_meter`            | m⁻¹             | If empty, **Calculate** button is enabled (see below). |

**Editable vs. read-only.**  
- Fields with existing values are **read-only** to prevent accidental edits.  
- Empty fields become **editable** so the user can complete missing metadata.  
- `camera_length_correction` is **always editable**.  
- Click **Edit Metadata** to unlock all fields for manual correction (useful when the imported value is wrong). A confirmation dialog warns if downstream processing results already exist.

## Pixels-per-meter calculator

Click **Calculate** to open the *PixelCalc* dialog:
- **Detector presets:**  
  `Dectris ELA`, `Dectris SINGLA`, `Gatan OneView`, `Thermo Fisher Ceta-D`, `Thermo Fisher Ceta-S`, `Timepix3/Medipix3`, `Other`.  
  Presets fill the **physical pixel size** (µm) and lock the field; `Other` lets you type a custom value.
- **Bin Factor:** prefilled from `binning_width` (you can edit).
- **Formula:**  
  \[
  \text{pixels\_per\_meter} \;=\; \frac{1}{\text{pixel\_size (m)} \times \text{bin\_factor}}
  \]
- The dialog **live-updates** the main window’s `pixels_per_meter` field and saves it to the INI.

If `pixels_per_meter` already exists, the Calculate button is disabled (to avoid accidental override). Clear the field to re-enable.

## Pixel mask controls

- **Mask from Image…** → choose a bitmap (`.bmp/.png/.jpg`), COSEDA creates a mask via `pixmask.generate_mask(...)` and saves it to `<dataset>.h5:/mask`.  
- **Remove Mask** → deletes `/mask` from the HDF5.  
- **Generate Full Mask** → writes a **full-valid** mask to `/mask`.

**Auto-UI:** If `/mask` exists, *Remove Mask* is shown and *Full Mask* is hidden; otherwise the reverse.

> **Note:** A pixel mask is **required** before running Peak Finding. If no mask is present, the Peakfinding window will block the run and prompt you to generate one first. Use *Generate Full Mask* if you have no beamstop or bad pixels to exclude.

## Additional controls

- **Apply to Workspace** → copy the current `[AcquisitionDetails]` metadata (and mask, if present) to all INI files loaded in the workspace. Useful when multiple datasets share the same acquisition conditions.
- **Edit Metadata** → unlock read-only fields for manual correction. A warning is shown if downstream processing results already exist for the dataset.

**Geometry interaction:** Mask validity is still defined in raw detector pixels. If detector geometry remapping is enabled later, masking is applied to raw-frame intensities first; panel geometry then controls where remaining pixels are placed in corrected display/analysis coordinates.

## Completion check

The **Preflight Check** is considered “complete” when all of these have values:

- `acceleration_voltage` (kV shown; stored in V)  
- `camera_length` (m)  
- `camera_length_correction`  
- `resolution_width`, `resolution_height` (px)  
- `binning_width`, `binning_height`  
- `pixels_per_meter` (m⁻¹)

Use **Calculate** to fill `pixels_per_meter` if missing. After completion, close the dialog and proceed with **Peak Finding**.

## Using the GUI

Open **Preflight Check** from the toolbar or menu.

1. Review the metadata fields. Empty fields are editable; fill in any missing values.
2. If `pixels_per_meter` is empty, click **Calculate**, select your detector preset (or enter a custom pixel size), and confirm. The field is updated live and saved to the INI.
3. If no pixel mask exists, click **Generate Full Mask** (or **Mask from Image…** to load a beamstop mask from a bitmap).
4. Optionally click **Apply to Workspace** to copy the current `[AcquisitionDetails]` metadata and mask to all datasets loaded in the workspace.
5. Close the dialog and proceed with **Peak Finding**.

> If you need to correct a value that was imported incorrectly, click **Edit Metadata** to unlock all read-only fields. A warning dialog appears if downstream results already exist.

## Tips

- **Units:** The UI label for *Camera Length* is meters; ensure your upstream importers wrote meters (not mm). If your microscope reports mm (1700 m camera length might be a bit much ;-), convert or store a correction via `camera_length_correction`.  
- **Voltage unit conversion:** The UI shows **kV**, but the INI is stored in **volts** (the dialog converts kV→V on save).  
- **Binned resolution:** This is display-only; it’s computed as `resolution ÷ bin`. If the import didn’t set binning, fix that first.  
- **INI writes are immediate:** Every edit persists to disk; no extra “Save” button.  
- **Mask presence:** The Remove/Full buttons toggle after file changes; if you manipulate the HDF5 externally, reopen the dialog to refresh.