webstudio/docs/entities.md

# Сущности фреймворка применительно к веб-сервису

Веб-сервис позволяет добавить типы Моделей для запуска цифрового двойника (DT), навыка, процесса или дерева поведения. Модели оформляются в виде пакетов. Пакет - это условный "контейнер" для запуска этой сущности в командной строке. Схема пакета общая для всех сущностей. Различны только данные/аргументы. Все вводимые поля, кроме первого (command), могут быть пустыми.

Типы пакетов:

- Процессы - "computing_process"
- Навыки (Серверы навыков) - "skill_server"
- Деревья поведения - "behavior_tree"
- Цифровые двойники - "digital_twin"

Нужно создать в веб-сервисе сущность/класс "Пакет", от которой будут наследоваться "Процесс", "Навык", "Цифровой двойник" (устройство/твёрдое тело/точка/воркспейс - всё, что добавляется в Scene Builder), "Дерево поведения". Пакеты будут создаваться в веб-интерфейсе в самом начальном разделе (где проекты, процессы, навыки).

## Примеры

Пример для процесса (Генератор датасетов)

```json
{
  "sid": 1,
  "type": "computing_process",
  "command": "blenderproc",
  "package": "dataset_generator.py",
  "executable": "",
  "args": {
    "folder": \${NAME:string:""},
  },
  "description": "Robossembler Dataset Generator"
}
```

Пример для цифрового двойника (ROS драйвер для камеры)

```json
{
  "sid": 2,
  "type": "digital_twin",
  "command": "ros2 launch",
  "package": "realsense2_camera",
  "executable": "rs_launch.py",
  "args": {
    "camera_namespace": \${NAME:string:""},
    "camera_name": \${NAME:string:""},
  },
  "description": "ROS Wrapper for Intel RealSense Cameras"
}
```

Пример для навыка (pose estimation skill server)
```json
{
  "sid": 3,
  "type": "skill_server",
  "command": "ros2 launch",
  "package": "dope6d",
  "executable": "dope.py",
  "args": {
    "param1": \${NAME:string:""},
    "param2": \${STRUCTURE:json:""},
    "param3": \${INT:string:""},
    "image_raw": \${TOPIC:CameraInfo:""},
  },
  "description": "Pose Estimation Skill Dope 6D"
}
```

Пример для дерева (behaviour tree)
```json
{
  "sid": 4,
  "type": "behaviour_tree",
  "command": "ros2 launch",
  "package": "rbs-bt",
  "executable": "bt_executor",
  "args": {
    "xml": \${NAME:string:""},
    "json": \${NAME:string:""}
  },
  "description": "Behaviour tree executor"
}
```

## Пример цифрового двойника камеры

1. В главном меню создаётся новый тип для сущности "Цифровой двойник" (см. схему выше)
2. После создания проекта на экране "Scene Builder" эти цифровые двойники добавляются и конфигурируются. Веб-сервис формирует таблицу цифровых двойников.

Экземпляр Камеры №1
```json
{
  "sid": 0,
  "package_model": 2, // ссылка на модель данного пакета
  "args": {
    "camera_namespace": "cv",
    "camera_name": "camera1",
  }
}
```
Экземпляр Камеры №2
```json
{
  "sid": 1,
  "package_model": 2, // ссылка на модель данного пакета
  "args": {
    "camera_namespace": "cv",
    "camera_name": "camera2",
  }
}
```

3. После завершения конфигурации цифрового двойника Backend фоново запускает команду `<command> <package> <executable> <key1>:=<value1> <key2>:=<value2>`. После также запускает команду `ros2_topic_to_json.py` (выводит все топики и их типы в системе), получает интерфейсы ROS данного двойника(ов) и записывает их в таблицу. Структура таблицы БД: `parent` (ссылка на экземпляр цифрового двойника из п.2), `topic_name` (строка или path), `msg_type` (строка), `hash` (хеш, пока не будет использоваться, оставлять пустым по дефолту). Все изменения в Scene Builder должны быть синхронизированы с БД. Если устройство удаляется из сцены, то её интерфейсы также удаляются из таблицы по parent'у.

## Пример навыка

см. предыдущий пример (вместо "Цифровой двойник" - "Навык", вместо Scene Builder - BT Builder).
В редакторе деревьев появляется пользовательский Навык (создан на этапе 1-3), при добавлении которого уже известны интерфейсы цифровых двойников (запущены заранее).
5. Пользователь добавляет Навык на холст (под капотом присваивается sid) и конфигурируем его (добавляя уже записанные в БД интерфейсы).
6. При конфигурации навыка пользователь видит только те топики, которые поддерживают данный тип интерфейса (то есть из цифровых двойников или других источников данных).
7. При добавлении навыка, формирующего топик, пользователь указывает его имя и веб-сервис размещает его в таблицу. При удалении данного навыка с холста, топик удаляется.

## Виды цифровых двойников

Parts:
`/parts/bolt_x/mesh_path [std_msgs/FilePath]`
`/parts/bolt_x/pose_6d [geometry_msgs/Pose]`
`/parts/bolt_x/bound_box [geometry_msgs/BoundBox]`
`/parts/bolt_x/grasp_pose [geometry_msgs/PoseArray]`

Wrist Cameras
`/robot_1/camera_rgb/camera_info [sensor_msgs/CameraInfo]`
`/robot_1/camera_rgbd/camera_info [sensor_msgs/CameraInfo]`

Robots + Controllers
`/robot_1/joint_trajectory_controller [sensor_msgs/CameraInfo]` // moveit
`/robot_2/move_cartesian [rbs_skill_interfaces/MoveItSendPose]` // cartesian

Assemblies:
`/assemblies/...`

Environment
`/environment/...`

Static:
`/camera/camera_info []`