dummy_simulation/README.md

## Структура проекта
```
gesture_rec/
├── config.py                    # Главный файл настроек
├── main.py                      # Точка входа
├── geom_controll
│   └── arm_control.py           # Преобразование позы в скорости
├── robot/
│   ├── debug_robot.py           # Робот-заглушка (вывод в консоль)
│   └── simulated_robot.py       # Симулятор с Pygame
├── submodules/
│   ├── gesture_detection/       # Распознавание скелета, жестов, ML
│   └── robot_controller_base/   # Базовый класс робота
├── requirements.txt
├── robot.png                    # Картинка робота для симуляции
└── README.md
```

## Установка

### 1. Клонирование репозитория

    git clone https://git.robofob.ru/sirius/dummy_simulation.git
    cd dummy_simulation
    
### 2. Инициализация подмодулей
Проект использует два внешних подмодуля:

- `robot_controller_base` – базовый класс для робота
- `gesture_detection` – модуль распознавания жестов (скелет, ML-детекторы)

Установка:
    
    git submodule add --branch main https://git.robofob.ru/sirius/robot_controller.git submodules/robot_controller_base
    git submodule add --branch main https://git.robofob.ru/sirius/gesture_rec.git submodules/gesture_detection

Если подмодули уже добавлены, обновите их:

    git submodule update --init --remote --recursive
    
### 3. Создание и активация виртуального окружения

    python3 -m venv venv
    source venv/bin/activate
    
### 4. Установка зависимостей

    pip install --upgrade pip
    pip install -r requirements.txt
    
Примечание: если у вас слабая видеокарта или нет CUDA, используйте `tensorflow-cpu` вместо `tensorflow`.

## Настройка
Все основные параметры находятся в классе `Config`. Перед запуском обязательно отредактируйте их под вашу конфигурацию.

### Камера
- `CAMERA_ID` – ID устройства (только для CAMERA_TYPE = 'web')
- `CAMERA_TYPE` – 'web' (обычная USB-камера) или 'oak' (OAK‑D)
- `MIRROR_CAMERA` – зеркалировать изображение (обычно True для естественного отображения)

### Детектор скелета
- `POSE_DETECTOR` – 'mediapipe' или 'oak' (только при CAMERA_TYPE='oak')
- `OAK_MODEL_TYPE` – модель для OAK (например 'efficienthrnet1')
- `OAK_DETECTION_THRESHOLD` – порог уверенности (0.0–1.0)
- `OAK_SHAVES` – число SHAVE-ядер для OAK

### Преобразование позы в скорости
- `ARM_CONTROL` – словарь:
    - `linear_arm` – рука для линейной скорости ('left' или 'right')
    - `angular_arm` – рука для угловой скорости
    - `max_speed_linear` – макс. линейная скорость (м/с)
    - `max_speed_angular` – макс. угловая скорость (рад/с)
    - `dead_zone` – зона нечувствительности (0.0–1.0)
    - `debug` – выводить отладочную информацию в консоль
    
### Статические жесты
- `SPECIAL_GESTURE_MODE` – 'ml' (использует модель для предсказания) или 'geometric' (геометрический)
- `ML_GESTURE_MODEL` – путь к обученной модели .pkl
- `ML_GESTURE_CLASSES` – список классов (например ['dome', 'cross', 'none'])

### Динамические жесты
- `DYNAMIC_GESTURE` ['enabled'] – включить/выключить
- `model_path` – путь к модели .h5
- `classes_path` – путь к файлу с классами (pickle)
- `window_size` – размер окна (число кадров)
- `threshold` – порог уверенности

### Симуляция:
- `MAP_WIDTH`, `MAP_HEIGHT` – размеры поля
- `BORDER_THICKNESS` – толщина стен
- `MAP_OBSTACLES` – список прямоугольных препятствий (x, y, w, h)
- `START_POS`, `FINISH_POS` – позиции старта и финиша
- `ROBOT_RADIUS` – радиус робота (пиксели)
- `ROBOT_IMAGE_PATH` – путь к PNG-изображению робота (или None - тогда будет треугольник)
- `INITIAL_HP`, `INITIAL_FIRE_CHARGE` – начальные HP и заряд для тушения
- `COLLISION_DAMAGE` – урон при столкновении с препятствием
- `EXTINGUISH_RADIUS`, `EXTINGUISH_ANGLE` – параметры конуса тушения (радиус и угол в градусах)
- `NUM_FIRES`, `FIRE_RADIUS`, `SCORE_PER_FIRE` – количество очагов, их радиус и очки за тушение
- `ROBOT_MODE` – 'simulator' (запуск игры с Pygame) или 'debug' (вывод команд в консоль)

### Пути к моделям:
Требуется указать свои абсолютные пути к используемым моделям.

## Запуск
Активируйте виртуальное окружение и выполните:
    
    python main.py
    
## Управление
Симулятор – поле с препятствиями, стартом и финишем. Робот движется согласно командам. При врезании в препятствия - получает урон. Некоторое время после урона (во время мигания) неуязвим, чтобы у вас было время вырулить. 
1. Управление скоростями
    - Линейная скорость (вперёд) – горизонтальное положение правой руки (рука вдоль тела – 0, вытянута в сторону – максимум).
    - Угловая скорость – вертикальное положение левой руки (рука на уровне плеча – 0, вверх – поворот вправо, вниз – поворот влево).
    
![Схема управления скоростями](images/arm_control.png)

2. Управление действиями
    - Включение/выключение управления скоростями – жест `cross` (скрещённые руки). При выключении робот останавливается.
    - Тушение пожара – жест `dome` (руки над головой). Если огонь попадает в конус перед роботом, он тушится. Заряд тушения тратится в любом случае.

![Схема управления жестами](images/gesture_control.png)

Закрытие окна игры или нажатие `q` в окне камеры – выход. При завершении игры (неважно выигрыш или проигрыш) нажмите `r` чтобы перезапустить симулятор.

## Создание собственного контроллера скоростей
По умолчанию преобразование позы в скорости реализовано в классе `ArmController` (файл `arm_control.py`).
Чтобы изменить логику управления, выполните одно из действий:
1. Изменить метод `compute_speeds` в `arm_control.py` – он должен принимать аргумент landmarks (список из 33 точек MediaPipe) и возвращать кортеж (linear, angular) – числа с плавающей точкой.
2. Создать свой класс-наследник от `ArmController` и переопределить `compute_speeds`. Затем в `main.py` заменить создание экземпляра на свой класс.

После этого не забудьте изменить параметры словаря `ARM_CONTROL` в `Config` вы можете добавлять туда свои поля и читать их в методе.
## Добавление своих жестов
Подмодуль `gesture_detection` содержит всё необходимое для обучения собственных моделей жестов.