diff --git a/README.md b/README.md index b6630b8..f40ceee 100644 --- a/README.md +++ b/README.md @@ -2,27 +2,55 @@ 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 (`/`); +This repository (`main`) contains the final web simulation: + +- continuous 3D conveyor digital twin (`/`); - engineering documentation page (`/documentation`); - author CAD conveyor source (`3d_models/conveer.FCStd`); - runtime conveyor 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; -- Rapier-backed product physics (contact routing **not** fully validated). +- camera-triggered measurement / rule-based classification (digital sensor simulation); +- B / C / D route mapping with CAD left/right diverters (−45° / +45°); +- Rapier physics: belt ≈ 1.0 m/s, fixed timestep 1/120 s, CCD on product profiles, discharge into receivers. -## Quick start +### Main functions + +1. Continuous SKU playback on a three-module CAD conveyor (clean → camera → sorter). +2. Camera-volume triggered measurement and B/C/D classification. +3. Physical diverter routing and receiver settle detection. +4. Desktop WebGL twin + mobile-capable 3D policy. +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 | + +See `package.json` for exact versions. Do not treat transitive npm packages as first-class product dependencies. + +## Dependencies / Node + +- Node.js **20+** +- npm (lockfile: `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 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 (needs preview or PLAYWRIGHT_BASE_URL) ``` ## Active routes @@ -35,20 +63,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 real 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 +114,24 @@ public/models/sorter/conveyor-clean.glb 1dc7a8d7891bfe756e277ad5368df74cb73410156b2fe0f92845afb8a56f285a ``` +## Classifier vs real CV + +**Web twin (`main`):** classification is a **digital sensor simulation**. When a product enters the camera scan volume, dimensions / roundness are measured in the twin and routed with the same B/C/D rules as Track 3 (`src/domain/classifier.ts`, `src/domain/cameraClassification.ts`). This is **not** a neural network and is **not** wired to a live RealSense camera in production. + +**Real CV (parallel prototype, not merged into the web app):** preserved on branch **`drho1y-mvp_1`** under `vision_classifier/` (OpenCV + RealSense D415 depth → L×W×H + circle_ratio → B/C/D → MQTT). No PyTorch/YOLO weights 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 # browser HUD demo +.venv/bin/python test_classify.py +./run.sh --preview # full pipeline on hardware (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). @@ -92,35 +155,79 @@ Classifier bounds (code + `official_sources/doc-1783095831.pdf` reference; PDF n - 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 + +- Fixed timestep **1/120 s**, max **4** substeps, gravity **[0, −9.81, 0]** +- Belt target speed **1.0 m/s** (supported-body velocity coupling) +- CCD enabled on active product physics profiles +- Single dynamic product rigid body through spawn → junction → receiver settle +- LEFT/RIGHT CAD diverters: `kinematicPositionBased` colliders synced to CAD yaw +- Discharge edge ends belt support; gravity fall into receivers +- Receiver volumes are sensors for completion + +Details: `docs/ENGINEERING.md`, `/documentation`. ## Validation -- Unit tests: **221/221** (`npm test -- --run`) -- Production build: **PASS** (`npm run build`) +```bash +npm ci +npm test -- --run # currently 245 unit tests +npm run build +# focused E2E (with preview on :3101): +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 +``` + - Two-page routing: `/` + `/documentation` - CAD / GLB checksums: verified against values above - Diverter frozen angles / duration: covered by unit tests -- Physical junction contact matrix: **45/45** — **ENGINEERING-DERIVED PHYSICAL VALIDATION** (not production-certified) +- Junction / discharge / camera classification: covered by domain tests (engineering-derived, not production-calibrated) -## Physics (junction contact) +## Production deploy (this host) -- Same dynamic product rigid body through spawn → junction → receiver settle -- LEFT/RIGHT CAD diverters use `kinematicPositionBased` colliders synced to the accepted CAD yaw -- B: physical straight corridor; C/D: contact-only redirection; receiver sensors detect only -- Temporary scripted junction handoff removed from the active product path +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 # or your checkout +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 the deployed app | yes (required for deploy) | recommended mirror | +| Author CAD `conveer.FCStd` (~5 MB) | yes | recommended upload | +| Official PDFs/ZIPs under `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**. Add them in the platform submission field when available. + +Презентация / видеодемонстрация: links must be supplied by the owner (not invented here). ## Current limitations -- Product profiles are **engineering-derived**, not production-calibrated. +- Web classifier is a digital sensor simulation, not live RealSense inference. +- Product profiles are engineering-derived, not production-calibrated. - 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. +- 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. ## 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`. +- Real CV remains on `drho1y-mvp_1`; do not force-merge it into `main` without a validated web integration. +- Rollback point for the pre-cleanup web baseline: git `4413f01` on `dan_branch` history. See also: `/documentation` in the running app, and `docs/ENGINEERING.md`.