Сущности¶

Понимание состава и назначения сущностей main-api поможет понять общую идею продукта и платформы.

Платформа использует ObjectID

Идентификаторами большой части сущностей в main-api и платформе выступают MongoDB ObjectID. Исключение составляют функциональные решения - для них идентификатором выступает строка.

Создание сущностей PUT-методами

В большей части API не реализованы методы POST для создания сущностей с генерацией идентификатора на стороне сервера для достижения идемпотентности операций. Для создания сущностей PUT-методами клиентам необходимо генерировать идентификаторы самостоятельно.

Организация¶

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

Сущность организации состоит из следующих полей:

Сущность организации

{
  "name": "string",  // (1)!
  "is_active": false,  // (2)!
  "is_admin": false,  // (3)!
  "id": "000000000000000000000000"  // (4)!
}

Название организации
Включение или отключение сущности. Влияет на обработку связанных с сущностью процессингов.
Признак организации-администратора
Идентификатор сущности, принимает тип MongoDB ObjectID.

Организации-администраторы являются администраторами платформы и обладают расширенными полномочиями по сравнению с обычными организациями - например, могут создавать новые организации и пользователей в них. Подробнее о правах.

Пользователь¶

Сущность пользователя - сотрудник внутри организации. Любые запросы к платформе выполняются от лица конкретного пользователя. Каждый пользователь принадлежит одной и только одной организации.

Сущность пользователя

{
  "name": "string", // (1)!
  "login": "string", // (2)!
  "password": "string",
  "is_active": false, // (3)!
  "is_admin": false, // (4)!
  "org": "000000000000000000000000" // (5)!
}

Имя пользователя
Логин (используется при авторизации)
Признак активности
Признак админа внутри своей организации
Ссылка на организацию пользователя

Разделения прав на операции между пользователями не предусмотрено, однако пользователь внутри организации может иметь признак is_admin. Включение такого признака дает пользователю права на дополнительные действия внутри своей организации.

Функциональное решение¶

Сущность функционального решения описывает запрос потребителя платформы на:

способ обработки данных (кадры или видеопоток);
настройки способа обработки данных (например, частоту анализа по кадрам или stream_settings для видеопотока);
перечень необходимых для работы потребителя моделей нейронных сетей.

Сущность функционального решения состоит из следующих полей:

Сущность функционального решения

{
  "name": "string", // (1)!
  "description": "string", // (2)!
  "is_enabled": false, // (3)!
  "available_for": ["000000000000000000000000"], // (4)!
  "required_models": {}, // (5)!
  "shot_settings": {}, // (6)!
  "stream_settings": {}, // (7)!
  "service_route_name": "string", // (8)!
  "service_url": "http://example.com", // (9)!
  "swagger_path": "string", // (10)!
  "ui_settings": null, // (11)!
  "id": "string" // (12)! 
}

Название функционального решения для отображения в интерфейсе
Описание функционального решения для отображения в интерфейсе
Включение или отключение сущности. Влияет на обработку связанных с сущностью процессингов.
Список идентификаторов организаций, которым доступна сущность.
Пример заполнения available_for
```
[
  "000000000000000000000000",
  "000000000000000000000001"
]
```
Набор необходимых для работы функционального решения нейронных сетей.

Для сущности ФР набор является подмножеством доступных в конфигурации моделей. Для процессинга - подмножеством заданных в ФР моделей. Если не указать в процессинге - набор будет унаследован от ФР.

Описывается следующим образом:
Пример заполнения required_models/enabled_models
```
{
  "garbage": { // (1)!
    "garbage": [ // (2)!
      "garbage_types4" // (3)!
    ]
  },
  "dumpster": {
    "dumpster": [
      "dumpster_types23",
      "dumpster_types22"
    ]
  },
  "dumpster_enclosure": {
    "dumpster_enclosure": []
  }
}
```
1. Название детектора
2. Название типа объекта
3. Список признаков (фичей) типа объекта
Настройки обработки по кадрам (шотам)
Пример заполнения shot_settings
```
{
  "interval_sec": 10, // (1)!
  "roi": [0,1,2,3] // (2)!
}
```
1. Интервал снятия изображения в секундах. Значение -1 отключит интервальную съемку, будет доступен только триггер (выполнение обработки одного кадра по запросу)
2. Region of interest - координаты прямоугольника, внутри которого будет производиться детектирование объектов. Не имеет смысла задавать в сущности функционального решения, которое будет использовано более чем с одной камерой
Настройки обработки видеопотока. Совпадают с таковыми в video-manager. На текущий момент не валидируются.
Префикс для интеграции в API-документацию. Может быть любым, но не должен дублироваться в рамках одной инсталляции.
Адрес, по которому слушает сервис функционального решения. Должен быть доступен сервису api-gateway.
Путь к openapi-документации сервиса функционального решения для отображения в общей API-документации. Обычно /openapi.json.
Настройки отображения вкладки функционального решения в UI.
Пример заполнения ui_settings
```
{
  "app_code": "trash", // (1)!
  "tab_name": "Мониторинг ТКО", // (2)!
  "order": 3 // (3)!
}
```
1. Код приложения (UI-приложение должно знать о его существовании)
2. Название вкладки в интерфейсе
3. Порядок сортировки при отображении в интерфейсе
Идентификатор функционального решения, строка. Влияет на пайплайн обработки (на топик Kafka, в частности)

Камера¶

Сущность камеры описывает, собственно, камеру.

Сущность камеры

{
  "external_id": null,  // (1)!
  "name": "Название камеры",  // (2)!
  "stream_url": "rtsp://ip:port/live?id=48f8d848",  // (3)!
  "shot_url": null,  // (4)!
  "integration_id": null,  // (5)!
  "coords": {  // (6)!
    "lon": 43.466431,
    "lat": 56.252282
  },
  "alt": 0,  // (7)!
  "azimuth": 0,  // (8)!
  "fl": 0,  // (9)!
  "available_for": [],  // (10)!
  "labels": null,  // (11)!
  "is_enabled": false,  // (12)!
  "videomanager_shard": null,  // (13)!
  "shotmanager_shard": "http://shot-manager-0:18730",  // (14)!
  "id": "312b3c1ecd877fe36206a0b2",  // (15)!
  "owner": "80755db904e7318decb2fb68"  // (16)!
}

Идентификатор во внешней системе, вместе с integration_id позволяет получать поток из внешней VMS
Название камеры, отображается в интерфейсе
Адрес, по которому доступен видеопоток с камеры
Адрес, по которому доступно получение кадров с камеры напрямую. Не то же самое, что stream_url
Набор необходимых для работы функционального решения нейронных сетей.

Для сущности ФР набор является подмножеством доступных в конфигурации моделей. Для процессинга - подмножеством заданных в ФР моделей. Если не указать в процессинге - набор будет унаследован от ФР.

Описывается следующим образом:
Пример заполнения required_models/enabled_models
```
{
  "garbage": { // (1)!
    "garbage": [ // (2)!
      "garbage_types4" // (3)!
    ]
  },
  "dumpster": {
    "dumpster": [
      "dumpster_types23",
      "dumpster_types22"
    ]
  },
  "dumpster_enclosure": {
    "dumpster_enclosure": []
  }
}
```
1. Название детектора
2. Название типа объекта
3. Список признаков (фичей) типа объекта
Координаты камеры, используются для отображения камер на карте
Высота камеры, сейчас нигде не используется
Азимут камеры, сейчас нигде не используется
Фокусное расстояние камеры, сейчас нигде не используется
Список идентификаторов организаций, которым доступна сущность.
Пример заполнения available_for
```
[
  "000000000000000000000000",
  "000000000000000000000001"
]
```
Метки камеры, словарь <ключ: значение>. Передается в video-manager
Включение или отключение сущности. Влияет на обработку связанных с сущностью процессингов.
Шард видеоменеджера
Шард шотменеджера
Идентификатор сущности, принимает тип MongoDB ObjectID.
Владелец камеры, таковым автоматически становится организация-создатель камеры

Создание камеры не приводит к началу обработки кадров или видеопотока. В NTechCity сущность камеры необходима для хранения информации о доступных пользователям камерах и их отображения на карте.

Шард shot-manager¶

При создании камеры, использование которой планируется в сценарии работы по шотам необходимо указать для нее шард shot-manager. Список доступных шардов задается в конфигурации сервиса, а также доступен в API.

Шард video-manager¶

При создании камеры, использование которой планируется в сценарии работы по видеопотоку необходимо указать для нее шард video-manager. Список доступных шардов задается в конфигурации сервиса, а также доступен в API.

Лицензия¶

Для возможности создания процессингов необходимо, чтобы организации была доступна лицензия для соответствующего функционального решения. Список лицензий доступен в API и управляется внутренней реализацией платформы.

Процессинг¶

Процессинг - включение обработки выбранной камеры для заданного функционального решения в нужном организации режиме.

Сущность процессинга состоит из следующих полей:

Сущность процессинга

{
  "enabled_models": null, // (1)!
  "shot_settings": {}, // (2)!
  "stream_settings": null, // (3)!
  "meta": {}, // (4)!
  "is_enabled": true, // (5)!
  "license_id": "trash_lic", // (6)!
  "id": "461b43a850b722f5af479977", // (7)!
  "cam_id": "b873bc0030e94b7fd702ffed", // (8)!
  "org_id": "80755db904e7318decb2fb68", // (9)!
  "fs_id": "trash", // (10)!
  "status": "active" // (11)!
}

Набор необходимых для работы функционального решения нейронных сетей.

Для сущности ФР набор является подмножеством доступных в конфигурации моделей. Для процессинга - подмножеством заданных в ФР моделей. Если не указать в процессинге - набор будет унаследован от ФР.

Описывается следующим образом:
Пример заполнения required_models/enabled_models
```
{
  "garbage": { // (1)!
    "garbage": [ // (2)!
      "garbage_types4" // (3)!
    ]
  },
  "dumpster": {
    "dumpster": [
      "dumpster_types23",
      "dumpster_types22"
    ]
  },
  "dumpster_enclosure": {
    "dumpster_enclosure": []
  }
}
```
1. Название детектора
2. Название типа объекта
3. Список признаков (фичей) типа объекта
Настройки обработки по кадрам (шотам)
Пример заполнения shot_settings
```
{
  "interval_sec": 10, // (1)!
  "roi": [0,1,2,3] // (2)!
}
```
1. Интервал снятия изображения в секундах. Значение -1 отключит интервальную съемку, будет доступен только триггер (выполнение обработки одного кадра по запросу)
2. Region of interest - координаты прямоугольника, внутри которого будет производиться детектирование объектов. Не имеет смысла задавать в сущности функционального решения, которое будет использовано более чем с одной камерой
Настройки обработки видеопотока. Совпадают с таковыми в video-manager. На текущий момент не валидируются.
Произвольный словарь мета-информации
Включение или отключение сущности. Влияет на обработку связанных с сущностью процессингов.
Идентификатор лицензии
Идентификатор сущности, принимает тип MongoDB ObjectID.
Идентификатор сущности, принимает тип MongoDB ObjectID.

Указывает на камеру, для которой включается обработка
Идентификатор сущности, принимает тип MongoDB ObjectID.

Указывает на организацию, от лица которой включается обработка
Идентификатор функционального решения, для которого будет выполняться обработка
Статус процессинга, выставляется системой

Нюансы работы процессинга:

разные камеры для одного функционального решения могут обрабатываться с помощью video-worker или shot-worker - в реализации это значит, что у процессинга может быть заполнено либо shot_settings, либо stream_settings. При этом заполненным полем считается и наличие пустого объекта у одного из полей;
на текущем этапе отсутсвует валидация stream_settings для video-worker на соответствие схеме;

Статусы процессинга¶

Статус	Описание
`disabled_by_user`	Процессинг был отключен пользователем
`active`	Процессинг активен и работает
`license_expired`	Истек срок действия лицензии
`license_processings_quota_exceeded`	Достигнут лимит лицензии по количеству процессингов
`license_shot_mode_removed`	В лицензии была запрещена обработка по шотам
`license_stream_mode_removed`	В лицензии была запрещена обработка по видеопотоку
`license_not_available`	Лицензия недоступна
`license_not_exist`	Лицензия не существует
`license_fs_changed`	В лицензии был изменен идентификатор функционального решения
`license_is_empty`	Лицензия пуста, включение обработки недоступно
`organisation_not_found`	Организация, указанная в процессинге не найдена
`fs_not_found`	Функциональное решение, указанное в процессинге не найдена
`camera_not_found`	Камера, указанная в процессинге не найдена
`fs_access_denied`	Нету прав на доступ к функциональному решению
`camera_access_denied`	Нету прав на доступ к камере
`organization_inactive`	Организация деактивирована
`fs_disabled`	Функциональное решение деактивировано
`camera_disabled`	Камера деактивирована

Каскадные операции¶

При удалении камеры, ФР или организации каскадно удаляются все имеющиеся процессинги для удаляемой камеры, ФР, организации.