README.md

---
license: cc-by-2.0
library_name: keras
tags:
- image-classification
- computer-vision
- cnn
- tensorflow
- keras
pipeline_tag: image-classification
datasets:
- LaurenceMoroney/horse-or-human
metrics:
- accuracy
---

# 🐴 Horse vs. Human Binary Image Classifier

A lightweight, high-performance 5-layer Convolutional Neural Network (CNN) built with **TensorFlow 2.x** and **Keras**. Designed for real-time, low-latency binary classification of 300x300 RGB images into two distinct classes: **Horse** (`0`) and **Human** (`1`).

---

## 🌟 Model Highlights
* **End-to-End Pipeline:** Features an internal `Rescaling` layer (`1./255`) so raw RGB pixel arrays can be passed directly into the model without manual preprocessing pipelines.
* **CPU & Edge Friendly:** Compact feature map footprint makes it ideal for deployment on lightweight hardware, local desktop applications, or edge micro-servers.
* **Modernized Keras API:** Fully updated for modern Keras standards (`model.fit`, `tf.keras.utils.image_dataset_from_directory`).

---

## 🏗️ Architecture Overview

The model employs 5 progressive feature-extraction blocks (Convolution + Max Pooling) to reduce spatial dimensions while building higher-level abstract feature maps, followed by a dense classification head:

```text
Input Image (300 × 300 × 3 RGB)
 └── Rescaling Layer (Scale to [0.0, 1.0])
 ├── [Block 1] Conv2D (16 filters, 3x3, ReLU)  ──> MaxPooling2D (2x2) [Output: 149x149x16]
 ├── [Block 2] Conv2D (32 filters, 3x3, ReLU)  ──> MaxPooling2D (2x2) [Output: 73x73x32]
 ├── [Block 3] Conv2D (64 filters, 3x3, ReLU)  ──> MaxPooling2D (2x2) [Output: 35x35x64]
 ├── [Block 4] Conv2D (64 filters, 3x3, ReLU)  ──> MaxPooling2D (2x2) [Output: 16x16x64]
 ├── [Block 5] Conv2D (64 filters, 3x3, ReLU)  ──> MaxPooling2D (2x2) [Output: 7x7x64]
 └── Flatten Layer [Vector Size: 3,136]
      └── Dense Layer (512 units, ReLU activation)
      └── Output Layer (1 unit, Sigmoid activation) [Output: Binary Probability]
```

---

## ⚡ Quickstart & Usage

Install dependencies:
```bash
pip install tensorflow numpy pillow huggingface_hub
```

Run inference directly in Python:
```python
import numpy as np
import tensorflow as tf
from huggingface_hub import hf_hub_download

# 1. Download model directly from Hugging Face Hub
model_path = hf_hub_download(
    repo_id="MightyDragon-Dev/horse-or-human-classifier", 
    filename="horse-or-human-model.keras"
)
model = tf.keras.models.load_model(model_path)

# 2. Load and prep test image
img_path = "sample.jpg"  # Target image file
img = tf.keras.utils.load_img(img_path, target_size=(300, 300))
img_array = tf.keras.utils.img_to_array(img)
img_array = np.expand_dims(img_array, axis=0)  # Shape: (1, 300, 300, 3)

# 3. Predict class probability
prediction = model.predict(img_array)[0][0]

if prediction > 0.5:
    print(f"Result: Human (Confidence: {prediction:.2%})")
else:
    print(f"Result: Horse (Confidence: {(1 - prediction):.2%})")
```

---

## 📊 Training Parameters & Dataset

| Parameter | Value |
| :--- | :--- |
| **Dataset Source** | Laurence Moroney's *Horses or Humans* Dataset |
| **Training Data** | 1,027 Synthetic Photoreal CGI Renderings (500 Horses / 527 Humans) |
| **Input Shape** | `(300, 300, 3)` |
| **Batch Size** | `32` |
| **Optimizer** | RMSprop (`learning_rate=0.001`) |
| **Loss Function** | `binary_crossentropy` |
| **Epochs Trained** | `15` |

---

## ⚠️ Intended Use & Limitations

* **Intended Use:** Fast binary filtering for desktop applications, learning computer vision fundamentals, or benchmarking lightweight edge devices.
* **Limitations:** The dataset consists primarily of photorealistic 3D rendered models in clean backgrounds. Performance on real-world photos with heavy occlusions, extreme lighting, or noisy backgrounds may exhibit domain shift.