BoxDecode: типи декодування.

nodes::SimaBoxDecode перетворює необроблені тензори з вихідного шару детектора на результати детектування. Він виконується після висновування моделі, застосовує математичні обчислення декодування для обраної родини моделей, фільтрує рамки з низькою впевненістю, виконує непересічну придушення (NMS) і генерує тензорний пакет, який починається з декодованих рамок. Моделі детектування можуть розібрати цей пакет як рамки; моделі для визначення поз і сегментації також можуть розібрати ключові точки або маски, які йдуть після рамок.

Для звичайного використання пакетів моделей, віддавайте перевагу конструктору, який враховує Model. Архів моделі надає порядок, розміщення, квантування тензорів, кількість класів, метадані зміни розміру та підказки щодо діапазону оцінок, необхідні декодеру. Ваш застосунок зазвичай лише вибирає родину декодування та порогові значення фільтрації.

Швидкий старт.

using namespace simaai::neat;

Model model("/path/to/yolov8_model.tar.gz");

auto boxdecode = nodes::SimaBoxDecode(
    model,
    BoxDecodeType::YoloV8,
    /* detection_threshold */ 0.25,
    /* nms_iou_threshold */ 0.45,
    /* top_k */ 100);

Для використання в окремому середовищі розробки:

simaai::neat::stages::BoxDecodeOptions opt(simaai::neat::BoxDecodeType::YoloV8);
opt.detection_threshold = 0.25;
opt.nms_iou_threshold = 0.45;
opt.top_k = 100;

Аргументи

Аргумент	Значення
`decode_type`	Тип моделі/формат заголовка, наприклад, `BoxDecodeType::YoloV8` або `BoxDecodeType::YoloX`. Обов’язково.
`detection_threshold`	Мінімальний бал, необхідний для збереження результату виявлення. Використовуйте значення, що відповідає конкретній моделі, наприклад, `0.25`.
`nms_iou_threshold`	Поріг IoU, який використовується алгоритмом придушення не-максимумів.
`top_k`	Максимальна кількість виявлених об’єктів, які потрібно зберегти. `0` використовує значення за замовчуванням для бекенду/моделі.
`original_width`, `original_height`	Розмір вихідного зображення, що використовується для відображення координат під час застосування конструктора raw-geometry.
`model_width`, `model_height`	Замінює розмір вхідних даних моделі. За допомогою `Model` цей конструктор змінює параметри просторового декодування, але не змінює структуру тензора, що використовується.
`resize_mode_override`	Використовуйте лише тоді, коли на попередньому етапі обробки `Preproc` не записуються метадані щодо зміни розміру, і вам потрібно явно вказати поведінку для масштабування, заповнення або обрізання.
`decode_type_option`	Розширений селектор підпорядкованих макетів. Залиште значення `Auto`, якщо використовуєте пакет моделей, якщо тільки ви не знаєте, який макет заголовка експортується.

Вхідні та вихідні дані.

Вхідні дані: необроблені тензори виявлення, отримані від моделі. Очікувані розміри тензорів залежать від типу моделі. У випадку з MPK/архівом моделі, Neat зчитує ці деталі з упакованого контракту.

Вихідні дані: один тензор BoxDecode, що містить декодовані виявлення. Моделі виявлення використовують стандартний формат BBOX. Моделі для визначення поз і сегментації зберігають початкові обмежувальні рамки та додають власні, специфічні для завдання, дані:

Завдання моделі	Допоміжний код C++	Допоміжний код Python	Декодовані тензори
Виявлення	`decode_bbox(...)`	`pyneat.decode_bbox(...)`	`[N, 6]` float32 boxes: `x1, y1, x2, y2, score, class_id`
Поза	`decode_pose(...)`	`pyneat.decode_pose(...)`	обмежувальні рамки `[N, 6]` та ключові точки `[N, 17, 3]` float32: `x, y, visibility`
Сегментація	`decode_segmentation(...)`	`pyneat.decode_segmentation(...)`	прямокутники `[N, 6]` float32 і маски `[N, 160, 160]` uint8.
SuperPoint	`decode_superpoint(...)`	`pyneat.decode_superpoint(...)`	ключові точки `[N,2]`, оцінки `[N]`, дескриптори `[N,D]`.

Графи, що використовуються для відображення результатів виявлення, можуть передавати дані до SimaRender. Код застосунку, якому потрібні лише обмежувальні рамки, може продовжувати використовувати decode_bbox(...) для обробки вихідних даних BoxDecode.

Суперточка

SuperPoint залишається частиною продукту BoxDecode, але генерує ключові точки, а не намагається видавати їх за прямокутники. Мінімальна конфігурація за замовчуванням A65:

BoxDecodeOptions options{BoxDecodeType::SuperPoint};
options.superpoint.descriptor_output_dtype = TensorDType::Float32;

auto decoder = nodes::SimaBoxDecode(model, options);

У Python використовуються ті самі значення за замовчуванням:

options = pyneat.BoxDecodeOptions(pyneat.BoxDecodeType.SuperPoint)
options.superpoint.descriptor_output_dtype = pyneat.TensorDType.Float32

decoder = pyneat.nodes.sima_box_decode(model, options=options)

A65V1 є профілем за замовчуванням. Обирайте інший профіль, якщо моделі потрібна інша числова поведінка; Neat не визначає поведінку на основі форми або значень тензора:

Профіль	Коли його слід обрати	Статус виробництва
`LightGlueV1`	Детектор, NMS, координати та поведінка дескриптора, сумісні з LightGlue	Підтримується
`MagicLeapDemoV1`	Поведінка закріпленої демонстраційної програми Magic Leap	Підтримується
`A65V1`	Сумісність зі старим декодером A65 SuperPoint	Підтримується; встановлено за замовчуванням
`PaperBicubicV1`	Зарезервовано числовий ідентифікатор для майбутньої повністю визначеної бікубічної політики.	Відхилено до моменту визначення у виробничому середовищі.

Числовий формат і кодування вихідних даних є незалежними. Наприклад, можна вибрати числовий формат A65 із використанням стандартного вихідного формату V1:

BoxDecodeOptions options{BoxDecodeType::SuperPoint};
options.superpoint.profile = SuperPointProfile::A65V1;
options.superpoint.output_format = SuperPointOutputFormat::FeaturePointsV1;

Використання застарілої схеми розміщення байтів є опціональним і має додаткові обмеження:

options.superpoint.profile = SuperPointProfile::A65V1;
options.superpoint.output_format = SuperPointOutputFormat::LegacyA65InterleavedV0;
options.superpoint.descriptor_output_dtype = TensorDType::Int8;

SuperPointProfile::Auto спочатку використовує авторитетні метадані MPK superpoint.profile. Якщо ні API, Model::Options.superpoint.profile, ні MPK не надають профіль, то використовується A65V1. Neat ніколи не визначає профіль на основі розмірів тензорів, значень, імен файлів або наступних вузлів.

Коли їхні загальнодоступні значення-за замовчуванням залишаються незмінними, detection_threshold=0.0, top_k=0, nms_radius=-1 і border_margin=-1 визначаються з обраного профілю. A65V1 визначає порогове значення 0.1, Top-K 600, радіус NMS 4 і межу 0. LightGlueV1 і MagicLeapDemoV1 використовують порогові значення 0.0005 і 0.015 відповідно; обидва використовують Top-K 600, радіус NMS 4 і межу 4.

nms_iou_threshold не застосовується до SuperPoint; використовуйте радіус у пікселях superpoint.nms_radius. За замовчуванням виводиться структурований масив FEATURE_POINTS_V1 версії. LegacyA65InterleavedV0 є явним форматом міграції та вимагає 256-вимірних дескрипторів INT8. Використовуйте decode_superpoint замість decode_bbox або BoxDecodeResults.

Версіоновані записи схеми MPK superpoint v1 мають режим відмови за замовчуванням. Вони повинні містити назву профілю, окремі ідентифікатори тензорів детектора та дескриптора, sha256: відбиток, що містить 64 шістнадцяткових цифри, і підтримувані вхідні представлення raw-logits-65 і coarse-pre-l2. Схема 0 залишається прийнятною лише як запис для міграції/ручного використання; відсутні поля представлення схеми 0 канонізуються до цих двох представлень необроблених даних і записуються як значення за замовчуванням у діагностиці. Невідомі версії схеми або маркери представлення призводять до помилки під час компіляції. Якщо перевантаження профілю API суперечить відбитку, який було встановлено для іншого профілю MPK, повторно встановіть відбиток MPK для вибраного профілю; Neat не відкидає та не переінтерпретує ці дані про походження.

Корисне навантаження BBOX у форматі wire.

Модуль декодування вихідних даних детектора генерує один тензор, позначений як BBOX, для кожного вхідного кадру. Цей тензор є буфером байтів першого рангу, що має тип UInt8.

Поле	Значення
`semantic.detection.format`	`"BBOX"`
`dtype`	`UInt8`
`shape`	`[N_bytes]`, де `N_bytes` – це обсяг запакованого буфера з архіву моделі.

Розмір тензора визначається в байтах, а не кількістю виявлених об’єктів. Структура даних використовує порядок байтів little-endian:

offset  size  content
------  ----  -------
  0      4    uint32  N = valid detections in this frame
  4     24    RawBox[0]
 28     24    RawBox[1]
  .      .      ...
  .      .    RawBox[N-1]
                   trailing bytes are padding and must be ignored

Кожен запис RawBox має розмір 24 байти:

Зміщення	Розмір	Тип	Поле	Значення
0	4	`int32`	`x`	Координата X у верхньому лівому куті у вихідних пікселях.
4	4	`int32`	`y`	Верхня ліва координата y у вихідних пікселях.
8	4	`int32`	`w`	Ширина в пікселях вихідного зображення.
12	4	`int32`	`h`	Висота в пікселях вихідного зображення.
16	4	`float32`	`score`	Впевненість після застосування NMS для `[0.0, 1.0]`.
20	4	`int32`	`class_id`	Ідентифікатор класу, визначений моделлю.

Відповідний формат Python struct для одного запису — "<iiiifi".

Координати вказуються в пікселях вихідного зображення, якщо наявні метадані попередньої обробки. Вони не нормалізовані до [0, 1] і не представлені у внутрішньому просторі вхідних даних моделі, який має форму прямокутника.

Коли `model.run` повертає необроблені результати.

Деякі маршрути моделі повертають необроблені вихідні дані у вигляді карт ознак замість декодованого тензора BBOX з model.run(...). Це не означає, що виконання моделі завершилося з помилкою. Це означає, що модель була виконана, але вказаний маршрут не містив етап декодування обмежувальних рамок (BoxDecode) в точці, де ви зчитуєте вихідні дані.

Використовуйте це правило:

detections=... або тензор BBOX: розпакуйте дані BBOX або використовуйте їх. допоміжні функції для декодування.
raw_output_heads=...: додайте етап BoxDecode, перевірте маршрут моделі або обробляйте необроблені тензори за допомогою спеціалізованої постобробки для конкретної моделі.

Не розглядайте необроблені дані як обмежувальні рамки. Структура необроблених тензорів залежить від експортованої родини моделей та специфікацій архіву моделі.

Замінити контракт.

Архів моделі може містити значення за замовчуванням для типу декодування, порогів, top_k та вихідної геометрії. Аргументи, що передаються в середовище виконання, замінюють ці значення за замовчуванням лише тоді, коли ви передаєте непустий або додатний параметр.

Аргумент середовища виконання	Значення, що передається	Поведінка
`decode_type`	порожньо / `Unspecified`	Зберігайте архів моделі або використовуйте функцію планування маршруту, якщо це підтримується.
`decode_type`	конкретний тип	Замініть сімейство декодувань для цього запуску.
`original_width` / `original_height`	`0`	Збережіть геометрію, що входить до пакета, або метадані попередньої обробки.
`original_width` / `original_height`	додатне ціле число	Замініть вихідні розміри для відображення координат.
`detection_threshold` / `score_threshold`	`0.0`	Збережіть встановлені значення.
`detection_threshold` / `score_threshold`	`> 0.0`	Обхід порогу оцінки.
`nms_iou_threshold`	`0.0`	Збережіть значення IoU для NMS, що використовується в пакетному режимі.
`nms_iou_threshold`	`> 0.0`	Замініть порогове значення IoU для NMS.
`top_k`	`0`	Збережіть упаковані дані про топ-K.
`top_k`	`> 0`	Замініть максимальну кількість збережених виявлених об’єктів.
`num_classes`	`0`	Використовуйте глибину заголовка класу, визначену на основі MPK.
`num_classes`	додатне ціле число, що відповідає MPK	Використовуйте явну кількість класів. Це необхідно, коли MPK не може надійно визначити поділ на окремі класи.
`num_classes`	– додатне ціле число, яке суперечить YOLO26 MPK.	Помилка виникає до побудови конвеєра, і повідомляються обидва значення. YOLO26 отримує свою групову структуру необробленого вихідного шару з глибини класів, тому ця невідповідність є помилкою в контракті моделі.
`num_classes`	– додатне ціле число для SSD або попередньої версії YOLO26, яка не передбачає визначення пози.	Зберегти існуючу поведінку, що передбачає явне перевизначення. Декодери пози та SuperPoint зберігають свої сімейні правила.

detection_threshold – це назва, яка використовується конструкторами вузлів/етапів BoxDecode. ModelOptions.score_threshold – це опція моделі, яка передає дані до того ж модуля керування.

Розшифруйте відображення типів даних.

Перелік API	Бекенд-токен	Типова модельна лінійка
`BoxDecodeType::Yolo`	`yolo`	Загальні голови у стилі YOLO
`BoxDecodeType::YoloV5`	`yolov5`	виявлення об’єктів за допомогою YOLOv5
`BoxDecodeType::YoloV5Seg`	`yolov5-seg`	Сегментація YOLOv5
`BoxDecodeType::YoloV7`	`yolov7`	виявлення об’єктів за допомогою YOLOv7
`BoxDecodeType::YoloV7Seg`	`yolov7-seg`	Сегментація YOLOv7
`BoxDecodeType::YoloV8`	`yolov8`	виявлення об’єктів за допомогою YOLOv8
`BoxDecodeType::YoloV8Seg`	`yolov8-seg`	Сегментація YOLOv8
`BoxDecodeType::YoloV8Pose`	`yolov8-pose`	YOLOv8 pose
`BoxDecodeType::YoloV9`	`yolov9`	виявлення об’єктів за допомогою YOLOv9
`BoxDecodeType::YoloV9Seg`	`yolov9-seg`	Сегментація YOLOv9
`BoxDecodeType::YoloV10`	`yolov10`	виявлення об’єктів за допомогою YOLOv10
`BoxDecodeType::YoloV10Seg`	`yolov10-seg`	Сегментація YOLOv10
`BoxDecodeType::YoloV26`	`yolo26`	Виявлення об’єктів за допомогою YOLO26
`BoxDecodeType::YoloV26Pose`	`yolo26-pose`	YOLO26 pose
`BoxDecodeType::YoloV26Seg`	`yolo26-seg`	Сегментація YOLO26
`BoxDecodeType::YoloV6`	`yolov6`	виявлення об’єктів за допомогою YOLOv6
`BoxDecodeType::YoloX`	`yolox`	виявлення об’єктів за допомогою YOLOX
`BoxDecodeType::Ssd`	`ssd`	Точний підготовлений контракт SSD300, SSD-Mobile-300, SSD-Mobile-320 або SSDlite-Mobile-320, обраний із впорядкованої головної геометрії.
`BoxDecodeType::SuperPoint`	`superpoint`	Постпроцесинг детектора та дескриптора SuperPoint
`BoxDecodeType::Detr`	`detr`	Виявлення об’єктів за допомогою трансформера в стилі DETR
`BoxDecodeType::EffDet`	`effdet`	Ефективне виявлення об’єктів за допомогою EfficientDet
`BoxDecodeType::RcnnStage1`	`rcnn-stage1`	Етап генерації пропозицій R-CNN
`BoxDecodeType::Centernet`	`centernet`	Детекція CenterNet

BoxDecodeType::Unspecified є невизначеним маркером і викликає помилку до початку роботи середовища виконання. Ідентифікатор рецепту SSD є внутрішнім контрактом Core (ssd300-v1, ssd-mobile-300-v1, ssd-mobile-320-v1 або ssdlite-mobile-320-v1), а не іншим загальнодоступним типом декодування або токеном бекенду. Core визначає його перед початком процесу оптимізації, тоді як встановлений об’єктний декодер продовжує отримувати підтримуваний токен ssd і вибирає відповідну фіксовану реалізацію з уже перевіреної геометрії заголовка.

Вибір правильного типу.

Якщо ви використовуєте пакет моделей, наданий або скомпільований компанією SiMa, виберіть BoxDecodeType, який відповідає сімейству моделей, і залиште decode_type_option у значенні Auto.
Якщо ваші результати виявлення відсутні або всі показники несподівано низькі, спочатку перевірте, чи відповідає сімейство декодерів експортованій моделі. YOLOX, YOLOv6 і YOLO26 використовують «сирі»/логітні шари, і до них не можна застосовувати той самий підхід, що й до шарів YOLO, які передбачають лише ймовірності.
Якщо рамки відображаються неправильно або їх розміри змінено некоректно, перевірте політику зміни розміру зображення. Використовуйте resize_mode_override лише тоді, коли ваш граф не має попереднього етапу Preproc, який записує метадані про зміну розміру.
Якщо ви створюєте власний набір моделей, переконайтеся, що в описі архіву точно вказано характеристики детекторів: порядок тензорів, логічна форма, фізичне зберігання, тип даних/квантування, діапазон значень, кількість класів і будь-які зрізані вихідні дані. Код застосунку не повинен містити жодних налаштувань для врахування цих деталей.

Рекомендації щодо форми та компонування.

Різні моделі детектування використовують різні схеми організації вихідних даних. Деякі використовують один тензор для кожного рівня ознак; інші розділяють обмежувальні рамки, інформацію про об’єкти, класи, ключові точки або маски на окремі тензори. Вихідні дані деяких моделей представлені у вигляді щільних тензорів HWC; інші тензори пакуються або розбиваються компілятором/середовищем виконання.

Для моделей, що використовують пакетну обробку, це регулюється відповідним контрактом. Для тензорів, з’єднаних вручну, головне правило полягає в тому, щоб точно відповідати експортованому формату вихідних даних. Не слід вибирати тип декодування лише на основі рангу або кількості каналів.

Розширені правила для тензорних контрактів:

Типи декодування сімейства YOLO: Yolo, YoloV5, YoloV7, YoloV8, YoloV9. YoloV10 та варіанти сегментації/визначення поз передбачають використання або незалежних головок, або згрупованих головок, які відповідають сімейству моделей.
Згорнуті шари YOLO повинні зберігати однакову кількість класів і глибину шарів. рівні функціональності.
YoloV26 використовує згруповані необроблені координати обмежувальних рамок (l/t/r/b) разом із заголовками, що визначають клас і оцінку.
Ssd – це не універсальний декодер для SSD-накопичувачів. Він обробляє лише чотири попередньо налаштовані профілі. з повного впорядкованого набору локальних/конфігураційних змінних H/W/C, визначеного під час компіляції. Будь-який інший набір або порядок змінних відхиляється, і виводиться повідомлення про помилку, яке містить інформацію про виявлений і підтримуваний набори:
- SSD300dboxes300_coco): вхідне зображення 300×300, карти ознак. {38,19,10,5,3,1}, апріорні значення для кожної комірки, {4,6,6,6,4,4}, порядок каналів впевненості. class*A + anchor, оцінки класів, отримані за допомогою функції softmax для кожного класу (включно з фоном під індексом 0).
- SSD-Mobile-300-v1 (ssd_anchor_generator): вхідний розмір 300×300, функція: карти {19,10,5,3,2,1}, апріорні значення для кожної комірки {3,6,6,6,6,6}, канал зворотного зв’язку замовити anchor*C + class, оцінки для кожного класу за допомогою сигмоїдної функції для кожного класу (фон ігнорується).
- SSD-Mobile-320-v1 (ssd_anchor_generator): вхідне зображення 320×320, вилучення ознак. карти {20,10,5,3,2,1}, апріорні значення для кожної комірки {3,6,6,6,6,6}, канал зворотного зв’язку замовити anchor*C + class, оцінки для кожного класу за допомогою сигмоїдної функції для кожного класу (фон ігнорується).
- SSDlite-Mobile-320-v1 (TorchVision DefaultBoxGenerator): 320×320 вхідні дані, карти ознак {20,10,5,3,2,1}, шість апріорних значень на комірку на кожному рівні, порядок локалізації anchor*4 + {dx,dy,dw,dh}, порядок впевненості anchor*C + class та оцінки класів за допомогою softmax для всіх 91 класу, включаючи фон.

Усі рецепти використовують згруповані локалізаційні голови для кожного рівня (глибина = 4 * priors-per-cell) у поєднанні з головами для оцінки класу (глибина = num_classes * priors-per-cell), масштабування дисперсії FasterRcnnBoxCoder (scale_xy 0.1, scale_wh 0.2) та попередню обробку з розтягуванням (анізотропне) зміна розміру. Активація оцінки фіксується рецептом (відповідає декодеру на пристрої), а згрупована структура, що базується на ролі, вибирається автоматично — залиште decode_type_option як Auto. Незгрупована структура відхиляється.

Розмір моделі є частиною профілю, а не лише геометрії голови. SSD300-v1 та SSD-Mobile-300-v1 вимагають 300×300; обидва профілі 320-v1 вимагають 320×320. Будь-яка цільова зміна розміру попередньої обробки або перевизначення розміру моделі відхиляється під час створення, оскільки таблиці апріорних значень і зворотна проєкція з розтягуванням дійсні лише для цього розміру кадру.

Конструкція SimaBoxDecode у сирому/автономному вигляді ніколи не визначає режим зміни розміру. Збережіть вимогу метаданих попередньої обробки Preproc або використовуйте явне перевантаження, щоб підтвердити зовнішньо виконану ResizeMode::Stretch; Letterbox і Crop відхиляються.

Контракт num_classes. Кількість закодованих класів завжди визначається з глибини голови впевненості (conf_depth / priors-per-cell, фон під індексом 0 включно). SSD300-v1 дозволяє вибір суміжного префіксу, наприклад, підготовлений маршрут 81-to-8; інші три профілі вимагають точної кількості закодованих класів. Недійсний вибір відхиляється під час створення. Залиште його без змін, щоб використовувати значення за замовчуванням профілю.

Detr визначає класи каналів на основі максимальної глибини головного об’єкта та вимагає наявності дійсного клас розмірності.
EffDet, RcnnStage1 та Centernet використовують контракти, що визначають їхню модельну структуру; роблять. не передавайте їх через модуль декодування типу YOLO.
*-seg типи декодування генерують вихідні дані, що містять інформацію про межі області, а також маскові дані, специфічні для конкретного завдання.

Якщо набір користувацьких моделей не відповідає жодній із повних замовлених сигнатур, підготуйте новий профіль, який буде явно підтримуватися, замість того, щоб послаблювати алгоритм зіставлення.

Нотатка про Python.

Під час налаштування параметрів моделі з використанням Python, якщо це можливо, використовуйте перелічуваний тип (enum) замість рядка:

opt = pyneat.ModelOptions()
opt.decode_type = pyneat.BoxDecodeType.YoloV8

Аналізуйте результати за допомогою допоміжного інструменту, який відповідає поставленій задачі моделі:

outputs = model.run([image])

boxes = pyneat.decode_bbox(outputs)[0].to_numpy()

pose = pyneat.decode_pose(outputs)[0]
pose_boxes = pose.boxes.to_numpy()
keypoints = pose.keypoints.to_numpy()

seg = pyneat.decode_segmentation(outputs)[0]
seg_boxes = seg.boxes.to_numpy()
masks = seg.masks.to_numpy()

Швидкий старт.​

Аргументи​

Вхідні та вихідні дані.​

Суперточка​

Корисне навантаження BBOX у форматі wire.​

Коли model.run повертає необроблені результати.​

Замінити контракт.​

Розшифруйте відображення типів даних.​

Вибір правильного типу.​

Рекомендації щодо форми та компонування.​

Нотатка про Python.​