semstitcher 0.1.0
Stitch SEM tile images using stage coordinates from metadata files
License: MIT
Requires Python: >=3.9
Keywords: JEOL, SEM, electron-microscopy, image-stitching, microscopy

---
title: Sem Stitcher
emoji: 🏢
colorFrom: blue
colorTo: yellow
sdk: gradio
sdk_version: 6.4.0
app_file: app.py
pinned: false
license: mit
short_description: Mosaic JEOL SEM or microprobe images and add analysis points
---

# 🔬 SEM Stitcher

Stitch scanning electron microscope (SEM) tile images using stage coordinates from metadata files.

[![Hugging Face Space](https://img.shields.io/badge/🤗%20Hugging%20Face-Space-blue)](https://huggingface.co/spaces/yourusername/sem-stitcher)
[![PyPI](https://img.shields.io/pypi/v/semstitcher)](https://pypi.org/project/semstitcher/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## Features

- **Stitch SEM tiles** using stage coordinates from metadata files
- **Overlay analysis points** from CSV files
- **Web interface** via Hugging Face Spaces (no coding required)
- **Python library** for integration into workflows
- 🖥**Command-line tool** for batch processing

Currently supports **JEOL** metadata format.

## Quick Start

### Web Interface (No Installation)

Visit the [Hugging Face Space](https://huggingface.co/spaces/yourusername/sem-stitcher) to use the web interface.

### Python Library

```bash
pip install semstitcher
```

```python
from semstitcher import stitch_tiles

# Basic stitching
mosaic, transform = stitch_tiles("path/to/tiles", output_path="mosaic.tif")

# With point overlay
mosaic, transform = stitch_tiles(
    "path/to/tiles",
    output_path="mosaic.tif",
    csv_path="analysis_points.csv"
)
```

### Command Line

```bash
# Basic stitching
semstitcher /path/to/tiles output.tif

# With point overlay
semstitcher /path/to/tiles output.tif --csv points.csv
```

## File Format Requirements

### Image and Metadata Files

- **Images**: `.tif` or `.tiff` files
- **Metadata**: `.txt` files with the same base name as the image
  - Example: `sample_001.tif` and `sample_001.txt`

### JEOL Metadata Format

The metadata file must contain at minimum:

```
$CM_STAGE_POS -2.4153 10.1840 10.7170 0 0 0
$$SM_MICRON_BAR 170
$CM_FULL_SIZE 5120 3840
```

### CSV Format for Analysis Points

```csv
Phase,Point,X-POS,Y-POS
Olivine,1,-2.5607,11.7652
Spinel,1,-3.1858,10.2133
Cpx,1,-3.2824,11.8894
```

Required columns: `X-POS`, `Y-POS`  
Optional columns for labels: `Phase`, `Point`

## API Reference

### `stitch_tiles()`

High-level function to stitch tiles and optionally overlay points.

```python
from semstitcher import stitch_tiles

mosaic, transform = stitch_tiles(
    input_dir="path/to/tiles",      # Directory with .tif and .txt files
    output_path="output.tif",        # Output file path (optional)
    csv_path="points.csv",           # CSV with analysis points (optional)
    point_radius=25,                 # Radius of point markers
    compression='lzw',               # TIFF compression
)
```

### `create_mosaic()`

Lower-level function for more control.

```python
from semstitcher import create_mosaic
from semstitcher.stitcher import load_tiles_from_directory

tiles = load_tiles_from_directory("path/to/tiles")
mosaic, transform = create_mosaic(tiles)
```

### `overlay_points()`

Add point markers to an existing mosaic.

```python
from semstitcher import overlay_points

mosaic = overlay_points(
    mosaic,
    transform,
    csv_path="points.csv",
    point_radius=25,
    point_color=(255, 105, 180),  # Pink
    text_color=(255, 255, 0),     # Yellow
)
```

## Coordinate System

This tool is designed for JEOL SEMs where:
- **Stage X** increases to the **left** in the image
- **Stage Y** increases **downward** in the image

The coordinate transformation is applied automatically.

## Development

```bash
# Clone the repository
git clone https://github.com/yourusername/sem-stitcher.git
cd sem-stitcher

# Install in development mode
pip install -e ".[dev]"

# Run tests
pytest

# Run the Gradio app locally
python app.py
```

## License

MIT License - see [LICENSE](LICENSE) for details.

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

### Planned Features

- [ ] Support for FEI/Thermo Fisher metadata format
- [ ] Support for Zeiss metadata format
- [ ] Automatic tile alignment using image features
- [ ] Blend overlapping regions
- [ ] Export to pyramidal TIFF for large mosaics


Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference