okediran/poultrycheck-dinov2

Hugging Face

Search models, datasets, users... Ctrl K Models Datasets Spaces Buckets Docs Enterprise Pricing

okediran / poultrycheck-dinov2

Liked 1 Image Classification ONNX computer-vision agriculture poultry livestock animal-health dinov2 Model card Files and versions xet Community Settings poultrycheck-dinov2 / READ.MD

okediran Create READ.MD 4cfa4c7 VERIFIED about 13 hours ago

Download Raw History Blame Edit Delete 22.1 kB

license: cc-by-4.0 library_name: onnx pipeline_tag: image-classification language: - en tags: - poultry - livestock - animal-health - precision-livestock-farming - computer-vision - image-classification - dinov2 - onnx - nigeria - agritech - experimental

🐔 PoultryCheck

An Experimental Computer-Vision Screening Model for Poultry-Dropping Images

DINOv2 Small · ONNX · CPU-ready · Leakage-aware evaluation

Developed by Tope Emmanuel Okediran

---

⚠️ Important notice. PoultryCheck is an experimental research screening aid. It is not a veterinary diagnostic tool, has not been clinically validated, and does not identify specific diseases. Its output must never replace examination by a veterinarian or an experienced animal-health professional.

---

📑 Table of Contents

1. Overview
2. Headline Results
3. Why This Project Matters
4. Aim, Objectives and Scope
5. Dataset
6. Preprocessing and Duplicate Handling
7. Evaluation Design and Leakage Controls
8. Model Candidates and Selection
9. Augmentation and Training
10. Grouped Held-Out Evaluation
11. Decision Thresholds and the Uncertain Output
12. Final Training and ONNX Export
13. Quick Start
14. Limitations and Responsible Use
15. Proposed Next Research Phase
16. Reproducibility
17. Citation and Attribution

---

🔬 Overview

PoultryCheck investigates a focused question:

Can a deep-learning image classifier distinguish photographs of poultry droppings labelled Healthy and Unhealthy, and can the resulting model be packaged for practical, lightweight inference?

The project delivers an end-to-end pipeline:

Stage	What was done
🧹 Data preparation	Image decoding checks, SHA-256 exact-duplicate removal, cross-label conflict removal
🛡️ Leakage control	Photo-number block grouping and held-out photo-number ranges
🏁 Benchmarking	Five architectures compared on unseen photo-number ranges
🎨 Augmentation study	Standard vs. strong recipes, three seeds each
🎯 Thresholding	Balanced (0.50) and sensitive (0.30) thresholds plus an Uncertain band
📦 Deployment	ONNX export (opset 17), PyTorch↔ONNX parity check, backend-ready adapter

The model outputs a continuous score, p_unhealthy, and a decision label: Healthy, Unhealthy, or Uncertain.

---

🏆 Headline Results

Evaluation	Result
Grouped held-out test (1,983 images)	98.59 % accuracy · AUC 0.9984 · Macro-F1 0.9859
Cross-session test (3 seeds, mean ± SD)	83.06 % ± 4.21 pp accuracy
ONNX parity (64 images)	Max absolute difference 0.00002; 64/64 classes identical
Model size	≈ 86.6 MB
CPU latency (notebook environment)	≈ 45 ms / image

🧭 How to read these numbers

The two accuracy figures are not contradictory. They come from different split designs and answer different questions:

• Grouped split (98.59 %) – keeps blocks of consecutive photo numbers together, so near-duplicate neighbours do not leak across train and test.
• Cross-session split (83.06 %) – evaluates on entirely separate photo-number ranges, a stricter stand-in for "a different day or session".

The gap between them is itself a key finding: split design matters, and the more demanding evaluation is the more cautious guide to real-world expectations. We report both openly.

---

🌍 Why This Project Matters

Timely observation of flock condition is central to poultry production. Droppings are one visible indicator that farmers and animal-health professionals may inspect as part of broader flock monitoring. Their appearance can vary for many reasons, so a photograph alone cannot establish a diagnosis.

PoultryCheck explores whether accessible computer-vision tools could provide an additional screening signal to support observation and decision-making, particularly where routine monitoring resources are constrained.

It makes no claim that dropping appearance alone is sufficient to determine the health of a bird or flock, and it does not identify pathogens, specific diseases or treatments.

---

🎯 Aim, Objectives and Scope

Aim

To develop and evaluate an experimental deep-learning pipeline for screening poultry-dropping photographs as Healthy or Unhealthy, and to export the selected model in a format suitable for backend deployment.

Objectives

• Prepare the labelled dataset via decoding, exact-content hashing, cross-label ambiguity removal and duplicate removal.
• Reduce evaluation leakage using photo-number block grouping and held-out photo-number ranges.
• Benchmark several architectures on unseen photo-number ranges.
• Compare standard and strong augmentation over multiple seeds.
• Report class-sensitive metrics on a grouped held-out test split.
• Select balanced and sensitive thresholds with a separate Uncertain band.
• Train a final model, export to ONNX and verify numerical agreement.
• Package the model, metadata, preprocessing adapter and requirements for reproducible inference.

Scope boundaries

✅ In scope: image-level binary screening.

❌ Not implemented: disease-specific classification, flock-level diagnosis, bird identification, longitudinal tracking, treatment recommendations, or multimodal fusion with behaviour, feed, environment or production records. These are future directions, not demonstrated capabilities.

---

🗂️ Dataset

Source: Poultry Birds Poo Imagery Dataset for Health Status Prediction: A Case of South-West Nigeria

Field	Detail
Contributors	Segun Adebayo, Halleluyah Aworinde, Akinwale Akinwunmi, Olufemi Alabi, Adebamiji Ayandiji, Aderonke Sakpere
Institution	Bowen University
Published	29 May 2023 (Version 1)
DOI	10.17632/8pnbzpt2k9.1
Link	data.mendeley.com/datasets/8pnbzpt2k9/1
Licence	CC BY 4.0
Content	Chicken dropping images from poultry farms rearing broilers and layers in Nigeria
Original format	14,618 labelled JPEG images, 100 × 100 pixels, in Healthy and Non-healthy folders
Capture times	Morning, afternoon, night and others
Collection method	13-megapixel mobile device connected to the Edge Impulse platform
Collectors	Researchers and poultry farmers
Quality check	Performed by an Animal Scientist
Collection period	February – April 2023 (three months)
Locations	Poultry farms on Bowen University campus and in the Iwo region

Cleaning pipeline

Dataset stage	Healthy	Unhealthy	Total
Initial files	7,991	6,627	14,618
Clean unique images	7,125	6,619	13,744

• ✔ No unreadable images were found.
• ✂ 14 files whose exact content appeared under both labels were removed (conflicting labels).
• ✂ 860 exact duplicate copies within retained labels were removed (one copy kept per hash).

Note: these are image counts, not counts of individual birds, farms, flocks or independent clinical cases. Farm identifiers, per-image collection dates and the number of assessors are not available to this project and should not be inferred.

---

🖼️ Preprocessing and Duplicate Handling

A single preprocessing adapter is used for both data preparation and deployment:

1. Apply EXIF orientation correction
2. Convert to RGB
3. Resize to 224 × 224 (bilinear, no cropping)
4. Convert to contiguous float32, NCHW, shape 1 × 3 × 224 × 224
5. Pass pixel values in the 0–255 range — normalisation is embedded in the ONNX graph, so no second external normalisation is applied

Duplicate detection uses SHA-256 hashes of original file bytes. This removes byte-identical files but cannot detect visually similar images that were resized, recompressed or cropped. Photo-number block grouping provides an additional (heuristic) safeguard.

---

🛡️ Evaluation Design and Leakage Controls

Photographs taken seconds apart can be near-duplicates. Random splitting would let such neighbours land in both training and test sets and overstate performance. PoultryCheck therefore uses two filename-based designs.

1️⃣ Cross-session photo-number-range split

Per class, images are ordered by photo number: the earlier 70 % of the range trains, the next 15 % validates, and the final 15 % tests, with a gap of BLOCK_SIZE photo numbers at boundaries. This acts as a stand-in for a different day or session. It is more demanding than random splitting, but filename ranges cannot guarantee different farms, dates or sessions.

2️⃣ Grouped split

A group is defined as class label + (photo number ÷ BLOCK_SIZE). All images in a group go to one split. Zero groups span more than one split.

Grouped split	Healthy	Unhealthy	Total
Train	4,991	4,646	9,637
Validation	1,092	1,032	2,124
Test	1,042	941	1,983

This reduces leakage from defined photo-number blocks but does not prove farm-level independence.

Final model training split

The final model uses ≈ 92 % of images for training and ≈ 8 % as a monitoring subset. It has no untouched test set; its performance should be represented by the earlier held-out evaluations, not by the near-perfect monitoring metrics seen during final training.

---

🧪 Model Candidates and Selection

Five architectures were benchmarked on the cross-session split: MobileNetV2, EfficientNetV2-S, ConvNeXt-Tiny, DINOv2 Small, and YOLO26 classification.

Selection used the average of validation AUC and test AUC across two unseen photo-number ranges (rankings shifted between ranges, so no single range decided the outcome), with an approximate deployable-size limit and a preference for the smaller model within a tie margin. YOLO was benchmarked but excluded from selection by configuration.

Candidate	Test accuracy	Test AUC	Healthy recall	Unhealthy recall
🥇 DINOv2 Small	0.8550	0.8997	0.9298	0.7744
YOLO26m-cls	0.7881	0.8709	0.7446	0.8348
ConvNeXt Tiny	0.8147	0.7799	0.9822	0.6344
EfficientNetV2	0.7051	0.7387	0.7240	0.6848
MobileNetV2	0.5761	0.7086	0.3873	0.7795

Selected: vit_small_patch14_dinov2.lvd142m with the standard augmentation recipe.

These are cross-session results on this dataset and split design — not external-farm performance.

---

🎨 Augmentation and Training

Preprocessed images are cached as uint8 tensors, and augmentation runs on the GPU:

Recipe	Transformations
Standard (selected)	Mild flips, rotation, scale/zoom, translation, brightness and contrast
Strong	Larger geometric changes plus saturation, channel gain and low-level noise

Stronger augmentation was treated as an empirical question, since heavy colour changes might obscure colour cues in droppings.

Recipe	Mean cross-session test accuracy	SD
Standard ✅	0.8306	0.0421
Strong	0.7713	0.1061

Standard per-seed accuracies: 0.8598, 0.7823, 0.8497.

Training setup (timm models): pretrained weights · one-output head · AdamW · higher learning rate for the head than the backbone · weight decay 0.05 · warm-up + cosine schedule · mixed-precision GPU training · gradient clipping at 1.0 · label smoothing · up to 12 epochs · lowest-validation-loss checkpoint.

---

📊 Grouped Held-Out Evaluation

Selected DINOv2 Small (standard augmentation) on 1,983 test images at the balanced threshold of 0.50:

Metric	Value
Accuracy	0.9859
AUC	0.9984
Healthy precision	0.9961
Healthy recall	0.9770
Healthy F1	0.9864
Unhealthy precision	0.9750
Unhealthy recall	0.9957
Unhealthy F1	0.9853
Macro F1	0.9859

These scores are high but must be read in the context of the dataset and grouping method. They do not establish equivalent performance on farms absent from the source dataset. The materially lower cross-session benchmark is an important caution against relying on this score alone.

---

🎚️ Decision Thresholds and the Uncertain Output

The model emits p_unhealthy, an estimated probability for the Unhealthy class.

Setting	Threshold	Accuracy	Healthy recall	Unhealthy recall	Macro F1
Balanced	0.50	0.9859	0.9770	0.9957	0.9859
Sensitive	0.30	0.9864	0.9770	0.9968	0.9864

The sensitive threshold flags more images for review, reducing missed Unhealthy examples at the cost of potentially more false alarms.

The Uncertain band

The adapter returns Uncertain when |p_unhealthy − threshold| ≤ band (band = 0.15).

Threshold	Uncertain interval (inclusive)
0.50 (balanced)	0.35 – 0.65
0.30 (sensitive)	0.15 – 0.45

Implementation note: the adapter's default threshold is 0.50. To use the sensitive pilot setting, you must pass threshold=0.30 explicitly (and keep band=0.15). It is not applied automatically.

---

📦 Final Training and ONNX Export

• Final model trained on nearly all cleaned images (≈ 92 % train / ≈ 8 % monitoring, grouped by photo-number blocks).
• Exported to ONNX, opset 17, with dynamic batch axes.
• Input: image — N × 3 × 224 × 224, float32, raw 0–255 pixels
• Output: p_unhealthy
• Validated with the ONNX checker.
• Parity check (64 random images, CPUExecutionProvider): max absolute probability difference 0.00002; identical classes on 64/64 images at threshold 0.50.
• Size ≈ 86.6 MB; ≈ 45 ms/image on CPU (average of 20 single-image runs in the notebook environment — actual latency depends on your host).

The parity check verifies implementation fidelity. It is not an independent accuracy evaluation.

---

🚀 Quick Start

Package contents

File	Purpose
poultry_model.onnx	Exported model
model_card.json	Metadata, thresholds, benchmark records
labels.txt	Class labels
model_adapter.py	Preprocessing + inference adapter (source of truth)
requirements_backend.txt	Inference dependencies
BACKEND_README.md	Backend integration notes

Install

pip install onnxruntime pillow numpy fastapi uvicorn python-multipart

(PyTorch and TensorFlow are not required for inference.)

Predict

from model_adapter import PoultryModel
# Load once when the backend starts
model = PoultryModel("poultry_model.onnx", "model_card.json")
# For each uploaded image, pass its raw bytes
with open("sample.jpg", "rb") as f:
    image_bytes = f.read()
# Sensitive pilot setting (explicit threshold required)
result = model.predict_bytes(image_bytes, threshold=0.30, band=0.15)
print(result)
# -> label, p_unhealthy, threshold, model_version

🔧 Do not rewrite the preprocessing independently in your web backend. Use model_adapter.py as the single source of truth.

---

⚠️ Limitations and Responsible Use

Limitation	Why it matters
Single-source dataset	All training images come from one dataset (two broiler/layer settings in South-West Nigeria). Coverage of independent farms, cameras, seasons and management systems is not established.
External validity unverified	Performance on new farms, cameras, lighting and production environments is unknown.
Filename grouping is a proxy	Photo-number blocks reduce one form of leakage but do not guarantee farm/session independence.
Label provenance	Labelling was quality-checked by an Animal Scientist per the dataset record, but the clinical reference standard, confirmation process and inter-rater agreement are not documented in detail.
Resolution	Source images are 100 × 100 pixels and are upsampled to 224 × 224; fine detail is limited.
Hash deduplication limits	Perceptually similar images with altered encodings may remain.
Possible confounding	Backgrounds, cameras, lighting or collection practice may influence predictions; reliance only on clinically meaningful features is not established.
Broad classes	No disease- or cause-specific output.
Threshold calibration	The 0.30 threshold is a pilot setting and should be re-assessed with labelled data from target farms.
Not a diagnosis	Outputs must not substitute for veterinary examination or professional advice.
Data rights	Dataset is CC BY 4.0 (attribution required). Confirm terms before redistributing weights or source images.
Appropriate description: "an experimental poultry-dropping image screening model."
Please avoid claims that PoultryCheck diagnoses disease, detects all sick birds, or is clinically validated.

---

🔭 Proposed Next Research Phase

The priority is external validation, not a bigger model. - 🏡 Collect photographs from multiple farms, camera types, lighting conditions and production settings, with consent and data governance. - 📝 Establish a clear annotation protocol: who labels, on what evidence, and how disagreements are resolved. - 🧾 Record context where feasible: flock age, behaviour, feed/water intake, environment, veterinary assessment. - ✂️ Split by farm (not only by image number) and report per-farm as well as pooled performance. - 📈 Report sensitivity, specificity, precision, recall, F1, ROC-AUC, calibration and confidence intervals, with confusion matrices and subgroup analyses. - 🔍 Apply explainability methods to check attention falls on droppings rather than backgrounds or acquisition artefacts. - 🎚️ Set thresholds with animal-health professionals, weighing missed concerns against unnecessary alerts. - 🧬 Explore multimodal precision livestock management by combining images with behavioural, environmental and production data (proposed; not part of the current model). - 👩🏾‍🌾 Evaluate usability and operational performance with farmers and professionals before claiming field usefulness.

🔁 Reproducibility

Item	Value
Notebook	PoultryCheck_FINAL_Benchmark_Train_Export
Dataset layout	Class subfolders Healthy / Unhealthy
Supported extensions	JPG, JPEG, PNG, BMP, WEBP
Image size	224 × 224
Architecture	vit_small_patch14_dinov2.lvd142m
Augmentation	Standard
Grouped split	≈ 70 / 15 / remainder
Block size	BLOCK_SIZE as set in the notebook configuration cell
ONNX opset	17
ONNX I/O names	image → p_unhealthy
Parity-test provider	CPUExecutionProvider
Training environment	GPU-enabled Google Colab (no immutable environment lockfile provided)

For a fully reproducible public release, publish the exact notebook, dependency versions, configuration values, benchmark CSV, evaluation plots and model package together.

---

📚 Citation and Attribution

Dataset (please cite the original authors)

Adebayo, S., Aworinde, H., Akinwunmi, A., Alabi, O., Ayandiji, A., & Sakpere, A. (2023). Poultry Birds Poo Imagery Dataset for Health Status Prediction: A Case of South-West Nigeria (Version 1) [Data set]. Mendeley Data. https://doi.org/10.17632/8pnbzpt2k9.1

@dataset{adebayo2023poultrypoo,
  author    = {Adebayo, Segun and Aworinde, Halleluyah and Akinwunmi, Akinwale and Alabi, Olufemi and Ayandiji, Adebamiji and Sakpere, Aderonke},
  title     = {Poultry Birds Poo Imagery Dataset for Health Status Prediction: A Case of South-West Nigeria},
  year      = {2023},
  version   = {1},
  publisher = {Mendeley Data},
  doi       = {10.17632/8pnbzpt2k9.1},
  url       = {https://data.mendeley.com/datasets/8pnbzpt2k9/1}
}

This project

(https://huggingface.co/okediran/poultrycheck-dinov2)
  author = {Okediran, Tope Emmanuel},
  title  = {PoultryCheck: An Experimental Computer-Vision Screening Model for Poultry-Dropping Images},
  year   = {2026},
  note   = {Experimental research model, version 1.0}
}

Attribution

PoultryCheck is an independent experimental research and software project developed by Tope Emmanuel Okediran. It uses the third-party dataset named above; dataset ownership remains with its original authors, and use is subject to the CC BY 4.0 licence.

---

PoultryCheck · Version 1.0 · Experimental · Not a diagnostic device

Built to open a conversation on accessible, responsibly validated AI for poultry health monitoring.