Add model card

README.md

@@ -0,0 +1,93 @@
+---
+license: apache-2.0
+library_name: keras
+pipeline_tag: image-classification
+tags:
+  - emotion-detection
+  - facial-expression-recognition
+  - image-classification
+  - keras
+  - tensorflow
+  - efficientnetv2
+---
+
+# Facial Emotion Recognition — Model
+
+Detects the emotion expressed in a photo of a human face.
+
+Facial emotion classification model in Keras 3 format (`best_model.keras`).
+Given a cropped face image it outputs probabilities over 7 emotion classes.
+
+- **Maintainer of this repository**: Mamd1
+- **Repository**: `Mamd1/emotion-detection-model`
+- **Demo Space**: `Mamd1/emotion-detection-app`
+- **License**: Apache-2.0
+
+## Attribution
+
+These weights were **not trained by the maintainer of this repository**. They are
+redistributed from the original Apache-2.0 licensed release by **Ali Ahmed**
+(`ali-ahmed-ai-developer/emotion_detection_model` on the Hugging Face Hub).
+Apache-2.0 permits redistribution and modification provided the license and
+attribution are preserved — this notice satisfies that requirement. Do not
+remove it.
+
+## Classes
+
+Index order matters — the output vector is in exactly this order:
+
+| Index | Class    |
+|-------|----------|
+| 0     | angry    |
+| 1     | disgust  |
+| 2     | fear     |
+| 3     | happy    |
+| 4     | neutral  |
+| 5     | sad      |
+| 6     | surprise |
+
+## Model details
+
+- **Backbone**: EfficientNetV2-S (ImageNet pre-trained)
+- **Head**: GlobalAveragePooling2D → BatchNorm → Dropout → Dense(512) → BatchNorm → Dropout → Dense(7)
+- **Input shape**: `(380, 380, 3)`, float32, values in `[0, 255]` (EfficientNetV2 rescales internally)
+- **Parameters**: ~21M
+- **File**: `best_model.keras` (~343 MB, stored via Git LFS)
+
+## Preprocessing
+
+The reference application converts the image to grayscale, then back to RGB
+(so R=G=B across 3 channels), resizes to 380x380, and passes raw `[0, 255]`
+float32 values. Matching this preprocessing is required for accurate results.
+
+## Usage
+
+```python
+import numpy as np
+import tensorflow as tf
+from PIL import Image
+from huggingface_hub import hf_hub_download
+
+CLASSES = ['angry', 'disgust', 'fear', 'happy', 'neutral', 'sad', 'surprise']
+
+path = hf_hub_download(
+    repo_id="Mamd1/emotion-detection-model",
+    filename="best_model.keras",
+)
+model = tf.keras.models.load_model(path)
+
+image = Image.open("face.jpg").convert("L").convert("RGB").resize((380, 380))
+x = np.expand_dims(np.array(image, dtype=np.float32), axis=0)
+
+probs = model.predict(x)[0]
+print(dict(zip(CLASSES, probs.tolist())))
+```
+
+## Limitations
+
+- Trained on tightly cropped faces. Wide shots, small faces, or busy backgrounds
+  degrade accuracy significantly — crop to the face first.
+- Facial expression recognition is not a reliable measure of a person's actual
+  internal emotional state. Do not use for consequential decisions about people
+  (hiring, security screening, medical or psychological assessment).
+- Accuracy varies across demographic groups and lighting conditions.