README.md

metadata

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.

{
  "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:

{
  "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

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

Using 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

# 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.