Canine Intelligence (Dog Classifier)

Canine Intelligence is an advanced computer vision application that detects dogs in photos or via webcam, accurately classifies them into one of 133 distinct breeds, and estimates four facial-expression categories.

Under the hood, it orchestrates multiple AI models: YOLOv8 precisely locates up to five dogs in a single frame, while MobileNetV2 and EfficientNetB3 seamlessly analyze each cropped image to deliver accurate breed and expression insights.

Disclaimer: The expression output is a visual pattern estimate. It is not a veterinary, behavioral, or medical assessment of a dog's actual emotional state.

Highlights & Features

• Real-time & Static Analysis: Supports both direct photo uploads and live webcam capture.
• Multi-Dog Detection: Automatically detects up to 5 dogs per image, drawing precise bounding boxes around each result.
• Smart Predictions: Provides the top-three breed candidates for every dog, complete with low-certainty indicators for ambiguous images.
• Expression Analysis: Evaluates four facial expression scores based on deep learning visual patterns.
• Optimized Performance: Features sequential webcam polling to ensure expensive inference requests never overlap or crash the browser.
• Secure Image Processing: In-memory image processing with strict format, byte-size, and pixel-count validation to prevent malicious payloads.
• Robust API: Local model readiness endpoint available at GET /health.
• Accessible UI: Includes modal controls, clear status messages, and keyboard dismissal for an excellent user experience.

Architecture

The system uses a sequential pipeline of highly optimized neural networks to process incoming images:

JPG / PNG / WEBP
        |
        v
YOLOv8n Dog Detector (COCO class 16, max 5 dogs)
        |
        +-------------------------+
        |                         |
        v                         v
MobileNetV2                  EfficientNetB3
133 breed classes           4 expression classes
        |                         |
        +------------+------------+
                     v
          Per-dog JSON + uncertainty

Local Setup

Use Python 3.11 to ensure full compatibility with the pinned portfolio environment.

1. Clone the repository:

   git clone https://github.com/LaboNapitupulu/Dog_Classifier.git
   cd Dog_Classifier

2. Initialize Environment:

   python -m venv .venv
   .\.venv\Scripts\Activate.ps1
   python -m pip install --upgrade pip
   pip install -r requirements.txt

   (Note: The runtime requirements are intentionally kept separate from notebook-only packages. Install the optional training environment using requirements-training.txt only when retraining or evaluating models).

3. Add Model Weights: Ensure you place the trained .h5 and .pt model weights in the required directories:

   models/
   ├── best_dog_breed_model.h5
   └── best_dog_emotion_model.h5
   
   yolov8n.pt
   

   These heavy files are intentionally ignored by Git. See models/README.md for details.

4. Run Validation and Start the App:

   python scripts/validate_label_order.py
   python -m unittest discover -s tests -v
   python app.py

   Open http://127.0.0.1:5000 in your browser. Model readiness can be checked at http://127.0.0.1:5000/health.

5. Debug Mode: Debug mode is disabled by default. For local debugging only:

   $env:DOG_CLASSIFIER_DEBUG='true'
   python app.py

API Contract

The core inference endpoint is available at POST /predict. It expects a multipart form field named file. A successful response stores predictions inside the results array, which includes:

• Detector, breed, and expression probability scores.
• breed_uncertain and emotion_uncertain flags.
• The three highest-scoring breed candidates.
• The exact bounding box coordinates for each detected dog.

⚠️ Security Note: Images are strictly limited to 16 MB and 25 million decoded pixels. Supported formats are JPG, PNG, and WEBP.

Model Evaluation Status

The repository does not currently claim production-grade accuracy out-of-the-box. The available breed training log is a validation log rather than an independent benchmark, and the emotion notebook evaluates the same validation split used during model selection.

Before publishing accuracy or macro-F1 figures, we recommend the following:

1. Retrain with reproducible train/validation/test manifests.
2. Keep the test set strictly isolated from model and threshold selection.
3. Report per-class precision, recall, F1, confusion matrices, and data counts.
4. Check for duplicate images and ensure images of the same dog/source appear in only one split.
5. Evaluate against mixed breeds, difficult lighting, pose changes, and out-of-domain photos; calibrate uncertainty thresholds from validation data only.

Note: The local emotion dataset is naturally imbalanced, making macro-F1 and per-class recall more informative than accuracy alone. The existing .h5 models are perfect for portfolio demonstrations but should be retrained before presenting independent test metrics.

Project Structure

Dog_Classifier/
├── app.py                  # Main Flask application
├── src/
│   ├── inference.py        # Model loading & prediction logic
│   └── breeds.py           # 133 breed class definitions
├── static/                 # CSS, JS, and static assets
├── templates/              # HTML views
├── tests/                  # Unit tests
├── scripts/
│   └── validate_label_order.py
├── notebooks/              # Jupyter notebooks for training
├── models/                 # Local .h5 model files (ignored by Git)
└── data/                   # Local datasets (ignored by Git)

License

MIT