Upload README.md with huggingface_hub

README.md

@@ -0,0 +1,105 @@
+---
+license: apache-2.0
+library_name: pytorch
+pipeline_tag: image-segmentation
+tags:
+  - semantic-segmentation
+  - semi-supervised-learning
+  - contrastive-learning
+  - dinov2
+  - pytorch
+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)
+
+**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.