🐄 Indian Cattle Breed Classifier

A modern, AI-powered web application for classifying Indian cattle and buffalo breeds using deep learning. Built with FastAPI, TensorFlow, React, and MongoDB, featuring incremental learning and real-time analytics.

✨ Features

🤖 AI-Powered Classification

• 29 Indian cattle and buffalo breeds supported
• EfficientNet-B0 transfer learning model
• Grad-CAM visualization showing AI attention areas
• Real-time prediction with confidence scores
• Top-3 predictions with detailed breed information

📈 Incremental Learning

• Continuous model improvement through user feedback
• Automatic retraining with new data
• Background processing for model updates
• Performance tracking and accuracy monitoring

🎨 Modern Web Interface

• React + TypeScript frontend
• Tailwind CSS for beautiful, responsive design
• PWA support for mobile devices
• Real-time analytics dashboard
• Drag & drop image upload
• URL-based image processing

📊 Analytics & Monitoring

• Real-time statistics and performance metrics
• Breed distribution analysis
• Accuracy trends over time
• User feedback tracking
• Admin dashboard for system management

🚀 Quick Start

Prerequisites

• Python 3.9+
• Node.js 18+
• MongoDB
• Docker (optional)

Installation

1. Clone the repository

   git clone https://github.com/yourusername/cattle-breed-classifier.git
   cd cattle-breed-classifier

2. Install Python dependencies

   pip install -r requirements.txt

3. Install frontend dependencies

   cd frontend
   npm install
   cd ..

4. Set up environment variables

   cp .env.example .env
   # Edit .env with your configuration

5. Start MongoDB

   # Using Docker
   docker run -d -p 27017:27017 --name mongodb mongo:6.0
   
   # Or install MongoDB locally
   # Follow MongoDB installation guide for your OS

6. Run the application

   # Start backend
   python -m uvicorn backend.main:app --reload --port 8000
   
   # In another terminal, start frontend
   cd frontend
   npm run dev

7. Access the application

   • Frontend: http://localhost:3000
   • Backend API: http://localhost:8000
   • API Documentation: http://localhost:8000/docs

🐳 Docker Deployment

Using Docker Compose (Recommended)

1. Start all services

   docker-compose up -d

2. Access the application

   • Application: http://localhost
   • MongoDB: localhost:27017

Using Docker

1. Build the image

   docker build -t cattle-classifier .

2. Run the container

   docker run -p 8000:8000 -e MONGODB_URL=mongodb://host.docker.internal:27017 cattle-classifier

🏗️ Architecture

Backend (FastAPI + TensorFlow)

• FastAPI for high-performance API
• TensorFlow 2.x for deep learning
• MongoDB for data storage
• Motor for async MongoDB operations
• Pydantic for data validation

Frontend (React + TypeScript)

• React 18 with hooks and context
• TypeScript for type safety
• Tailwind CSS for styling
• React Query for data fetching
• Framer Motion for animations

Database Schema

// Images collection
{
  _id: ObjectId,
  image_path: String,
  predicted_breed: String,
  corrected_breed: String,
  confidence: Number,
  is_reviewed: Boolean,
  timestamp: Date,
  grad_cam_heatmap: String
}

// Metrics collection
{
  _id: ObjectId,
  metric_type: String,
  timestamp: Date,
  accuracy: Number,
  progress: Number
}

🎯 API Endpoints

Prediction

• POST /api/predict - Upload image or URL for breed prediction
• GET /api/breeds - Get list of supported breeds
• GET /api/breed/{name} - Get detailed breed information

Feedback

• POST /api/feedback - Submit prediction feedback
• GET /api/feedback/pending - Get pending reviews
• GET /api/feedback/stats - Get feedback statistics

Analytics

• GET /api/stats - Get system statistics
• GET /api/stats/trends - Get accuracy trends
• GET /api/stats/breed-distribution - Get breed distribution

Admin

• POST /api/admin/retrain - Start model retraining
• GET /api/admin/retrain/status - Get retraining status
• GET /api/admin/dashboard - Get admin dashboard data

🧠 Model Training

Initial Training

python train.py --data_dir /path/to/training/data --epochs 50 --fine_tune_epochs 20

Supported Breeds

• Cows: Gir, Sahiwal, Red Sindhi, Tharparkar, Kankrej, Ongole, Rathi, Deoni, Dangi, Hallikar, Amritmahal, Bargur, Kangayam, Kasaragod, Kenkatha, Kherigarh, Malnad Gidda, Nagori, Nimari, Pulikulam, Umblachery, Alambadi
• Buffaloes: Murrah, Jaffarabadi, Mehsana, Nili Ravi, Nagpuri, Banni, Shurti

Model Architecture

• Base Model: EfficientNet-B0 (ImageNet pretrained)
• Input Size: 224x224x3
• Output: 29 classes (softmax)
• Optimizer: Adam
• Loss: Categorical Crossentropy

📱 PWA Features

• Offline support with service worker
• Installable on mobile devices
• Push notifications for retraining completion
• Background sync for feedback submission

🔧 Configuration

Environment Variables

MONGODB_URL=mongodb://localhost:27017
REDIS_URL=redis://localhost:6379
PORT=8000
PYTHONPATH=/app

Model Configuration

• Image preprocessing: Resize to 224x224, normalize
• Data augmentation: Rotation, flip, zoom, shear
• Transfer learning: EfficientNet-B0 → Custom head
• Fine-tuning: Unfreeze top layers, lower learning rate

📊 Performance Metrics

• Model Accuracy: 85-95% (varies by breed)
• Inference Time: <2 seconds per image
• Top-3 Accuracy: 95-98%
• Model Size: ~50MB (TFLite: ~15MB)

🚀 Deployment

Render (Recommended)

1. Connect GitHub repository
2. Set environment variables
3. Deploy automatically

Heroku

1. Create Heroku app
2. Add MongoDB addon
3. Deploy using Procfile

Google Cloud Run

1. Build and push Docker image
2. Deploy to Cloud Run
3. Configure MongoDB Atlas

AWS/GCP/Azure

• Use container services (ECS, GKE, AKS)
• Configure load balancers
• Set up managed databases

🤝 Contributing

1. Fork the repository
2. Create feature branch (git checkout -b feature/amazing-feature)
3. Commit changes (git commit -m 'Add amazing feature')
4. Push to branch (git push origin feature/amazing-feature)
5. Open Pull Request

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• TensorFlow Team for the deep learning framework
• FastAPI Team for the excellent web framework
• React Team for the frontend library
• Indian Agriculture Community for breed information
• Open Source Community for various libraries and tools

📞 Support

• Documentation: Wiki
• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Email: support@cattleclassifier.com

🔮 Roadmap

• Mobile app (React Native)
• Multi-language support
• Advanced analytics
• Integration with veterinary databases
• Real-time video classification
• Blockchain-based breed certification
• IoT sensor integration
• AR/VR visualization

---

Made with ❤️ for Indian Agriculture