---
license: mit
pipeline_tag: image-segmentation
tags:
- wsss
- boundary-refinement
- pytorch
---

# HGA Pretrained Checkpoints (PASCAL VOC 2012 & MS COCO 2014)

This repository hosts the official best-performing model checkpoints for the **HGA (Hierarchical-Geometric Alignment)** weakly supervised semantic segmentation (WSSS) paradigm.

Both checkpoints leverage the high-performance **EfficientViT-SAM-XL0** backbone, but employ different decoder architectures optimized for their respective dataset scales.

## 📊 Benchmark Checklist

| Checkpoint Filename | Target Dataset | Backbone | Decoder Type | Reached mIoU |
|:---|:---:|:---:|:---:|:---:|
| **`best_model_voc.pth`** | PASCAL VOC 2012 Val | EfficientViT-SAM-XL0 | **RC (Resize-Conv) Decoder** | **84.91%** |
| **`best_model_coco.pth`** | MS COCO 2014 Val | EfficientViT-SAM-XL0 | **CT (Transpose-Conv) Decoder** | **59.31%** |

---

## ⚠️ Critical Setup Instructions (Decoder Mismatch Prevention)

To prevent PyTorch `state_dict` loading errors (such as `KeyError` or missing key warnings), you must configure the decoder type in your `config.py` to match the downloaded checkpoint exactly:

### 1. For PASCAL VOC 2012 (`best_model_voc.pth`):
Ensure your decoder configuration is set to use the patched **Resize-Convolution (RC) Decoder**:
```python
# Inside your config.py for VOC evaluation:
decoder_type = "RC"  # Ensure this matches the RC-Decoder setup
```

### 2. For MS COCO 2014 (`best_model_coco.pth`):
Ensure your decoder configuration is set to use the standard **Transposed Convolution (CT) Decoder**:
```python
# Inside your config.py for COCO evaluation:
decoder_type = "CT"  # Ensure this matches the CT-Decoder setup
```

---

## 🚀 Evaluation & Reproducibility Guide

The evaluation scripts are designed to automatically reconstruct the correct network architecture based on your configuration files.

1. Download the target checkpoint file (`.pth`) and place it under your local `checkpoints/` folder.
2. Clone our official codebase and configure your directory paths:
   👉 **[Uncertainty-42/HGA GitHub Repository](https://github.com/Uncertainty-42/HGA)**
3. Run the evaluation shell scripts directly from the repository root:

```bash
# To evaluate PASCAL VOC:
bash val_voc.sh

# To evaluate MS COCO:
bash val_coco.sh
```

## 📝 Citation
Our paper is currently under review/pre-print preparation. The official BibTeX citation and arXiv link will be updated here as soon as the preprint is publicly released.