Типы 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].

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() отрисовывает плотный результат normal или edge в его канонической визуализации; для других типов результата он вызывает исключение. Аннотированные изображения для остальных задач получают через predict(save=True).