WUT-AI-AI4Mat/microstructure-hq-sam

HQ-SAM Fine-Tuned Checkpoints for Microstructure Segmentation

Model Description

This repository contains dataset-specific fine-tuned parameter checkpoints for HQ-SAM with its ViT-B backbone. The files do not contain the full base model. Load them together with sam_hq_vit_b.pth using the matching source script.

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/hqsam_lora_decoder_best.pth
EMPS	LoRA plus mask decoder	2	checkpoints/EMPS/hqsam_lora_decoder_best.pth
Grain	LoRA plus mask decoder	2	checkpoints/Grain/hqsam_lora_decoder_best.pth
EBC	LoRA, mask decoder, and class tokens	3	checkpoints/EBC/semantic_hqsam_best.pth
Super	LoRA, mask decoder, and class tokens	3	checkpoints/Super/semantic_hqsam_best.pth
MetalDAM	LoRA, mask decoder, and class tokens	5	checkpoints/MetalDAM/semantic_hqsam_best.pth
UHCS	LoRA, mask decoder, and class tokens	7	checkpoints/UHCS/semantic_hqsam_best.pth

Class counts include background.

Base Model Requirement

Download the official HQ-SAM ViT-B checkpoint from: https://huggingface.co/lkeab/hq-sam/resolve/main/sam_hq_vit_b.pth

The files in this repository contain LoRA and mask-decoder parameters. Multiclass files additionally contain learned class tokens.

Training Details

• Base architecture: HQ-SAM ViT-B
• 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:

hf download NAMESPACE/microstructure-hq-sam checkpoints/EMPS/hqsam_lora_decoder_best.pth --local-dir weights/hq-sam
python hqsam/test_lora_decoder.py \
  --dataset-root /path/to/EMPS \
  --checkpoint weights/pretrained/sam_hq_vit_b.pth \
  --finetuned-checkpoint weights/hq-sam/checkpoints/EMPS/hqsam_lora_decoder_best.pth \
  --output-dir results/hq_sam_emps

For multiclass checkpoints, use hqsam/test_semantic_hqsam.py and pass the class count from the table.

Inference Parameters

The original automatic-mask path uses points_per_side=32, points_per_batch=64, pred_iou_thresh=0.85, stability_score_thresh=0.8, box_nms_thresh=0.7, and crop_n_layers=0. The binary fine-tuned path uses pred_iou_thresh=0.78 and stability_score_thresh=0.8.

Evaluation, Intended Use, and Limitations

Evaluation saves original-resolution masks and calculates the common benchmark metrics through Myutils/metrics.py. These checkpoints are intended for research reproduction on the named datasets. They require the matching HQ-SAM ViT-B base checkpoint and may not generalize to unseen materials or imaging conditions. They are not validated for safety-critical or industrial quality-control decisions.

License and Citation

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