Upload README.md with huggingface_hub

README.md

@@ -0,0 +1,124 @@
+---
+license: apache-2.0
+language: en
+library_name: pytorch
+tags:
+  - medical-imaging
+  - brain-mri
+  - segmentation
+  - implicit-neural-representation
+  - meta-learning
+  - siren
+  - parameter-efficient
+datasets:
+  - oasis
+metrics:
+  - dice
+pipeline_tag: image-segmentation
+---
+
+# MetaSeg-SIREN 2D 5-class (OASIS)
+
+Meta-learned **SIREN implicit neural network** for 5-class brain MRI
+segmentation on neurite-OASIS coronal slices. Trained with the MetaSeg recipe
+(Vyas et al., MICCAI 2025): 5,000 outer-loop MAML iterations + 4,001
+classifier-only finetune epochs.
+
+## Performance
+
+| Metric | Value | Source |
+|---|---:|---|
+| Mean Dice (OASIS test split, n=80) | **0.925 ± 0.013** | Reproduction of paper Table 1 row 1 (paper: 0.93 ± 0.012, within 1σ) |
+| INR parameters | 83 K | – |
+| Seg head parameters | 645 | – |
+| Inference time (per slice, A100 BF16) | ~0.3 s | inner_steps=100 |
+
+Output classes:
+
+| ID | Class |
+|---:|---|
+| 0 | background |
+| 1 | CSF / ventricles |
+| 2 | cortex |
+| 3 | white matter |
+| 4 | deep grey matter (thalamus, caudate, putamen, hippocampus, etc.) |
+
+## Usage
+
+```python
+from inr_brain_seg import InrBrainSeg
+
+model = InrBrainSeg.from_pretrained("basimazam/metaseg-siren-2d-5cls")
+mask  = model.segment("path/to/T1.nii.gz")
+# mask is a numpy.ndarray of integer class labels, same spatial shape as the input.
+```
+
+The model expects a **mid-coronal slice at 192² resolution**, percentile-normalised
+to `[0, 1]`. If you pass a full 3D NIfTI volume, the wrapper extracts the mid-coronal
+slice automatically; see `preprocessing.json` for the canonical recipe.
+
+CLI:
+
+```sh
+inr-seg-single \
+    --model basimazam/metaseg-siren-2d-5cls \
+    --input  /data/T1.nii.gz \
+    --output /data/T1_seg.nii.gz
+```
+
+## Training details
+
+* **Backbone**: SIREN with `omega_0=30`, 3 hidden layers of width 128.
+* **Outer loop**: 5,000 MAML iterations, lr 1e-4, inner_steps=2 at lr 1e-4.
+* **Classifier finetune**: 4,001 epochs, lr 5e-5, BCE loss.
+* **Validation budget**: 50 inner-loop steps.
+* **Test-time inner loop**: K=100 steps at lr 1e-4 (paper default).
+
+Training data: 314 neurite-OASIS subjects (train split). Validation: 21
+subjects. Held-out test: 80 subjects.
+
+## Intended use
+
+Research only. The model is not validated for clinical use. Best for in-domain
+neurite-OASIS-style coronal T1 slices.
+
+For **cross-site** scans (different scanner / vendor / field strength), the
+zero-shot Dice drops to ~0.30. Use the adapter variant
+[`basimazam/metaseg-siren-adapter-v2-ixi`](https://huggingface.co/basimazam/metaseg-siren-adapter-v2-ixi)
+which lifts cross-site Dice to 0.69 with a 65,920-parameter MLP adapter.
+
+## Reproducibility
+
+The full reproduction log lives at
+[`results/RESULTS.md`](https://github.com/basim-azam/inr-brain-seg/blob/main/results/RESULTS.md)
+in the accompanying repository, including hardware, wall-clock, seed values,
+and paper-deviation discussion.
+
+## Citation
+
+```bibtex
+@inproceedings{azam2026inrbrainseg,
+  title     = {Coordinate-Field Implicit Networks for Cross-Site Brain MRI Segmentation},
+  author    = {Azam, Basim},
+  booktitle = {Asian Conference on Computer Vision (ACCV)},
+  year      = {2026}
+}
+
+@inproceedings{vyas2025metaseg,
+  title     = {Fit Pixels, Get Labels: Meta-Learned Implicit Networks for Image Segmentation},
+  author    = {Vyas, Kushal and others},
+  booktitle = {MICCAI},
+  year      = {2025}
+}
+
+@inproceedings{sitzmann2020siren,
+  title     = {Implicit Neural Representations with Periodic Activation Functions},
+  author    = {Sitzmann, Vincent and others},
+  booktitle = {NeurIPS},
+  year      = {2020}
+}
+```
+
+## License
+
+Apache License 2.0.