99 lines
4.1 KiB
Markdown
99 lines
4.1 KiB
Markdown
# 🍡 Dorayaki - Smart Supermarket Shelf AI & Inventory Recognition
|
||
|
||
Hệ thống nhận diện sản phẩm trên kệ siêu thị và quản lý tồn kho thời gian thực dựa trên kiến trúc kết hợp **YOLO** (Object Detection) và **Local Feature Matching** (SURF / SIFT, ORB, BRISK, Hybrid) theo paper quốc tế (*Electronics 2023, 12, 3640*).
|
||
|
||
---
|
||
|
||
## 📋 Yêu cầu hệ thống (System Requirements)
|
||
- **Hệ điều hành:** Windows 10/11, macOS hoặc Linux (Ubuntu/Debian).
|
||
- **Python:** Python 3.9, 3.10 hoặc 3.11 (khuyên dùng Python 3.10).
|
||
- **Phần cứng:** CPU tối thiểu 4 lõi, RAM 8GB (có GPU NVIDIA là lợi thế nhưng CPU chạy hoàn toàn mượt mà).
|
||
|
||
---
|
||
|
||
## 🚀 Hướng dẫn cài đặt và chạy Step-by-Step
|
||
|
||
### Bước 1: Sao chép toàn bộ thư mục dự án sang máy mới
|
||
Đảm bảo bạn copy toàn bộ thư mục dự án, đặc biệt là các thư mục cốt lõi:
|
||
- code/: Toàn bộ mã nguồn backend, frontend, thuật toán nhận diện.
|
||
-
|
||
uns/: Chứa file trọng số mô hình YOLO đã train (
|
||
uns/detect/train/weights/best.pt).
|
||
- stock/: Chứa file catalog stock.csv và ảnh mẫu sản phẩm chuẩn sku_001 -> sku_016.
|
||
- dd/ & image.jpg: Các ảnh kệ hàng mẫu để test và demo.
|
||
-
|
||
equirements.txt: Danh sách thư viện cần thiết.
|
||
|
||
### Bước 2: Tạo môi trường ảo Python (Khuyên dùng)
|
||
Mở Terminal / PowerShell / Command Prompt tại thư mục dự án:
|
||
|
||
#### Cách 1: Sử dụng Conda (Khuyên dùng nếu đã cài Anaconda/Miniconda)
|
||
`ash
|
||
conda create -n dorayaki python=3.10 -y
|
||
conda activate dorayaki
|
||
`
|
||
|
||
#### Cách 2: Sử dụng venv chuẩn của Python
|
||
- **Trên Windows:**
|
||
`ash
|
||
python -m venv venv
|
||
venv\Scripts\activate
|
||
`
|
||
- **Trên macOS / Linux:**
|
||
`ash
|
||
python3 -m venv venv
|
||
source venv/bin/activate
|
||
`
|
||
|
||
### Bước 3: Cài đặt các thư viện phụ thuộc
|
||
Chạy lệnh sau để cài đặt toàn bộ package:
|
||
`ash
|
||
pip install -r requirements.txt
|
||
`
|
||
|
||
*(Ghi chú nếu máy có GPU NVIDIA và muốn tăng tốc độ YOLO, có thể cài PyTorch CUDA theo hướng dẫn tại pytorch.org).*
|
||
|
||
### Bước 4: Khởi chạy ứng dụng Dorayaki Web App
|
||
|
||
#### Cách 1: Chạy bằng lệnh Python
|
||
`ash
|
||
python code/app.py --port 8080
|
||
`
|
||
*(Nếu dùng macOS/Linux có thể dùng python3 code/app.py --port 8080)*
|
||
|
||
#### Cách 2: Chạy nhanh bằng script có sẵn
|
||
- **Trên Windows:** Click đúp vào file
|
||
un_app.bat
|
||
- **Trên Linux/macOS:** Chạy ./run_app.sh
|
||
|
||
### Bước 5: Mở ứng dụng trên trình duyệt
|
||
Mở trình duyệt (Chrome, Edge, Safari, Firefox) và truy cập:
|
||
👉 **http://localhost:8080** (hoặc **http://127.0.0.1:8080**)
|
||
|
||
---
|
||
|
||
## 🛠️ Các lệnh kiểm tra hệ thống (Test Scripts)
|
||
|
||
1. **Test toàn diện hệ thống (Test Suite):**
|
||
`ash
|
||
python code/test_suite.py
|
||
`
|
||
2. **Test nhận diện sản phẩm trên ảnh image.jpg:**
|
||
`ash
|
||
python code/test_image.py
|
||
`
|
||
3. **Test nhận diện các chỗ trống trên kệ (Empty Shelf Slots):**
|
||
`ash
|
||
python code/test_empty.py
|
||
`
|
||
*(Kết quả trực quan sẽ được xuất ra file detected_empty_slots.jpg với viền đỏ bao quanh các vị trí hết hàng).*
|
||
|
||
---
|
||
|
||
## 🌟 Các tính năng chính của ứng dụng
|
||
1. **Phát hiện sản phẩm (YOLO):** Tự động detect hơn 170+ vật phẩm trên kệ trong 1 lượt scan.
|
||
2. **Phát hiện chỗ trống trên kệ (Out-of-Stock Detection):** Tự động phát hiện các vị trí hết hàng và khoanh đỏ, ước lượng số lượng sản phẩm đang thiếu.
|
||
3. **Phân loại đa thuật toán:** Cho phép chọn giữa **Hybrid (Paper)**, **SURF / SIFT**, **ORB**, **BRISK**.
|
||
4. **Tương tác trực quan:** Click vào bất kỳ sản phẩm nào trên ảnh kệ để xem tên, giá, ngày nhập, hạn sử dụng, số lượng tồn kho và xem các điểm matching inliers.
|
||
5. **Đa ngôn ngữ:** Hỗ trợ chuyển đổi nhanh Tiếng Anh và Tiếng Nhật.
|
||
6. **Tải ảnh linh hoạt:** Chọn ảnh từ danh mục mẫu, chụp ảnh trực tiếp từ webcam/camera điện thoại, hoặc upload ảnh từ máy tính.
|