From 0b3c74c4632339ba743bd2093c50d40cdf5de4ab Mon Sep 17 00:00:00 2001 From: moscovskayaliza Date: Thu, 25 Jun 2026 13:51:10 +0300 Subject: [PATCH] upd readme --- README.md | 62 +++++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 47 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index cefc881..2d3a83e 100644 --- a/README.md +++ b/README.md @@ -19,7 +19,8 @@ gesture_rec/ ├── skeleton/ # Детекция скелета │ ├── oak_pose_detector.py # Детектор на oak (efficienthrnet) │ └── mediapipe_detector.py # MediaPipe -├── gesture_control/ # Распознавание статичных жестов +├── gesture_control/ +│ ├── arm_control.py # Преобразование позы в значения для угловой и линейной скоростей │ └── special_gestures.py # Специальные жесты (геометрия или ML) ├── ml_gestures/ # ML для статичных жестов │ ├── feature_extractor.py # Нормализация landmarks @@ -207,7 +208,38 @@ vis = detector.draw_landmarks(frame, landmarks) Подробнее о параметрах модели в [репозитории](https://github.com/kschlegel/OAK-HumanPoseEstimation.git). -### 1. Геометрическое распознавание жестов +### 1. Определение значений скоростей +По умолчанию преобразование позы в скорости реализовано в классе `ArmController` (файл `arm_control.py`). + +Чтобы изменить логику управления, выполните одно из действий: +1. Изменить метод `compute_speeds` в `arm_control.py` – он должен принимать аргумент landmarks (список из 33 точек MediaPipe) и возвращать кортеж (linear, angular) – числа с плавающей точкой. +2. Создать свой класс-наследник от `ArmController` и переопределить `compute_speeds`. Затем в `main.py` заменить создание экземпляра на свой класс. + +После этого не забудьте изменить параметры словаря `ARM_CONTROL`, вы можете добавлять туда свои поля и читать их в методе. Текущий класс создается и используется следующим образом: +``` +from gesture_control.arm_control import ArmController + +mirror = True # для всех фронтальных камер +ARM_CONTROL = { + 'linear_arm': 'right', + 'angular_arm': 'left', + 'max_speed_linear': 1.0, + 'max_speed_angular': 1.0, + 'dead_zone': 0.2, + 'debug': False + } +arm_control = ArmController(ARM_CONTROL, mirror=mirror) +linear, angular = arm_control.compute_speeds(landmarks) # Дальше эти скорости можно подавать на контроллер +``` +- `ARM_CONTROL` – словарь: + - `linear_arm` – рука для линейной скорости ('left' или 'right') + - `angular_arm` – рука для угловой скорости + - `max_speed_linear` – макс. линейная скорость (м/с) + - `max_speed_angular` – макс. угловая скорость (рад/с) + - `dead_zone` – зона нечувствительности (0.0–1.0) + - `debug` – выводить отладочную информацию в консоль + +### 2. Геометрическое распознавание жестов Класс `SpecialGestureDetector` в режиме `mode='geometric'` анализирует координаты скелета и применяет набор правил. На текущий момент геометрически распознаются два жеста: @@ -216,7 +248,7 @@ vis = detector.draw_landmarks(frame, landmarks) Все пороги (уверенность `min_conf`, коэффициенты) заданы внутри `_geometric_predict` и могут быть подстроены под ваши условия. Чтобы распознавать собственный жест, отредактируйте метод `_geometric_predict` в файле `gesture_control/special_gestures.py`. -#### 1.1. Порядок действий: +#### 2.1. Порядок действий: 1. Определите, какие ключевые точки MediaPipe участвуют в жесте (список индексов см. в коде или в документации MediaPipe). 2. Напишите условие, используя координаты `(x, y)` нужных точек. Например, жест «рука в сторону»: `left_wrist[0] > left_shoulder[0] + width` и `right_wrist[0] < right_shoulder[0] - width`. 3. Вставьте проверку до финального return 'none', чтобы при совпадении условий возвращать строку с именем вашего жеста. @@ -230,15 +262,15 @@ if arms_out: ``` **Важно:** геометрический режим не требует обучения, но чувствителен к позе и ракурсу. Для более сложных жестов рекомендуем использовать ML. -#### 1.2. Использование в коде: +#### 2.2. Использование в коде: ``` from gesture_control.special_gestures import SpecialGestureDetector detector = SpecialGestureDetector(mode='geometric') gesture = detector.predict(landmarks) # вернет none или название жеста ``` -### 2. ML-распознаванием статичных жестов +### 3. ML-распознаванием статичных жестов Распознавание отдельных кадров с помощью обученного классификатора. -#### 2.1. Сбор датасета +#### 3.1. Сбор датасета Создай папку для изображений. Можешь поместить туда фотографии жестов из интернета. Либо же можешь самостоятельно снять изображения с камеры: Скрипт `utils/capture_photo.py` сохраняет изображения с камеры. ``` @@ -253,7 +285,7 @@ python3 utils/capture_photo.py --dir data/raw --camera_type web Управление: `s` – начать обратный отсчёт (3 сек) и сохранить фото, `q` – выход. Нажмите `s`, подождите 3 секунды, фото сохранится в папку `data/raw`. Нажмите `q` чтобы закончить. -#### 2.2. Разметка +#### 3.2. Разметка Скрипт `utils/annotate.py` показывает каждое фото с распознанным скелетом и позволяет назначить класс: ``` python3 utils/annotate.py --folder data/raw --classes dome,cross,none --output data.csv @@ -266,7 +298,7 @@ python3 utils/annotate.py --folder data/raw --classes dome,cross,none --output d Управление: для каждого фото нажмите цифру, соответствующую жесту (1–dome, 2–cross, 3–none), или `n` для пропуска или `q` – выйти. При выходе данные сохранятся в `gesture_data.csv`. CSV с колонками `class`, `f0…f98` (99 нормализованных координат). -#### 2.3. Обучение модели +#### 3.3. Обучение модели ``` python3 ml_gestures/train.py --csv data.csv --model ml_gestures/models/special_model.pkl --type mlp --balance --target_classes dome,cross ``` @@ -281,7 +313,7 @@ python3 ml_gestures/train.py --csv data.csv --model ml_gestures/models/special_m После обучения сохраняются модель и отчёт `special_model_report.json` с метриками (accuracy, precision/recall/f1 по классам, матрица ошибок). -#### 2.4. Оценка модели +#### 3.4. Оценка модели После обучения модель сохраняется, и создаётся отчёт `special_model_report.json` с метриками (`accuracy`, `precision`, `recall`, `f1`, `confusion matrix`). Для повторной оценки используйте: ``` python3 ml_gestures/evaluate.py --csv data.csv --model ml_gestures/models/special_model.pkl --test_size 0.2 @@ -293,7 +325,7 @@ python3 ml_gestures/evaluate.py --csv data.csv --model ml_gestures/models/specia Печатает результаты тестирования в консоль. -#### 2.5. Использование обученной модели +#### 3.5. Использование обученной модели ``` from ml_gestures.predict import MLGesturePredictor @@ -301,9 +333,9 @@ predictor = MLGesturePredictor('model.pkl', class_names=['dome','cross','none']) gesture = predictor.predict(landmarks) # возвращает строку с классом ``` -### 3. ML-распознавание динамических жестов +### 4. ML-распознавание динамических жестов Распознавание жестов по последовательности кадров с помощью LSTM. -#### 3.1. Сбор датасета +#### 4.1. Сбор датасета Скрипт `utils/record_dynamic.py` записывает серию кадров (скелет) в течение заданной длительности. ``` python3 utils/record_dynamic --label wave_right --output dynamic_data.csv --duration 2.0 @@ -318,7 +350,7 @@ python3 utils/record_dynamic --label wave_right --output dynamic_data.csv --dura Управление: нажмите `space`, через 3 секунды начнется запись, последовательность точек с меткой сохранится в файл `dynamic_data.csv`. В CSV сохраняются колонки: `label`, `sequence_id`, `frame_idx`, `f0…f98`. Нажмите `q` чтобы закончить. **Важно**: при записи в консоль выводится число кадров последовательности – используйте его как ориентир для `--max_len` в обучении (можно округлить вверх). -#### 3.2. Обучение LSTM +#### 4.2. Обучение LSTM ``` python3 ml_gestures_dynamic/train --data dynamic_data.csv --model dynamic_model.h5 --max_len 14 --epochs 50 --test_size 0.2 ``` @@ -333,7 +365,7 @@ python3 ml_gestures_dynamic/train --data dynamic_data.csv --model dynamic_model. После обучения сохраняются: модель (`.h5`), файл с классами (`_classes.pkl`) и отчёт (`_report.json`) с метриками. -#### 3.3. Оценка модели +#### 4.3. Оценка модели После обучения модель сохраняется, и создаётся отчёт `dynamic_model_report.json` с метриками (`accuracy`, `precision`, `recall`, `f1`, `confusion matrix`). Для повторной оценки используйте: ``` python3 ml_gestures_dynamic/evaluate --data dynamic_data.csv --model dynamic_model.h5 --max_len 14 --test_size 0.2 @@ -344,7 +376,7 @@ python3 ml_gestures_dynamic/evaluate --data dynamic_data.csv --model dynamic_mod - `--max_len` – длина последовательности (количество кадров). Должен совпадать с длиной, использованной при записи. Если последовательности короче, они дополняются нулями; если длиннее – обрезаются. - `--test_size` – доля тестовой выборки (по умолчанию 0.2). -#### 3.4. Использование в коде +#### 4.4. Использование в коде Класс `DynamicGesturePredictor` накапливает кадры в буфере и выдаёт предсказание, когда накоплено достаточно данных. ``` from ml_gestures_dynamic.predict import DynamicGesturePredictor