ZSI Wildlife Identifier 🐾

A Flutter-based mobile application designed to identify endangered marine species with AI-powered image classification. The app uses an ensemble of PyTorch-trained deep learning models (EfficientNet-B0, ResNet-50, MobileNet-V3) trained on 66 CITES-protected marine species, enabling users to capture or upload photos and receive instant, highly accurate classifications to support conservation awareness and education.

Focus: 🌊 Marine Biodiversity | 🐋 CITES-Protected Species | 🇮🇳 Indo-Pacific Region

Status: ✅ Frontend Production-Ready | ✅ Backend Model v1 Deployed (98.47% accuracy) | ✅ Complete Species Database (66 marine species)

✨ Features

Core Identification Features

• 📸 AI-Powered Wildlife Identification: Capture photos with camera or upload from gallery for instant species classification
• 🎯 High Accuracy Models:
  • Primary Model: EfficientNet-B0 trained on 66 CITES-protected marine species with 98.47% accuracy
  • Ensemble Options: ResNet-50 + MobileNet-V3 ensemble with weighted voting for enhanced robustness
  • Auto-Fallback: Seamlessly switches between single model and ensemble based on availability
• 📊 Confidence Scoring: Real-time confidence levels for each prediction with visual indicators
• 🌍 Comprehensive Marine Species Coverage:
  • 66 endangered marine species including:
  • Sharks: Hammerheads, Thresher sharks, Requiem sharks
  • Rays & Guitarfish: Manta rays, Devil rays, Sawfish, Guitarfish
  • Other fish: Seahorses, Groupers, Snakeheads
  • Geographic focus: Indo-Pacific region
• ℹ️ Detailed Species Info: Conservation status, IUCN Red List links, scientific names, geographic distribution

User Features

• 🔐 Flexible Authentication:
  • Email & password registration/login
  • OTP-based phone verification
  • Guest mode for quick access
• 👤 User Profiles: Track identification history, earn badges, manage preferences
• 🏆 Achievement Badges: Unlock badges as you identify more species
• 💬 Community Comments: Share observations and insights on sightings
• 🔍 Advanced Filtering: Filter by confidence, date, location, habitat type
• 📋 Life Lists: Track unique species you've identified
• 💾 Offline Support: Works with cached data when network unavailable

Data & Analytics

• 📚 Species Database: Browse 66+ species with detailed conservation information
• 📈 Upload History: Track all identifications with timestamps and metadata
• 🗺️ Location-Based Features: Map-aware filtering and geographic insights

🚀 Getting Started

Prerequisites

Flutter Frontend

• Flutter SDK: Latest stable version (3.19+)
• Dart: 3.3+
• Platforms: Android 7.0+, iOS 11.0+, Web, Linux, Windows, macOS

Python Backend (Optional - for local inference)

• Python: 3.10+
• PyTorch: 2.10.0+ with CUDA support
• CUDA: 12.8+ (for GPU acceleration, optional)
• RAM: Minimum 4GB (8GB+ recommended)
• GPU: NVIDIA RTX 4060+ recommended for training

Verify Flutter:

flutter doctor

📥 Installation

Step 1: Clone the Repository

git clone https://github.com/Sym-jay/zsi_app.git
cd zsi_app

Step 2: Frontend Setup

cd Frontend/ZSI_Frontend

# Install dependencies
flutter pub get

# Run the app (choose platform)
flutter run -d linux          # Linux desktop
flutter run -d chrome         # Web browser
flutter run -d android        # Android emulator/device
flutter run -d ios            # iOS simulator/device

Step 3: Backend Setup (Optional - for API inference)

cd Backend/ZSI_Backend

# Create and activate virtual environment
python3 -m venv venv
source venv/bin/activate      # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Run API server
python3 api.py                # Starts Flask server on http://localhost:5000

🏗️ Building for Production

Android APK

cd Frontend/ZSI_Frontend
flutter build apk --release
# Output: build/app/outputs/flutter-apk/app-release.apk

Web Release

cd Frontend/ZSI_Frontend
flutter build web --release
# Output: build/web/

Desktop (Linux/Windows/macOS)

cd Frontend/ZSI_Frontend
flutter build windows    # Windows
flutter build macos      # macOS
flutter build linux      # Linux

🔄 Machine Learning Models

Model Architecture & Performance

Primary Model (Production)

• Name: EfficientNet-B0
• Accuracy: 98.47% on 66 CITES species
• Training Data: 621 base images × 150 augmentation = 99,150 samples
• Training Method:
  • 20 epochs with SGD optimizer
  • Learning rate: 0.001 with step decay
  • Batch size: 32
  • Mixed precision training for efficiency
• Status: ✅ Deployed and active in Flutter app

Ensemble Models (v3 - Recently Trained)

• Components:
  • EfficientNet-B0: 87.5% on validation set
  • ResNet-50: 85.0% on validation set
  • MobileNet-V3: 82.0% on validation set
  • Ensemble Voting: 88.5% combined accuracy
• Training Data: 127 images × 150 augmentation = 19,050 samples (7 species)
• Architecture: Weighted voting ensemble
  • EfficientNet-B0: 40% weight
  • ResNet-50: 35% weight
  • MobileNet-V3: 25% weight
• Status: ✅ Trained and ready for integration

Data Augmentation Strategy

Both models use the same augmentation pipeline:

• Rotation: ±45 degrees
• Flipping: Horizontal (70%), Vertical (20%)
• Translation: ±15%
• Scaling: 0.85-1.1x
• Color Jitter: ±20% brightness, contrast, saturation
• Perspective: 20% probability
• Gaussian Blur: Kernel 3×3

This aggressive augmentation ensures model robustness to:

• Different camera angles
• Varying lighting conditions
• Partial occlusions
• Background variations

Training Scripts

ensemble_trainer_simple.py

Main training script with full augmentation (150x per image):

cd Backend/ZSI_Backend
source venv/bin/activate
python ensemble_trainer_simple.py

Features:

• Automatic dataset extraction from zip
• 150x augmentation factor (matches production training)
• Trains 3 models: EfficientNet-B0, ResNet-50, MobileNet-V3
• Ensemble voting evaluation
• Saves results to ensemble_models/training_results_v3.json

api.py - Flask REST API

Provides endpoints for model inference:

# Start API server
python3 api.py

Available Endpoints:

1. Health Check

curl http://localhost:5000/health

2. Predict (Single Image)

curl -F "image=@path/to/image.jpg" http://localhost:5000/predict

Response:

{
  "species": "Bengal Tiger",
  "scientific_name": "Panthera tigris",
  "confidence": 0.9847,
  "top_5": [
    {"species": "Bengal Tiger", "confidence": 0.9847},
    {"species": "Siberian Tiger", "confidence": 0.0142}
  ]
}

3. Get Available Classes

curl http://localhost:5000/classes

Flutter Integration

The Flutter app automatically handles model loading:

lib/core/services/ai_service.dart:

// Automatically loads primary model
model = await _loadModel('assets/models/efficientnet_b0.tflite');

// Falls back to ensemble if available
ensembleModels = await _loadEnsembleModels([
  'assets/models/efficientnet_b0_v3.tflite',
  'assets/models/resnet50_v3.tflite',
  'assets/models/mobilenet_v3_v3.tflite'
]);

Inference:

// Single model prediction
var result = await _predictSingle(image);

// Ensemble voting (if available)
var ensembleResult = await _predictEnsemble(image);

📂 Project Structure

zsi_app/
├── Frontend/
│   └── ZSI_Frontend/                    # Flutter app
│       ├── lib/
│       │   ├── main.dart                # Entry point
│       │   ├── screens/                 # UI Screens
│       │   │   ├── identification_screen.dart
│       │   │   ├── browse_species_screen.dart
│       │   │   ├── home_screen.dart
│       │   │   ├── login_screen.dart
│       │   │   ├── splash_screen.dart
│       │   │   └── species_detail_screen.dart
│       │   ├── core/
│       │   │   ├── services/
│       │   │   │   ├── ai_service.dart              # ML inference
│       │   │   │   ├── auth_service.dart            # Authentication
│       │   │   │   ├── database_service.dart        # Persistence
│       │   │   │   ├── feedback_service.dart        # User feedback
│       │   │   │   └── animal_dataset.dart          # Species data
│       │   │   └── config/
│       │   │       ├── cache_config.dart
│       │   │       ├── error_handler.dart
│       │   │       └── image_compression.dart
│       │   ├── widgets/                 # Reusable components
│       │   ├── dialogs/                 # Dialog screens
│       │   ├── utils/                   # Utility functions
│       │   └── pubspec.yaml             # Dependencies
│       ├── assets/
│       │   ├── images/
│       │   └── models/                  # ML models
│       └── test/
├── Backend/
│   └── ZSI_Backend/                     # Python ML backend
│       ├── ensemble_models/             # Trained model weights
│       │   ├── model_efficientnet_b0.pth           # Primary (98.47%)
│       │   ├── model_efficientnet_b0_v3.pth        # v3 ensemble
│       │   ├── model_resnet50_v3.pth               # v3 ensemble
│       │   ├── model_mobilenet_v3_v3.pth           # v3 ensemble
│       │   ├── ensemble_config.json                # Voting config
│       │   └── training_results_v*.json            # Results
│       ├── ensemble_trainer_simple.py              # Main training script
│       ├── ensemble_trainer_augmented.py           # Augmented version
│       ├── train_ensemble_full.py                  # Full pipeline
│       ├── api.py                                  # Flask API
│       ├── requirements.txt                        # Python deps
│       ├── venv/                                   # Virtual env
│       ├── dataset_extracted/                      # Training data
│       └── ZSI_Backend/
│           └── venv/
├── Documentation/
│   ├── APP_FEATURE_AUDIT.md              # Complete feature inventory
│   ├── ENSEMBLE_TRAINING_COMPLETE.md     # Ensemble details
│   ├── PROGRESS_UPDATE.md                # Training progress
│   └── STATUS_REPORT.md                  # Executive summary
└── README.md                             # This file

📊 Performance Metrics

Model Accuracy

Model	Accuracy	Validation Set	Training Samples
EfficientNet-B0 (Production)	98.47%	66 species	99,150
EfficientNet-B0 (v3)	87.5%	7 species	19,050
ResNet-50 (v3)	85.0%	7 species	19,050
MobileNet-V3 (v3)	82.0%	7 species	19,050
Ensemble (v3)	88.5%	7 species	19,050

Inference Speed

Device	Model	Inference Time
NVIDIA RTX 4060 (GPU)	EfficientNet-B0	50-100ms
CPU (4-core)	EfficientNet-B0	500-1000ms
Mobile (Android Snapdragon)	EfficientNet-B0	200-400ms

App Size

• Flutter APK: ~50-100 MB (with embedded model)
• Model Size: ~16 MB per EfficientNet-B0, ~6 MB per MobileNet-V3, ~91 MB per ResNet-50
• Species Database: ~2 MB

🔄 Workflow & Development

Local Development

1. Work locally on your machine
2. Make commits to git
3. Push to master: git push -f origin master
4. GitHub serves as backup for solo development

Model Training Pipeline

1. Extract dataset: unzip zsi_dataset.zip
2. Configure training parameters in ensemble_trainer_simple.py
3. Run training: python ensemble_trainer_simple.py
4. Monitor progress: tail -f ensemble_training_augmented.log
5. Verify results in ensemble_models/training_results_v3.json
6. Integrate models into Flutter app
7. Commit and push

🤝 Contributing

Since you're the sole developer, the workflow is straightforward:

1. Make Changes: Edit code locally
2. Test: Run flutter test and verify on device
3. Commit: git commit -m "feat: description"
4. Push: git push -f origin master
5. Deploy: Build APK and distribute

🐛 Known Issues & Limitations

Current Limitations

• Ensemble models only trained on 7 species (limited dataset)
• User profiles and comments stored in-memory (not persistent)
• No push notifications
• No dark mode support
• Limited internationalization

Fixed Issues ✅

• ✅ 66% → 98.47% accuracy achieved
• ✅ VirtualEnv setup and dependencies
• ✅ GPU training pipeline
• ✅ Model export and conversion
• ✅ Flutter integration with local models
• ✅ Ensemble architecture implemented
• ✅ Data augmentation (150x) applied

📊 Project Status & Roadmap

Current Status (March 2026)

• Frontend: ✅ Production Ready

  • All 13 screens functional
  • 30+ features implemented
  • Clean architecture with proper state management
  • Ready for deployment

• Backend (Primary Model): ✅ Complete

  • 98.47% accuracy
  • 66 CITES species covered
  • Deployed in production

• Backend (Ensemble v3): ✅ Complete

  • 3-model ensemble trained
  • 88.5% ensemble accuracy
  • Ready for integration testing

Recent Achievements

• ✅ Comprehensive feature audit (13 screens, 30+ features)
• ✅ App launch checklist completed
• ✅ Ensemble model training pipeline
• ✅ 150x data augmentation implementation
• ✅ Multi-model training (EfficientNet, ResNet, MobileNet)
• ✅ Ensemble voting implementation

Upcoming (Post-Deployment)

• Integrate v3 ensemble models into Flutter app
• A/B test single vs ensemble models
• Implement user feedback-based fine-tuning
• Add push notifications
• Persistent user profile storage
• Dark mode support
• Internationalization (i18n)

📞 Support & Contact

• Repository: https://github.com/Sym-jay/zsi_app
• Issues: Use GitHub Issues for bug reports
• Documentation: See Documentation/ folder for detailed guides

📜 License

Distributed under the MIT License. See LICENSE for more information.

---

Last Updated: March 20, 2026
Contributors: Sym-jay
Status: Active Development