README.md

---
license: apache-2.0
library_name: pytorch
pipeline_tag: image-segmentation
tags:
  - semantic-segmentation
  - semi-supervised-learning
  - contrastive-learning
  - dinov2
  - pytorch
  - arxiv:2607.03068
datasets:
  - pascal-voc
---

# PixCon: Clean-Positive Contrastive Learning for Foundation-Model Semi-Supervised Segmentation

[![arXiv](https://img.shields.io/badge/arXiv-2607.03068-b31b1b.svg)](https://arxiv.org/abs/2607.03068)
[![Demo](https://img.shields.io/badge/🤗%20Space-Live%20demo-yellow.svg)](https://huggingface.co/spaces/psychofict/pixcon-demo)

> **PixCon model family** — **Pascal VOC** · [Cityscapes](https://huggingface.co/psychofict/pixcon-cityscapes) · [ADE20K](https://huggingface.co/psychofict/pixcon-ade20k) · [🤗 Interactive demo](https://huggingface.co/spaces/psychofict/pixcon-demo) · [🌐 Project page](https://psychofict.github.io/PixCon/) · [💻 Code](https://github.com/psychofict/PixCon) · [📄 Paper](https://arxiv.org/abs/2607.03068)

![PixCon on Pascal VOC — input (left) and predicted segmentation overlay (right)](preview.png)

**TL;DR.** With a DINOv2 teacher, a strict confidence threshold already retains a *measured*
~98%-clean pseudo-label set, so the accuracy that remains lives in how the embedding space is
*structured by class*, not in the filter. **PixCon** adds a single clean-positive pixel-contrastive
branch on top of a UniMatch V2 consistency backbone: a per-class memory bank that admits **only
labeled pixels the student already classifies correctly**, giving a contamination-free positive
set (ρ_F = 0) *by construction*, unlike prior contrastive SSSS banks (ReCo, U²PL) built from
confidence-filtered pseudo-labels. It adds **no inference-time parameters** and needs **no
bank-specific threshold**.

## Method

| Component | Setting |
|---|---|
| Backbone | DINOv2-Base (ViT-B/14), fine-tuned end-to-end |
| Decoder | DPT-lite (4 ViT layers → coarse-to-fine pyramid) |
| Consistency | Two strong+CutMix views, complementary channel dropout (UniMatch V2) |
| Threshold | Fixed conf ≥ 0.95 |
| Auxiliary | **PixCon**: 1×1 projection head, per-class memory bank (256/class), clean-positive filter (labeled ∧ pred==GT), supervised InfoNCE (τ = 0.1) |
| Optimizer | AdamW, backbone LR 5e-6, decoder LR 2e-4, poly schedule |

The contribution is the **clean-positive bank**: every entry is a labeled pixel whose student
prediction already matches the ground truth. A first-order analysis of the supervised-InfoNCE
gradient shows the false-positive term scales as ρ_F/(1−ρ_F); we *measure* ρ_F (0.018 on Pascal,
0.106 on ADE20K) rather than assume it.

## Results (honest framing)

In a **compute-matched one-switch** comparison against a strong DINOv2 UniMatch V2 baseline across
Pascal VOC, Cityscapes, and ADE20K, PixCon **matches or improves** the baseline:

- **Pascal-1/8: improves every seed** (per-seed gain ~**+0.2 mIoU**, the correctness lever).
- Its **three-seed mean reaches 87.90 mIoU**, the published UniMatch V2-B figure. (The larger
  3-seed mean gap is driven substantially by variance reduction and is reported as suggestive,
  not as a per-seed accuracy claim.)
- Because contamination is already rare under a foundation-model teacher, the **ρ_F = 0 guarantee
  acts chiefly as robustness** as teachers weaken; the accuracy gain comes from *cleaner positive
  supervision*.

> The released checkpoint is a **single representative seed** (88.00 mIoU, the seed closest to the
> reported mean), not a best-of-seeds pick. The headline number is the **three-seed mean 87.90**
> (per-seed: 87.60 / 88.00 / 88.10).

## Usage

```python
import torch
from torchvision import transforms as T
from PIL import Image

from model.segmentor import PixConSegmentor      # from the PixCon code
from core.inference import whole_inference

# Build the architecture and load the released EMA-teacher weights.
model = PixConSegmentor(backbone='dinov2_vitb14', nclass=21, pretrained=False).eval()
sd = torch.load('pixcon_pascal_1_8.pth', map_location='cpu')
# strict=False: the contrastive proj_head is not in the eval path and is absent from the
# released weights; the backbone/decoder/segmentation head all load.
model.load_state_dict(sd, strict=False)            # slim EMA-teacher state_dict

# ImageNet normalization (matches training).
norm = T.Compose([T.ToTensor(),
                  T.Normalize((0.485, 0.456, 0.406), (0.229, 0.224, 0.225))])
img = norm(Image.open('example.jpg').convert('RGB')).unsqueeze(0)

with torch.no_grad():
    logits = whole_inference(model, img)           # [1, 21, H, W], pads to /14 internally
    pred = logits.argmax(1)                         # [1, H, W] class indices (Pascal VOC, 21 classes)
```

An interactive demo is available as a Hugging Face Space (see the paper page).

## Citation

```bibtex
@article{tarubinga2026pixcon,
  title   = {PixCon: Clean-Positive Contrastive Learning for Foundation-Model
             Semi-Supervised Segmentation},
  author  = {Tarubinga, Ebenezer},
  journal = {arXiv preprint arXiv:2607.03068},
  year    = {2026}
}
```

## License

Released under Apache-2.0 (confirm this is compatible with your DINOv2 / UniMatch V2 dependencies
before publishing). DINOv2 weights are loaded from `facebookresearch/dinov2` at build time.