docs: finalize submission materials

Document domain, launch/build commands, structure, env vars, cloud split,
physics contracts of the accepted baseline, and CV on drho1y-mvp_1.

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
root
2026-08-02 22:13:30 +02:00
parent bb76963902
commit 3777fecacf

186
README.md
View File

@@ -2,27 +2,56 @@
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. 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.
## Current product **Production domain:** https://arhipovdan.ru
This repository contains: ## Current solution
- web-based conveyor sorting simulation (`/`); Final web simulation lives on **`main`** (same commit as `dan_branch`):
- engineering documentation page (`/documentation`);
- author CAD conveyor source (`3d_models/conveer.FCStd`); - continuous 3D conveyor digital twin (`/`);
- runtime conveyor GLB (`public/models/sorter/conveyor-clean.glb`); - engineering documentation (`/documentation`);
- author CAD (`3d_models/conveer.FCStd`) + runtime GLB (`public/models/sorter/conveyor-clean.glb`);
- product STL assets (`public/models/*.stl`); - product STL assets (`public/models/*.stl`);
- camera / classification stage; - camera / classification stage (digital twin rules, not live RealSense);
- B / C / D route mapping with CAD left/right diverters; - B / C / D routing with CAD left/right diverters (−45° / +45°);
- Rapier-backed product physics (contact routing **not** fully validated). - Rapier-backed product physics (contact routing **not** fully validated).
## Quick start 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.
### Main functions
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`.
## Technology stack
| Layer | Packages |
|---|---|
| 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 |
Exact versions: `package.json` / `package-lock.json`.
## Dependencies / Node
- Node.js **20+**
- npm (locked via `package-lock.json`)
### Exact commands
```bash ```bash
npm ci npm ci # install
npm run dev # http://127.0.0.1:3100 npm run dev # development → http://127.0.0.1:3100
npm test -- --run npm test -- --run # unit tests
npm run build npm run build # production build → dist/
npm run preview # http://127.0.0.1:3100 npm run preview # serve build → http://127.0.0.1:3100
npm run test:e2e # Playwright (set PLAYWRIGHT_BASE_URL if needed)
``` ```
## Active routes ## Active routes
@@ -35,20 +64,37 @@ npm run preview # http://127.0.0.1:3100
Removed routes (`/details`, `/device-test`) are not part of the product. Removed routes (`/details`, `/device-test`) are not part of the product.
## Runtime architecture ## Project structure
``` ```
index.html src/ React app, domain logic, 3D twin, pages
→ src/main.tsx public/ Runtime static assets (models, draco)
→ src/App.tsx models/ Product STL + sorter/conveyor-clean.glb
→ MainPage (/) | DocumentationPage (/documentation) 3d_models/ Author CAD (conveer.FCStd)
→ SorterDigitalTwinContinuous docs/ Engineering notes (ENGINEERING.md)
→ ConveyorCadModel (conveyor-clean.glb) e2e/ Playwright smoke / routes
→ product visuals / physics (STL + Rapier) input_info/ Official Ozon input packs (PDFs/ZIPs)
→ classifier (domain) official_sources/ Classifier bounds PDF cited by code
→ diverter product state machine (READY→ARMED→OPENING→HOLDING→CLOSING) Dockerfile Multi-stage Vite build + nginx
docker-compose.server.yml
nginx.conf
.github/workflows/ci.yml
``` ```
## Environment variables
No runtime secrets are required for local demo or production static hosting.
Optional **build-time** identity (Docker / CI only; never commit secrets):
| Variable | Purpose |
|---|---|
| `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` |
Do not commit `.env` files. Local `npm run build` derives identity from git when available.
## Active assets ## Active assets
| Path | Role | | Path | Role |
@@ -69,6 +115,24 @@ public/models/sorter/conveyor-clean.glb
1dc7a8d7891bfe756e277ad5368df74cb73410156b2fe0f92845afb8a56f285a 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.
```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 ## Sorting logic
**CURRENT_IMPLEMENTATION_VERIFIED_IN_CODE** (`src/domain/classifier.ts`, `src/domain/pusherMotion.ts`, unit tests). **CURRENT_IMPLEMENTATION_VERIFIED_IN_CODE** (`src/domain/classifier.ts`, `src/domain/pusherMotion.ts`, unit tests).
@@ -83,38 +147,80 @@ Frozen diverter timing / planes (verified in code + tests):
- rotation duration: **0.50 s** - rotation duration: **0.50 s**
- opening safety margin: **0.15 s** - opening safety margin: **0.15 s**
- contact plane S: **1.0538** (fallback hinge geometry ≈ 1.0536) - contact plane S: **1.0538**
- clear plane S: **1.6000** - clear plane S: **1.6000**
Classifier bounds (code + `official_sources/doc-1783095831.pdf` reference; PDF not re-parsed in this doc pass): Classifier bounds (code + `official_sources/doc-1783095831.pdf` reference):
- dimensions strictly **> 10×10×10 mm** and **< 450×320×320 mm** - dimensions strictly **> 10×10×10 mm** and **< 450×320×320 mm**
- circular when **K > 0.8** - circular when **K > 0.8**
- check order: dimensions → C, else circular → D, else B - check order: dimensions → C, else circular → D, else B
Missing primary brief (do not cite as present): `input_info/extracted/Постановка_Задача_3_сжато_2.pdf`. ## 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 ## Validation
- Unit tests: **196/196** (`npm test -- --run`) ```bash
- Production build: **PASS** (`npm run build`) npm ci
- Two-page routing: `/` + `/documentation` npm test -- --run # currently 196 unit tests
- CAD / GLB checksums: verified against values above npm run build
- Diverter frozen angles / duration: covered by unit tests 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
```
## Production deploy (this host)
Nginx terminates TLS for `arhipovdan.ru` and proxies to Docker `owl-web-1` on `127.0.0.1:3100` (`docker-compose.server.yml` + `Dockerfile`).
```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
```
## Repository vs cloud materials
| 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 |
Confirmed public presentation / video / cloud-folder URLs are **not stored in this repository**. Owner must supply them in the platform submission field.
## Current limitations ## Current limitations
- Full contact-only sorting through CAD diverters is **not fully validated**. - Web classifier is a digital twin simulation, not live RealSense inference.
- Belt surface-velocity physics (true 1 m/s tangential drive) is **planned**, not complete. - 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. - Per-SKU mass / COM / friction profiles still need calibration.
- Author CAD horn / complete transmission is absent or incomplete in the active GLB (`AUTHOR_CAD_INCOMPLETE`). - Author CAD horn / transmission incomplete in active GLB (`AUTHOR_CAD_INCOMPLETE`).
- Official compliance claims are limited by the **missing** extracted task PDF and by not re-parsing PDFs in every doc pass. - Official compliance limited by missing extracted task PDF / PDF re-parse policy.
- Generated screenshots, videos, Gate stage folders, and tool `out/` trees are **not** canonical. - Generated screenshots, videos, and stage folders are not canonical.
## Repository policy ## Repository policy
- Keep author CAD, active runtime assets, official sources, build configs, and tests that protect active behavior. - Keep author CAD, active runtime assets, official sources, build configs, and tests.
- Generated outputs and historical media are not product truth. - Real CV remains on `drho1y-mvp_1`; do not force-merge into `main` without validated web integration.
- Rollback point: git baseline `4413f01` on `dan_branch`. - Rollback / accepted product baseline content: `13ce16b` (current `main` tree via `bb76963`).
See also: `/documentation` in the running app, and `docs/ENGINEERING.md`. See also: `/documentation` in the running app, and `docs/ENGINEERING.md`.