```{image} ../../src/orangecontrib/ewoks3dxrd/icons/filters-1.svg
:alt: Lattice Filter Icon
:class: widget-title-icon
```
# Lattice Filter Widget
The **Lattice Filter** widget is used to isolate diffraction peaks belonging to a specific crystal phase. 
By comparing the reciprocal distance $ds$ of experimental peaks to the theoretical $ds$ values of a given lattice, 
it filters out noise and peaks from other phases.

## Functionality

This widget is used for:
1. **Define a Phase**: Input lattice parameters and space group symmetry.
2. **Apply Tolerance Filtering**: Filter peaks that fall within a specific distance ($\Delta ds$) from theoretical diffraction rings.
3. **Visual Verification**: Compare "before and after" datasets overlaid with theoretical ring positions.



## User Interface
![Image showing the initial state of the lattice filtering widget](../_static/tuto/initial_lattice_filtering.png)

## Control Panel

### Lattice Settings
These parameters define the "mask" used for filtering.
* **Lattice Name**: The identifier for the phase (e.g., "Fe").
* **Lattice Parameters**: Six values defining the unit cell:
    * $a, b, c$ (in Å)
    * $\alpha, \beta, \gamma$ (in degrees).
* **Space Group**: The symmetry group number used to calculate allowed reflections.
* **Reciprocal Distance Tolerance ($ds$ Tol)**: The maximum allowed deviation from a theoretical ring for a peak to be kept.
* **Max Reciprocal Distance ($ds$ Max)**: (Optional) A hard cutoff for the maximum reciprocal distance to consider.

### Execution Control

```{include} ./execution_filtering.md
```

## Main View (Tabs)

### 1. Filter Peaks Tab
To show the filtering efficiency.
* **Unfiltered Data**: Shown as a background scatter plot ($ds$ vs $\eta$).
* **Filtered Data**: Peaks that passed the lattice criteria are highlighted.
* **Lattice Rings**: Theoretical vertical lines are drawn at calculated $ds$ positions. 
    If your peaks don't align with these lines, check your lattice parameters or the previous Geometry Transformation step.

### 2. Custom Peak Analysis Tab
Provides a adjustable plotting mechanism to verify the quality of the filtered peaks across other dimensions (e.g., Intensity vs $\omega$, $G$-vector components, etc).


## Example Usage
1. Connect a widget that outputs a `geometry_transformation_url` or browse from your folder and select the geometry transformation data group.
2. Select your lattice `.par` or `.cif` file in the **LatticeBox**.
3. Set $ds$ Tol, for example say 0.01.
4. Click **Execute**. The plot will show $ds$ vs $\eta$ plot.
5. Repeat the step 3 and 4 until you visually find the good $ds$ Tol value that aligns the input peaks $ds$ value aligns with provided lattice unit cell parameters. 
![Image showing the lattice filtering widget after task completion](../_static/tuto/lattice_filtering.png)