wine_platform — Vision Automation Workflow

Purpose

The Vision Automation Workflow continuously validates the physical wine inventory stored in the cellar shelves by comparing:

• Detected bottle count from camera images
• Expected inventory stored in the Pince database

The workflow is implemented as two coordinated runtime lanes:

1. Motion-triggered lane — activated when activity is detected in the cellar
2. Scheduled lane — executed periodically via cron

Both lanes ultimately run the same stock detection pipeline and produce machine-readable outputs for further processing.

Outputs include:

• JSON run summary
• CSV comparison result
• structured detection artifacts

---

1. Automation Lanes

Lane	Trigger	Script	Purpose
Motion lane	Synology Surveillance motion webhook	motion_runtime.py	Detect changes after human interaction
Scheduled lane	Cron scheduler	stock_runtime.py	Periodic validation of shelf inventory

Both lanes eventually execute the same detection pipeline.

---

2. Motion-Triggered Lane

Trigger

Synology Surveillance Station detects motion and calls:

POST /integration/surveillance/motion

This launches:

motion_runtime.py

Responsibilities:

• ensure single instance execution
• wait grace period after motion
• turn cellar light on
• verify shelf visibility
• retry if shelf blocked
• launch the stock detection pipeline

---

Motion Workflow

flowchart TD
A[Motion detected by Synology] --> B[Webhook to FastAPI]
B --> C[motion_runtime.py starts]
C --> D[Initial delay]
D --> E[Turn cellar light ON]
E --> F[Wait stabilization]
F --> G[Visibility probe]
G -->|Visible| H[Run stock_runtime]
G -->|Blocked| I[Retry wait]
I --> G
H --> J[Pipeline executes]
J --> K[Write JSON/CSV]
K --> L[Light OFF]
L --> M[Exit]

---

3. Scheduled Lane (Cron)

Cron periodically executes:

stock_runtime.py

Typical uses:

• periodic verification
• missed event detection
• nightly reconciliation
• system monitoring

---

Scheduled Workflow

flowchart TD
A[Cron scheduler]
A --> B[Start stock_runtime.py]
B --> C[Light ON]
C --> D[Wait stabilization]
D --> E[Take snapshot]
E --> F[Crop bins]
F --> G[ONNX detection]
G --> H[Compare with DB]
H --> I[Write JSON]
I --> J[Write CSV]
J --> K[Light OFF]
K --> L[End]

---

4. Stock Detection Pipeline

Pipeline steps:

Step	Component	Description
0	Light control	Enable illumination
1	take_clean_snapshot	Capture RTSP image and rectify shelf
2	crop_with_json	Extract shelf bins
3	onnx_batch	Bottle detection
4	DB_compare	Compare with Pince DB

---

Pipeline Architecture

flowchart LR
CAM[Tapo Camera RTSP] --> SNAP[take_clean_snapshot]
SNAP --> CROP[crop_with_json]
CROP --> ONNX[onnx_batch]
ONNX --> COMPARE[DB_compare]
COMPARE <-- DB[(MariaDB)]
COMPARE --> OUT[JSON + CSV]

---

5. Result Artifacts

Typical output directory:

Synology NAS
/Volumes/web/web_images/Stock_vision/
├── data
   ├── cells_runtime
   ├── cells_runtime_res
   ├── models
   ├── proposals
   └── snapshots
       └── tmp

Output file in directory:

.
├── data
│   ├── cells_runtime
│   │   ├── 01_01.png
│   │   ├── ......png
│   │   ├── 08_05.png
│   │   └── crop_cells_debug
│   ├── cells_runtime_res
│   │   ├── 01_01.png
│   │   ├── ......png
│   │   ├── 08_05.png
│   │   ├── diff_only.csv
│   │   ├── diff_only.json
│   │   ├── results.csv
│   │   └── stock_runtime_summary.json
│   ├── models
│   │   └── best_V4.onnx
│   ├── proposals
│   │   ├── evidence
│   │   └── out
│   └── snapshots
│       ├── cells_polygons.json
│       ├── corner_json_history
│       ├── shelf_rectified.jpg
│       ├── snapshot.jpg
│       └── tmp
└── repo_tree.md

JSON summary example:

{
 "pipeline":"stock_runtime",
 "ok":true,
 "seconds_total":18.5
}

---

6. Inventory Validation

Detected bottles per shelf bin VS Expected inventory stored in Pince DB (MariaDB on Synology NAS)

Possible outcomes:

Result	Meaning
Match	Inventory correct
Missing bottle	Bottle removed but not registered
Extra bottle	Bottle added but not registered
Unknown detection	Bottle present but not identified

---

7. Reliability Design

Motion lane protections

• single instance lock
• delayed start
• retry visibility probe
• timeout protection
• controlled light management

Pipeline protections

• non-fatal light control
• detailed step logging
• JSON run summary
• safe shutdown