drholy/ozone-tech_owl_prime
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

release: consolidate web simulation and real CV prototype

Browse Source 
Add cleaned RealSense/OpenCV CV under cv/ with secret-free example
config, MQTT disabled by default, and canonical README coverage for
web + CV relationship without claiming production integration.

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
root
2026-08-02 22:23:05 +02:00
parent 3777fecacf
commit 21e83be26e
26 changed files with 5050 additions and 178 deletions
Download Patch File Download Diff File Expand all files Collapse all files

341
README.md
View File

@@ -1,111 +1,171 @@
# OZON Sorter Digital Twin
Web digital twin of an Ozon Tech Track 3 conveyor sorting line: continuous product playback, camera/classification stage, B/C/D routing, and author-CAD diverter motion.
Complete Track 3 Ozon Tech solution in one repository: a web digital twin of the sorting line, plus a real RealSense/OpenCV CV prototype.
**Production domain:** https://arhipovdan.ru
**Production:** https://arhipovdan.ru
## Current solution
## 1. Overview
Final web simulation lives on **`main`** (same commit as `dan_branch`):
This repository delivers a continuous web simulation of an Ozon conveyor sorter: CAD conveyor, product models, camera/measurement stage, B/C/D classification, diverters, and Rapier physics. The public demo runs on https://arhipovdan.ru with routes `/` (simulation) and `/documentation` (engineering status).
- continuous 3D conveyor digital twin (`/`);
- engineering documentation (`/documentation`);
- author CAD (`3d_models/conveer.FCStd`) + runtime GLB (`public/models/sorter/conveyor-clean.glb`);
- product STL assets (`public/models/*.stl`);
- camera / classification stage (digital twin rules, not live RealSense);
- B / C / D routing with CAD left/right diverters (−45° / +45°);
- Rapier-backed product physics (contact routing **not** fully validated).
Separately, `cv/` contains a **working hardware prototype** that reads Intel RealSense D415 depth, measures parcels with OpenCV, classifies B/C/D, and can publish results over MQTT. It is **not** wired into the live website.
Accepted release head: **`bb76963`** (content tree identical to stable baseline `13ce16b`). Later experimental junction/discharge commits were reverted by owner request and are **not** part of the submitted product.
Both paths share the same Track 3 classification domain (exclusive 10×10×10 … 450×320×320 mm, roundness K > 0.8). The web twin uses a digital sensor simulation; the CV folder uses real depth frames.
### Main functions
`main` is the canonical complete solution. Developers do not need other branches to run the web app or inspect/run the CV prototype.
1. Continuous SKU playback on a three-module CAD conveyor (clean → camera → sorter).
2. Measurement / classification stage with Track 3 B/C/D rules.
3. Diverter state machine and route visualization.
4. Desktop WebGL twin; mobile uses a lightweight presentation policy when WebGL budget requires it.
5. Canonical engineering status on `/documentation`.
Large submission artifacts (presentation, video, optional CAD/model mirrors) belong in team cloud storage; runtime assets required by deploy stay in Git.
## Technology stack
## 2. Submission components
| Layer | Packages |
| Component | Location | Notes |
|---|---|---|
| Web digital twin | `src/`, `public/` | Production-integrated |
| Real CV prototype | `cv/` | WORKING_PROTOTYPE, not live-integrated |
| Author CAD | `3d_models/conveer.FCStd` | FreeCAD source |
| Official materials | `input_info/`, `official_sources/` | PDFs/ZIPs cited by docs/code |
| Production domain | https://arhipovdan.ru | Docker + nginx |
| Presentation / video | cloud (owner) | Links TBD — see §17 |
## 3. Production demo
- **URL:** https://arhipovdan.ru
- **`/`** — continuous digital-twin simulation
- **`/documentation`** — canonical engineering status
- Unknown routes redirect to `/`
Device behavior on current baseline:
- **Desktop:** interactive WebGL 3D
- **Mobile:** lightweight **2D** fallback (not full WebGL 3D)
Build identity: `/version.json`.
## 4. Web capabilities
- Three-module CAD conveyor (clean → camera → sorter)
- Camera / measurement simulation and Track 3 classifier
- B / C / D routing with CAD diverters (−45° / +45°)
- Rapier product physics (contact sorting **not** fully validated)
- Continuous playback HUD + documentation page
## 5. Real CV prototype
| Field | Value |
|---|---|
| UI | React, react-router-dom |
| 3D | three, @react-three/fiber, @react-three/drei, @react-three/postprocessing |
| Physics | @react-three/rapier, @dimforge/rapier3d-compat |
| Build | Vite, TypeScript, @vitejs/plugin-react |
| Tests | Vitest, Playwright |
| Path | `cv/` |
| Origin | `drho1y-mvp_1` / `vision_classifier/` |
| Technology | RealSense D415 + OpenCV (depth segmentation + metrics) |
| Status | WORKING_PROTOTYPE |
| Integration | **Not** connected to production web runtime |
Exact versions: `package.json` / `package-lock.json`.
See **[cv/README.md](cv/README.md)** for install, demo, live camera, and MQTT.
## Dependencies / Node
- Node.js **20+**
- npm (locked via `package-lock.json`)
### Exact commands
```bash
npm ci # install
npm run dev # development → http://127.0.0.1:3100
npm test -- --run # unit tests
npm run build # production build → dist/
npm run preview # serve build → http://127.0.0.1:3100
npm run test:e2e # Playwright (set PLAYWRIGHT_BASE_URL if needed)
```
## Active routes
| Route | Purpose |
|---|---|
| `/` | Continuous digital-twin simulation |
| `/documentation` | Canonical product / engineering status |
| `*` | Redirects to `/` |
Removed routes (`/details`, `/device-test`) are not part of the product.
## Project structure
## 6. Architecture
```
src/ React app, domain logic, 3D twin, pages
public/ Runtime static assets (models, draco)
models/ Product STL + sorter/conveyor-clean.glb
3d_models/ Author CAD (conveer.FCStd)
docs/ Engineering notes (ENGINEERING.md)
e2e/ Playwright smoke / routes
input_info/ Official Ozon input packs (PDFs/ZIPs)
official_sources/ Classifier bounds PDF cited by code
Dockerfile Multi-stage Vite build + nginx
Real device path:
RealSense D415 → depth preprocess → segmentation → measurement
→ B/C/D → optional MQTT / hardware
Web path:
Digital product → simulated sensor → classifier
→ physical digital twin → B/C/D receiver visualization
```
Shared: B/C/D semantics and official dimension/roundness rules.
Not shared today: live camera frames into the website.
## 7. Repository structure
```
.github/ CI (build, unit, e2e)
3d_models/ Author CAD (conveer.FCStd)
cv/ Real CV prototype (Python)
docs/ Engineering notes
e2e/ Playwright smoke/routes
input_info/ Official Ozon input packs
official_sources/ Classifier bounds PDF
public/ Runtime static assets (GLB/STL/draco)
src/ React/Three web twin
Dockerfile Web production image
docker-compose.server.yml
nginx.conf
.github/workflows/ci.yml
package.json / lock
vite / vitest / playwright / tsconfig
README.md
```
## Environment variables
No other top-level product directories are required to run or understand the solution.
No runtime secrets are required for local demo or production static hosting.
## 8. Requirements
Optional **build-time** identity (Docker / CI only; never commit secrets):
**Web:** Node.js 20+, npm (`package-lock.json`).
**CV:** Python 3.10+, ffmpeg, V4L2; RealSense D415 for live mode (`cv/requirements.txt`).
**Hardware (CV live / MQTT):** D415 USB3; optional MQTT broker + servo/motor controllers on site network.
| Variable | Purpose |
## 9. Web quick start
```bash
npm ci
npm run dev # http://127.0.0.1:3100
npm test -- --run
npm run build
npm run preview # http://127.0.0.1:3100
```
## 10. CV quick start
```bash
cd cv
./demo.sh # venv + deps; HUD on :8080 (needs D415 for live view)
# without camera:
python3 -m venv .venv && .venv/bin/pip install -r requirements.txt
.venv/bin/python test_classify.py
.venv/bin/python test_geometry.py
# live pipeline (hardware):
./run.sh --preview --no-mqtt --no-motor
```
`npm install` does **not** install CV dependencies.
## 11. Configuration
**Web (build-time, optional):** `VITE_BUILD_COMMIT`, `VITE_BUILD_BRANCH`, `VITE_BUILD_RELEASE` → `/version.json`. No runtime secrets.
**CV:** copy `cv/config.example.yaml` → `cv/config.yaml` (gitignored). MQTT/motor/routing **disabled by default**. Never commit real passwords or broker credentials.
## 12. Classification rules
Verified in web (`src/domain/classifier.ts`) and CV (`cv/classify.py`):
- dimensions strictly **> 10×10×10 mm** and **< 450×320×320 mm**
- circular when **K > 0.8** (web) / `circle_ratio ≥ 0.8` (CV)
- order: dimensions fail → **C**; else circular → **D**; else **B**
Official citation: `official_sources/doc-1783095831.pdf` (present; not re-parsed on every doc pass). Missing extracted brief PDF is not claimed.
## 13. Physics (accepted `main`)
From current source (not superseded experimental branches):
- belt speed **1.0 m/s** (`CONVEYOR_SPEED_MPS`)
- fixed timestep **1/60 s** (`PHYSICS_TIMESTEP_SEC`)
- CCD for light/thin product bodies
- diverters LEFT **−45°**, RIGHT **+45°**
- full contact-only junction sorting through CAD: **not fully validated**
## 14. CAD and assets
| Asset | Path |
|---|---|
| `VITE_BUILD_COMMIT` | Short git commit in `/version.json` |
| `VITE_BUILD_BRANCH` | Branch name in `/version.json` |
| `VITE_BUILD_RELEASE` | Release label in `/version.json` |
| Author CAD | `3d_models/conveer.FCStd` |
| Runtime GLB | `public/models/sorter/conveyor-clean.glb` |
| Products | `public/models/*.stl` |
Do not commit `.env` files. Local `npm run build` derives identity from git when available.
Keep runtime assets in Git for deploy. Mirror large CAD/models/presentation/video to cloud for submission.
## Active assets
| Path | Role |
|---|---|
| `3d_models/conveer.FCStd` | Author CAD (canonical source) |
| `public/models/sorter/conveyor-clean.glb` | Active runtime conveyor |
| `public/models/*.stl` | Product models |
| `input_info/*` | Official Ozon packs (PDFs/ZIPs) |
| `official_sources/doc-1783095831.pdf` | Official classifier bounds source cited by code |
### Frozen checksums (SHA-256)
SHA-256 (frozen):
```
3d_models/conveer.FCStd
@@ -115,112 +175,39 @@ public/models/sorter/conveyor-clean.glb
1dc7a8d7891bfe756e277ad5368df74cb73410156b2fe0f92845afb8a56f285a
```
## Classifier vs real CV
**Web twin (`main`):** rule-based classification in the digital twin (`src/domain/classifier.ts`) using Track 3 bounds and roundness. Camera overlay / measurement in the twin is a **simulation**, not live RealSense inference. This is **not** a neural network in production.
**Real CV (parallel prototype, not in the web app):** preserved on branch **`drho1y-mvp_1`** under `vision_classifier/` — OpenCV + Intel RealSense D415 depth → L×W×H + circle_ratio → B/C/D → MQTT. No PyTorch/YOLO weight files are stored in git.
## 15. Testing
```bash
git fetch origin
git switch drho1y-mvp_1
cd vision_classifier
# see vision_classifier/README.md and START.md
./demo.sh
.venv/bin/python test_classify.py
./run.sh --preview # hardware path (Orange PI + RealSense)
```
Integration status: **WORKING_PROTOTYPE on `drho1y-mvp_1`**, **not integrated** into https://arhipovdan.ru.
## Sorting logic
**CURRENT_IMPLEMENTATION_VERIFIED_IN_CODE** (`src/domain/classifier.ts`, `src/domain/pusherMotion.ts`, unit tests).
| Category | Physical route | Active CAD diverter |
|---|---|---|
| B | STRAIGHT | none |
| C | PHYSICAL_LEFT | LEFT, **−45°** |
| D | PHYSICAL_RIGHT | RIGHT, **+45°** |
Frozen diverter timing / planes (verified in code + tests):
- rotation duration: **0.50 s**
- opening safety margin: **0.15 s**
- contact plane S: **1.0538**
- clear plane S: **1.6000**
Classifier bounds (code + `official_sources/doc-1783095831.pdf` reference):
- dimensions strictly **> 10×10×10 mm** and **< 450×320×320 mm**
- circular when **K > 0.8**
- check order: dimensions → C, else circular → D, else B
## Physical simulation
- Belt target speed **1.0 m/s** (`CONVEYOR_SPEED_MPS`)
- Fixed physics timestep **1/60 s** (`PHYSICS_TIMESTEP_SEC`)
- CCD enabled for small/fast or thin product rigid bodies
- LEFT/RIGHT CAD diverters −45° / +45°
- Rapier world with gravity **[0, −9.81, 0]**
- Full contact-only junction sorting through CAD diverters is **not fully validated**
Details: `docs/ENGINEERING.md`, `/documentation`.
## Validation
```bash
npm ci
npm test -- --run # currently 196 unit tests
npm test -- --run
# current release result: 196/196
npm run build
npx vite preview --host 127.0.0.1 --port 3101 &
PLAYWRIGHT_BASE_URL=http://127.0.0.1:3101 npm run test:e2e -- e2e/routes.spec.ts e2e/smoke.spec.ts
cd cv && .venv/bin/python test_classify.py && .venv/bin/python test_geometry.py
```
## Production deploy (this host)
## 16. Deployment
Nginx terminates TLS for `arhipovdan.ru` and proxies to Docker `owl-web-1` on `127.0.0.1:3100` (`docker-compose.server.yml` + `Dockerfile`).
Nginx terminates TLS for `arhipovdan.ru` and proxies to Docker `owl-web-1` (`docker-compose.server.yml` + `Dockerfile`) on `127.0.0.1:3100`. Deploy from `main` with build-args for `/version.json`. CV is **not** part of the web container.
```bash
cd /opt/arhipovdan/app
COMMIT=$(git rev-parse --short HEAD)
BRANCH=$(git rev-parse --abbrev-ref HEAD)
RELEASE=$(date -u +%Y%m%d-%H%M%S)
docker compose -p owl -f docker-compose.server.yml build \
--build-arg "BUILD_COMMIT=${COMMIT}" \
--build-arg "BUILD_BRANCH=${BRANCH}" \
--build-arg "BUILD_RELEASE=${RELEASE}"
docker compose -p owl -f docker-compose.server.yml up -d --force-recreate
curl -s https://arhipovdan.ru/version.json
```
## 17. Submission materials
## Repository vs cloud materials
| Material | Status |
|---|---|
| Presentation URL | REQUIRED_FROM_OWNER |
| Video demo URL | REQUIRED_FROM_OWNER |
| Cloud folder URL | REQUIRED_FROM_OWNER |
| Material | In git | Cloud expected |
|---|---|---|
| Source, README, docs, configs, tests | yes | — |
| Runtime GLB/STL used by deploy | yes (required) | recommended mirror |
| Author CAD `conveer.FCStd` (~5 MB) | yes | recommended upload |
| Official PDFs/ZIPs (`input_info/`, `official_sources/`) | yes | optional mirror |
| Presentation / video demonstration | **not in repo** | **required for platform field** |
| ML weights | none (CV is classical OpenCV depth) | N/A |
Do not invent links. Runtime site assets remain in Git even when mirrored to cloud.
Confirmed public presentation / video / cloud-folder URLs are **not stored in this repository**. Owner must supply them in the platform submission field.
## 18. Known limitations
## Current limitations
- Mobile uses 2D lite fallback on current baseline
- CV is a prototype and is not live-integrated into arhipovdan.ru
- Simulation physics is engineering-derived; hardware calibration still required
- Contact routing through CAD diverters not fully validated
- Large presentation/video must be uploaded to cloud by owner
- Web classifier is a digital twin simulation, not live RealSense inference.
- Full contact-only sorting through CAD diverters is not fully validated.
- Belt surface-velocity physics (true tangential drive) is planned, not complete.
- Per-SKU mass / COM / friction profiles still need calibration.
- Author CAD horn / transmission incomplete in active GLB (`AUTHOR_CAD_INCOMPLETE`).
- Official compliance limited by missing extracted task PDF / PDF re-parse policy.
- Generated screenshots, videos, and stage folders are not canonical.
## 19. Branch history policy
## Repository policy
- Keep author CAD, active runtime assets, official sources, build configs, and tests.
- Real CV remains on `drho1y-mvp_1`; do not force-merge into `main` without validated web integration.
- Rollback / accepted product baseline content: `13ce16b` (current `main` tree via `bb76963`).
See also: `/documentation` in the running app, and `docs/ENGINEERING.md`.
**`main` is the canonical complete solution** (web + cleaned CV under `cv/`). Historical branches (`dan_branch`, `drho1y-mvp_1`, …) may remain for audit but are not required to run the product.