README.md

# 🌱 Crop Disease Detection AI

[![Python](https://img.shields.io/badge/Python-3.8%2B-blue.svg)](https://python.org)
[![PyTorch](https://img.shields.io/badge/PyTorch-2.1.0-red.svg)](https://pytorch.org)
[![Streamlit](https://img.shields.io/badge/Streamlit-1.28.0-red.svg)](https://streamlit.io)
[![Hugging Face Spaces](https://img.shields.io/badge/🤗%20Hugging%20Face-Spaces-blue)](https://huggingface.co/spaces)
[![License](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

An AI-powered crop disease detection system using deep learning to identify diseases in pepper, potato, and tomato crops from leaf images. The system provides accurate disease classification, risk assessment, visual explanations, and treatment recommendations.

> **🚀 Now Ready for Deployment**: This project is optimized for Hugging Face Spaces deployment with Streamlit and Docker. All components have been tested and verified for production use.

## 🎯 Project Overview

This project implements a comprehensive crop disease detection pipeline that:
- **Detects 15 different diseases** across pepper, potato, and tomato crops
- **Provides visual explanations** using Grad-CAM heatmaps
- **Offers treatment recommendations** from an integrated knowledge base
- **Calculates risk levels** based on confidence and environmental factors
- **Supports multiple interfaces**: Streamlit web app, CLI tool, and training notebooks
- **🚀 Deployment Ready**: Optimized for Hugging Face Spaces with Docker support

### 🏆 Key Features

- **🤖 AI Model**: ResNet50-based transfer learning with 26.1M parameters
- **📊 Disease Classes**: 17 classes including healthy variants for each crop
- **🎨 Visual Explanations**: Grad-CAM heatmaps highlighting infected regions
- **📚 Knowledge Base**: Comprehensive disease information with symptoms and treatments
- **⚡ Real-time Processing**: Fast inference with GPU/CPU support
- **🌐 Web App**: Streamlit interface optimized for Hugging Face Spaces
- **🖥️ CLI Tool**: Command-line interface for batch processing
- **� Training Pipeline**: Complete model training and evaluation system

## 📁 Project Structure

```
AiCropDiseasesDetection/
├── 📂 api/                     # FastAPI backend
│   ├── main.py                 # API server with endpoints
│   ├── requirements.txt        # API dependencies
│   └── __init__.py             # Package marker
├── 📂 data/                    # Dataset (train/val/test splits)
│   ├── train/                 # Training images
│   ├── val/                   # Validation images
│   └── test/                  # Test images
├── 📂 knowledge_base/          # Disease information
│   └── disease_info.json      # Symptoms, treatments, prevention
├── 📂 models/                  # Trained model weights
│   ├── crop_disease_v3_model.pth      # Latest V3 model (recommended)
│   └── README.txt              # Model information
├── 📂 notebooks/               # Jupyter notebooks
│   └── train_resnet50.ipynb   # Training notebook
├── 📂 outputs/                 # Results and visualizations
│   ├── heatmaps/              # Grad-CAM visualizations
│   └── *.json                 # Evaluation results
├── 📂 src/                     # Core source code
│   ├── dataset.py             # Data loading and preprocessing
│   ├── model.py               # ResNet50 architecture
│   ├── train.py               # Training pipeline
│   ├── evaluate.py            # Model evaluation
│   ├── explain.py             # Grad-CAM explanations
│   ├── risk_level.py          # Risk assessment logic
│   └── predict_cli.py         # CLI predictor
├── 📂 tests/                   # Unit tests
├── crop_disease_gui.py         # Tkinter GUI application
├── requirements.txt            # Main dependencies
└── TRAINING_REPORT.md          # Performance analysis
```

## 🛠️ Technology Stack

### Core Technologies
- **Deep Learning**: PyTorch 2.1.0, torchvision 0.16.0
- **Model Architecture**: ResNet50 with transfer learning
- **Web Framework**: Streamlit 1.28.0+
- **Computer Vision**: OpenCV, PIL/Pillow
- **Visualization**: Grad-CAM, matplotlib

### Dependencies
- **Core ML**: PyTorch, torchvision, numpy
- **Image Processing**: OpenCV-Python, Pillow
- **Web Interface**: Streamlit
- **Visualization**: matplotlib, grad-cam
- **Utilities**: requests, tqdm, pydantic

### Development Tools
- **Environment**: Python 3.9+ (Docker: python:3.9-slim)
- **Notebooks**: Jupyter/Google Colab support
- **Deployment**: Docker + Hugging Face Spaces
- **Version Control**: Git
- **Local Development**: Optimized for Windows PowerShell

## 🚀 Installation & Setup

### Prerequisites
- Python 3.8 or higher
- pip package manager
- (Optional) CUDA-compatible GPU for faster training

### 1. Clone Repository
```bash
git clone https://github.com/vivek12coder/AiCropDiseasesDetection.git
cd AiCropDiseasesDetection
```

### 2. Create Virtual Environment
```powershell
# Windows PowerShell (recommended)
python -m venv .venv
.\.venv\Scripts\Activate.ps1

# Alternative for Command Prompt
python -m venv .venv
.venv\Scripts\activate.bat

# macOS/Linux
python -m venv .venv
source .venv/bin/activate
```

### 3. Install Dependencies
```powershell
# Install main dependencies
pip install -r requirements.txt

# For API development (optional)
pip install -r api/requirements.txt
```

### 4. Pre-trained Model
The repository includes the latest pre-trained model:
- `models/crop_disease_v3_model.pth` - Latest V3 model (recommended)

> **Note**: Older model versions have been removed to keep the project clean. Only the latest, best-performing model is included.

### 5. Verify Installation
```bash
python -c "import torch; print(f'PyTorch: {torch.__version__}')"
python -c "import torchvision; print(f'TorchVision: {torchvision.__version__}')"
```

## 📖 Usage Guide

### 🌐 Streamlit Web App (Recommended)

The easiest way to use the system:

```powershell
streamlit run app.py
```

**Features:**
- � **Image Upload**: Drag & drop or browse for crop leaf images
- 🔍 **AI Analysis**: One-click disease detection with confidence scores
- 📊 **Visual Explanations**: Grad-CAM heatmaps showing AI focus areas
- 📚 **Disease Information**: Detailed symptoms, treatments, and prevention
- 🎯 **Risk Assessment**: Environmental risk level calculation
- ⚙️ **Settings**: Customizable analysis options

**Supported Image Formats**: JPG, JPEG, PNG, BMP

### 📊 Model Training & Evaluation

Train and evaluate your own model with custom data:

```powershell
# Evaluate existing model
python -m src.evaluate

# Train new model
python -m src.train

# Generate visual explanations
python -m src.explain
```

### 🔍 CLI Prediction Tool

Quick single-image prediction via command line:

```powershell
# Predict disease for a single image
python -m src.predict_cli -i test_leaf_sample.jpg -m models\crop_disease_v3_model.pth

# With custom class names file
python -m src.predict_cli -i your_image.jpg --classes custom_classes.json
```

### 🔬 Jupyter Notebooks

Explore the training process interactively:

```powershell
jupyter notebook notebooks/train_resnet50.ipynb
```

## 💡 Usage Examples

### Python Usage Example

```python
# For programmatic use
import sys
sys.path.append('src')

from src.model import CropDiseaseResNet50
from src.dataset import preprocess_image
import torch
from PIL import Image

# Load model
model = CropDiseaseResNet50(num_classes=15)
checkpoint = torch.load('models/crop_disease_v3_model.pth', map_location='cpu')
model.load_state_dict(checkpoint)
model.eval()

# Make prediction
image = Image.open('your_leaf_image.jpg')
input_tensor = preprocess_image(image)
with torch.no_grad():
    prediction = model(input_tensor)
    confidence = torch.softmax(prediction, dim=1).max().item()
    
print(f"Prediction confidence: {confidence:.2%}")
```

### Command Line Usage

```powershell
# Evaluate model performance
python -m src.evaluate

# Single image CLI prediction
python -m src.predict_cli -i test_leaf_sample.jpg -m models\crop_disease_v3_model.pth
```

### GUI Application Workflow

1. **Launch Application**: `python crop_disease_gui.py`
2. **Upload Image**: Click "📁 Select Image" button
3. **Analyze**: Click "🔍 Analyze Disease" button
4. **View Results**: See detailed analysis in results panel

## 🎯 Model Performance

### Current Performance (V3 Model)
- **Model Architecture**: ResNet50 with custom classifier layers
- **Parameters**: 26.1M total parameters
- **Input Size**: 224x224 RGB images
- **Classes**: 15 disease classes across 3 crops
- **Inference Speed**: ~0.1 seconds per image on CPU

### Supported Disease Classes

**Pepper Diseases:**
- Bell Pepper Bacterial Spot
- Bell Pepper Healthy

**Potato Diseases:**
- Early Blight
- Late Blight
- Healthy

**Tomato Diseases:**
- Target Spot
- Tomato Mosaic Virus
- Tomato Yellow Leaf Curl Virus
- Bacterial Spot
- Early Blight
- Late Blight
- Leaf Mold
- Septoria Leaf Spot
- Spider Mites (Two-spotted)
- Healthy

> **Note**: The model has been trained on limited data. For production use, consider collecting more training samples per class.

## 🔧 Configuration

### Environment Variables
```powershell
# Optional: Set device preference
$env:TORCH_DEVICE="cuda"  # or 'cpu'

# Optional: Set model path
$env:MODEL_PATH="models/crop_disease_v3_model.pth"
```

### API Configuration
Edit `api/main.py` for production settings:
- CORS origins
- Authentication
- Rate limiting
- Logging levels

## 🚀 Deployment

### 🤗 Hugging Face Spaces (Recommended)

The project is ready for one-click deployment on Hugging Face Spaces:

1. **Fork/Clone** this repository
2. **Create a new Space** on [Hugging Face Spaces](https://huggingface.co/spaces)
3. **Select "Docker" SDK** when creating the Space
4. **Upload the project files** or connect your Git repository
5. **Wait for build** (5-10 minutes) and your app will be live!

**📖 Detailed Instructions**: See [DEPLOY_INSTRUCTIONS.md](DEPLOY_INSTRUCTIONS.md)

### 🖥️ Local Streamlit App

```powershell
# Install dependencies
pip install -r requirements.txt

# Run Streamlit app
streamlit run app.py

# Open browser to: http://localhost:8501
```

### 🐳 Docker Deployment

```powershell
# Build image
docker build -t crop-disease-ai .

# Run container
docker run -p 7860:7860 crop-disease-ai

# Open browser to: http://localhost:7860
```

### Local Development
```powershell
# GUI Application
python crop_disease_gui.py

# API Server
python -m api.main

# CLI Prediction
python -m src.predict_cli -i test_leaf_sample.jpg
```

### Local (Non-Docker) Quick Start

Use these steps on Windows PowerShell to run locally without Docker:

```powershell
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
# Optional: API extras
pip install -r api/requirements.txt

# Evaluate model
python -m src.evaluate

# Run API
python -m api.main

# Single-image CLI prediction
python -m src.predict_cli -i test_leaf_sample.jpg -m models\crop_disease_v3_model.pth
```

### Cloud Deployment
The API is ready for deployment on:
- **AWS**: EC2, Lambda, ECS
- **Google Cloud**: Cloud Run, Compute Engine
- **Azure**: Container Instances, App Service
- **Heroku**: Container deployment

## 🤝 Contributing

### Development Setup
1. Fork the repository
2. Create feature branch: `git checkout -b feature/new-feature`
3. Make changes and test thoroughly
4. Submit pull request with detailed description

### Contribution Guidelines
- Follow PEP 8 style guidelines
- Add unit tests for new features
- Update documentation for API changes
- Ensure backward compatibility

### Areas for Contribution
- **Data Collection**: Expand disease image dataset
- **Model Improvements**: Experiment with new architectures
- **Feature Enhancement**: Add new crops/diseases
- **Performance Optimization**: Speed and accuracy improvements
- **Documentation**: Tutorials and examples

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 👥 Authors & Acknowledgments

**Project Team:**
- **Lead Developer**: [Your Name]
- **AI/ML Engineer**: [Team Member]
- **Data Scientist**: [Team Member]

**Acknowledgments:**
- PlantVillage dataset for training data
- PyTorch team for deep learning framework
- FastAPI team for web framework
- Open source community for various tools

## 📞 Support & Contact

### Getting Help
- **Documentation**: Check this README and code comments
- **Issues**: Create GitHub issue for bugs/feature requests
- **Discussions**: Use GitHub discussions for questions

### Contact Information
- **GitHub Repository**: https://github.com/vivek12coder/AiCropDiseasesDetection
- **Issues**: Create GitHub issue for bugs/feature requests
- **Project Owner**: @vivek12coder

## 🔮 Future Roadmap

### Phase 1: Data Enhancement (Weeks 1-2)
- [ ] Collect 1000+ images per disease class
- [ ] Implement advanced data augmentation
- [ ] Create balanced train/val/test splits

### Phase 2: Model Optimization (Weeks 3-4)
- [ ] Experiment with EfficientNet, MobileNet
- [ ] Implement ensemble methods
- [ ] Add uncertainty estimation

### Phase 3: Feature Expansion (Weeks 5-6)
- [ ] Add more crop types (rice, wheat, etc.)
- [ ] Implement real-time video processing
- [ ] Mobile app development

### Phase 4: Production Enhancement (Weeks 7-8)
- [ ] Cloud deployment with auto-scaling
- [ ] Monitoring and logging system
- [ ] User analytics and feedback system

---

## 📊 Quick Start Checklist

- [ ] Install Python 3.8+
- [ ] Clone repository
- [ ] Install dependencies: `pip install -r requirements.txt`
- [ ] Test GUI: `python crop_disease_gui.py`
- [ ] Test API: `python -m api.main`
- [ ] Test CLI: `python -m src.predict_cli -i test_leaf_sample.jpg`
- [ ] Upload test image and verify results
- [ ] Explore API documentation at http://127.0.0.1:8000/docs

**🎉 Ready to detect crop diseases with AI!**