Типи Results

Об'єкт Results

Один об'єкт Results описує одне зображення. Одне джерело зображення повертає один такий об'єкт, джерело-список або каталог повертає список, а stream=True повертає генератор, що послідовно їх видає.

from libreyolo import LibreYOLO, SAMPLE_IMAGE model = LibreYOLO("LibreYOLO9t.pt")result = model(SAMPLE_IMAGE) print(result.orig_shape, result.path)print(result.boxes.xyxy)print(result.boxes.conf)print(result.names[int(result.boxes.cls[0])])

Слоти даних

Кожен слот має значення None, якщо модель не створила відповідні дані. Слот, який заповнює сімейство, визначається його задачею.

result.normals є доступним для читання й запису псевдонімом result.normal_map.

Одночасно можна встановити кілька слотів. Модель сегментації заповнює і boxes, і masks; модель оцінювання погляду заповнює boxes рамками облич, а gaze кутами; модель сітки заповнює boxes рамками людей, а meshes вирівнює з ними за рядками.

Boxes

Рамки виявлення для одного зображення.

with_id(id) і with_orig_shape(orig_shape) повертають новий об'єкт Boxes, у якому замінено відповідне поле.

Masks

Маски екземплярів для одного зображення. data є тензором масок; xy повертає контури кожного екземпляра в пікселях, а xyn повертає їх нормалізованими.

Keypoints

Ключові точки пози, вирівняні за рядками з boxes. xy містить пару координат для кожної ключової точки, а xyn містить нормалізовану пару. conf є третім каналом, якщо він наявний у даних, інакше має значення None. has_visible є булевим масивом зі значенням true там, де conf > 0, і значенням true для всіх елементів, якщо каналу впевненості немає.

Points

Локалізація точок для одного зображення. data має форму (N, 4) з рядками x, y, class, confidence. Координати задано в абсолютних пікселях; xy, cls і conf розділяють стовпці, а xyn нормалізує координати.

Probs

Оцінки класифікації. top1 є індексом найкращого результату, top5 містить п'ять найкращих індексів, а top1conf і top5conf містять їхні оцінки.

OBB

Орієнтовані рамки. data містить 7 або 8 значень у кожному рядку: xywhr, необов'язковий ідентифікатор відстеження, потім впевненість і клас.

Gaze

Кути погляду для кожного обличчя в радіанах, форма (N, 2), з вирівнюванням за рядками відносно рамок облич у boxes. Стовпець 0 містить нахил, а стовпець 1 поворот згідно з домовленістю L2CS: додатний поворот спрямовує погляд ліворуч відносно людини, а додатний нахил спрямовує його вниз. pitch_deg і yaw_deg перетворюють значення на градуси, а direction_3d повертає одиничний вектор напрямку.

SemanticMask

Щільна семантична карта у формі (H, W) з цілочисловими ідентифікаторами класів на полотні початкового зображення. 255 є значенням ігнорування й ніколи не враховується як клас (SemanticMask.IGNORE_INDEX). classes перелічує наявні ідентифікатори класів, а class_mask(class_id) повертає булеву маску одного класу.

PanopticSegmentation

Кожен піксель отримує рівно один сегмент без перекриття, що поєднує області фону та екземпляри об'єктів. data є цілочисловою картою ідентифікаторів сегментів у формі (H, W); ідентифікатор сегмента 0 означає відсутність мітки (PanopticSegmentation.IGNORE_INDEX). segments_info є списком словників, по одному для кожного сегмента, кожен з яких містить щонайменше {"id": int, "category_id": int}, де id відповідає значенню на карті, а category_id індексує names. segment_ids перелічує наявні ідентифікатори, а segment_mask(segment_id) повертає булеву маску одного сегмента.

Поділ на об'єкти та фон є властивістю категорії, а не сегмента. Дані можуть денормалізувати її в кожен сегмент як "isthing": bool; якщо це відбувається, значення має збігатися з картою на рівні категорій.

DepthMap

Щільна карта відносної оберненої глибини у формі (H, W) зі значеннями з рухомою комою на полотні початкового зображення. Вищі значення означають меншу відстань до камери. Значення є відносними, а не метричними в метрах. min, max і mean обчислюються за скінченними значеннями, а normalized() масштабує карту до [0, 1].

DepthMap(data, orig_shape=None, encoding="inverse_depth") також приймає encoding="depth" і encoding="log_depth". Валідатори інтерпретують це перед вирівнюванням. Значення відносної глибини й далі не гарантують метричного масштабу.

NormalMap

Щільне поле нормалей поверхні типу float32 у формі (H, W, 3) на полотні початкового зображення в системі координат камери OpenCV: +x праворуч, +y донизу, +z углиб сцени. Нормалі спрямовано до камери, тому поверхня, паралельна площині зображення, має нормаль (0, 0, -1). Кожен піксель містить одиничний вектор. assert_normalized(atol=1e-4) перевіряє цей інваріант.

EdgeMap

Щільна карта ймовірностей країв типу float32 у формі (H, W) на полотні початкового зображення, де 0 означає не край, а 1 означає край. Безперервну карту збережено, щоб поріг обирав код виклику: binary(threshold=0.5) застосовує поріг, а array повертає подання numpy.

RestoredImage

Відновлене зображення RGB у формі (H, W, 3) типу uint8. Для надроздільної здатності полотно у Results.restore_scale разів більше за вхідне зображення. array повертає подання numpy, а save(path) записує зображення.

Matte

М'яка матова маска непрозорості типу float32 у формі (H, W) у діапазоні [0, 1] на полотні початкового зображення. 1 означає повністю передній план, а 0 повністю тло. М'яка матова маска охоплює жорстку маску видалення тла з порогом 0.5 і зберігає згладжені краї, які відкидає бінарна маска. array повертає подання numpy.

Для результату з матовою маскою Results.cutout(image=None) повертає масив RGBA у формі (H, W, 4) типу uint8, четвертим каналом якого є матова маска, а Results.save(path, image=None) записує цей виріз як PNG із прозорим тлом. Обидва методи беруть RGB з image, якщо його надано, інакше повторно завантажують його зі шляху Results.path.

OCRRegions

Локалізований текст із транскрипціями. data містить багатокутники типу float у формі (N, 4, 2) у пікселях початкового зображення, впорядковані від лівого верхнього кута до правого верхнього, правого нижнього й лівого нижнього; області розташовано в порядку читання, зверху вниз, а потім зліва направо. texts є списком із N транскрипцій. conf містить оцінку розпізнавання кожної області, а det_conf оцінку виявлення, обидва мають форму (N,).

Чотирикутники виявлення є справжніми багатокутниками, тому вони не заповнюють Results.boxes. xyxy повертає їхні вирівняні за осями оболонки.

Embeddings

L2-нормалізовані вектори із задачі embed, які завжди мають форму (N, D). Результат для всього зображення містить один рядок і не має рамок; ембединги областей вирівняно за рядками з boxes. Оскільки кожен рядок нормалізовано, косинусна подібність дорівнює скалярному добутку.

Identities

Іменовані збіги з галереєю, вирівняні за рядками з embeddings. Створюються, коли об'єкт Gallery передано до передбачення embed. name є списком, у якому елемент має значення None нижче порога збігу, а найближче ім'я нижче порога ніколи не вгадується. score є масивом оцінок збігу, а data об'єднує їх у пари.

Meshes

Параметричні сітки людського тіла, вирівняні за рядками з рамками людей у boxes. Усі дані подано в системі координат камери початкового зображення. transl має метричні значення в метрах, причому +z спрямовано від камери; vertices і joints3d мають метричні значення та вже враховують transl; joints2d задано в пікселях полотна початкового зображення, а не кадрованої ділянки, яку обробляла мережа. Жодне поле не містить світової системи координат або системи відліку сили тяжіння.

Схеми параметрів різняться між моделями тіла, тому форми ніде не задано жорстко. body_model називає параметризацію, а кількість зчитується з тензорів: num_vertices, num_joints, num_betas і has_vertices. params повертає словник параметрів, а save_obj(path, index=0) записує одну сітку. Поля: global_orient, body_pose, betas, transl, vertices, faces, joints3d, joints2d, conf, focal_length та extras.

Для body_model="mhr" обертання подано кутами Ейлера в радіанах, а не представленням вісь-кут, body_pose є плоским вектором параметрів для суглобів, а не трійкою для кожного суглоба, а betas є коефіцієнтами ідентифікаційної форми. Масштаб скелета, поза кистей і вираз обличчя містяться в extras.

Перетворення та вибір

Кожен об'єкт даних має методи to(*args, **kwargs), cpu(), cuda() і numpy(), а виклик одного з них для Results одночасно застосовує його до кожного заповненого слоту.

from libreyolo import LibreYOLO, SAMPLE_IMAGE model = LibreYOLO("LibreYOLO9t.pt")result = model(SAMPLE_IMAGE) # Усі дані переміщуються разом.result = result.cpu().numpy() # Рядки як звичайні словники, а потім як JSON.print(result.summary()[:1])print(result.to_json())

result[idx] вибирає рядки в усіх вирівняних за рядками даних. len(result) повертає кількість виявлень або точок, якщо рамок немає. result.update(...) повертає копію із заміненими вказаними слотами; метод приймає кожен слот, а також track_id і restore_scale.

summary і to_json

summary(normalize=False, decimals=5, embeddings=False) повертає список звичайних словників, по одному рядку для кожного виявлення, сегмента, точки або області залежно від установлених слотів. to_json(**kwargs) передає свої аргументи до summary і повертає рядок JSON.

plot() відображає дані кожного завдання. Накладання на зображення типово повертають масиви BGR; pil=True запитує PIL. Карти глибини, нормалей, країв і альбедо, кубоїди 3D і фрагменти дій типово повертають зображення PIL; pil=False повертає масив.

Boxes3D

Boxes3D(data, orig_shape=None, intrinsics=None) містить рядки (N, 14): центр xyz, розміри wlh, кватерніон wxyz, оцінку ранжування, ID класу, впевненість 2D і впевненість 3D. Координати задано в метрах у системі камери: x праворуч, y вниз і z вперед; світова система координат не мається на увазі. Внутрішні параметри 3x3 стосуються початкового полотна. Рядки узгоджено з Results.boxes.

AlbedoMap

AlbedoMap(data, orig_shape=None) містить лінійний RGB. Перетворення для відображення створює sRGB; кількісна валідація альбедо використовує початкові лінійні значення.

Actions

Actions(data, orig_shape=None, names=None, fps=None, instruction=None) представляє фрагмент дій float32 (T, D). first повертає перший рядок; зріз вибирає часові кроки. Значення залишаються в одиницях датасету політики. names описує виміри дій, fps частоту керування, а instruction текст умови.

GeneratedImage

GeneratedImage(data, orig_shape=None, *, prompt=None, seed=None, params=None) містить одне синтезоване зображення, (H, W, 3) uint8 RGB. array повертає представлення numpy, а image повертає PIL.Image. prompt є текстом, що створив зображення, а seed цілим числом, яке відтворює його з тією самою моделлю та налаштуваннями; params фіксує решту виклику: model, imgsz і всі чинні налаштування сімейства. save(path) записує зображення, а PNG також зберігає to_dict(), тобто форму, запит, seed і params, як JSON у текстовому блоці libreyolo.

У згенерованому результаті Results.boxes і Results.path мають значення None, orig_shape є власним (H, W) зображення, а len(result) дорівнює 1. Results.save(path) записує зображення, plot() повертає його як зображення PIL, а summary() повертає один рядок із записом корисних даних.

Gaussians

Gaussians(xyz, scales, rotations, opacities, sh, *, camera=None, seed=None, params=None, input_image=None) містить один згенерований 3D-об'єкт як гауссові сплати у власній системі координат об'єкта: z угору, з центром у кубі [-0.5, 0.5]^3. Кожен рядок є одним гауссіаном.

len(gaussians) дорівнює N, а gaussians[gaussians.opacities > 0.1] повертає новий Gaussians з вибраними рядками. save(path) записує за розширенням. .ply має стандартне компонування 3D Gaussian Splatting з логарифмічними масштабами та логітними непрозоростями, повернене y угору, як очікують переглядачі сплатів, і рядок заголовка comment libreyolo із seed, камерою та params у форматі JSON. Корисні дані з кольором вищого порядку (K > 1) спричиняють NotImplementedError для .ply. .splat є компактним вебформатом, 32 байти на гауссіан. render(size=512, background=(0, 0, 0)) повертає точковий рендер із виведеного вхідного ракурсу як PIL.Image: швидкий огляд, а не растеризацію гауссіанів.

У згенерованому 3D-результаті Results.boxes має значення None; path, orig_shape і orig_img описують вихідне зображення, а len(result) дорівнює

1. Results.save(path) записує об'єкт, plot() повертає цей точковий рендер, а summary() повертає один рядок із записом корисних даних.