# Аудит визуального реализма

**Дата:** 2026-07-15  
**Стек визуализации:** Three.js + React Three Fiber + drei (клиентский WebGL)  
**Решение по стеку:** **остаёмся на R3F** — смена на Babylon/Unity Web не обоснована; текущий стек уже даёт industrial twin и STL.

Легенда: **Измерено** (код/сборка/тесты) · **Оценка** (экспертный вывод без GPU-профайлера браузера в этом отчёте).

---

## 1. Цель аудита

Отделить:

1. Что уже выглядит как оборудование.  
2. Что всё ещё «игровое» или декоративное.  
3. Что критично для доверия жюри за первые 10 секунд.

---

## 2. Текущая визуальная архитектура

| Компонент | Continuous `/` | Details `/details` |
| --------- | -------------- | ------------------ |
| Scene root | `SorterDigitalTwinContinuous` | `SorterDigitalTwin` |
| Items | `PhysicalPlaybackItem` / motion domain | `Item3D` + sim state |
| Conveyor | `Conveyor3D` + network layout | Аналогичные примитивы, другой wiring |
| Actuators | Gate/pusher анимации | State-driven actuators |
| Sensors | Overlay + measurement HUD | `SensorRig3D` / panels |
| Models | STL через `modelAssets` + fallbacks | То же семейство ассетов |
| Camera | Cinematic / demo camera path | Свободная/инженерная |

**Проблема parity:** два twin визуально расходятся — разные акценты освещения/композиции/детализации. Для жюри это снижает ощущение «одной реальной линии».

---

## 3. Чек-лист визуальных факторов

| Фактор | Статус | Комментарий | Тип |
| ------ | ------ | ----------- | --- |
| Геометрия / пропорции | Частично OK | Layout в мм через `physicalLayout` | Измерено |
| Масштаб сцены | OK | Единая физическая раскладка | Измерено |
| Камера / перспектива | OK на `/` | Cinematic playback | Измерено |
| Focal length / DoF | Минимально | DoF не форсируется (мешает чтению) | Оценка |
| Освещение | Среднее | Достаточно для читаемости; не studio HDRI | Оценка |
| Контактные тени | Ограничено | `shadows: false` в quality presets (perf) | Измерено |
| AO / post FX | Выкл. в presets | `effectsEnabled: false` | Измерено |
| Материалы PBR | Базовые | Шероховатость/металл упрощены | Оценка |
| Текстуры / загрязнения | Слабо | Нет сильного wear layer | Оценка |
| Края / bevel | Частично | STL + примитивы | Оценка |
| Движение ленты / ролики | OK с trade-off | Static/sparse rollers в perf-режимах | Измерено (ветка perf) |
| Приводы / задержки | Симулированы кинематикой | Не servo-physics | Измерено |
| Motion blur | Нет | Сознательно | Измерено |
| Anti-aliasing | По режиму | low/medium off; high/demo on | Измерено |
| Звук / вибрация | Нет | Не реализовано | Измерено |
| Заполнение накопителей | Упрощено | B receiver timing учтён в истории perf | Измерено (история) |
| CV overlay | Есть | RULE line + inspection | Измерено |
| Presentation declutter | Есть | Скрытие панелей в presentation | Измерено |

---

## 4. Режимы качества

Источник: `src/domain/qualityMode.ts` (**Измерено**).

| Mode | dprMax | AA | Shadows | maxItems | rollers | target FPS |
| ---- | -----: | -- | ------- | -------: | ------- | ---------: |
| low | 1 | нет | нет | 3 | none | 30 |
| medium | 1.25 | нет | нет | 5 | sparse | 30 |
| high | 1.5 | да | нет | 6 | full | 60 |
| demo | 1.5 | да | нет | 6 | full | 60 |

Автовыбор: по ширине viewport и опционально по recent FPS; `adaptQuality` понижает режим при просадке.

**Целевая демо:** стабильные 60 FPS при возможности, иначе стабильные 30 без рывков (**требование брифа**; фактический FPS на клиенте жюри — **не измерен в этом аудите на всех устройствах**).

---

## 5. Что выглядит убедительно

- Непрерывный путь товара от входа до B/C/D с подписями зон.  
- STL-модели там, где ассет доступен; осознанные fallbacks для тяжёлых STL.  
- Proof HUD и CV overlay связывают картинку с решением.  
- Fault визуально останавливает поток (freeze).  
- Presentation mode убирает engineering chrome.

---

## 6. Что снижает доверие («игровое»)

| Симптом | Почему заметно | Рекомендация |
| ------- | -------------- | ------------ |
| Разный вид `/` и `/details` | «Две разные игрушки» | Shared scene kit (Open) |
| Нет теней/AO | Плоские объекты | Осторожно включить в demo на мощных GPU клиентов |
| Pseudo-CV bbox | Идеальная геометрия | Оставить RULE + confidence честно |
| Отсутствие звука | Тихая «сцена» | Опциональный ambient loop (низкий приоритет) |
| Идеально ровное движение без контактов | Нет micro-collisions | Seeded jitter уже частично компенсирует |

---

## 7. Критичность для показа

| Приоритет | Находка | Действие |
| --------- | ------- | -------- |
| P0 | Proof + classification visible | Сделано |
| P0 | Presentation + hotkeys | Сделано |
| P1 | Twin visual unify | Open |
| P2 | Shadows/AO в demo-only | Open, perf-gated |
| P3 | Sound / wear textures | Backlog |

---

## 8. Вывод

Визуальный стек **достаточен**. Узкое место не «не тот движок», а **согласованность двух сцен** и **сдержанный shading ради FPS**. Для жюри важнее читаемый контур решения, чем ray-traced реализм. Следующий максимум ROI: унификация twin + актуальный production dist.