Перейти до основного вмісту

Надсилайте метадані у форматі JSON.

Використовуйте MetadataSender, коли зовнішній переглядач, пристрій запису або сервіс приймає метадані у форматі UTF-8 JSON через UDP. Insight — один із приймачів, який підтримує цей протокол обміну даними.

Договір про надання послуг з монтажу електропроводки​

  • Хост за замовчуванням: 127.0.0.1
  • Стандартний базовий порт для метаданих: 9100
  • Правило для каналу: metadata_port_base + channel
  • Режим надсилання за замовчуванням: неблокуючий (MSG_DONTWAIT).
  • Кодування корисного навантаження: текст у форматі JSON, кодований у UTF-8.
  • Необхідні поля верхнього рівня: type, data.
  • Максимальний обсяг корисних даних: 65 507 байтів.

MetadataSender забезпечує, щоб розмір кожного пакета UDP не перевищував 1200 байтів. Пакети JSON розміром до 1200 байтів залишаються незмінними та передаються як один датаграм. Більші пакети розбиваються на частини з використанням цього 12-байтного двійкового заголовка:

БайтРозмірЦінність
01Магічний байт 0x4e
11Версія протоколу 0x01
28Ідентифікатор повідомлення, представлений як 64-бітне ціле число без знака у форматі big-endian.
101Індекс фрагмента, що починається з нуля.
111Загальна кількість фрагментів.

Кожен блок містить до 1188 байтів JSON. Одержувач збирає блоки з однаковою адресою відправника та ідентифікатором повідомлення в порядку індексів блоків перед аналізом JSON. Доставка через UDP залишається найкращим зусиллям: відправник не повторює відправлення невдалого блоку, і send_raw_json(...) або send_metadata(...) повертає false після першої локальної невдалої спроби відправлення.

Одержувачі повинні приймати як незмінені JSON-датаграми, так і версіоновані блоки. Оновіть Insight до версії, яка підтримує збирання блоків, до або одночасно з цією версією Neat Library. Старіші версії Insight продовжують приймати корисне навантаження до 1200 байтів, але не можуть декодувати більші блоки.

Для Insight об’єднайте канал метаданих N із відеопотоком UDP на порту 9000 + N. Якщо Insight або інший одержувач працює за контейнерним портом, явно передайте відображений хост і порт із програми.

Відстеження, треки та інші спеціальні метадані можна надсилати як загальний JSON. Підтримка накладок для переглядача залежить від одержувача; візуалізація відстеження Insight відстежується окремо в sima-neat/insight#8.

C++​

simaai::neat::MetadataSenderOptions opt;
opt.host = "127.0.0.1";
opt.channel = 0;
opt.metadata_port_base = 9100;

std::string err;
simaai::neat::MetadataSender sender(opt, &err);

sender.send_metadata(
    "tracking",
    R"({"tracks":[{"id":"trk-1","bbox":[10,20,30,40]}]})",
    12345,
    "frame-7",
    &err);

send_metadata(...) перевіряє data_json і формує цей пакет:

{
  "type": "tracking",
  "timestamp": 12345,
  "frame_id": "frame-7",
  "data": {
    "tracks": [
      {
        "id": "trk-1",
        "bbox": [10, 20, 30, 40]
      }
    ]
  }
}

Використовуйте send_raw_json(...) лише тоді, коли програма-ініціатор вже сформувала повний основний пакет даних:

sender.send_raw_json(
    R"({"type":"object-detection","data":{"objects":[{"id":"obj_1","label":"car","confidence":0.92,"bbox":[120,80,96,64]}]}})",
    &err);

За замовчуванням, система розподілу завдань у режимі реального часу не блокує роботу.​

MetadataSender за замовчуванням застосовує MSG_DONTWAIT до кожної датаграми, тому переповнений локальний буфер надсилання не може затримати потік, який також обробляє відео або завдання обчислень. Коли ядро не може одразу прийняти датаграм, функція надсилання повертає false замість очікування. Розглядайте цей пакет метаданих як втрачений і продовжуйте роботу в режимі реального часу; доставка через UDP не гарантується.

Конструктор за замовчуванням і параметри надсилання за замовчуванням є еквівалентними:

simaai::neat::MetadataSenderSendOptions send_opt;
simaai::neat::MetadataSender sender(opt, send_opt, &err);

Абоненти, які чітко висловлюють бажання блокувати спроби доставки, можуть активувати цю функцію:

simaai::neat::MetadataSenderSendOptions send_opt;
send_opt.nonblocking = false;
simaai::neat::MetadataSender sender(opt, send_opt, &err);

Використовуйте stats(), щоб розрізняти перевантаження від інших несправностей і, у режимі явного блокування, виявляти повільні з’єднання:

const auto stats = sender.stats();
std::cerr << "sent=" << stats.datagrams_sent
          << " would_block=" << stats.would_block
          << " enobufs=" << stats.no_buffer_space
          << " max_send_ns=" << stats.max_send_duration_ns << '\n';

stats() можна безпечно переглядати під час виконання процесів надсилання даних. Розглядайте отримані результати як поточний знімок діагностичної інформації, а не як знімок даних, отриманий в певний момент часу.

Python​

import json
import pyneat

opt = pyneat.MetadataSenderOptions()
opt.host = "127.0.0.1"
opt.channel = 0
opt.metadata_port_base = 9100

sender = pyneat.MetadataSender(opt)

sender.send_metadata(
    "object-detection",
    json.dumps(
        {
            "objects": [
                {
                    "id": "obj_1",
                    "label": "car",
                    "confidence": 0.92,
                    "bbox": [120, 80, 96, 64],
                }
            ]
        }
    ),
    12345,
    "frame-7",
)

stats = sender.stats()
print(stats.datagrams_sent, stats.would_block, stats.max_send_duration_ns)

Як і в C++, явно встановіть значення send_opt.nonblocking = False і передайте його як другий аргумент конструктора, лише якщо потрібна блокуюча поведінка.