Формати датасетів

Спільний YAML

Застосовується до detect, segment, pose та obb.

train, val і test можуть бути каталогами зображень, файлами .txt зі списками зображень або списками таких елементів. Шляхи міток визначаються однією заміною:

images/.../image.jpg -> labels/.../image.txt

Для датасету у власному форматі COCO JSON ключ annotations зіставляє вибірку з її файлом JSON, а шлях вибірки задає корінь зображень:

path: dataset
train: images/train
val: images/val
annotations:
  train: annotations/train.json
  val: annotations/val.json

За наявності names назви категорій у власному COCO JSON мають збігатися з назвами класів YAML, які визначають ідентифікатори міток моделі. Без names ідентифікатори категорій COCO сортуються й щільно зіставляються з 0..N-1.

YAML датасету не містить ключа task. Явний вибір моделі й завдання має перевагу.

Правила, спільні для кожного текстового файла міток:

• один файл міток .txt на зображення;
• відсутній або порожній файл міток означає відсутність об'єктів;
• class_id є цілим числом у 0..nc-1;
• координати є скінченними нормалізованими числами з рухомою комою в [0, 1];
• координати задано відносно початкової ширини й висоти зображення;
• рядки не містять упевненості та ідентифікатора відстеження.

from libreyolo.data import parse_yolo_label_line # class_id cx cy w h, нормалізовані до [0, 1]row = parse_yolo_label_line("0 0.5 0.5 0.25 0.5", 640, 480, num_classes=80) # (class_id, x1, y1, x2, y2, area) у пікселяхprint(row)

detect

Рівно п'ять полів у рядку:

<class_id> <cx> <cy> <w> <h>

cx cy w h задає нормалізовану рамку, вирівняну за осями, а w і h мають бути додатними.

segment

Рядок полігона:

<class_id> <x1> <y1> ... <xN> <yN>

N становить щонайменше 3, кількість координат після class_id має бути парною, а полігон не може бути виродженим. Також приймається п'ятипольний рядок виявлення, що представляє прямокутний сегмент.

pose

YAML додає обов'язковий kpt_shape зі значенням [K, 2] або [K, 3] і необов'язковий flip_idx, цілочислову перестановку 0..K-1.

<class_id> <cx> <cy> <w> <h> <k1x> <k1y> [<k1v>] ... <kKx> <kKy> [<kKv>]

Кількість полів точно дорівнює 5 + K * D, де D є другим значенням kpt_shape. Координати ключових точок нормалізовані. Видимість v, якщо вона наявна, дорівнює 0, 1 або 2.

obb

Рівно дев'ять полів:

<class_id> <x1> <y1> <x2> <y2> <x3> <y3> <x4> <y4>

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

Канонічний аналізатор типово працює суворо й відхиляє координати поза діапазоном. Завантаження датасету та валідації може обмежувати координати до [0, 1] для інших коректних міток на межі обрізання, але все одно відхиляє вироджені рамки. Розбір ураховує завдання: дев'ять полів означають obb лише в режимі obb, тоді як у режимі segment вони можуть представляти полігон із чотирьох точок.

Усередині нормалізовані кути перетворюються на канонічний xywhr, де кут у радіанах представляє поворот сторони ширини навколо центра рамки. Публічні результати надають виявлення OBB як рядки xywhr, conf, cls.

Завантаження OBB із власного COCO JSON приймає анотації в такому порядку пріоритету: obb як вісім кутів у пікселях; obb як [cx, cy, w, h, angle] із кутом у радіанах; полігон або RLE segmentation COCO, повторно вписаний у прямокутник мінімальної площі; bbox COCO, зчитаний як вирівняний за осями та приведений до канонічного вигляду.

Mosaic і mixup вимкнено для навчання OBB, доки не з'явиться аугментація OBB з урахуванням кутів.

Канонічним аналізатором рядків є libreyolo.data.parse_yolo_obb_label_line.

semantic

Кожне зображення поєднується зі щільною одноканальною маскою у форматі без втрат, типово PNG, замість файла .txt:

images/.../image.jpg -> <masks_dir>/.../image.png

Маска одноканальна, а PNG у режимі палітри зчитуються як індекси палітри. Кожне значення пікселя є ідентифікатором класу в 0..nc-1, значення пікселя 255 означає ігнорування та не входить до функції втрат і метрик, а роздільна здатність маски має дорівнювати роздільній здатності зображення.

Спільний контракт доповнюють два необов'язкові ключі YAML. masks_dir є назвою каталогу масок, якою замінюється images у кожному шляху зображення, типово masks. label_mapping є перетворенням {source_id: train_id}, застосованим до значень пікселів маски під час завантаження. Незіставлені початкові значення стають значенням ігнорування, а навчальні ідентифікатори мають входити до 0..nc-1.

Якщо masks_dir не вказано, маски растеризуються під час завантаження з полігонних міток segment, визначених за домовленістю заміни images на labels, а після класів об'єктів додається клас background, тому nc збільшується на один.

Канонічний завантажувач: libreyolo.data.SemanticDataset.

panoptic

LibreYOLO дослівно приймає формат COCO-panoptic (Kirillov et al., CVPR 2019). Окремого паноптичного формату LibreYOLO немає.

Один RGB PNG на зображення з роздільною здатністю зображення кодує ідентифікатор сегмента кожного пікселя в його кольорі:

segment_id = R + 256 * G + 256 * 256 * B

Кожен піксель належить рівно одному сегменту, а сегменти ніколи не перекриваються. Ідентифікатор сегмента 0, чорний RGB, позначає порожню область: нерозмічені пікселі, вилучені з метрики.

{
  "images":      [{"id": 139, "file_name": "000000000139.jpg"}],
  "annotations": [{"image_id": 139, "file_name": "000000000139.png",
                   "segments_info": [
                     {"id": 3226956, "category_id": 1, "area": 2840,
                      "bbox": [413, 158, 53, 138], "iscrowd": 0}]}],
  "categories":  [{"id": 1, "name": "person", "isthing": 1, "supercategory": "person"}]
}

annotations[].file_name задає назву PNG з ідентифікаторами сегментів усередині panoptic_dir, а segments_info[].id відповідає значенню в цьому PNG. iscrowd позначає групові області: вони ніколи не є хибнонегативними, а передбачення, що здебільшого покриває таку область, не є хибнопозитивним.

Належність до об'єктів або фону є властивістю кожної категорії. isthing розташовується в categories, а не в segments_info.

Значення category_id у COCO-panoptic є початковими ідентифікаторами датасету й зазвичай не є послідовними. Моделі передбачають послідовні 0..nc-1, тому початкові ідентифікатори перетворюються через names YAML за назвою категорії, як у власному завантажувачі COCO JSON для виявлення. Категорія JSON, відсутня в names, є помилкою, а не непомітно відкидається, бо інакше вона постійно оцінювалася б як хибнонегативна.

path: coco
val: images/val2017
annotations:
  val: annotations/panoptic_val2017.json
panoptic_dir:
  val: annotations/panoptic_val2017
names: {0: person, 1: bicycle, 132: rug-merged}

annotations і panoptic_dir приймають окремий шлях або відповідність для кожної вибірки.

Валідація повідомляє Panoptic Quality, обчислену з роздільною здатністю еталонних даних та усереднену за наявними категоріями, а потім розділену на PQ_things і PQ_stuff. Зіставлення унікальне: передбачений та еталонний сегменти однієї категорії збігаються, коли IoU перевищує 0.5.

Канонічний завантажувач: libreyolo.data.PanopticDataset.

depth

Кожне зображення поєднується зі щільною одноканальною картою глибини:

images/.../image.jpg -> <depths_dir>/.../image.png

Карта є одноканальним PNG чи TIF або файлом .npy із роздільною здатністю зображення. Значення є звичайною глибиною в одиниці, узгодженій для датасету. Нульові, від'ємні, NaN та нескінченні значення позначають недійсні пікселі й не враховуються у функції втрат і метриках.

Карти .npy з рухомою комою використовуються без змін і не застосовують depth_scale.

Канонічний завантажувач: libreyolo.data.DepthDataset.

edge

Кожне зображення RGB поєднується з одноканальною картою без втрат із тією самою основою назви та необов'язковою маскою дійсності:

images/val/scene.jpg -> edges/val/scene.png
                     -> masks/val/scene.png

Карта є одноканальним PNG або TIF, а не візуалізацією RGB, із роздільною здатністю зображення. Цілочислові карти діляться на максимальне значення свого типу, а карти з рухомою комою вже мають бути скінченними та входити до [0, 1]. 0 означає відсутність краю, а 1 означає край. Пікселі необов'язкової маски дійсні, коли їхнє значення ненульове. Зміна розміру використовує інтерполяцію найближчого сусіда для цілей і масок, а доповнені пікселі недійсні й не беруть участі у валідації.

path: edge-dataset
train: images/train
val: images/val
edges_dir: edges
masks_dir: masks
nc: 1
names: {0: edge}

Валідація стоншує неперервні передбачення за допомогою немаксимального придушення градієнта в чотирьох напрямках і повідомляє F-міри ODS та OIS за налаштовуваним перебором порогів. Передбачені та еталонні пікселі зіставляються один-до-одного в межах edge_max_dist * image_diagonal, з типовим нормалізованим допуском 0.0075.

Канонічний завантажувач: libreyolo.data.EdgeDataset. Завантажувач працює лише з форматом і не завантажує чи розповсюджує дані бенчмарків.

normal

Кожне зображення поєднується з триканальним 16-бітним PNG із тією самою основою назви та необов'язковою маскою дійсності з тією самою основою:

images/val/room.jpg -> normals/val/room.png
                    -> masks/val/room.png

PNG є точно триканальним uint16 із каналами, збереженими як RGB, і має роздільну здатність зображення. Декодуйте через n = png / 65535 * 2 - 1, а потім повторно нормалізуйте кожен вектор. Декодовані вектори використовують систему координат камери OpenCV, де +x спрямовано праворуч, +y вниз, +z углиб сцени, а самі вектори спрямовані до камери. Необов'язкова маска є одноканальним PNG, де ненульове значення означає дійсний піксель; без маски дійсним є кожен скінченний ненульовий декодований вектор. Недійсні та доповнені цільові пікселі всередині представлено як (0, 0, 0). Під час зміни розміру три компоненти інтерполюються білінійно, а потім повторно нормалізуються, маски дійсності використовують інтерполяцію найближчого сусіда, а горизонтальне віддзеркалення також змінює знак компонента x.

Валідація повідомляє середню та медіанну кутову помилку в градусах і відсоток дійсних пікселів у межах 11.25, 22.5 і 30 градусів.

Канонічний завантажувач: libreyolo.data.NormalDataset.

restore

Кожне спотворене вхідне зображення поєднується з чистою ціллю RGB:

inputs/.../image.jpg -> targets/.../image.jpg

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

Поля YAML, подібні до класів, є заповнювачами схеми: використовуйте nc: 1 і names: {0: image}. Моделі відновлення надають Results.restored, а не виявлення.

Канонічний завантажувач: libreyolo.data.RestoreDataset.

matte

Кожне зображення RGB поєднується з еталонним одноканальним matte з тією самою основою назви, де 0 означає тло, а 255 означає передній план:

images/subject.jpg -> mattes/subject.png

Приймаються дві структури. Кореневий каталог із images/ та каталогом matte, автоматично знайденим серед mattes/, matte/, gt/, masks/, mask/ і alpha/, передається як data=. Або YAML із path та окремими для вибірок val_images і val_mattes, а також необов'язковими train_images і train_mattes, кожен шлях відносний до path або абсолютний.

Matte зчитується у відтінках сірого як непрозорість у [0, 1] і змінює розмір до полотна передбачення за допомогою білінійної інтерполяції, якщо форми відрізняються. Метриками є MAE та S-measure (Fan et al., ICCV 2017) на початковому полотні зображення, а S-measure визначає найкращу контрольну точку.

Поля YAML, подібні до класів, є заповнювачами схеми: використовуйте nc: 1 і names: {0: matte}. Моделі matte надають Results.matte.

У цій версії валідація доступна лише для інференсу. Канонічний засіб зіставлення пар: libreyolo.data.matte_dataset.resolve_matte_pairs.

ocr

Мітки зберігаються в одному файлі JSONL на вибірку, по одному об'єкту JSON на зображення:

images/val/receipt.jpg -> labels/val.jsonl

{"image": "receipt.jpg", "regions": [{"polygon": [[10, 12], [118, 14], [117, 40], [9, 38]], "text": "TOTAL 12.50"}]}

polygon є чотириточковим чотирикутником в абсолютних піксельних координатах із порядком верхній лівий, верхній правий, нижній правий, нижній лівий. Області з нерозбірливим текстом використовують "text": "###", домовленість ICDAR для ігнорування: вони не враховуються в оцінюванні розпізнавання, а передбачення, що їх перекривають, ігноруються замість штрафу під час зіставлення виявлень.

Метрики включають hmean виявлення з однозначним зіставленням полігонів за IoU вище 0.5, наскрізну F1, що потребує одночасно IoU вище 0.5 і точного збігу транскрипції після нормалізації NFKC та вилучення пробілів з урахуванням регістру, а також 1-NED для зіставлених пар. Наскрізна F1 визначає найкращу контрольну точку.

Приймаються дві структури: кореневий каталог із images/<split>/ і labels/<split>.jsonl, переданий як data=, або YAML із path та необов'язковими назвами каталогів images і labels.

Поля YAML, подібні до класів, є заповнювачами схеми: використовуйте nc: 1 і names: {0: text}. Моделі OCR надають Results.ocr.

У цій версії валідація доступна лише для інференсу. Канонічний засіб визначення зразків: libreyolo.data.ocr_dataset.resolve_ocr_samples.

classify

Дерево каталогів у стилі ImageFolder, а не файли міток:

dataset_root/
  train/
    class_a/*.jpg
    class_b/*.jpg
  val/
    class_a/*.jpg
    class_b/*.jpg

train/ обов'язковий для навчання й визначає відповідність класу індексу за відсортованою назвою папки. val/ обов'язковий для валідації. test/ може бути наявним, але типові команди навчання й валідації його не використовують. Ненавчальні вибірки мають містити ті самі назви папок класів, що й очікуваний набір класів навчання або контрольної точки. Підтримувані розширення зображень визначено в libreyolo.data.classify_dataset.IMAGE_EXTENSIONS.

gaze і point

Для gaze не реалізовано контракт файла датасету для навчання чи валідації.

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