👁️ Direction

Конвейер генерации синтетических данных и среда симуляции для машинного обучения

Сокращение разрыва Sim2Real с помощью точной генерации данных и интерактивного взаимодействия со средой симуляции.

direction-ai.tech

---

⚡ Что это такое?

Direction — это открытый фреймворк, предназначенный для создания качественных датасетов под задачи компьютерного зрения (Object Detection: YOLO, PASCAL VOC, COCO), а также для построения интерактивных симуляций для различных моделей машинного обучения.

В отличие от стандартных генераторов, которые строят рамки разметки по упрощенным границам коллайдеров, Direction использует алгоритм Raycast Surface Sampling. Он сканирует реальную геометрию трехмерных объектов (включая анимированные сетки персонажей — Skinned Meshes), учитывая перекрытия, препятствия и перспективу камеры.

Благодаря быстрой двусторонней связи между Unity и Python через протокол ZeroMQ, проект не ограничивается только экспортом картинок. Его можно использовать как динамический симулятор для более сложных сценариев — например, для обучения агентов с подкреплением, где модель в реальном времени реагирует на состояние виртуального мира.

---

✨ Ключевые возможности

🎯 Точная разметка для компьютерного зрения

• Raycast Occlusion Culling: Метод проекции облака точек определяет реальную видимость объекта. Если объект частично скрыт препятствием, рамка разметки автоматически адаптируется и охватывает только ту часть, которую действительно видно на камере.
• Поддержка Mesh и SkinnedMesh: Корректная работа как со статическими трехмерными моделями, так и со сложными анимированными персонажами.
• Dynamic Baking: Динамическое запекание деформаций сетки в реальном времени для построения точной разметки в любой фазе движения (например, при беге или прыжке).

🤖 Гибкость и обучение с подкреплением (RL)

• Среда закрытого цикла: Наличие постоянного интерактивного соединения позволяет реализовать цикл «наблюдение — действие». Вы можете передавать данные о состоянии симуляции (координаты объектов, сенсоры, изображения) в Python, обрабатывать их своей моделью и отправлять команды управления обратно в Unity.
• Успешные тесты в RL: Архитектура проекта позволяет интегрировать внешние библиотеки для обучения агентов навигации, избеганию препятствий или управлению роботизированными системами внутри сцены.
• Универсальный API: Фреймворк спроектирован так, чтобы конечный пользователь мог передавать любые типы данных и метаданных, адаптируя систему под свои исследовательские или прикладные задачи.

🌐 Технологии переноса из симуляции в реальность (Sim2Real)

• Domain Randomization (DR): Случайная генерация параметров окружения: изменение освещения, погодных условий, текстур, материалов и цвета объектов для повышения обобщающей способности моделей.
• Вариативность камеры: Автоматическое изменение угла обзора, наклона, высоты и крена камеры для имитации случайной или неточной установки реальных сенсоров.
• Имитация оптических искажений: Наложение эффектов реальных линз (шум матрицы, размытие при движении, хроматическая аберрация и дисторсия).

🔌 Интеграция с Python через ZeroMQ

• Шаблоны REQ-REP и PUB-SUB: Налаженный обмен сообщениями позволяет гибко управлять симуляцией со стороны скриптов на Python (запуск, остановка, сброс сцены, изменение параметров физики).
• Высокая скорость работы: Данные могут передаваться по сетевым сокетам напрямую в память, минуя промежуточную запись на жесткий диск, что снижает задержки при обучении моделей.

---

📊 Результаты применения в задачах компьютерного зрения

Пример показателей точности при обучении модели YOLOv11m на гибридной выборке (97% синтетических данных, сгенерированных в Direction, и 3% реальных изображений для адаптации домена).

Метрика	COCO Baseline	Direction	Статус
mAP50	~0.72	0.71+	🚀 Близко к целевому значению
mAP50-95	0.51	0.48 - 0.52	✅ Стабильный результат

Гибридный подход позволяет значительно сократить затраты на ручную разметку реальных данных при сохранении сопоставимого качества работы алгоритмов в реальных условиях эксплуатации.

---

🛠 Архитектура

Сторона C# (Unity)

За отправку и прием сообщений отвечает класс ZeroMqManager. Логика обработки геометрии объектов реализована в компоненте TrainingObject:

// Пример обработки статической и динамической геометрии в движке
if (isStatic) {
    // Кэшируется один раз для сохранения высокой производительности (здания, инфраструктура)
    points = _staticParts; 
} else {
    // Временное запекание сетки анимации каждый кадр для точного отслеживания контуров
    skinnedMeshRenderer.BakeMesh(_tempMesh);
    points = ScanMesh(_tempMesh);
}

Сторона Python (Интеграция и управление)

Скрипты запускаются на стороне Python, подключаются к Unity и могут решать как задачи сбора данных, так и задачи пошагового управления агентами.

from unity_connector import UnityConnector

# Инициализация подключения к запущенной симуляции
connector = UnityConnector(script_name="simulation_controller.py")

# Сценарий 1: Обработка команд управления интерфейсом из Unity
connector.on_command("SET_THRESHOLD", lambda data: update_params(data))

# Сценарий 2: Пример интеграции с циклом обучения с подкреплением (RL)
@connector.on_event("ENVIRONMENT_STATE")
def handle_state(state_data):
    # Получаем текущее состояние среды (вектор признаков или изображение)
    observation = state_data["observation"]
    
    # Передаем состояние в вашу модель машинного обучения
    action = my_ml_model.predict(observation)
    
    # Отправляем выбранное действие обратно в Unity для выполнения
    connector.send_event("EXECUTE_ACTION", {"action": action})

---

🚀 Начало работы

Требования

1. Unity 2021.3+ (поддерживаются конвейеры рендеринга URP и Built-in RP).
2. Пакет NetMQ (устанавливается через NuGet внутри Unity).
3. Python 3.9+ с установленной библиотекой pyzmq.

Установка

1. Клонируйте репозиторий:

   git clone https://github.com/TheLemzz/Direction.git

2. Откройте проект в Unity Editor.
3. Установите необходимые Python-зависимости:

   pip install -r requirements.txt

Базовый сценарий использования (Генерация данных)

1. Настройка сцены в Unity:
   • Разместите префаб ZeroMqManager на вашей рабочей сцене.
   • Добавьте компонент YOLOAnnotationGenerator на камеру, которая будет производить съемку.
2. Подготовка объектов разметки:
   • Добавьте скрипт TrainingObject.cs на объекты, которые модель должна распознавать.
   • Для неподвижных объектов (например, зданий или дорожных знаков) включите параметр IsStatic.
   • Для динамических или анимированных объектов (персонажей, животных) отключите параметр IsStatic.
3. Запуск:
   • Запустите сцену в Unity в режиме Play, укажите директорию для сохранения данных и начните процесс. Система автоматически начнет рандомизировать окружение и экспортировать аннотации в формате YOLO (.txt) параллельно с процессом симуляции.

---

🤝 Вклад в проект

Если вы нашли ошибку, хотите предложить улучшение или поделиться своим сценарием использования (включая новые алгоритмы RL или интеграцию с другими фреймворками), пожалуйста, создайте тему в разделе Issues или отправьте свой Pull Request.

---

📄 Лицензия

Проект распространяется под свободной лицензией Apache 2.0. Подробная информация находится в файле LICENSE.