README.md

---
library_name: pytorch
pipeline_tag: image-classification
tags:
- vision-transformer
- age-estimation
- gender-classification
- face-analysis
- computer-vision
- pytorch
- transformers
- multi-task-learning
language:
- en
license: apache-2.0
datasets:
- UTKFace
metrics:
- accuracy
- mae
model-index:
- name: Age Gender Prediction
  results:
  - task:
      type: image-classification
      name: Gender Classification
    dataset:
      name: UTKFace
      type: face-analysis
    metrics:
    - type: accuracy
      value: 94.3
      name: Gender Accuracy
    - type: mae
      value: 4.5
      name: Age MAE (years)
---
# 🏆 ViT Age-Gender Prediction: Vision Transformer for Facial Analysis

[![Model](https://img.shields.io/badge/Model-Vision%20Transformer-blue)](https://huggingface.co/abhilash88/age-gender-prediction)
[![Accuracy](https://img.shields.io/badge/Gender%20Accuracy-94.3%25-green)](https://huggingface.co/abhilash88/age-gender-prediction)
[![Pipeline](https://img.shields.io/badge/Pipeline-One%20Liner-brightgreen)](https://huggingface.co/abhilash88/age-gender-prediction)

A state-of-the-art Vision Transformer model for simultaneous age estimation and gender classification, achieving **94.3% gender accuracy** and **4.5 years age MAE** on the UTKFace dataset.

## 🚀 One-Liner Usage

```python
from transformers import pipeline
classifier = pipeline("image-classification", model="abhilash88/age-gender-prediction", trust_remote_code=True)
result = classifier("your_image.jpg")
print(f"Age: {result[0]['age']}, Gender: {result[0]['gender']}")
```

**That's it!** One line to get age and gender predictions.

## 📱 Complete Examples

### Basic Pipeline Usage
```python
from transformers import pipeline

# Create classifier
classifier = pipeline("image-classification", model="abhilash88/age-gender-prediction", trust_remote_code=True)

# Predict from file
result = classifier("your_image.jpg")
print(f"Age: {result[0]['age']} years")
print(f"Gender: {result[0]['gender']}")
print(f"Confidence: {result[0]['gender_confidence']:.1%}")

# Predict from URL
result = classifier("https://example.com/face_image.jpg")
print(f"Prediction: {result[0]['age']} years, {result[0]['gender']}")

# Predict from PIL Image
from PIL import Image
img = Image.open("image.jpg")
result = classifier(img)
print(f"Result: {result[0]['age']} years, {result[0]['gender']}")
```

### Simple Helper Functions
```python
from model import predict_age_gender, simple_predict

# Method 1: Detailed result
result = predict_age_gender("your_image.jpg")
print(f"Age: {result['age']}, Gender: {result['gender']}")
print(f"Confidence: {result['confidence']:.1%}")

# Method 2: Simple string output
prediction = simple_predict("your_image.jpg")
print(prediction)  # "25 years, Female (87% confidence)"
```

### Google Colab
```python
# Install requirements
!pip install transformers torch pillow

from transformers import pipeline
import matplotlib.pyplot as plt
from PIL import Image

# Create classifier
classifier = pipeline("image-classification", model="abhilash88/age-gender-prediction", trust_remote_code=True)

# Upload image in Colab
from google.colab import files
uploaded = files.upload()
filename = list(uploaded.keys())[0]

# Predict and display
result = classifier(filename)
img = Image.open(filename)

plt.figure(figsize=(8, 6))
plt.imshow(img)
plt.title(f"Prediction: {result[0]['age']} years, {result[0]['gender']} ({result[0]['gender_confidence']:.1%})")
plt.axis('off')
plt.show()

print(f"Age: {result[0]['age']} years")
print(f"Gender: {result[0]['gender']}")
print(f"Confidence: {result[0]['gender_confidence']:.1%}")
```

### Batch Processing
```python
from transformers import pipeline

classifier = pipeline("image-classification", model="abhilash88/age-gender-prediction", trust_remote_code=True)

# Process multiple images
images = ["image1.jpg", "image2.jpg", "image3.jpg"]
results = []

for image in images:
    result = classifier(image)
    results.append({
        'image': image,
        'age': result[0]['age'],
        'gender': result[0]['gender'],
        'confidence': result[0]['gender_confidence']
    })

for result in results:
    print(f"{result['image']}: {result['age']} years, {result['gender']} ({result['confidence']:.1%})")
```

### Real-time Webcam
```python
import cv2
from transformers import pipeline

classifier = pipeline("image-classification", model="abhilash88/age-gender-prediction", trust_remote_code=True)

cap = cv2.VideoCapture(0)
while True:
    ret, frame = cap.read()
    if ret:
        # Save frame temporarily
        cv2.imwrite("temp_frame.jpg", frame)
        
        # Predict
        result = classifier("temp_frame.jpg")
        
        # Display prediction
        text = f"Age: {result[0]['age']}, Gender: {result[0]['gender']}"
        cv2.putText(frame, text, (10, 30), cv2.FONT_HERSHEY_SIMPLEX, 1, (0, 255, 0), 2)
        cv2.imshow('Age-Gender Detection', frame)
        
    if cv2.waitKey(1) & 0xFF == ord('q'):
        break

cap.release()
cv2.destroyAllWindows()
```

### URL Images
```python
from transformers import pipeline

classifier = pipeline("image-classification", model="abhilash88/age-gender-prediction", trust_remote_code=True)

# Direct URL prediction
image_url = "https://images.unsplash.com/photo-1507003211169-0a1dd7228f2d?w=300"
result = classifier(image_url)

print(f"Age: {result[0]['age']} years")
print(f"Gender: {result[0]['gender']}")
print(f"Confidence: {result[0]['gender_confidence']:.1%}")
```

## 📊 Pipeline Output Format

The pipeline returns a list with one prediction:

```python
[
    {
        "label": "25 years, Female",
        "score": 0.873,
        "age": 25,
        "gender": "Female", 
        "gender_confidence": 0.873,
        "gender_probability_female": 0.873,
        "gender_probability_male": 0.127
    }
]
```

**Access the values:**
- `result[0]['age']` - Predicted age (integer)
- `result[0]['gender']` - Predicted gender ("Male" or "Female")
- `result[0]['gender_confidence']` - Confidence score (0-1)
- `result[0]['label']` - Formatted string summary

## 🎯 Model Performance

| Metric | Performance | Dataset |
|--------|------------|---------|
| **Gender Accuracy** | **94.3%** | UTKFace |
| **Age MAE** | **4.5 years** | UTKFace |
| **Architecture** | ViT-Base + Dual Head | 768→256→64→1 |
| **Parameters** | 86.8M | Optimized |
| **Inference Speed** | ~50ms/image | CPU |

### Performance by Age Group
- **Adults (21-60 years)**: 94.3% gender accuracy, 4.5 years age MAE ✅ **Excellent**
- **Young Adults (16-30 years)**: 92.1% gender accuracy ✅ **Very Good**  
- **Teenagers (13-20 years)**: 89.7% gender accuracy ✅ **Good**
- **Children (5-12 years)**: 78.4% gender accuracy ⚠️ **Limited**
- **Seniors (60+ years)**: 87.2% gender accuracy ✅ **Good**

## ⚠️ Usage Guidelines

### ✅ Optimal Performance
- **Best for**: Adults 16-60 years old
- **Image quality**: Clear, well-lit, front-facing faces
- **Use cases**: Demographic analysis, content filtering, marketing research

### ❌ Known Limitations  
- **Children (0-12)**: Reduced accuracy due to limited training data
- **Very elderly (70+)**: Higher prediction variance
- **Poor conditions**: Low light, extreme angles, heavy occlusion

### 🎯 Tips for Best Results
- Use clear, well-lit images
- Ensure faces are clearly visible and front-facing
- Consider confidence scores for critical applications
- Validate results for your specific use case

## 🛠️ Installation

```bash
# Minimal installation
pip install transformers torch pillow

# Full installation with optional dependencies  
pip install transformers torch torchvision pillow opencv-python matplotlib

# For development
pip install transformers torch pillow pytest black flake8
```

## 📈 Use Cases & Examples

### Content Moderation
```python
from transformers import pipeline

classifier = pipeline("image-classification", model="abhilash88/age-gender-prediction", trust_remote_code=True)

def moderate_content(image_path):
    result = classifier(image_path)
    age = result[0]['age']
    
    if age < 18:
        return f"Minor detected ({age} years) - content flagged for review"
    return f"Adult content approved: {age} years, {result[0]['gender']}"

status = moderate_content("user_upload.jpg")
print(status)
```

### Marketing Analytics
```python
from transformers import pipeline

classifier = pipeline("image-classification", model="abhilash88/age-gender-prediction", trust_remote_code=True)

def analyze_audience(image_folder):
    from glob import glob
    
    demographics = {"male": 0, "female": 0, "total_age": 0, "count": 0}
    
    for image_path in glob(f"{image_folder}/*.jpg"):
        result = classifier(image_path)
        demographics[result[0]['gender'].lower()] += 1
        demographics['total_age'] += result[0]['age']
        demographics['count'] += 1
    
    demographics['avg_age'] = demographics['total_age'] / demographics['count']
    demographics['male_percent'] = demographics['male'] / demographics['count'] * 100
    demographics['female_percent'] = demographics['female'] / demographics['count'] * 100
    
    return demographics

stats = analyze_audience("customer_photos/")
print(f"Average age: {stats['avg_age']:.1f}")
print(f"Gender split: {stats['male_percent']:.1f}% Male, {stats['female_percent']:.1f}% Female")
```

### Age Verification
```python
from transformers import pipeline

classifier = pipeline("image-classification", model="abhilash88/age-gender-prediction", trust_remote_code=True)

def verify_age(image_path, min_age=18):
    result = classifier(image_path)
    age = result[0]['age']
    confidence = result[0]['gender_confidence']
    
    if confidence < 0.7:  # Low confidence
        return "Please provide a clearer image"
    
    if age >= min_age:
        return f"Verified: {age} years old (meets {min_age}+ requirement)"
    else:
        return f"Age verification failed: {age} years old"

verification = verify_age("id_photo.jpg", min_age=21)
print(verification)
```

## 🔧 Technical Details

- **Base Model**: google/vit-base-patch16-224 (Vision Transformer)
- **Input Resolution**: 224×224 RGB images  
- **Architecture**: Dual-head design with age regression and gender classification
- **Training Dataset**: UTKFace (23,687 images)
- **Training**: 15 epochs, AdamW optimizer, 2e-5 learning rate

## 🌟 Key Features

- ✅ **True one-line usage** with transformers pipeline
- ✅ **High accuracy** (94.3% gender, 4.5 years age MAE)
- ✅ **Multiple input types** (file paths, URLs, PIL Images, NumPy arrays)
- ✅ **Batch processing** support
- ✅ **Real-time capable** (~50ms inference)
- ✅ **Google Colab ready**
- ✅ **Production tested**

## 🚀 Quick Start Examples

### Absolute Minimal Usage
```python
from transformers import pipeline
result = pipeline("image-classification", model="abhilash88/age-gender-prediction", trust_remote_code=True)("image.jpg")
print(f"Age: {result[0]['age']}, Gender: {result[0]['gender']}")
```

### With Helper Function
```python
from model import simple_predict
print(simple_predict("image.jpg"))  # "25 years, Female (87% confidence)"
```

### Error Handling
```python
from transformers import pipeline

classifier = pipeline("image-classification", model="abhilash88/age-gender-prediction", trust_remote_code=True)

def safe_predict(image_path):
    try:
        result = classifier(image_path)
        return f"Age: {result[0]['age']}, Gender: {result[0]['gender']}"
    except Exception as e:
        return f"Prediction failed: {e}"

prediction = safe_predict("any_image.jpg")
print(prediction)
```

## 📝 Citation

```bibtex
@misc{age-gender-prediction-2025,
  title={Age-Gender-Prediction: Vision Transformer for Facial Analysis},
  author={Abhilash Sahoo},
  year={2025},
  publisher={Hugging Face},
  url={https://huggingface.co/abhilash88/age-gender-prediction},
  note={One-liner pipeline with 94.3\% gender accuracy}
}
```

## 📄 License

Licensed under Apache 2.0. Commercial use permitted with attribution.

---

**🎉 Ready to use!** Just one line of code to get accurate age and gender predictions from any facial image! 🚀

**Try it now:**
```python
from transformers import pipeline
result = pipeline("image-classification", model="abhilash88/age-gender-prediction", trust_remote_code=True)("your_image.jpg")
print(f"Age: {result[0]['age']}, Gender: {result[0]['gender']}")
```