Add model card

README.md

@@ -1,3 +1,84 @@
 ---
 license: mit
+tags:
+  - face-generation
+  - flow-matching
+  - arc2face
+  - synthetic-data
+  - fairness
 ---
+
+# ID-Flow
+
+Pretrained **ID-Flow** weights from [**SynthFaces: Balanced Large Scale Human Dataset**](https://arxiv.org/abs/2610.40119v1)
+(accepted to BMVC 2026).
+
+ID-Flow is a label-conditional geodesic flow-matching model on the unit hypersphere of ArcFace identity embeddings
+(~11.8M parameters). Given an (age, race, gender) combination it samples a new identity embedding, which
+[Arc2Face](https://github.com/foivospar/Arc2Face) turns into face images. Sampling all 126 label combinations uniformly
+gives a demographically balanced set of synthetic identities.
+
+- Code: [github.com/ControlGenAI/SynthFaces](https://github.com/ControlGenAI/SynthFaces) (to be released)
+- Paper: [arXiv:2610.40119](https://arxiv.org/abs/2610.40119v1)
+
+## Files
+
+| file | description |
+|---|---|
+| `idflow.pt` | weights-only, self-describing checkpoint (model weights + hyper-parameters), 47 MB |
+
+Label order is `[age, race, gender]`: age `0-2, 3-9, 10-19, 20-29, 30-39, 40-49, 50-59, 60-69, 70+`; race
+`White, Black, Latino_Hispanic, East Asian, Southeast Asian, Indian, Middle Eastern`; gender `Male, Female`.
+
+## Usage: ID-Flow → Arc2Face
+
+Setup (from the code repository):
+
+```bash
+git clone https://github.com/ControlGenAI/SynthFaces && cd SynthFaces
+pip install -r requirements.txt
+huggingface-cli download shredder67/id-flow idflow.pt --local-dir .
+python scripts/download_arc2face.py --root Arc2Face      # Arc2Face + InsightFace models
+```
+
+Sample a balanced set of identities (all 126 label groups), then generate images with Arc2Face:
+
+```bash
+python scripts/sample_identities.py --ckpt idflow.pt --n_total 1000 --output_dir outputs/identities
+
+python scripts/sample_images.py sample \
+    --embeddings_path outputs/identities/id_embeddings.pt \
+    --output_dir outputs/images --images_per_identity 4
+python scripts/sample_images.py merge --output_dir outputs/images --n_parts 1
+```
+
+Or sample identity embeddings for chosen labels directly in Python:
+
+```python
+import torch
+from idflow import load_idflow
+
+model = load_idflow("idflow.pt", device="cuda:0")
+y = torch.tensor([[3, 0, 1]] * 16, device="cuda:0")   # age 20-29, White, Female
+ids = model.sample(bs=16, y=y, guidance_scale=2.0, device="cuda:0")  # (16, 512) unit-norm ArcFace embeddings
+```
+
+The embeddings can be passed to Arc2Face as `id_embeddings.pt` (see `scripts/sample_images.py`). A guidance scale of
+2.0 is used in the paper; higher values follow the labels more closely at the cost of diversity.
+
+## Notes
+
+The Arc2Face, InsightFace and Stable Diffusion 1.5 weights used for image generation are distributed under their own
+licenses (the Arc2Face and InsightFace weights are non-commercial); please check them before use.
+
+## Citation
+
+```bibtex
+@article{karpukhin2026synthfaces,
+  title   = {SynthFaces: Balanced Large Scale Human Dataset},
+  author  = {Karpukhin, Sergey and Bobkov, Denis and Morozov, Kirill and Alanov, Aibek},
+  journal = {arXiv preprint arXiv:2610.40119},
+  year    = {2026},
+  note    = {Accepted to BMVC 2026}
+}
+```