docs: API contract, README for the server and live mode, real-model test
docs/API.md is the full contract: run flags and environment, auth, coordinate convention, the identity vocabulary, every REST endpoint and WebSocket message with examples, the backpressure rule, what a client may rely on, the design decisions with their rejected alternatives, measured performance, known limitations, and notes for the future mobile client. README.md (Vietnamese) now documents the client-server shape, both modes, the flags, the API, the test commands, and the source layout. It also repairs the PowerShell escape damage in the original file (backtick-r had become a line break, backtick-b a backspace, backtick-a a bell), which had left the code fences and file paths mangled. test_real_model.py is the opt-in integration test (DORAYAKI_REAL_MODEL=1): it guards the measured baseline (170 detections, 105 recognized on image.jpg) and proves a pan keeps labels stable with no unexplained changes. run_app.sh / run_app.bat pass arguments through to the server. Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
This commit is contained in:
kiyo9w
parent
da2bed1c35
commit
4960553254
5 changed files with 568 additions and 77 deletions
|
|
@ -1,99 +1,150 @@
|
|||
# 🍡 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*).
|
||||
Hệ thống nhận diện sản phẩm trên kệ siêu thị và quản lý tồn kho theo kiến trúc **client - server**: mô hình thị giác máy tính (YOLO + Local Feature Matching: SURF/SIFT, ORB, BRISK, Hybrid theo paper *Electronics 2023, 12, 3640*) chạy trong một **recognition server**, còn các client (web, thiết bị chụp ảnh) chỉ gửi khung hình và nhận kết quả.
|
||||
|
||||
Server phục vụ **2 chế độ**:
|
||||
|
||||
1. **Live (nhận diện thời gian thực)** - camera hoặc video gửi liên tục qua WebSocket, sản phẩm được phát hiện trên từng khung hình, theo dõi (tracking) xuyên khung hình, phân loại một lần cho mỗi sản phẩm và gắn nhãn ngay trên màn hình.
|
||||
2. **Photo (ảnh tĩnh)** - chụp/upload/chọn ảnh kệ, nhận diện toàn bộ kệ trong một lần, bấm vào từng sản phẩm để xem chi tiết, tồn kho và điểm matching.
|
||||
|
||||
---
|
||||
|
||||
## 📋 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ệ điều hành:** Windows 10/11, macOS hoặc Linux.
|
||||
- **Python:** 3.10 - 3.12 (khuyên dùng 3.11/3.12).
|
||||
- **Phần cứng:** CPU 4 lõi trở lên, RAM 8GB. GPU không bắt buộc: trên máy M5 đo được CPU nhanh hơn MPS (28ms so với 112ms mỗi khung hình).
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Hướng dẫn cài đặt và chạy Step-by-Step
|
||||
## 🚀 Cài đặt và chạy
|
||||
|
||||
### 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 1: Chuẩn bị thư mục dự án
|
||||
|
||||
### 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ần có đầy đủ:
|
||||
|
||||
#### 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
|
||||
- `code/` - mã nguồn server, client web, client mẫu.
|
||||
- `runs/` - trọng số YOLO đã train (`runs/detect/train/weights/best.pt`).
|
||||
- `stock/` - catalog `stock.csv` và ảnh mẫu sản phẩm `sku_001` -> `sku_022`.
|
||||
- `add/` và `image.jpg` - ảnh kệ mẫu để test/demo.
|
||||
- `requirements.txt`, `requirements-dev.txt`.
|
||||
|
||||
### Bước 2: Tạo môi trường ảo
|
||||
|
||||
```bash
|
||||
conda create -n dorayaki python=3.11 -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
|
||||
`
|
||||
hoặc venv:
|
||||
|
||||
### 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
|
||||
`
|
||||
```bash
|
||||
python3 -m venv .venv
|
||||
source .venv/bin/activate # Windows: .venv\Scripts\activate
|
||||
```
|
||||
|
||||
*(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 3: Cài đặt thư viện
|
||||
|
||||
### Bước 4: Khởi chạy ứng dụng Dorayaki Web App
|
||||
```bash
|
||||
pip install -r requirements-dev.txt
|
||||
```
|
||||
|
||||
#### Cách 1: Chạy bằng lệnh Python
|
||||
`ash
|
||||
(`requirements-dev.txt` = `requirements.txt` + `httpx` cho test.)
|
||||
|
||||
### Bước 4: Khởi chạy recognition server
|
||||
|
||||
```bash
|
||||
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
|
||||
Script có sẵn: `run_app.bat` (Windows) hoặc `./run_app.sh` (Linux/macOS).
|
||||
|
||||
### 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 tham số thường dùng:
|
||||
|
||||
| Tham số | Mặc định | Ý nghĩa |
|
||||
| --- | --- | --- |
|
||||
| `--host` | `127.0.0.1` | Đổi thành `0.0.0.0` để mở cho máy khác trong LAN (nên đặt `DORAYAKI_API_TOKEN`). |
|
||||
| `--device` | `cpu` | `cpu`, `mps`, `cuda`, `cuda:0`. |
|
||||
| `--imgsz` | `640` | Kích thước đầu vào của detector. |
|
||||
| `--live-method` | `hybrid` | Thuật toán mặc định cho chế độ live. |
|
||||
| `--max-sessions` | `4` | Số client live đồng thời. |
|
||||
| `--ssl-certfile` / `--ssl-keyfile` | - | Bật HTTPS (cần cho camera trên điện thoại). |
|
||||
|
||||
### Bước 5: Mở ứng dụng
|
||||
|
||||
Mở trình duyệt: **http://127.0.0.1:8080** (hoặc `http://127.0.0.1:8080`)
|
||||
|
||||
- Tab **Live**: chọn camera (hoặc "Video file…") rồi bấm **Start**. Sản phẩm hiện khung xanh kèm tên và giá khi đã nhận diện chắc chắn; khung vàng "要確認" là trường hợp chưa chắc chắn.
|
||||
- Tab **Photo**: chọn ảnh mẫu, chụp ảnh hoặc upload ảnh kệ. Nhấn vào sản phẩm để xem chi tiết và bấm **Show matching** để xem các điểm matching.
|
||||
|
||||
Camera trên điện thoại chỉ hoạt động khi trang mở bằng **https** hoặc **localhost** (yêu cầu bảo mật của trình duyệt).
|
||||
|
||||
---
|
||||
|
||||
## 🛠️ Các lệnh kiểm tra hệ thống (Test Scripts)
|
||||
## 🔌 API (dùng cho client khác)
|
||||
|
||||
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).*
|
||||
Server có REST + WebSocket đầy đủ, tài liệu chi tiết trong [`docs/API.md`](docs/API.md). Swagger UI: **http://127.0.0.1:8080/docs**.
|
||||
|
||||
```bash
|
||||
# Nhận diện một ảnh kệ
|
||||
curl -X POST --data-binary @image.jpg -H 'Content-Type: image/jpeg' \
|
||||
'http://127.0.0.1:8080/v1/recognize?classify=true'
|
||||
|
||||
# Client live mẫu (camera, video, hoặc pan qua ảnh tĩnh)
|
||||
python code/stream_client.py --source image.jpg --pan 12 --seconds 20
|
||||
python code/stream_client.py --source 0 # webcam
|
||||
```
|
||||
|
||||
Bất kỳ client nào gửi được ảnh JPEG đều dùng được: điện thoại, iPad, camera gắn xe đẩy, camera đeo cổ, robot. Giao thức không phụ thuộc trình duyệt.
|
||||
|
||||
---
|
||||
|
||||
## 🌟 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.
|
||||
## 🛠️ Kiểm tra hệ thống (Tests)
|
||||
|
||||
```bash
|
||||
cd code
|
||||
YOLO_OFFLINE=1 ../.venv/bin/python -m unittest test_observe test_engine test_tracking test_live test_api -v
|
||||
|
||||
# Test với model thật (tải trọng số, chạy ~15s)
|
||||
DORAYAKI_REAL_MODEL=1 YOLO_OFFLINE=1 ../.venv/bin/python -m unittest test_real_model -v
|
||||
|
||||
cd ..
|
||||
YOLO_OFFLINE=1 .venv/bin/python code/test_suite.py # bộ test gốc
|
||||
.venv/bin/python code/bench_engine.py # đo tốc độ detect/classify
|
||||
```
|
||||
|
||||
Lưu ý: chạy test bằng danh sách module cụ thể, **không dùng** `unittest discover` vì sẽ import `test.py`/`fast_test.py` (script scratch với đường dẫn máy khác và cửa sổ OpenCV chặn).
|
||||
|
||||
---
|
||||
|
||||
## 🌟 Tính năng chính
|
||||
|
||||
1. **Nhận diện thời gian thực (Live)**: phát hiện sản phẩm trên từng khung hình, theo dõi xuyên khung hình, phân loại một lần cho mỗi sản phẩm, gắn nhãn tên/giá ngay trên khung hình; hiển thị số khung/giây và độ trễ.
|
||||
2. **Phát hiện chỗ trống trên kệ (Out-of-Stock)**: khoanh đỏ các vị trí hết hàng kèm ước lượng số lượng thiếu; có bộ lọc ổn định để khung không nhấp nháy.
|
||||
3. **Nhận diện ảnh tĩnh (Photo)**: nhận diện toàn bộ kệ trong một lần thay vì bấm từng sản phẩm.
|
||||
4. **Phân loại đa thuật toán**: Hybrid (Paper), SURF/SIFT, ORB, BRISK - đổi được ngay trong lúc chạy.
|
||||
5. **Trạng thái trung thực**: chỉ hiện tên sản phẩm khi kết quả được chấp nhận; trường hợp mơ hồ hiện "要確認" kèm các ứng viên, không đoán bừa.
|
||||
6. **Tương tác chi tiết**: bấm vào sản phẩm để xem tên, giá, ngày nhập, hạn sử dụng, tồn kho và điểm matching.
|
||||
7. **Đa client**: nhiều client kết nối đồng thời, mỗi client có session và tracking riêng.
|
||||
8. **Đa ngôn ngữ**: Tiếng Anh và Tiếng Nhật.
|
||||
9. **Gợi ý chất lượng ảnh**: cảnh báo lóa (glare), rung (blur), chụp quá xa.
|
||||
|
||||
---
|
||||
|
||||
## 📁 Cấu trúc mã nguồn
|
||||
|
||||
```
|
||||
code/
|
||||
app.py # server: REST /v1 + WebSocket /v1/stream + phục vụ web client
|
||||
engine.py # RecognitionEngine: detector + matcher + catalog, thread-safe
|
||||
live.py # LiveSession: tracking, phân loại nền, gắn nhãn, chất lượng ảnh
|
||||
tracking.py # SessionTracker: ByteTrack với ID riêng cho từng session
|
||||
detector.py # YOLO detector
|
||||
feature_matcher.py # SURF/SIFT, ORB, BRISK, Hybrid
|
||||
identity.py # accepted / ambiguous / unknown / rejected
|
||||
empty_shelf_detector.py, inventory.py, pipeline.py, observe.py
|
||||
stream_client.py # client mẫu (camera / video / pan ảnh tĩnh)
|
||||
bench_engine.py # đo tốc độ
|
||||
web/ # web client (index.html, styles.css, app.js)
|
||||
docs/API.md # tài liệu API đầy đủ
|
||||
```
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue