---

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.

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 to use the web interface.

Python Library

pip install semstitcher

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

# 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

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.

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.

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.

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

# 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 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