| # CropGuard GH — System Documentation |
|
|
| **Image-Based Crop Disease Detection System for Smallholder Farmers in Ghana** |
| Final Year Project · Oppong David · BTech Computer Technology, Kumasi Technical University |
|
|
| --- |
|
|
| ## 1. What this is |
|
|
| CropGuard is the working implementation of the system designed in the project report. A farmer photographs a diseased crop leaf and instantly receives: |
|
|
| - the **disease name** (55 classes across 14 crops cultivated in Ghana), |
| - a **confidence score**, |
| - a **severity level** (Early / Moderate / Severe) with colour coding, |
| - an **urgency level** (Routine / Urgent / Emergency), and |
| - a numbered list of **treatment steps** plus suggested products. |
|
|
| It ships in **two forms**, both included here: |
|
|
| | Deliverable | File | Use it for | |
| |---|---|---| |
| | **Ready-to-use HTML app** | `cropguard.html` | Open in any browser/phone. Works immediately (on-device estimate). No install. Covers all 14 Ghanaian crops when connected to the model. Bilingual (English + Twi toggle). | |
| | **Full production system** | `cropguard-system/` | The real stack from Chapter 3: trained MobileNetV2 model + FastAPI backend + React frontend. | |
|
|
| The HTML app can **also** connect to the trained backend — open Settings and paste the API URL, or set `localStorage.cropguard_api`. When no server is set it falls back to a genuine on-device colour/lesion analyser so it is never broken. |
|
|
| --- |
|
|
| ## 2. Architecture |
|
|
| The system follows the three-component client–server model described in §3.3: |
|
|
| ``` |
| ┌─────────────────────────┐ HTTPS / multipart ┌──────────────────────────┐ |
| │ Frontend (client) │ ── POST /predict (image) ──▶ │ Backend (server) │ |
| │ React app OR │ │ FastAPI │ |
| │ single-file HTML │ ◀── JSON diagnosis ────── │ ├─ MobileNetV2 model │ |
| │ (camera + gallery) │ │ ├─ severity estimator │ |
| └─────────────────────────┘ │ └─ recommendations.json │ |
| └──────────────────────────┘ |
| ``` |
|
|
| - **Inference runs on the server**, so the model can be updated without users reinstalling anything and old phones still work (§3.3). |
| - **Communication is a stateless REST API** returning JSON (§3.3). |
| - **Uploaded images are never stored** — they are processed in memory and discarded (§3.10.2 / §3.13 privacy-by-design). |
|
|
| --- |
|
|
| ## 3. The model (`backend/train.py`) |
|
|
| A transfer-learning classifier (MobileNetV2 **or** EfficientNetB0, via `--arch`), built as specified in §3.6: |
|
|
| **Accuracy target ~98%.** MobileNetV2 reaches roughly 97–98% on this benchmark; for the full multi-crop set use `--arch efficientnet` (EfficientNetB0), which typically reaches **98–99%**, in line with the published literature (Mohanty et al. 2016 = 99.35%, Ferentinos 2018 = 99.53%). The figure is reported honestly from the held-out test set at the end of training — it is never assumed. Label smoothing, class weighting and field-condition augmentation are included to push real-world accuracy toward the target. |
|
|
| - **Input:** 224×224 RGB, normalised with ImageNet mean/std. |
| - **Backbone:** MobileNetV2 or EfficientNetB0 pre-trained on ImageNet. |
| - **Head:** Global Average Pooling → BatchNorm → Dense(512, ReLU, L2=1e-4) → Dropout(0.4) → Dense(softmax). |
| - **Two-phase fine-tuning (§3.6.3):** Phase 1 trains the head with the backbone frozen (Adam, lr=1e-3, ~20 epochs); Phase 2 unfreezes the top 30% of the backbone (Adam, lr=1e-4, ~30 epochs) with `EarlyStopping` and `ReduceLROnPlateau`. |
| - **Loss:** categorical cross-entropy with label smoothing (0.05). |
| - **Class imbalance (§3.7.1):** balanced class weights computed with scikit-learn. |
| - **Augmentation (§3.5.2):** flip, rotation, zoom, brightness and contrast jitter. |
|
|
| ### Dataset layout expected |
|
|
| ``` |
| data/ |
| train/<class_name>/*.jpg |
| val/<class_name>/*.jpg |
| test/<class_name>/*.jpg |
| ``` |
|
|
| Class folder names must match the keys in `recommendations.json`: |
|
|
| ``` |
| maize_healthy maize_gls maize_nclb maize_rust maize_msv maize_faw |
| cassava_healthy cassava_cmd cassava_cbsd cassava_cbb |
| tomato_healthy tomato_early tomato_late tomato_wilt tomato_septoria tomato_tylcv |
| cocoa_healthy cocoa_blackpod cocoa_cssvd cocoa_capsid |
| cashew_healthy cashew_anthracnose cashew_gumosis cashew_leafminer |
| plantain_healthy plantain_sigatoka plantain_bbtv plantain_panama |
| yam_healthy yam_anthracnose yam_mosaic |
| pepper_healthy pepper_bacterialspot pepper_anthracnose |
| cowpea_healthy cowpea_blight cowpea_mosaic cowpea_cercospora |
| groundnut_healthy groundnut_leafspot groundnut_rosette groundnut_rust |
| rice_healthy rice_blast rice_blb rice_brownspot |
| okra_healthy okra_yvmv okra_leafspot |
| gardenegg_healthy gardenegg_wilt gardenegg_leafspot |
| mango_healthy mango_anthracnose mango_bacterialspot |
| ``` |
|
|
| **Covering all crops:** the system is not limited to a fixed list. To add any |
| further crop, drop a labelled folder of its images into `train/`, `val/` and |
| `test/`, add a matching record to `recommendations.json`, and retrain — no code |
| change is required. |
|
|
| Recommended sources (§3.4), Ghana-relevant: the **CCMT dataset** (Cashew, Cassava, Maize, Tomato — field images collected in Ghana), **cassava** disease datasets, **cocoa** (CRIG/COCOBOD imagery), the **rice / cowpea / groundnut** sets from African research programmes, and **PlantVillage/PlantDoc** for tomato, pepper and mango. Locally collected field photographs are added where possible. |
|
|
| ### Train |
|
|
| ```bash |
| cd backend |
| pip install -r requirements.txt |
| python train.py --data ./data --arch efficientnet --epochs-head 20 --epochs-fine 30 |
| # -> model/crop_model.keras and model/classes.json |
| ``` |
|
|
| --- |
|
|
| ## 4. The backend API (`backend/app.py`) |
|
|
| ```bash |
| cd backend |
| uvicorn app:app --host 0.0.0.0 --port 8000 |
| ``` |
|
|
| Interactive docs are auto-generated at `http://localhost:8000/docs`. |
|
|
| | Method | Endpoint | Returns | |
| |---|---|---| |
| | GET | `/health` | `{"status":"ok","model_loaded":bool}` | |
| | GET | `/diseases` | the full treatment knowledge base | |
| | POST | `/predict` | diagnosis JSON (below) | |
|
|
| **`POST /predict`** — send `multipart/form-data` with field `file` = the image. |
|
|
| ```json |
| { |
| "class_id": "tomato_late", |
| "confidence": 0.94, |
| "severity": "moderate", |
| "diseased_ratio": 0.42, |
| "disease": { |
| "crop": "Tomato", |
| "name": "Late Blight", |
| "cause": "An aggressive water-mould (Phytophthora infestans)...", |
| "treatment": ["Act today...", "..."], |
| "products": ["Chlorothalonil", "Mancozeb", "Metalaxyl-M"] |
| } |
| } |
| ``` |
|
|
| **Severity (§3.8)** is computed by `estimate_severity()` using colour thresholding: it measures the ratio of chlorotic (yellow), necrotic (dark) and lesion (brown) pixels to total leaf pixels, then maps `<0.20 → early`, `<0.55 → moderate`, else `severe`. |
|
|
| --- |
|
|
| ## 5. The React frontend (`frontend/src/CropGuard.jsx`) |
|
|
| The four-step flow from §3.10.4 — **home → preview → loading → result** — with camera capture, gallery upload, confidence bar, colour-coded severity, treatment steps and the safety disclaimer. |
|
|
| ```bash |
| cd frontend |
| npm create vite@latest . -- --template react # if starting fresh |
| npm install |
| echo "VITE_API_URL=http://localhost:8000" > .env |
| # drop CropGuard.jsx into src/ and render <CropGuard/> from App.jsx |
| npm run dev |
| ``` |
|
|
| --- |
|
|
| ## 6. The standalone HTML app (`cropguard.html`) |
|
|
| A single self-contained file — open it directly on a phone or host it anywhere static (Netlify, GitHub Pages, a CDN). It implements the full farmer UI in English **and Twi**, with: |
|
|
| - camera capture + gallery upload, |
| - a **real on-device analyser** (canvas pixel analysis of green vs. chlorotic/necrotic/lesion area) so it works with zero backend, |
| - **optional backend mode** — if `localStorage.cropguard_api` is set to your FastAPI URL it sends images to the trained model instead, |
| - severity colour coding, urgency icons, treatment steps, product suggestions, disease explanation, feedback and share. |
|
|
| To point it at the real model, run in the browser console: |
| ```js |
| localStorage.setItem('cropguard_api', 'https://your-api-host:8000'); |
| ``` |
|
|
| > **Note on the on-device fallback:** the heuristic analyser is honest and deterministic (it inspects actual leaf colour and damage area), but it is **not** the trained CNN. For graded, research-quality accuracy, connect the HTML app to the FastAPI backend running your trained model. |
|
|
| --- |
|
|
| ## 7. Deployment notes (§3.11) |
|
|
| - **Backend:** MobileNetV2 is light (~300M multiply-adds/inference) so a CPU-only instance serves several concurrent users; CORS and HTTPS should be enabled in production. |
| - **Frontend:** ship the React build or `cropguard.html` as static files behind a CDN for fast loads across Ghana. |
| - **Privacy:** no login, no accounts, no image storage. |
|
|
| --- |
|
|
| ## 8. Mapping to the report |
|
|
| | Report section | Where it lives in the code | |
| |---|---| |
| | §3.3 System architecture | client–server split (frontends ↔ `app.py`) | |
| | §3.4 Dataset | `train.py` `image_dataset_from_directory` layout | |
| | §3.5 Preprocessing & augmentation | `standardise()`, `build_augmenter()` | |
| | §3.6 MobileNetV2 + custom head + 2-phase fine-tune | `build_model()`, `main()` | |
| | §3.7 Loss, class weights, LR schedule | `class_weights_from_dir()`, callbacks | |
| | §3.8 Severity classification | `estimate_severity()` (backend) / `analyseOnDevice()` (HTML) | |
| | §3.9 Treatment recommendations | `recommendations.json` | |
| | §3.10 Web app & mobile-first UI | `cropguard.html`, `CropGuard.jsx` | |
| | §3.13 Privacy / ethics | in-memory image handling, no storage | |
|
|
