README.md

---
language: en
license: mit
library_name: keras
pipeline_tag: image-classification
tags:
  - cat-emotion
  - vgg16
  - transfer-learning
  - cnn
  - tensorflow
  - keras
  - image-classification
  - computer-vision
  - depi
datasets:
  - custom
metrics:
  - accuracy
---

# 🐱 Cat Emotion Classification with VGG16

A deep learning model for classifying cat emotions from images using **VGG16 transfer learning**, achieving **82.19% validation accuracy** across 5 emotion classes.

## Model Description

This model classifies cat facial expressions into one of five emotional categories. It uses VGG16 (pre-trained on ImageNet) as a feature extractor with a custom classification head featuring GlobalAveragePooling2D, BatchNormalization, and two Dense layers.

**Part of:** Digital Egypt Pioneers Initiative (DEPI) Machine Learning Internship

| Property | Value |
|----------|-------|
| **Architecture** | VGG16 + GAP + BN + Dense(512, 256) |
| **Input Size** | 224×224×3 RGB |
| **Output** | 5 classes (softmax) |
| **Parameters** | ~15.3M (trainable: ~2.1M) |
| **Framework** | TensorFlow / Keras |
| **Accuracy** | 82.19% |

## Classes

| Index | Class | Description |
|-------|-------|-------------|
| 0 | `angry` | Cat displaying angry expressions |
| 1 | `normal` | Cat in a neutral/normal state |
| 2 | `rested` | Cat in a relaxed/resting state |
| 3 | `sad` | Cat displaying sad expressions |
| 4 | `surprised` | Cat displaying surprised expressions |

## Quick Start

```python
from tensorflow.keras.models import load_model
import numpy as np
from PIL import Image

# Load model
model = load_model('best_vgg16_model.keras')

# Predict
img = Image.open('cat.jpg').resize((224, 224))
img_array = np.expand_dims(np.array(img) / 255.0, axis=0)

prediction = model.predict(img_array)
classes = ['angry', 'normal', 'rested', 'sad', 'surprised']

predicted_class = classes[np.argmax(prediction)]
confidence = np.max(prediction)
print(f"Emotion: {predicted_class} ({confidence:.2%})")
```

## Training Details

### Architecture (V2 — Final)

```
VGG16 (ImageNet, last 8 layers unfrozen)
    ↓
GlobalAveragePooling2D
    ↓
BatchNormalization
    ↓
Dense(512, ReLU) → Dropout(0.5)
    ↓
BatchNormalization
    ↓
Dense(256, ReLU) → Dropout(0.3)
    ↓
Dense(5, Softmax)
```

### Training Strategy

| Phase | Epochs | Learning Rate | Description |
|-------|--------|--------------|-------------|
| Phase 1 — Feature Extraction | 15 | 1e-4 | All VGG16 layers frozen |
| Phase 2 — Fine-Tuning | 25 | 1e-5 | Last 8 VGG16 layers unfrozen |

- **Optimizer:** Adam
- **Loss:** Categorical Crossentropy
- **Class Weights:** Balanced (computed with sklearn)
- **Callbacks:** EarlyStopping (patience=5), ReduceLROnPlateau, ModelCheckpoint

### Data Augmentation
- Rotation: 30°
- Width/Height shift: 0.25
- Zoom: 0.25
- Horizontal flip
- Brightness: [0.8, 1.2]
- Shear: 0.15

## Performance

### Model Comparison

| Version | Input | Architecture | Accuracy |
|---------|-------|-------------|----------|
| V1 (Baseline) | 128×128 | Flatten → Dense(256) | 81.18% |
| **V2 (Final)** | **224×224** | **GAP → BN → Dense(512,256)** | **82.19%** |

### Dataset

- **Training:** ~11,513 images
- **Validation:** ~2,880 images
- **Source:** [Kaggle — Cats Data Set](https://www.kaggle.com/datasets/bilalmahmoud/cats-data-set)

## Files

- `best_vgg16_model.keras` — Trained VGG16 model (V1, 134MB)
- `README.md` — This model card

## Intended Use

- **Primary use:** Classifying cat emotions from images
- **Users:** Researchers, students, pet tech developers
- **Out of scope:** Other animal species, real-time production systems

## Limitations

- Trained on a specific cat emotion dataset — may not generalize to all cat breeds or lighting conditions
- 5 emotion categories only — does not cover all possible feline emotional states
- Best results with clear, well-lit frontal images of cats

## Links

- 🐱 **GitHub:** [Bolaal/Cat-Emotion-Classification-with-CNN](https://github.com/Bolaal/Cat-Emotion-Classification-with-CNN)
- 📊 **Dataset:** [Kaggle — Cats Data Set](https://www.kaggle.com/datasets/bilalmahmoud/cats-data-set)

## Citation

```bibtex
@misc{cat-emotion-vgg16-2025,
  author = {Belal Mahmoud Hussien},
  title = {Cat Emotion Classification with VGG16},
  year = {2025},
  publisher = {Hugging Face},
  url = {https://huggingface.co/Belall87/Cat-Emotion-Classification-with-CNN}
}
```

## Author

**Belal Mahmoud Hussien**
- 📧 Email: belalmahmoud8787@gmail.com
- 💼 LinkedIn: [belal-mahmoud-husien](https://linkedin.com/in/belal-mahmoud-husien)
- 🐱 GitHub: [@Bolaal](https://github.com/Bolaal)
- 🤗 Hugging Face: [@Belall87](https://huggingface.co/Belall87)