From 3777fecacf82a3615adba125a392e6cd9dfc26b4 Mon Sep 17 00:00:00 2001 From: root Date: Sun, 2 Aug 2026 22:13:30 +0200 Subject: [PATCH] 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 --- README.md | 186 ++++++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 146 insertions(+), 40 deletions(-) diff --git a/README.md b/README.md index 23a3208..5df513a 100644 --- a/README.md +++ b/README.md @@ -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. -## Current product +**Production domain:** https://arhipovdan.ru -This repository contains: +## Current solution -- web-based conveyor sorting simulation (`/`); -- engineering documentation page (`/documentation`); -- author CAD conveyor source (`3d_models/conveer.FCStd`); -- runtime conveyor GLB (`public/models/sorter/conveyor-clean.glb`); +Final web simulation lives on **`main`** (same commit as `dan_branch`): + +- 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; -- B / C / D route mapping with CAD left/right diverters; +- 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). -## 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 -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 +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 @@ -35,20 +64,37 @@ npm run preview # http://127.0.0.1:3100 Removed routes (`/details`, `/device-test`) are not part of the product. -## Runtime architecture +## Project structure ``` -index.html -→ src/main.tsx -→ src/App.tsx -→ MainPage (/) | DocumentationPage (/documentation) -→ SorterDigitalTwinContinuous -→ ConveyorCadModel (conveyor-clean.glb) -→ product visuals / physics (STL + Rapier) -→ classifier (domain) -→ diverter product state machine (READY→ARMED→OPENING→HOLDING→CLOSING) +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 +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 | Path | Role | @@ -69,6 +115,24 @@ 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. + +```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). @@ -83,38 +147,80 @@ Frozen diverter timing / planes (verified in code + tests): - rotation duration: **0.50 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** -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** - circular when **K > 0.8** - 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 -- Unit tests: **196/196** (`npm test -- --run`) -- Production build: **PASS** (`npm run build`) -- Two-page routing: `/` + `/documentation` -- CAD / GLB checksums: verified against values above -- Diverter frozen angles / duration: covered by unit tests +```bash +npm ci +npm test -- --run # currently 196 unit tests +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 +``` + +## 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 -- Full contact-only sorting through CAD diverters is **not fully validated**. -- Belt surface-velocity physics (true 1 m/s tangential drive) is **planned**, not complete. +- 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 / complete transmission is absent or incomplete in the 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. -- Generated screenshots, videos, Gate stage folders, and tool `out/` trees are **not** canonical. +- 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. ## Repository policy -- Keep author CAD, active runtime assets, official sources, build configs, and tests that protect active behavior. -- Generated outputs and historical media are not product truth. -- Rollback point: git baseline `4413f01` on `dan_branch`. +- 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`.