diff --git a/README.md b/README.md index 12e795f..21c8e29 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,133 @@ -Для работы установите дополнительные модули и файл `requirements.txt`: +## Структура проекта +``` +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` содержит всё необходимое для обучения собственных моделей жестов. diff --git a/config.py b/config.py index 54c9a9b..f27e204 100644 --- a/config.py +++ b/config.py @@ -6,7 +6,7 @@ class Config: # ===== Скелет ===== POSE_DETECTOR = 'mediapipe' # 'oak' или 'mediapipe' - OAK_MODEL_TYPE = 'efficienthrnet2' + OAK_MODEL_TYPE = 'efficienthrnet1' OAK_DETECTION_THRESHOLD = 0.1 OAK_SHAVES = 6 diff --git a/images/arm_control.png b/images/arm_control.png new file mode 100644 index 0000000..1345bcb Binary files /dev/null and b/images/arm_control.png differ diff --git a/images/gesture_control.png b/images/gesture_control.png new file mode 100644 index 0000000..90850d3 Binary files /dev/null and b/images/gesture_control.png differ