Citrus Detection System: YOLOv8, FastAPI & Vue3 Full-Stack Tutorial

System Overview

The system provides an intelligent computer vision platform for citrus orchards, enabling farmers and agronomists to quickly count fruit yield and distinguish between on-tree and fallen fruit distributions, replacing inefficient manual counting.

Two core detection capabilities are offered: image detection and video detection. Users upload orchard photos or patrol videos; the system automatically identifies citrus fruits, classifies them as "on-tree" or "fallen", and outputs count statistics, confidence details, and annotated result images/videos.

Beyond detection, the system includes a complete model experiment framework — comparative experiments, ablation experiments, and negative-sample ablation experiments — with charts and tables documenting every model-selection and optimization decision. This demonstrates how to turn an algorithm-tuning process into a reproducible, visualizable engineering deliverable rather than just producing a model file.

Technical Architecture

Backend

FastAPI ≥ 0.104.0 + Uvicorn ≥ 0.24.0 (ASGI server)

Ultralytics YOLOv8 ≥ 8.0.0 (includes ByteTrack tracker)

SQLite for persistence

ONNX Runtime ≥ 1.17.0 for accelerated inference

SAHI ≥ 0.12.1 for sliced inference (high-precision mode)

OpenCV ≥ 4.8.0 for image/video I/O and drawing

Pydantic ≥ 2.0.0 for data validation

lapx ≥ 0.5.2 (ByteTrack matching dependency)

Frontend

Vue 3 + Vite 5.4.21

Element Plus for UI components

@icon-park/vue-next for icons

Axios for HTTP requests

Vue Router for navigation

Model

YOLOv8n (Nano) retrained with negative samples, deployed in ONNX format by default.

Core Features

Image Detection Page

Drag-and-drop / click upload with automatic duplicate replacement

Confidence threshold and IoU threshold sliders

High-precision mode toggle (SAHI sliced inference)

Canvas real-time drawing of detection boxes (green for on-tree, orange for fallen)

Detection statistics cards + detail table with confidence progress bars

Low-confidence automatic warning alerts

Video Detection Page

Video upload with progress bar

Asynchronous task processing with 2-second polling

Auto-play of annotated result video (H.264 encoded for browser playback)

Tracking-based deduplication counting (each fruit counted once across frames via ByteTrack)

Experiment Pages

Ablation Experiment tab: anchor-free mechanism validated by object size and scene density

Comparative Experiment tab: YOLOv8n vs YOLOv5n comprehensive metrics comparison

Negative Sample Ablation tab: false-positive comparison before/after negative-sample training

Detection history list (every detection automatically logged)

Business Process Flows

Image Detection Flow

Upload → Preprocess → Model Inference (YOLOv8n ONNX) → Post-process (NMS, classification) → Draw boxes on canvas → Return stats + annotated image → Persist record to SQLite.

Video Detection Flow

Upload → Save to temporary directory → Async task queue → Frame extraction → Tracking + detection per frame → Deduplication via ByteTrack → Encode annotated frames to H.264 video (ffmpeg) → Return result video URL → Cleanup temporary files.

Deployment Guide

Backend Environment (Python 3.10+)

pip install -r requirements.txt

requirements.txt contents:

fastapi>=0.104.0
uvicorn[standard]>=0.24.0
python-multipart>=0.0.6
ultralytics>=8.0.0
opencv-python>=4.8.0
numpy>=1.24.0
pydantic>=2.0.0
lapx>=0.5.2
sahi>=0.12.1
onnxruntime>=1.17.0

Additional training dependencies (separate):

pip install -r model_train/requirements.txt
# fiftyone>=0.24.0
# protobuf>=4.25.0

Optional: pip install pytest for regression tests.

Frontend Environment (Node.js 18+)

npm config set registry https://registry.npmmirror.com/
cd web
npm install

Project Structure

yolov8/
├── main.py                 # FastAPI entry, routes, lifespan
├── requirements.txt        # Python deps
├── app/                    # Backend modules
│   ├── config.py           # Centralized config (env overridable)
│   ├── model.py            # YOLOv8 singleton wrapper
│   ├── schemas.py          # Pydantic models
│   ├── database.py         # SQLite persistence
│   ├── image_service.py    # Image detection logic
│   ├── video_service.py    # Video detection logic
│   ├── cleanup_service.py  # Periodic result cleanup
│   ├── experiment_service.py       # Detection records CRUD
│   ├── metrics_service.py          # Training metrics reading
│   └── experiment_results_service.py # Experiment data reading
├── model_train/            # Training scripts, datasets, artifacts
├── web/                    # Frontend project
├── static/results/         # Runtime generated images/videos
├── uploads/                # Video upload temp dir
├── data/                   # SQLite DB, fuzzy sample pool (gitignored)
└── tests/                  # pytest regression tests

Starting Backend

Three methods: python main.py (internal uvicorn with hot reload) uvicorn main:app --port 8000 Production: uvicorn main:app --host 0.0.0.0 --port 8000 --workers 4 Lifespan hook loads model ( model_train/output/train_negatives/weights/best.onnx) and starts cleanup task (retention 7 days). Swagger docs at /docs.

Starting Frontend

cd web
npm run dev

Vite dev server at http://localhost:5173 with proxy for /api, /static, /health to backend port 8000.

Key Implementation Details

SAHI sliced inference : enabled via high-precision toggle; splits large images into overlapping patches for small-object detection.

ONNX Runtime : used for CPU/GPU accelerated inference instead of PyTorch runtime.

ByteTrack tracking : integrated via Ultralytics; lapx provides Hungarian matching.

Negative sample training : separate model_train/ pipeline uses FiftyOne for dataset curation; reduces false positives on background clutter.

SQLite persistence : stores detection records, experiment metrics, and fuzzy sample pool for active learning.