sirius_unity_sim/README.md

# Развертывание симуляции зоны ЧС в Unity 

# 1. Установка UnityHub

Установка лаунчера подробно описано [на официальном сайте](https://docs.unity.com/en-us/hub/install-hub-linux#install-the-hub-on-an-ubuntu-linux-distribution). Дублирую информацию:

1.1 Проверяем наличие или устанавливаем при необходимости утилиту curl:
```
sudo apt install curl
```
1.2 Добавляем публичный ключ для подписи
```
sudo install -d /etc/apt/keyrings
curl -fsSL https://hub.unity3d.com/linux/keys/public | sudo gpg --dearmor -o /etc/apt/keyrings/unityhub.gpg
```
1.3 Добавляем репозиторий Unity Hub (только для x86_64/amd64)
```
echo "deb [arch=amd64 signed-by=/etc/apt/keyrings/unityhub.gpg] https://hub.unity3d.com/linux/repos/deb stable main" | sudo tee /etc/apt/sources.list.d/unityhub.list
```
1.4 Устанавливаем приложение
```
sudo apt update
sudo apt install unityhub
```
# 2. Установка Unity

Заходим в Unityhub и во вкладке `Installs` нажимаем `Install Editor`. В появившимся окне выбираем `Unity 6.0`, проверяем, достаточно ли свободного места на диске, никакие дополнительные модули не ставим и подтверждаем установку. При необходимости модули можно будет доставить потом.

# 3. Развертывание симуляции

1. Склонировать симуляцию из [Git‑репозитория](https://git.robofob.ru/sirius/sirius_unity_sim.git) в любую удобную папку на диске:
```bash
git clone --recurse-submodules https://git.robofob.ru/sirius/sirius_unity_sim.git
```

Если репозиторий уже был склонирован без модуля, то выполнить:
```bash
git submodule init
git submodule update
```
1. Скачиваем модели мира [Industrial_Zone_Modular_Pack](https://disk.yandex.ru/d/leNWr7JXhXlNJQ), [AllSkyFree](https://disk.yandex.ru/d/WjRCJTkRmQfaCQ), [Vefects](https://disk.yandex.ru/d/pohMh5mcrlVngA) и разархивируем их в папку `Assets`. Должна получится струткура:
```
Assets/
├─ AllSkyFree/
├─ Industrial_Zone_Modular_Pack/
├─ Vefects
└─ ...
```
1. В UnityHub добавляем проект `Add new project` и выбираем папку `sirius_unity_sim`.
2. Открываем проект и ждем процесса компиляции проекта. Unity не сможет скомпилировать некоторые скрипты и из-за этого предложит перейти в режим `Safe Mode`. Соглашаемся.
> Если по каким-то причинам все скомпилилось удачно, то это значит, что у вас уже есть недостающие библиотеки. Переходите к п.5
3. После открытия программы устанавливаемя дополнительные пакеты для организации свзяи ROS+Unity:
    - Через меню `Window > Package manager` выбрать раздел `Unity Registry` и установить библиотеку `Mathematics`,`Burst`
    - Через интерфейс "+" выбрать `Add package from git URL...` и ввести прикрепленные ниже ссылки
      - [ROS-TCP-Connector](https://github.com/Unity-Technologies/ROS-TCP-Connector) - перессылка сообещинй из ROS в Unity и обратно
`https://github.com/Unity-Technologies/ROS-TCP-Connector.git?path=/com.unity.robotics.ros-tcp-connector`.
      - Visualizations -  визуализация данных ROS-сообщений в Unity в реальном времени
`https://github.com/Unity-Technologies/ROS-TCP-Connector.git?path=/com.unity.robotics.visualizations`
      - [URDF-Importer](https://github.com/Unity-Technologies/URDF-Importer) 
`https://github.com/Unity-Technologies/URDF-Importer.git?path=/com.unity.robotics.urdf-importer#v0.5.2`
1. Если Unity самостоятельно не вышел из безопасного режима, то выходим вручную `Safe Mode > Exit Safe Mode`.
2. Во вкладке `Robotics > ROS Settings` переключаем на протокол `ROS2` и ждем компиляции проекта. После компиляции оставшихся скриптов не должно возникнуть никаких критических ошибок.

# 4. ROS2: установка дополнительных пакетов
Рабочим воркспейсом будем считать `~/sirius_ws`.

1. В `sirius_ws/src` клонируем пакет [ROS TCP Endpoint](https://github.com/Unity-Technologies/ROS-TCP-Endpoint):
```bash
cd ~/sirius_ws/src
git clone -b main-ros2 https://github.com/Unity-Technologies/ROS-TCP-Endpoint.git
```

2. Собираем workspace из его корня командой
```bash
cd ~/sirius_ws
colcon build --symlink-install
```
# 5. Запуск симуляции

1. На стороне ROS2 запускает TCP-сервер:
```bash
ros2 run ros_tcp_endpoint default_server_endpoint --ros-args -p ROS_IP:=127.0.0.1
```
2. Отрыть проект `sirius_sim` и в файлах проекта (вкладка `Project` в нижней части экрана) открыть сцену `main.unity`, которая распологается в папке `Assets/Scenes`.
3. В Unity запускаем симуляцию нажав кнопку `Play` (внешний вид: ▶) на панели инструментов (чуть выше окна просмотра сцены `Scene` / игрового окна `Game`). В верхнем левом углу игрового окна будет отображаться плашка с указанием IP-адреса и индикацией состояния подключения (внешний вид: ⇄): если стрелки <span style="color:red">красного цвета</span> - соединения нет, если <span style="color:blue">синего</span> - есть, <span style="color:yellow">жетлого</span> - есть соединение, но с проблемами (игнорируем). Ошибки работы симуляции будут выводиться в собственную консоль Unity. Для прекращения работы симуляции повторно нажмите кнопку `Play`.
> Во время симуляции можно изменять параметры скриптов, положение объектов и другие элементы, но после ее завершения все изменения автоматически откатятся к начальному состоянию.

## 🚨 Известные проблемы и их решения

### Проблема импорта текстур

При импроте текстур и материалов может возникнуть конфликт при рендеринге: предметы на сцене будут ярко розового цвета. Для устранения этой проблемы перейдите в строке меню наверху:<br>
`Edit > Render Pipeline > Universal Render Pipeline > Upgrade Project Materials to URP Materials или Upgrade Selected Project Materials to URP Materials` (второй вариант доступен при предварительном выборе проблемных текстур перед вызовом контекстного меню).

### Ошибка компиляции библиотеки URDF-Importer `DllNotFoundException: libdl.so`
> [Похожее Issue](https://github.com/Unity-Technologies/URDF-Importer/issues/224)

Полный текст ошибки:
```console
DllNotFoundException: libdl.so assembly:<unknown assembly> type:<unknown type> member:(null)
Assimp.Unmanaged.UnmanagedLibrary+UnmanagedLinuxLibraryImplementation.NativeLoadLibrary (System.String path) (at <d40f2b0ad6814d4c8094142d8473733f>:0)
Assimp.Unmanaged.UnmanagedLibrary+UnmanagedLibraryImplementation.LoadLibrary (System.String path) (at <d40f2b0ad6814d4c8094142d8473733f>:0)
Assimp.Unmanaged.UnmanagedLibrary.LoadLibrary (System.String libPath) (at <d40f2b0ad6814d4c8094142d8473733f>:0)
Assimp.Unmanaged.UnmanagedLibrary.LoadLibrary () (at <d40f2b0ad6814d4c8094142d8473733f>:0)
Assimp.AssimpUnity.InitializePlugin () (at ./Library/PackageCache/com.unity.robotics.urdf-importer@4ed58f8d00fe/Runtime/UnityMeshImporter/Plugins/AssimpNet/AssimpUnity.cs:147)
```
Чтобы устранить эту ошибку, выполните следующие шаги:
1. Проверить наличие файла `libdl.so.2` в директории `/usr/lib/x86_64-linux-gnu`.
2. Если имеется, то добавить ссылку командой `sudo ln -s /usr/lib/x86_64-linux-gnu/libdl.so.2 /usr/lib/libdl.so`.
3. Если нет то найти и модифицировать команду из п.2.
4. Повторно открыть проект.