Semapp 1.0.21
Package for SEM visualization
Requires Python: >=3.9
Keywords: SEM, GUI

# SEMapp - SEM Data Visualization Application

A comprehensive PyQt5-based desktop application for visualizing and analyzing Scanning Electron Microscope (SEM) data. SEMapp supports multiple KLARF file formats (Standard, COMPLUS4T, and KRONOS), providing an intuitive interface for defect mapping, image analysis, and batch processing.

## Features

### Core Functionality
- **Multi-Format KLARF Support**: Parse and extract defect data from `.001` (KLARF) files
  - Standard mode: Traditional KLARF format
  - COMPLUS4T mode: Multi-wafer KLARF files with automatic wafer detection
  - KRONOS mode: Special format with OCR-based number detection
- **Interactive Wafer Mapping**: Visual representation of defect positions on wafer surface
- **Image Visualization**: Display TIFF images corresponding to defect locations
- **Dynamic Defect Filtering**: Real-time defect filtering based on size threshold
- **Overview Window**: Full-screen mapping with image thumbnails

### Data Processing
- **Automatic File Organization**: Organize TIFF files into wafer-specific subfolders
- **Coordinate Extraction**: Extract and convert defect coordinates from KLARF format
- **TIFF Splitting**: Split multi-page TIFF files into individual images
- **File Renaming**: Automatic renaming based on coordinates and settings
- **CSV Export**: Save defect mapping data for external analysis
- **Batch Processing**: Process multiple wafers in a single session

### Image Processing
- **Threshold Processing**: Detect and analyze particles in SEM images
- **Particle Detection**: Configurable threshold and minimum size parameters
- **Mapping Generation**: Create interpolated maps of particle density and statistics
- **OCR Detection**: Automatic number detection in KRONOS mode using Tesseract

### User Interface
- **Wafer Selection**: Grid-based wafer slot selection (1-26)
- **Image Type Selection**: Choose from different image scales and types
- **Defect Size Slider**: Dynamic threshold control for defect visualization
- **Interactive Plot**: Click on defect positions to view corresponding images
- **Settings Configuration**: Customize image types and processing parameters
- **Toast Notifications**: Non-intrusive feedback for operations
- **Progress Dialogs**: Visual feedback during long operations

## Installation

### Prerequisites
- Python 3.9 or higher
- pip package manager
- Tesseract OCR (optional, for KRONOS mode number detection)
  - Windows: Download from [UB-Mannheim Tesseract](https://github.com/UB-Mannheim/tesseract/wiki)
  - Linux: `sudo apt-get install tesseract-ocr`
  - macOS: `brew install tesseract`

### Install from PyPI
```bash
pip install semapp
```

### Install from Source
```bash
git clone https://github.com/thi-mey/SEMapp.git
cd SEM_VF
pip install -e .
```

### Dependencies
All dependencies are automatically installed:
- PyQt5 >= 5.15.11
- matplotlib >= 3.10.3
- pandas >= 2.2.3
- Pillow >= 11.2.1
- numpy >= 2.2.5
- pytesseract (optional, for OCR features)

## Quick Start

### Launching the Application
```bash
# From command line after installation
semapp

# Or run directly from source
python -m semapp.main
```

### Basic Workflow

1. **Select a Directory**
   - Click "Select Folder" to choose your data directory
   - Application automatically detects standard, COMPLUS4T, or KRONOS mode

2. **Choose a Wafer**
   - Select a wafer slot from the grid (1-26)
   - Available wafers are highlighted in green

3. **Configure Settings** (Optional)
   - Click "Settings" to configure image types and scales
   - Define scale and image type combinations

4. **Open TIFF Data**
   - Click "Open TIFF" to load defect data and images
   - Wafer mapping is displayed automatically

5. **Analyze Defects**
   - Click on defect points in the map to view corresponding images
   - Use the defect size slider to filter by threshold
   - Adjust threshold and min size sliders for particle detection

6. **View Overview**
   - Click "Overview" to see full-screen mapping with image thumbnails
   - Save the overview as PNG, PDF, or SVG

## File Structure

### Standard Mode
```
project_directory/
├── 1/                          # Wafer slot 1
│   ├── data.tif               # TIFF image file
│   ├── recipe_file.001        # KLARF defect file
│   └── mapping.csv            # Generated coordinate mapping
├── 2/                          # Wafer slot 2
│   ├── data.tif
│   ├── recipe_file.001
│   └── mapping.csv
└── ...
```

### COMPLUS4T Mode
```
project_directory/
├── data.tiff                   # Single TIFF file with all defects
├── recipe_file.001             # KLARF file containing multiple wafer IDs
├── 16/                         # Subfolder created for wafer ID 16
│   ├── data_page_331.tiff      # Split TIFF pages
│   ├── -9.1_1.1.tif            # Renamed files
│   └── mapping.csv             # Wafer-specific mapping
├── 21/                         # Subfolder created for wafer ID 21
│   └── mapping.csv
└── ...
```

### KRONOS Mode
```
project_directory/
├── 11/                         # Wafer ID 11
│   ├── data.tiff               # Multi-page TIFF
│   ├── recipe_file.001        # KLARF file
│   ├── detection_results.csv   # OCR detection results
│   ├── mapping.csv             # Filtered defect mapping
│   └── data_page_10.tiff       # Split pages
└── ...
```

## KLARF File Format

SEMapp parses KLARF (`.001`) files to extract:
- **Wafer IDs**: 
  - `WaferID "@16";` (COMPLUS4T mode)
  - `WaferID "Read Failed.11";` (KRONOS mode)
- **Sample Size**: Total number of defects
- **Die Pitch**: X and Y pitch values
- **Die Origin**: Origin coordinates
- **Sample Center Location**: Center coordinates
- **Defect List**: Individual defect positions and sizes

## Processing Operations

### Split and Rename
- **Split TIFF**: Split multi-page TIFF files into individual pages
- **Rename Files**: Rename files based on coordinates and settings
- **Batch Processing**: Process all wafers at once

### Threshold Processing
- **Particle Detection**: Detect particles using configurable threshold
- **Statistics**: Calculate density, area, and particle counts
- **CSV Export**: Save results for analysis

### Mapping
- **Interpolated Maps**: Generate interpolated maps of particle statistics
- **Multiple Metrics**: Density, average area, total area percentage
- **Visualization**: Save maps as PNG files

### Clean Operations
- **Remove Non-Conforming Files**: Clean up files that don't match naming conventions
- **Organize Structure**: Create proper directory structure

## Configuration

### Settings File
The application uses a JSON settings file to define image types and scales:
```json
[
  {
    "Scale": "5x5",
    "Image Type": "SE"
  },
  {
    "Scale": "10x10",
    "Image Type": "BSE"
  }
]
```

### Detection Configuration (KRONOS)
- **ROI**: Region of Interest for number detection (default: X: 1100, Y: 0, W: 250, H: 35)
- **CPU Cores**: Configurable number of CPU cores for multiprocessing
- **Resize Factor**: Optional image resizing for faster processing

## Keyboard Shortcuts

- **Escape**: Close overview window
- **Ctrl+T**: Toggle theme (if enabled)

## Troubleshooting

### Tesseract Not Found
If you encounter Tesseract errors in KRONOS mode:
1. Install Tesseract OCR (see Prerequisites)
2. On Windows, ensure it's installed in the default path or update the path in `detection.py`

### No Images Displayed
- Verify TIFF files are in the correct location
- Check that KLARF files contain valid defect data
- Ensure coordinates are correctly extracted (check `mapping.csv`)

### Processing Errors
- Verify file permissions
- Check that all required files exist
- Review console output for detailed error messages

## Development

### Project Structure
```
semapp/
├── main.py                 # Main application entry point
├── Layout/                 # UI layout components
│   ├── create_button.py   # Button and control creation
│   ├── main_window_att.py # Window layout management
│   ├── settings.py        # Settings window
│   └── styles.py          # UI styles
├── Plot/                  # Plotting and visualization
│   ├── frame_attributes.py # Main plot frame
│   ├── overview_window.py  # Overview window
│   └── utils.py            # Plot utilities
└── Processing/            # Data processing modules
    ├── klarf_reader.py     # KLARF file parsing
    ├── processing.py       # Main processing class
    ├── rename_tif.py        # File renaming
    ├── split_tif.py         # TIFF splitting
    ├── threshold.py        # Threshold processing
    └── detection.py        # OCR detection
```

### Running Tests
```bash
# Run from project root
python -m semapp.main
```

## License

This project is licensed under the GPL-3.0-or-later License - see the LICENSE file for details.

## Author

**Thibaut Meyer**
- Email: thibaut.meyer3@gmail.com
- GitHub: [@thi-mey](https://github.com/thi-mey)

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## Acknowledgments

- PyQt5 community for the excellent GUI framework
- Tesseract OCR for number detection capabilities
- All contributors and users of SEMapp