Yolocilin

Medicine Box Detection, Identification and Information System

Scan a medicine box · Identify the drug · Get a short explanation

AI pipeline (YOLOv8 + OCR + fuzzy matching) · FastAPI backend · Flutter Android app
Computer Engineering internship project · Git Feature Branch Workflow

Not medical advice. Yolocilin helps identify packaging text against a seed catalog. Always confirm with the official leaflet or a pharmacist.

Why this project?

Photographing a box and guessing the brand is brittle. Yolocilin turns that into a clear pipeline:

Detect the box (YOLOv8)
Read the print (OpenCV + EasyOCR)
Match against a curated catalog (RapidFuzz + SQLite, 1163 drugs)
Show results on Android — with optional Gemini explanation and scan history

Built as a modular internship system: learnable examples/, production src/ + backend/ + mobile/.

Features

Area	What you get
Detection	Multi-box YOLO with confidence fallback
OCR	Fast / accurate modes; EasyOCR on CPU (typical wait); early exit only on near-complete match
Matching	RapidFuzz + reliability gates — wrong-name suffix fragments rejected (Report 27)
Barcode	Optional GTIN lookup (`/barcode/lookup` + `/barcode/scan`); analyze tries it before OCR (Report 28)
Catalog	TİTCK-enriched seed CSV → SQLite (1163 rows)
API	Analyze, medicines, barcode, explain, server scans
Mobile (Yolocilin)	Gallery + camera, results, local history, best-effort server sync
Ops	Docker, GitHub Actions CI, production CORS/docs hardening
Quality	pytest + Flutter tests + API E2E smoke (Report 25)

Sample inputs

Single box	Multi-box

How it works

Yolocilin (Flutter)
        │
        ▼
POST /api/v1/analyze  (FastAPI)
        │
        ▼
YOLOv8 → Crop → OpenCV → EasyOCR → RapidFuzz → SQLite (1163)
        │
        ├─► local history + POST /api/v1/scans
        ▼
JSON → Result screen
        │
        ▼ (optional)
POST /api/v1/explain → Gemini → “İlaç hakkında”

Parallel path (does not replace OCR):
Yolocilin or photo → GET/POST /api/v1/barcode → exact GTIN lookup → same explain

More detail: docs/architecture.md

Tech stack

Layer	Tools
Detection	YOLOv8n, Ultralytics, PyTorch
Vision	OpenCV, EasyOCR
Matching	RapidFuzz
Barcode	zxing-cpp (EAN-13 / DataMatrix; optional path)
Data	CSV seed + SQLite (`medicines` + `medicine_barcodes` + `scans`)
Backend	FastAPI, Pydantic, Uvicorn
LLM	Google Gemini (optional)
Mobile	Flutter / Dart — Yolocilin
DevOps	pytest, Docker, GitHub Actions

Rationale: docs/technology-selection.md

Dataset (Kaggle)

Privacy-cleaned medicine-box detection set for YOLOv8 (single class).


Images	395 (train 363 · valid 15 · test 17)
Format	YOLOv8 images + labels + `data.yaml`
License	CC BY 4.0
Download	melikeklahc/yolocilin-medicine-box-detection

Third-party screenshots and frames with personal handwritten notes were removed before publish. Images under data/dataset/ stay gitignored; use Kaggle (or Roboflow) to obtain the files.

Quick start

git clone https://github.com/Melikeda/yolocilin.git
cd yolocilin
python -m venv venv

# Windows
venv\Scripts\Activate.ps1

pip install -r requirements.txt
cp .env.example .env   # optional local overrides

Supported Python: 3.11+ (CI uses 3.11; Docker image uses 3.12).

CLI analyze

python run_analyze.py --image data/samples/parol_plus.jpg --mode fast

Trained YOLO weights are not in Git. The app auto-finds best.pt under common runs/detect/... layouts or models/best.pt (see models/README.md). Override with YOLO_MODEL_PATH.

API

python run_api.py

Method	Path	Description
GET	`/health`	Readiness
POST	`/api/v1/analyze`	Image → match results (`mode=fast\|accurate`)
GET	`/api/v1/medicines`	Search / list catalog
GET	`/api/v1/barcode/lookup`	Exact GTIN / EAN lookup
POST	`/api/v1/barcode/scan`	Image → barcode decode → catalog
POST	`/api/v1/explain`	Short Gemini text (needs key)
POST/GET/DELETE	`/api/v1/scans`	Server scan history

Dev docs: http://127.0.0.1:8000/docs (disabled when ENVIRONMENT=production).

curl -X POST "http://127.0.0.1:8000/api/v1/analyze?mode=fast" \
  -F "file=@data/samples/parol_plus.jpg"

Docker

docker compose up --build

Mobile (Android)

. .\scripts\env-flutter.ps1
flutter emulators --launch medicine_box_emulator
.\scripts\push-samples-to-emulator.ps1
cd mobile
flutter run

Default API URL on emulator: http://10.0.2.2:8000.
Details: mobile/README.md · remote testers: Firebase App Distribution

CPU OCR often takes tens of seconds to a few minutes per photo in fast mode. Blurry, distant, or multi-box shots may return not found instead of a guessed brand (Report 27).

Configuration & security

Topic	Notes
Env template	`.env.example`
Production	`ENVIRONMENT=production`, explicit `CORS_ORIGINS` (no `*`), `/docs` off
Explain	`LLM_ENABLED=true` + valid `GEMINI_API_KEY` (or mock mode)
Rate limits	Analyze / explain / scans (per IP)
Scan DELETE	Production: set `SCANS_API_KEY` and send `X-API-Key`, or leave unset to disable DELETE
Secrets	Never commit `.env`, API keys, `google-services.json`, or Firebase service-account JSON

See SECURITY.md and Report 20.

Project layout

yolocilin/
├── backend/app/           # FastAPI (analyze, medicines, explain, scans)
├── src/                   # Pipeline (YOLO, OCR, matching, SQLite models)
├── mobile/                # Yolocilin Flutter client
├── models/                # Optional: drop best.pt here (see models/README.md)
├── data/
│   ├── database/          # medicines.csv (+ SQLite at runtime)
│   ├── dataset/           # YOLO data.yaml (images gitignored — Roboflow)
│   └── samples/           # Test photos
├── docs/                  # Architecture, roadmap, reports, experiments, assets/
├── examples/              # Step-by-step learning scripts
├── tests/                 # pytest (incl. E2E smoke)
├── scripts/               # Dev helpers, e2e_api_flow, benchmarks
├── results/               # Local debug outputs only (gitignored)
├── runs/                  # Local Ultralytics train/predict (gitignored)
├── run_api.py             # API entry (not src/app.py)
├── run_analyze.py
├── docker-compose.yml
└── requirements.txt

Status: v1.0.0

Internship MVP is released: Yolocilin v1.0.0.

Pipeline, FastAPI, Docker, CI, Flutter Android app, camera, bilingual UI, Gemini explain, local + server scan history, production hardening, catalog (1163), E2E/perf tooling, optional barcode path.

Post-MVP (not required for 1.0)

Item	Notes
PostgreSQL migration	Optional scale-up
Cloud deploy + HTTPS	Reverse proxy / hosting
Per-user auth for scans	Scans are global until auth
iOS client	Android-first today

Roadmap: docs/roadmap.md · Dataset: Kaggle · Changelog: CHANGELOG.md

Tests & performance

ruff check backend src tests scripts   # lint
pytest                                 # backend
pytest tests/test_e2e_api_flow.py -q   # API E2E smoke
python scripts/e2e_api_flow.py --skip-analyze
python scripts/benchmark_analyze.py --image data/samples/parol_plus.jpg --mode fast

cd mobile
flutter analyze
flutter test

Documentation

Doc	Description
technical-report.md	CV-facing product summary
architecture.md	System design
setup-guide.md	Full environment setup
roadmap.md	Phases & remaining work
Kaggle dataset	YOLO medicine-box images (CC BY 4.0)
ocr-engines.md	EasyOCR (PaddleOCR trial: Report 26)
experiments/	Closed evaluations (not loaded at runtime)
kaggle-dataset.md	How the Kaggle dataset was published
Medium — Computer Vision	Internship notes: YOLO, OpenCV, OCR
Medium — FastAPI	Internship notes: REST API
Medium — Database	Internship notes: CSV / SQLite catalog
technology-selection.md	Why each tool
reports/	Phase technical reports (01–29)
SECURITY.md	Security & disclosure
CONTRIBUTING.md	Branch / PR workflow
CHANGELOG.md	Notable changes

Contributing

Branch from main: feature/<short-name>
Keep changes focused; link issues in the PR
Run backend + mobile checks before review

See CONTRIBUTING.md.

License

MIT — see LICENSE.

Author

Melike Eda Külahcı — Computer Engineering student


GitHub	Melikeda
LinkedIn	melike-kulahci
Medium	m.edakulahci
Kaggle	yolocilin-medicine-box-detection

If Yolocilin helped you learn or build something, a star is appreciated.

Navigation Menu

Repository files navigation

Yolocilin

Medicine Box Detection, Identification and Information System

Why this project?

Features

Sample inputs

How it works

Tech stack

Dataset (Kaggle)

Quick start

CLI analyze

API

Docker

Mobile (Android)

Configuration & security

Project layout

Status: v1.0.0

Post-MVP (not required for 1.0)

Tests & performance

Documentation

Contributing

License

Author

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
.github		.github
backend		backend
data		data
docs		docs
examples		examples
mobile		mobile
models		models
results		results
scripts		scripts
src		src
tests		tests
.dockerignore		.dockerignore
.env.example		.env.example
.firebaserc.example		.firebaserc.example
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
docker-compose.yml		docker-compose.yml
firebase.json		firebase.json
pyproject.toml		pyproject.toml
pytest.ini		pytest.ini
requirements.txt		requirements.txt
run_analyze.py		run_analyze.py
run_api.py		run_api.py

Latest commit

History

Folders and files

Repository files navigation

Yolocilin

Medicine Box Detection, Identification and Information System

Why this project?

Features

Sample inputs

How it works

Tech stack

Dataset (Kaggle)

Quick start

CLI analyze

API

Docker

Mobile (Android)

Configuration & security

Project layout

Status: v1.0.0

Post-MVP (not required for 1.0)

Tests & performance

Documentation

Contributing

License

Author

About

Topics

Resources

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages