Структура проекта

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.11 -m venv venv
source venv/bin/activate

Если у вас не скачен питон этой версии, сначала выполните:

sudo apt install python3.11 python3.11-venv

Если у нас не устанавливается питон 3.11, то это потому что он отсутствует в официальных репозиториях по умолчанию, надо добавить репозиторий перед скачиванием:

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 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 pip install 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' (вывод команд в консоль)

Пути к моделям:

Требуется указать свои абсолютные пути к используемым моделям, предобученные можно скачать отсюда, пролистайте в конец.

Запуск

Активируйте виртуальное окружение и выполните:

python main.py

Управление

Симулятор – поле с препятствиями, стартом и финишем. Робот движется согласно командам. При врезании в препятствия - получает урон. Некоторое время после урона (во время мигания) неуязвим, чтобы у вас было время вырулить.

1. Управление скоростями
   • Линейная скорость (вперёд) – горизонтальное положение правой руки (рука вдоль тела – 0, вытянута в сторону – максимум).
   • Угловая скорость – вертикальное положение левой руки (рука на уровне плеча – 0, вверх – поворот вправо, вниз – поворот влево).

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

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

Добавление своих жестов

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