README.md

---
license: mit
library_name: pytorch
pipeline_tag: image-segmentation
tags:
- semantic-segmentation
- microstructure
- microscopy
- materials-science
- segment-anything
- lora
- micro-sam
---

# MicroSAM Fine-Tuned Checkpoints for Microstructure Segmentation

## Model Description

This repository contains dataset-specific fine-tuned parameter checkpoints for
the MicroSAM `vit_b_lm` model. The files contain fine-tuned parameters rather
than a complete base model. The matching scripts obtain the `vit_b_lm` base
model through `micro_sam.util.get_sam_model` and then load these parameters.

Source code:
https://github.com/WUT-AI-AI4Mat/Segmentation-methods-evaluation-for-quantitative-microstructure-analysis

## Fine-Tuning Routes and Checkpoints

| Dataset | Route | Classes | File |
| --- | --- | ---: | --- |
| Aachen-Heerlen | LoRA plus mask decoder | 2 | `checkpoints/Aachen-Heerlen/microsam_lora_decoder_best.pth` |
| EMPS | LoRA plus mask decoder | 2 | `checkpoints/EMPS/microsam_lora_decoder_best.pth` |
| Grain | LoRA plus mask decoder | 2 | `checkpoints/Grain/microsam_lora_decoder_best.pth` |
| EBC | LoRA, mask decoder, and class tokens | 3 | `checkpoints/EBC/semantic_microsam_best.pth` |
| Super | LoRA, mask decoder, and class tokens | 3 | `checkpoints/Super/semantic_microsam_best.pth` |
| MetalDAM | LoRA, mask decoder, and class tokens | 5 | `checkpoints/MetalDAM/semantic_microsam_best.pth` |
| UHCS | LoRA, mask decoder, and class tokens | 7 | `checkpoints/UHCS/semantic_microsam_best.pth` |

Class counts include background.

## Base Model Requirement

Initialize the required base model with:

```bash
python -c "from micro_sam.util import get_sam_model; get_sam_model(model_type='vit_b_lm')"
```

The corresponding BioImage.IO checkpoint is available at:
https://uk1s3.embassy.ebi.ac.uk/public-datasets/bioimage.io/diplomatic-bug/1.2/files/vit_b.pt

## Training Details

- Base architecture: MicroSAM ViT-B-LM
- SAM encoder input: longest side resized and padded to 1024 x 1024
- Training batch size: 1
- Epochs: 200
- Optimizer: AdamW
- Learning rate: 0.0001
- Weight decay: 0.0001
- Scheduler: CosineAnnealingLR with minimum learning rate 0.000001
- Early-stopping patience: 50
- LoRA rank: 8
- LoRA alpha: 16
- LoRA dropout: 0.05
- LoRA targets: `qkv` and `proj`
- Binary objective: BCE, Dice, and IoU MSE
- Multiclass objective: cross-entropy and Dice

## Usage

Example for binary EMPS segmentation:

```bash
hf download NAMESPACE/microstructure-micro-sam checkpoints/EMPS/microsam_lora_decoder_best.pth --local-dir weights/micro-sam
python microsam/test_lora_decoder.py \
  --dataset-root /path/to/EMPS \
  --finetuned-checkpoint weights/micro-sam/checkpoints/EMPS/microsam_lora_decoder_best.pth \
  --output-dir results/micro_sam_emps
```

For multiclass checkpoints, use `microsam/test_semantic_microsam.py` and pass
the class count from the table.

## Inference Parameters

Automatic instance segmentation uses `min_size=10`,
`center_distance_threshold=0.5`, and `boundary_distance_threshold=0.5`.

## Evaluation, Intended Use, and Limitations

Evaluation saves original-resolution masks and calculates the common benchmark
metrics through `Myutils/metrics.py`. These checkpoints require the matching
MicroSAM `vit_b_lm` base model and source environment. MicroSAM dependencies
such as `vigra` and `python-elf` are most reliably installed through the
official Conda environment on Linux. The checkpoints are intended for research
reproduction and are not validated for safety-critical or industrial
quality-control decisions.

## License and Citation

The released experiment files are provided under the MIT license. MicroSAM and
its base model remain subject to upstream terms and the base checkpoint is not
redistributed here. A paper citation will be added after publication.