Типы 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; модель gaze заполняет boxes рамками лиц, а gaze — углами; модель mesh заполняет boxes рамками людей, а meshes — мешами, построчно согласованными с ними.

Boxes

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

with_id(id) и with_orig_shape(orig_shape) возвращают новый Boxes с заменённым полем.

Masks

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

Keypoints

Ключевые точки позы, построчно соответствуют boxes. xy — пара координат на каждую точку, xyn — нормализованная пара. conf — третий канал, если он есть в данных, иначе None. has_visible — булев массив, истинный там, где conf > 0, и полностью истинный, когда канала уверенности нет.

Points

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

Probs

Оценки классификации. top1 — индекс победителя, top5 — пять лучших индексов, а top1conf и top5conf — их оценки.

OBB

Повёрнутые рамки. data содержит 7 или 8 значений в строке: xywhr, необязательный ID трека, затем уверенность и класс.

Gaze

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

SemanticMask

Плотная семантическая карта, форма (H, W) из целочисленных ID классов на холсте исходного изображения. 255 — значение игнорирования, оно никогда не считается классом (SemanticMask.IGNORE_INDEX). classes перечисляет присутствующие ID классов, а class_mask(class_id) возвращает булеву маску одного класса.

PanopticSegmentation

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

Принадлежность к thing или stuff — свойство категории, а не сегмента. Полезная нагрузка может денормализовать её в каждый сегмент как "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

Мягкая карта непрозрачности (matte), float32 (H, W) в диапазоне [0, 1] на холсте исходного изображения. 1 — полностью передний план, 0 — полностью фон. Мягкий matte включает в себя жёсткую маску удаления фона, полученную порогом 0.5, и сохраняет сглаженные края, которые бинарная маска отбрасывает. array возвращает numpy-представление.

На результате matte Results.cutout(image=None) возвращает RGBA-массив (H, W, 4) uint8, четвёртый канал которого — это matte, а Results.save(path, image=None) сохраняет этот вырез как PNG с прозрачным фоном. Оба берут RGB из image, если он передан, иначе перечитывают его по Results.path.

OCRRegions

Найденный текст вместе с распознанными строками. data — полигоны (N, 4, 2) из чисел с плавающей точкой в пикселях исходного изображения, порядок вершин — верхняя левая, верхняя правая, нижняя правая, нижняя левая, а сами регионы идут в порядке чтения, сверху вниз, затем слева направо. texts — список из N распознанных строк. conf — оценка распознавания по каждому региону, а det_conf — оценка детекции, обе формы (N,).

Четырёхугольники детекции — настоящие полигоны, поэтому они не заполняют Results.boxes. xyxy даёт оболочки, выровненные по осям.

Embeddings

L2-нормированные векторы из задачи embed, всегда формы (N, D). Результат по всему изображению несёт одну строку и не имеет рамок; эмбеддинги регионов построчно соответствуют boxes. Поскольку каждая строка нормирована, косинусное сходство — это скалярное произведение.

Identities

Именованные совпадения по галерее, построчно соответствуют embeddings. Появляются, когда в предсказание embed передана Gallery. 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() возвращает одну строку с записью данных.