Unity Airplane Environment

🛩️ Высокореалистичная среда симуляции полёта для обучения с подкреплением

Особенности • Установка • Быстрый старт • Архитектура • Обучение • Лицензия

---

📖 О проекте

Unity Airplane Environment — это комплексная среда для обучения автономных агентов управлению летательными аппаратами с использованием методов глубокого обучения с подкреплением (Deep Reinforcement Learning).

Проект разработан в рамках инициативы TensorAeroSpace и предоставляет:

• 🎯 Реалистичную физическую модель аэродинамики
• 🤖 Интеграцию с Unity ML-Agents
• 🌍 Детализированные 3D-карты и окружения
• 🌦️ Динамические погодные условия
• 📊 Инструменты мониторинга и визуализации

---

✨ Особенности

🛫 Физика полёта

Компонент	Описание
Аэродинамика	Полноценная модель подъёмной силы, сопротивления и моментов
Управляющие поверхности	Элероны, рули высоты, рули направления, закрылки
Двигательная система	Реалистичная модель тяги с расходом топлива
Центр масс	Динамическое управление центром тяжести

🤖 ML-Agents интеграция

Пространство наблюдений (Observations):
├── Ориентация самолёта (roll, pitch, yaw)
├── Вектор до цели (направление + расстояние)
├── Скорость и высота
├── Состояние управляющих поверхностей
├── Параметры двигателя
└── G-нагрузка и аэродинамические углы

Пространство действий (Actions):
├── Тяга двигателя      [-1, 1]
├── Элероны (крен)      [-1, 1]
├── Руль высоты         [-1, 1]
└── Руль направления    [-1, 1]

🌍 Окружение

• Карта Llanbedr — детализированная местность для тестовых полётов
• Ангары и постройки — модульная система зданий
• Погодные эффекты — дождь, ветер, изменяющиеся условия
• Живая природа — анимированные птицы для реалистичности

---

📦 Установка

Требования

• Unity 2023.2.20f1 или новее
• Unity ML-Agents Package
• Git LFS (для больших файлов)

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

# Клонирование с поддержкой Git LFS
git lfs install
git clone https://github.com/TensorAeroSpace/UnityAirplaneEnvironment.git
cd UnityAirplaneEnvironment

Открытие в Unity

1. Откройте Unity Hub
2. Нажмите Add → Add project from disk
3. Выберите папку UnityAirplaneEnvironment
4. Откройте проект с версией Unity 2023.2.20f1

Установка ML-Agents (если не установлен)

# Установка Python-пакета для обучения
pip install mlagents==1.1.0

---

🚀 Быстрый старт

1. Откройте сцену

Assets/AlbLab3/Scenes/MLAgentsScenes/MLAgentsScene.unity

2. Запустите в режиме Play

Нажмите ▶️ в Unity Editor для запуска симуляции с предобученной моделью.

3. Ручное управление (Heuristic Mode)

Клавиша	Действие
W / S	Руль высоты (тангаж)
A / D	Элероны (крен)
Q / E	Руль направления (рыскание)
Shift / Ctrl	Тяга двигателя

---

🏗️ Архитектура

UnityAirplaneEnvironment/
├── Assets/
│   ├── AlbLab3/
│   │   ├── AerodynamicObjects/     # Модули аэродинамики
│   │   ├── Scripts/                 # Основные скрипты
│   │   │   ├── AircraftManager.cs   # Управление самолётом
│   │   │   ├── FlightDynamicsLabManager.cs
│   │   │   └── ...
│   │   ├── Llanbedr Map/           # 3D-карта местности
│   │   ├── Models/                  # 3D-модели
│   │   └── Scenes/                  # Unity-сцены
│   │
│   ├── FlyingAgent.cs              # 🤖 Основной RL-агент
│   ├── TargetCube.cs               # 🎯 Целевая точка
│   │
│   ├── RainMaker/                  # 🌧️ Система погоды
│   └── living birds/               # 🐦 Анимированные птицы
│
├── Packages/
│   └── com.unity.ml-agents/        # ML-Agents пакет
│
└── ProjectSettings/                # Настройки проекта

---

🧠 Обучение

Конфигурация обучения

Создайте файл trainer_config.yaml:

behaviors:
  Plane:
    trainer_type: sac
    hyperparameters:
      buffer_size: 200000
      buffer_init_steps: 10000
      batch_size: 256
      learning_rate: 3.0e-4
      learning_rate_schedule: constant
      steps_per_update: 1.0
      tau: 0.005
      init_entcoef: 0.2
      save_replay_buffer: false
    network_settings:
      normalize: true
      hidden_units: 256
      num_layers: 2
      vis_encode_type: simple
    reward_signals:
      extrinsic:
        gamma: 0.99
        strength: 1.0
    max_steps: 4000000
    time_horizon: 128
    summary_freq: 30000
    keep_checkpoints: 5

Запуск обучения

# Запуск обучения с визуализацией в TensorBoard
mlagents-learn trainer_config.yaml --run-id=flight_training_v1

# Мониторинг в TensorBoard
tensorboard --logdir=results

Система наград

Событие	Награда	Описание
Приближение к цели	+1.0 × Δdist	За каждый метр приближения
Достижение цели	+50.0	Бонус за достижение
Таймаут	-0 до -5	Штраф пропорционален расстоянию
Критический угол	-20.0
Каждый шаг	-0.0005	Стимул к быстрому решению

---

🔧 Расширение

Создание собственного агента

using Unity.MLAgents;
using Unity.MLAgents.Actuators;
using Unity.MLAgents.Sensors;

public class CustomFlyingAgent : Agent
{
    public override void CollectObservations(VectorSensor sensor)
    {
        // Добавьте свои наблюдения
        sensor.AddObservation(transform.rotation);
        sensor.AddObservation(targetDirection);
    }

    public override void OnActionReceived(ActionBuffers actions)
    {
        // Обработайте действия агента
        float thrust = actions.ContinuousActions[0];
        float aileron = actions.ContinuousActions[1];
        
        // Применение к самолёту
        ApplyControls(thrust, aileron);
        
        // Вычисление награды
        AddReward(CalculateReward());
    }
}

---

🐳 Docker

Для запуска в headless-режиме:

cd unity-docker
docker build -t tensoraerospace/unity-env .
docker run -it tensoraerospace/unity-env

---

📚 Ресурсы

• 📖 Unity ML-Agents Documentation
• 🎮 Unity Manual
• 🧠 PPO Algorithm Paper

---

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

Мы приветствуем вклад в развитие проекта!

1. 🍴 Форкните репозиторий
2. 🌿 Создайте ветку (git checkout -b feature/amazing-feature)
3. 💾 Закоммитьте изменения (git commit -m 'Add amazing feature')
4. 📤 Запушьте ветку (git push origin feature/amazing-feature)
5. 🔃 Откройте Pull Request

---

📄 Лицензия

Этот проект распространяется под лицензией MIT. Подробности в файле LICENSE.

---

TensorAeroSpace — Обучаем машины летать 🚀

_{Made with ❤️ for the RL community}