ozone-tech_owl_prime/docs/PHYSICAL_MOTION_FIX_REPORT.md

Physical Motion Fix Report

Причины предыдущего хаоса

Ранее движение товара рассчитывалось независимо по осям с использованием интерполяции между хардкодными точками, что приводило к телепортации или "зависанию" объектов (в том числе над корзиной). Также отсутствовала система хранения объектов после завершения их этапа маршрутизации. Указанные в ModelAssets STL-модели загружались, но отображались некорректно. Из-за отсутствия независимой физической модели каждый фрейм пытался обновлять позиции локально.

Решение

1. Создана physicalItemMotion.ts — единая физико-кинематическая модель getPhysicalItemPose. Она гарантирует детерминированное вычисление [x,y,z] и вращения на основе elapsedMs, отсчитанного от момента спавна товара, а также CONVEYOR_SPEED_MPS (1 м/с).
2. Синхронизация ленты и товара: Время и расстояние на ленте точно соответствуют d = 1.0 \times t. Движущаяся текстура ленты использует эту же скорость.
3. Хранение (settled) элементов: В SorterDigitalTwinContinuous.tsx теперь рендерятся все созданные (spawned) объекты за последние 20 циклов. Объекты попадают в корзину C или D по желобу (chute), меняя высоту, и остаются там (isSettled).
4. STL модели: Добавлен единый компонент PhysicalPlaybackItem.tsx, который грузит STLGeometry или использует FallbackPrimitive в случае их отсутствия, применяя при этом корректные материалы с реалистичным roughness и metalness.

Подтверждение

• Скорость товара 1 м/с подтверждена тестами в physicalItemMotion.test.ts.
• Объекты остаются внутри cage благодаря смещению на базе slotIndex.
• Fallback применён только к отсутствующим или "heavy" STL. (Короб 300, 400, Тарелка, Бутылка, Цилиндр, ЛанчБокс — STL).

Результаты QA и сборка

• npm run build — Успешно (0 ошибок).
• npm run test — Успешно (117 тестов пройдено).
• docker-compose — Контейнеры пересобраны и запущены.
• Production QA Script завершен с 0 ошибок консоли (NO_CONSOLE_ERRORS).

Скриншоты лежат в папке docs/physical_motion_fix_screenshots/:

• stl_models_visible.png
• belt_sync_t0.png
• belt_sync_t1.png
• item_on_belt_no_flying.png
• route_to_c_chute.png
• item_settled_in_c_cage.png
• route_to_d_chute.png
• item_settled_in_d_cage.png
• no_overlay_overlap.png
• demo_complete_items_not_chaotic.png

Ограничения: slotIndex использует простую матричную сетку 3xN, что при сильном переполнении корзины может вызвать небольшие наложения (clipping) STL-моделей друг на друга, но это визуально приемлемо и объекты остаются строго внутри корзины.