Metadata-Version: 2.4
Name: epattern
Version: 1.0.0
Summary: Electron diffraction pattern simulation, spot detection, and vector matching toolkit.
License-Expression: Apache-2.0
License-File: LICENSE
Author: Liu François
Author-email: liu.francois.kanayama@gmail.com
Maintainer: Arnaud Demortière
Maintainer-email: arnaud.demortiere@u-picardie.fr
Requires-Python: >=3.11,<3.15
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Provides-Extra: cuda11
Provides-Extra: cuda12
Requires-Dist: abtem (>=1.0.9,<2.0.0)
Requires-Dist: ase (>=3.22)
Requires-Dist: cupy-cuda11x (>=13.6.0,<14.0.0) ; extra == "cuda11"
Requires-Dist: cupy-cuda12x (>=13.6.0,<14.0.0) ; extra == "cuda12"
Requires-Dist: h5py (>=3.10,<4.0.0)
Requires-Dist: joblib (>=1.4,<2.0.0)
Requires-Dist: matplotlib (>=3.8,<4.0.0)
Requires-Dist: numpy (<2.0)
Requires-Dist: opencv-python (<5.0.0)
Requires-Dist: pandas (>=2.2,<3.0.0)
Requires-Dist: pillow (>=10.0.0,<12.0.0)
Requires-Dist: scikit-image (>=0.22,<1.0.0)
Requires-Dist: scipy (>=1.12,<2.0.0)
Requires-Dist: torch (>=2.4.0)
Requires-Dist: tqdm (>=4.66,<5.0.0)
Description-Content-Type: text/markdown

# ePattern

ePattern is a Python toolkit for electron diffraction pattern simulation, spot detection, and crystal orientation indexing via vector matching.

## Features

### Simulation
- Bloch-wave diffraction spot simulation using abTEM
- HDF5 export with orientation index
- Configurable tilt ranges and parallel execution

### Spot Detection
- Preprocessing pipeline with multiple noise reduction methods (Gaussian, DoG, Top-Hat, Rolling Ball)
- Auto-prominence or manual prominence peak detection
- Sub-pixel centroid refinement
- Optional coordinate alignment
- HDF5 export of detected spots

### Vector Matching
- **Geometric baseline**: Gaussian-weighted spot-to-spot matching with intensity correlation
- **Deep Sets encoder**: Contrastive learning (Triplet Loss) for fast latent-space matching
- GPU acceleration via PyTorch (encoder) and CuPy (preprocessing)
- Multi-material phase identification and orientation determination

### GUI
- Integrated Tkinter interface for all features
- Visual verification of detected spots

## Requirements

- Python 3.11 or higher
- NVIDIA GPU (optional, for CUDA acceleration)

## Installation

### CPU only

```bash
pip install epattern
```

### GPU (CUDA 12)

```bash
pip install torch --index-url https://download.pytorch.org/whl/cu124
pip install "epattern[cuda12]"
```

### GPU (CUDA 11)

```bash
pip install torch --index-url https://download.pytorch.org/whl/cu118
pip install "epattern[cuda11]"
```

> **Note**: Check your CUDA version with `nvidia-smi` before choosing.

## Quick Start

### Launch the GUI

```bash
epattern
```

### Programmatic Usage

#### Simulation

```python
from epattern import simulate_diffraction

simulate_diffraction(
    cif_file="structure.cif",
    output_path="simulation.h5",
    detector_size=512,
    camera_length=200,
    pixel_size=14,
    energy=200000,
    thickness=500,
    g_max=1.5,
    sg_max=0.1,
    intensity_threshold=1.5,
    tilt_x_min=-2,
    tilt_x_max=2,
    tilt_x_step=1,
    tilt_y_min=-2,
    tilt_y_max=2,
    tilt_y_step=1,
    tilt_z_min=-2,
    tilt_z_max=2,
    tilt_z_step=1,
    batch_size=10,
    parallel_workers=2,
)
```

#### Spot Detection

```python
from epattern import detect_spots

peaks, transforms, settings = detect_spots(
    data_path="path/to/images",
    scan_cols=100,
    output_path="output/detection.h5",
    binning=True,
    align=True,
    auto_prominence=True,
    prominence_min=2.0,
    noise_factor=1.8,
    background_percentile=20.0,
    min_distance=8,
    threshold=3.0,
    max_items=150,
    noise_reduction_methods=[
        {"name": "Gaussian", "params": {"sigma": 1.0}},
    ],
)
```

#### Vector Matching

```python
from epattern import create_encoder, run_matching

# Load a trained encoder
model = create_encoder(
    latent_dim=64,
    weights_path="weights/encoder.pt",
    device="cuda",
)

# Match experimental patterns against reference databases
results = run_matching(
    query_h5="detection.h5",
    ref_h5_paths=["LMNO.h5", "LFP.h5"],
    material_names=["LMNO", "LFP"],
    method="encoder",
    model=model,
    top_k=5,
    device="cuda",
)

# Results is a DataFrame with predicted materials and orientations
print(results[["scan_x", "scan_y", "pred_material_name", "confidence"]])
```

## About

This project was developed within the **Image & Data Science** group of the [LRCS laboratory](https://www.lrcs.u-picardie.fr/) / [RS2E network](https://www.energie-rs2e.com/en), led by Arnaud Demortière (Director of Research at CNRS). The group develops Deep Learning and AI-based algorithms to analyze diffraction patterns and multispectral imagery for battery materials research.


## Authors and Contributors

Author:
- Liu François

Contributors:
- Fayçal Adrar
- Junhao Cao
- Nicolas Folastre
- Arnaud Demortière

## License

This project is distributed under the Apache License 2.0.
See the [LICENSE](LICENSE) file for details.

