README.md

---
title: Iris Recognition — Banned Traveler Detection
emoji: 👁️
colorFrom: blue
colorTo: indigo
sdk: docker
app_port: 7860
pinned: false
---

# 👁️ Iris Recognition — Banned Traveler Detection API

A production-ready REST API that accepts an **iris image** and returns whether the person is **Banned** or **Allowed** to travel, based on a trained deep-learning iris recognition model.

---

##  Model Architecture

| Property | Value |
|---|---|
| Architecture | Custom ResNet (Residual Blocks) |
| Input | 150 × 150 px — Grayscale |
| Output | 2000 classes (1000 persons × 2 eyes) |
| Loss | Sparse Categorical Crossentropy |
| Optimizer | AdamW (lr=3e-4, wd=1e-4) |
| Test Accuracy | ~95% |

### Preprocessing Pipeline
1. Convert image to **grayscale**
2. **Resize** to 150×150 while preserving aspect ratio (white padding)
3. **Normalize** pixel values to `[0, 1]`

---

##  Dataset

Trained on the **CASIA-Iris-Thousand** dataset:
- 1,000 subjects × 2 eyes = 2,000 classes
- 10 images per class = 20,000 images total
- Images are grayscale, stored as `.jpg`

Label format: `{person_id}-{L|R}` (e.g., `437-R` = person 437, right eye)

---

##  Files Required in the Space

Upload these files to your Space repository:

```
├── main.py                  ← FastAPI app (this repo)
├── Dockerfile               ← Docker build config
├── requirements.txt         ← Python dependencies
├── README.md                ← This file
├── IrisRecognizer95.h5      ←  Upload your trained model weights
└── Banned_travelers22.csv   ←  Upload the banned travelers CSV
```

> **Important:** The model file (`IrisRecognizer95.h5`) and CSV (`Banned_travelers22.csv`) are **not included** in the repo — upload them manually via the Space's Files tab.

---

##  API Endpoints

### `GET /`
Returns a welcome message and available endpoints.

### `GET /health`
Returns service health status.

```json
{
  "status": "ok",
  "model_loaded": true,
  "csv_loaded": true,
  "num_classes": 2000,
  "banned_records": 20000
}
```

### `POST /predict`
Upload an iris image and get the prediction.

**Request:** `multipart/form-data`
| Field | Type | Description |
|---|---|---|
| `file` | image | Iris image (JPEG or PNG) |

**Response:**
```json
{
  "person_id": "437",
  "predicted_label": "437-R",
  "status": "Banned",
  "confidence": 0.9998,
  "is_banned": true,
  "message": "  BANNED — Person 437 is NOT allowed to travel."
}
```

### Status Values
| Value | Meaning |
|---|---|
| `Banned` | Person is on the banned travelers list |
| `Allowed` | Person is cleared to travel |
| `Unknown` | Person predicted but not found in the CSV records |

---

##  Testing the API

### Using Swagger UI
1. Open `https://<your-space-url>/docs`
2. Click `POST /predict` → Try it out
3. Upload an iris image and execute

### Using curl
```bash
curl -X POST "https://<your-space-url>/predict" \
     -H "accept: application/json" \
     -F "file=@iris_image.jpg"
```

### Using Python
```python
import requests

url = "https://<your-space-url>/predict"
with open("iris_image.jpg", "rb") as f:
    response = requests.post(url, files={"file": ("iris.jpg", f, "image/jpeg")})

print(response.json())
```

---

##  Running Locally

```bash
# Clone & install
git clone <your-repo>
cd iris-api
pip install -r requirements.txt

# Set paths if your files have different names
export MODEL_PATH=IrisRecognizer95.h5
export CSV_PATH=Banned_travelers22.csv

# Run
python main.py
# API available at http://localhost:7860
```

---

##  CSV Format

The banned travelers CSV must have these columns:

| Column | Type | Example |
|---|---|---|
| `Label` | string | `437-R` |
| `person_id` | int/string | `437` |
| `Status` | string | `Banned` or `Allowed` |

---

##  Environment Variables

| Variable | Default | Description |
|---|---|---|
| `MODEL_PATH` | `IrisRecognizer95.h5` | Path to Keras model file |
| `CSV_PATH` | `Banned_travelers22.csv` | Path to banned travelers CSV |

---

##  Notes

- The model uses `LabelEncoder` fitted on the CSV labels at startup — no separate encoder file needed.
- Confidence threshold is not applied server-side; the caller can filter by the returned `confidence` value.
- The API handles JPEG, PNG, and BMP formats.