Upload README.md with huggingface_hub

README.md

@@ -0,0 +1,75 @@
+---
+license: mit
+pipeline_tag: image-classification
+tags:
+- facial-expression-recognition
+- emotion-recognition
+- fer2013
+- pytorch
+library_name: pytorch
+---
+
+# Residual Masking Network (RMN) — Facial Expression Recognition
+
+Official checkpoint for **"Facial Expression Recognition using Residual Masking Network"** (ICPR 2020).
+
+- 📄 Paper: [IEEE Xplore](https://ieeexplore.ieee.org/abstract/document/9411919)
+- 💻 Code: [github.com/phamquiluan/ResidualMaskingNetwork](https://github.com/phamquiluan/ResidualMaskingNetwork)
+- 🏆 State-of-the-art single-model accuracy on FER2013: **74.14%** (76.82% with ensemble)
+
+## Files
+
+| File | Description |
+|---|---|
+| `Z_resmasking_dropout1_rot30_2019Nov30_13.32` | Training checkpoint of the `resmasking_dropout1` architecture used by the [`rmn`](https://pypi.org/project/rmn/) pip package. Model weights are stored under the `"net"` key. |
+| `face_detection_yunet_2023mar.onnx` | YuNet face detector used by the `rmn` package pipeline. |
+
+## Usage
+
+The easiest way is through the `rmn` package:
+
+```bash
+pip install rmn
+```
+
+```python
+import cv2
+from rmn import RMN
+
+m = RMN()
+image = cv2.imread("some-image.png")
+results = m.detect_emotion_for_single_frame(image)
+print(results)
+```
+
+Or load the raw checkpoint directly:
+
+```python
+import torch
+from huggingface_hub import hf_hub_download
+from models import resmasking_dropout1  # from the GitHub repo
+
+path = hf_hub_download(
+    repo_id="phamquiluan/ResidualMaskingNetwork",
+    filename="Z_resmasking_dropout1_rot30_2019Nov30_13.32",
+)
+model = resmasking_dropout1(in_channels=3, num_classes=7)
+state = torch.load(path, map_location="cpu")
+model.load_state_dict(state["net"])
+model.eval()
+```
+
+Emotion labels (FER2013): `angry, disgust, fear, happy, sad, surprise, neutral`.
+
+## Citation
+
+```bibtex
+@inproceedings{pham2021facial,
+  title={Facial expression recognition using residual masking network},
+  author={Pham, Luan and Vu, The Huynh and Tran, Tuan Anh},
+  booktitle={2020 25th International Conference on Pattern Recognition (ICPR)},
+  pages={4513--4519},
+  year={2021},
+  organization={IEEE}
+}
+```