## Структура проекта
```
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 update --init --remote --recursive
    
В будущем, чтобы подтянуть в сабмодулях изменения последнего коммита:

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

    python3.10 -m venv venv
    source venv/bin/activate
    
Если у вас не скачен питон этой версии, сначала выполните:
```
sudo apt install python3.10 python3.10-venv
```

Если у нас не устанавливается питон 3.10, то это потому что он отсутствует в официальных репозиториях по умолчанию, надо добавить репозиторий перед скачиванием:
```
sudo apt update && sudo apt install -y software-properties-common
sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt update
```
    
### 4. Установка зависимостей

#### 4.1. Способ 1

Сделайте bash скрипт исполняемым и запустите последовательность установки:

    chmod +x install_deps.sh
    ./install_deps.sh

#### 4.2. Способ 2

Вручную:

    pip install --upgrade pip
    pip install numpy==1.24.3
    pip install pandas==2.0.3
    pip install pyyaml==6.0.3
    pip install opencv-python==4.12.0.88
    pip install opencv-python-headless==4.12.0.88
    pip install matplotlib==3.7.5
    pip install protobuf==3.20.3
    pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu
    pip install --no-deps mediapipe==0.10.11
    pip install attrs
    pip install scikit-learn==1.3.2
    pip install joblib==1.4.2
    pip install depthai==2.28.0
    pip install --no-deps tensorflow==2.13.1
    pip install \
        absl-py \
        astunparse \
        flatbuffers \
        gast \
        google-pasta \
        grpcio \
        h5py \
        keras==2.13.1 \
        libclang \
        opt-einsum \
        tensorboard==2.13.0 \
        tensorflow-estimator==2.13.0 \
        termcolor \
        wrapt \
        requests
    pip install numpy==1.24.3
    pip install scipy==1.11.0
    pip install pygame==2.6.1
    
#### Типичные проблемы во время установки:
Важно: красные предупреждения о нехватке зависимостей для tensorflow будут, но можно их игнорировать, т.к. эти модули не используются в данном проекте, а их установка мешает зависимостям MediaPipe.

1. Если будет ошибка с `"AttributeError: google..."` но это потому что `tensorflow` подменяет версию библиотеки `protobuf`, выполните:
```
pip uninstall protobuf google protobuf
pip install protobuf==3.20.3
```
Примечание: если у вас слабая видеокарта или нет CUDA, используйте `tensorflow-cpu` вместо `tensorflow`.

2. Если будет проблема с функцией cv2.imshow() то, переустановите cv2 без заголовков:
```
pip uninstall opencv-python opencv-python-headless
pip install opencv-python==4.12.0.88
```
3. Если будет ошибка с PIL, попробуйте обновить библиотеку:
```
pip upgrage pillow
```
4. **Внимание:** если вам пришлось делать после основной установки какие-то дополнительные, обязательно зафиксируйте еще раз версию numpy!
```
pip install numpy==1.24.3
```

## Настройка
Все основные параметры находятся в классе `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' (вывод команд в консоль)

### Пути к моделям:
Требуется указать свои абсолютные пути к используемым моделям, предобученные можно скачать [отсюда](https://git.robofob.ru/sirius/gesture_rec.git), пролистайте в конец.

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

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

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

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

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