Hand Tracking Gamepad Controller

Проект представляет собой программу, которая позволяет управлять виртуальным геймпадом с помощью жестов рук, распознаваемых через веб-камеру. Для трекинга рук используется MediaPipe Hands, а для эмуляции геймпада - библиотека vgamepad.

---

Возможности

• Управление левым и правым стиком геймпада с помощью положения ладоней

• Поддержка двух рук

• Распознавание состояния пальцев (согнут / разогнут)

• Эмуляция кнопок геймпада:

  • A
  • LB
  • RB
  • START

• Зеркальный режим

• Смена фона (камера / зелёный / синий)

• Визуализация скелета руки и состояний пальцев

---

Ограничения и бинды

Важно: в программе реализована только часть кнопок геймпада.

Это сделано намеренно - проект писался под конкретную игру (Hotline Miami), где не требовался полный набор кнопок Xbox-геймпада. Тем не менее, логика проекта не ограничивает пользователя:

• Вы можете добавлять собственные бинды
• Расширять существующую систему жестов
• Назначать дополнительные кнопки или триггеры

Для этого достаточно дописать обработку жестов и вызвать соответствующие методы vgamepad.

---

Управление

Стики

• Левая рука → левый стик
• Правая рука → правый стик
• Смещение ладони относительно центра зоны определяет направление и силу отклонения стика

Кнопки (по умолчанию)

Жест	Описание жеста	Зона	Кнопка
✊	Все пальцы сжаты	Левая	A
🤟	Указательный + мизинец, без большого	Левая	LB
✊	Все пальцы сжаты	Правая	RB
🤟	Указательный + мизинец, без большого	Правая	START

---

Зависимости

Версия Python: 3.12, конкретно этот проект делался на 3.12.6

Рабочая версия mediapipe, на которой делался проект:

mediapipe==0.10.21

НЕ работает на более новых версиях (например, 0.10.32) из-за изменений во внутренней логике MediaPipe Hands.

Полный список зависимостей:

pip install mediapipe==0.10.21 opencv-python numpy vgamepad

---

Установка и запуск

0. Установка Python

Для работы проекта требуется Python 3.12.6.

Скачайте Python с официального сайта:

При установке обязательно отметьте галочку: Add Python to PATH

Проверить успешность установки можно командой:

python --version

Должно отобразиться:

Python 3.12.6

---

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

Склонируйте репозиторий с GitHub (либо скачайте zip и распакуйте):

git clone https://github.com/kiraping1337/hand-tracking-gamepad.git

---

2. Создание виртуального окружения (venv)

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

Windows

python -m venv venv
venv\Scripts\activate

После активации окружения в терминале появится префикс (venv).

---

3. Установка зависимостей

Установите необходимые библиотеки:

pip install mediapipe==0.10.21 opencv-python numpy vgamepad

⚠️ Важно: проект работает только с MediaPipe версии 0.10.21. На более новых версиях (например, 0.10.32) программа не запускается корректно.

---

4. Установка ViGEmBus

Для работы библиотеки vgamepad требуется установленный ViGEmBus Driver.

Если виртуальный геймпад не появляется в системе или игра не реагирует на ввод, убедитесь, что драйвер установлен.

---

5. Запуск программы

Подключите веб-камеру и запустите скрипт:

python main.py

---

Горячие клавиши

Клавиша	Действие
q	Выход
b	Синий фон
g	Зелёный фон
r	Обычная камера
m	Вкл/выкл зеркальный режим

---

Как добавить свой бинд

Добавление собственного бинда сводится к трём шагам: описание жеста, создание флага кнопки и применение его к геймпаду.

---

1. Определение жеста

В программе уже реализовано распознавание состояния пальцев в виде словаря fingers:

• fingers["thumb"]
• fingers["index"]
• fingers["middle"]
• fingers["ring"]
• fingers["pinky"]

Каждое значение True (палец разогнут) или False (палец согнут).

Примеры жестов:

• Кулак: все значения False
• Два пальца: index=True, middle=True, остальные False
• Указательный палец: index=True, остальные False

---

2. Создание флага кнопки

В начале основного цикла объявите новый флаг кнопки, например для кнопки X:

btn_x = False

---

3. Привязка жеста к кнопке

В блоке логики управления кнопками геймпада добавьте условие для нужной зоны.

Пример: кнопка X нажимается, если на левой руке подняты указательный и средний пальцы:

if zone_name == "Left Zone":
    if fingers["index"] and fingers["middle"] and not fingers["ring"] and not fingers["pinky"]:
        btn_x = True

---

4. Применение кнопки к геймпаду

Ниже, в секции применения данных к геймпаду, добавьте обработку кнопки:

if btn_x:
    gamepad.press_button(vg.XUSB_BUTTON.XUSB_GAMEPAD_X)
else:
    gamepad.release_button(vg.XUSB_BUTTON.XUSB_GAMEPAD_X)

После этого кнопка X будет корректно нажиматься и отпускаться в зависимости от жеста.