aicropdiseases / README.md

Vivek Vishwakarma

Update README.md

a9c42b1 verified 5 months ago

14.1 kB

	# 🌱 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!