# Geometry Calibration

Calibration is an essential step to determine the precise geometric parameters of the experiment (detector tilts, sample-to-detector distance, etc.).

##  Prerequisites

Refining these parameters requires 3DXRD data acquired from a "standard" sample with known lattice parameters (typically a Si or CeO₂ single crystal).

Calibration is an essential step to determine accurately the geometric parameters of the experiment (tilt, sample-detector distance, ...).

Fitting those require _3DXRD_ data acquired for a sample with known lattice parameters (usually a `Si` single crystal).

You can produce an initial `.par` or `.PONI` file by using the 
1. [notebooks of the ImageD11 project](https://github.com/FABLE-3DXRD/ImageD11/tree/v2.1.2/ImageD11/nbGui/calibration). or 
2. pyFAI-calib2 [calibration](https://pyfai.readthedocs.io/en/stable/usage/cookbook/calib-gui/index.html#cookbook-calibration-gui).


While these methods have methods for producing powder calibration and single crystal calibration files, you can use them as a starting point if you use only powder calibration, and if you use single crystal calibration you don't have to use this GUI for the single-crystal workflow. If you already have approximate geometry parameters, you can bypass the powder step and start directly with single-crystal calibration.


The Calibration Workflow

To begin, navigate to _Help_ _>_ _Example workflows_ and select the 3DXRD Geometry Calibration example.
1. **Preparation**: Follow the _Segmentation_ and _Detector Correction_ steps exactly as described in the [3DXRD Data Processing guide](./tutorial.md).

![Fit Geometry with filled parameters](_static/tuto/initial_fit_geometry.png)

## Executing Fit Geometry

Double-click the _Fit Geometry node_ to open the refinement interface.
1. **Input Configuration**:
    1. Load your Lattice file (defining the crystal structure).
    2. Load your initial Geometry file or manually type the values into the respective group boxes.
2. **Selecting Parameters to Refine**:
    1. Each parameter (distance, tilts, centers) has a checkbox.
    2. Checked: The parameter will be optimized during the fit.
    3. Unchecked: The parameter remains fixed.

Tip: If you are unsure, start with the default checked parameters.

## The Iterative Fitting Process

Follow the numbered steps in the GUI for a successful calibration:
1. **Fit Geometry**: Click this to run the fit approximation algorithm based on the current peak positions and selected Geometry and Lattice parameters.
2. **Find Grain**: Click this to attempt to index a single grain from the peaks.
- **Success**: The system will identify a grain near the spatial origin (0, 0, 0).
- **Failure**: A pop-up will appear stating "No grain found." If this happens, re-adjust your initial parameters and retry step 1.

### Verifying the Result
The widget displays a _Peaks-Lattice plot_. You can visually verify the quality of the fit:
1. **Correct Fit**: The ring curves (theoretical) align perfectly with the detected peak markers.
1. **Poor Fit**: The rings and peaks are offset or skewed. Continue iterating between _Fit Geometry_ and _Find Grains_ until the alignment is precise.

Once a single grain is found and the rings align with the peaks, your geometry parameters are accurately calibrated and ready for the main data processing workflow.

![Fitted Geometry parameter with given Single Crystal](_static/tuto/aligned_geometry_peaks.png)