Types de résultats

Objet Results

Un objet Results décrit une image. Une source image unique en renvoie un, une source liste ou un répertoire en renvoie une liste, et stream=True renvoie un générateur qui les produit.

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])])

Emplacements des charges utiles

Chaque emplacement vaut None si le modèle ne l'a pas produit. La tâche de la famille détermine l'emplacement qu'elle remplit.

result.normals est un alias en lecture-écriture de result.normal_map.

Plusieurs emplacements peuvent être définis simultanément. Un modèle de segmentation remplit boxes et masks, un modèle de regard remplit boxes avec les bounding boxes des visages et gaze avec les angles, et un modèle de maillage remplit boxes avec les bounding boxes des personnes et meshes aligné ligne par ligne avec celles-ci.

Boxes

Bounding boxes de détection pour une image.

with_id(id) et with_orig_shape(orig_shape) renvoient un nouvel objet Boxes dans lequel ce champ est remplacé.

Masks

Masques d'instances pour une image. data est le tenseur de masques, xy renvoie les contours par instance en pixels et xyn les renvoie normalisés.

Keypoints

Points clés de pose, alignés ligne par ligne avec boxes. xy est la paire de coordonnées de chaque point clé et xyn la paire normalisée. conf est le troisième canal lorsque les données en possèdent un, sinon None. has_visible est un tableau booléen, true lorsque conf > 0, et entièrement true en l'absence de canal de confiance.

Points

Localisation de points pour une image. data a la forme (N, 4) et ses lignes sont x, y, class, confidence. Les coordonnées sont des pixels absolus. xy, cls et conf séparent les colonnes, tandis que xyn normalise les coordonnées.

Probs

Scores de classification. top1 est l'indice gagnant, top5 les cinq meilleurs indices, et top1conf et top5conf leurs scores.

OBB

Bounding boxes orientées. data contient 7 ou 8 valeurs par ligne : xywhr, un identifiant de suivi facultatif, puis la confiance et la classe.

Gaze

Angles du regard par visage en radians, de forme (N, 2), alignés ligne par ligne avec les bounding boxes des visages dans boxes. La colonne 0 est le tangage et la colonne 1 le lacet selon la convention L2CS : un lacet positif tourne le regard vers la gauche du sujet et un tangage positif le tourne vers le bas. pitch_deg et yaw_deg convertissent en degrés, et direction_3d renvoie le vecteur direction unitaire.

SemanticMask

Carte sémantique dense, de forme (H, W), contenant les identifiants de classe entiers sur le canevas de l'image d'origine. 255 est la valeur à ignorer et n'est jamais compté comme classe (SemanticMask.IGNORE_INDEX). classes énumère les identifiants de classe présents et class_mask(class_id) renvoie le masque booléen d'une classe.

PanopticSegmentation

Chaque pixel reçoit exactement un segment sans chevauchement, ce qui unifie les régions stuff et les instances thing. data est une carte entière d'identifiants de segments (H, W). L'identifiant 0 est sans étiquette (PanopticSegmentation.IGNORE_INDEX). segments_info est une liste de dictionnaires, un par segment, contenant chacun au moins {"id": int, "category_id": int}, où id correspond à une valeur de la carte et category_id indexe names. segment_ids énumère les identifiants présents et segment_mask(segment_id) renvoie le masque booléen d'un segment.

La distinction thing ou stuff est une propriété de la catégorie, pas du segment. Une charge utile peut la dénormaliser sur chaque segment sous la forme "isthing": bool, auquel cas la valeur doit correspondre à la table au niveau de la catégorie.

DepthMap

Carte dense de profondeur inverse relative, de forme (H, W) et composée de flottants sur le canevas de l'image d'origine. Les valeurs élevées signifient une plus grande proximité avec la caméra. Les valeurs sont relatives et ne représentent pas des mètres. min, max et mean sont calculés sur les valeurs finies, et normalized() remet la carte à l'échelle dans [0, 1].

DepthMap(data, orig_shape=None, encoding="inverse_depth") accepte aussi encoding="depth" et encoding="log_depth". Les validateurs interprètent cet encodage avant l'alignement. Les valeurs de profondeur relative n'offrent toujours aucune garantie d'échelle métrique.

NormalMap

Champ dense de normales de surface, float32 (H, W, 3), sur le canevas de l'image d'origine dans le repère caméra OpenCV : +x vers la droite, +y vers le bas et +z dans la scène. Les normales font face à la caméra, une surface fronto-parallèle vaut donc (0, 0, -1). Chaque pixel est un vecteur unitaire. assert_normalized(atol=1e-4) vérifie cet invariant.

EdgeMap

Carte dense de probabilités des contours, float32 (H, W), sur le canevas de l'image d'origine, où 0 n'est pas un contour et 1 en est un. La carte continue est conservée afin que le seuil reste au choix de l'appelant : binary(threshold=0.5) en applique un et array renvoie la vue numpy.

RestoredImage

Image RGB restaurée, uint8 (H, W, 3). Pour la super-résolution, le canevas est Results.restore_scale fois plus grand que l'entrée. array renvoie la vue numpy et save(path) écrit l'image.

Matte

Matte d'opacité souple, float32 (H, W) dans [0, 1] sur le canevas de l'image d'origine. 1 représente entièrement le premier plan et 0 entièrement l'arrière-plan. Un matte souple englobe un masque dur de suppression de l'arrière-plan seuillé à 0.5 et conserve les bords anti-crénelés qu'un masque binaire supprime. array renvoie la vue numpy.

Sur un résultat de matting, Results.cutout(image=None) renvoie un tableau RGBA uint8 (H, W, 4) dont le quatrième canal est le matte, et Results.save(path, image=None) écrit cette découpe comme PNG à arrière-plan transparent. Les deux utilisent le RGB de image s'il est fourni, sinon ils le rechargent depuis Results.path.

OCRRegions

Texte localisé avec transcriptions. data contient des polygones float (N, 4, 2) en pixels de l'image d'origine, dans l'ordre haut-gauche, haut-droit, bas-droit, bas-gauche. Les régions suivent l'ordre de lecture, du haut vers le bas puis de gauche à droite. texts est la liste des N transcriptions. conf est le score de reconnaissance par région et det_conf le score de détection, tous deux de forme (N,).

Les quadrilatères de détection sont de véritables polygones, ils ne remplissent donc pas Results.boxes. xyxy donne leurs enveloppes alignées sur les axes.

Embeddings

Vecteurs normalisés L2 de la tâche embed, toujours de forme (N, D). Un résultat portant sur l'image entière contient une ligne et aucune bounding box. Les embeddings de régions sont alignés ligne par ligne avec boxes. Chaque ligne étant normalisée, la similarité cosinus est un produit scalaire.

Identities

Correspondances nommées d'une galerie, alignées ligne par ligne avec embeddings. Produites lorsqu'une Gallery est transmise à une prédiction embed. name est une liste dont une entrée vaut None sous le seuil de correspondance. Le nom le plus proche sous ce seuil n'est jamais deviné. score est le tableau des scores de correspondance et data les associe.

Meshes

Maillages paramétriques de corps humains, alignés ligne par ligne avec les bounding boxes de personnes dans boxes. Tout est exprimé dans le repère caméra de l'image d'origine. transl est métrique, en mètres, avec +z orienté à l'opposé de la caméra. vertices et joints3d sont métriques et incluent déjà transl. joints2d est exprimé en pixels sur le canevas de l'image d'origine, et non sur le recadrage reçu par le réseau. Aucun champ ne porte de repère mondial ou gravitationnel.

La disposition des paramètres diffère entre les modèles corporels, rien n'est donc codé en dur concernant les formes. body_model nomme le paramétrage et les nombres sont relus dans les tenseurs : num_vertices, num_joints, num_betas et has_vertices. params renvoie le dictionnaire de paramètres et save_obj(path, index=0) écrit un maillage. Les champs sont global_orient, body_pose, betas, transl, vertices, faces, joints3d, joints2d, conf, focal_length et extras.

Pour body_model="mhr", les rotations sont des angles d'Euler en radians plutôt qu'un format axe-angle, body_pose est un vecteur plat de paramètres par articulation plutôt qu'un triplet par articulation, et betas contient les coefficients de blendshape d'identité. L'échelle du squelette, la pose des mains et l'expression faciale se trouvent dans extras.

Conversion et sélection

Chaque charge utile possède to(*args, **kwargs), cpu(), cuda() et numpy(). L'appel de l'une de ces méthodes sur Results l'applique en une fois à tous les emplacements remplis.

from libreyolo import LibreYOLO, SAMPLE_IMAGE model = LibreYOLO("LibreYOLO9t.pt")result = model(SAMPLE_IMAGE) # Toutes les charges utiles sont déplacées ensemble.result = result.cpu().numpy() # Lignes sous forme de dictionnaires simples, puis en JSON.print(result.summary()[:1])print(result.to_json())

result[idx] sélectionne les lignes des charges utiles alignées. len(result) est le nombre de détections, ou de points en l'absence de bounding boxes. result.update(...) renvoie une copie dans laquelle les emplacements nommés sont remplacés. Il accepte chaque emplacement ainsi que track_id et restore_scale.

summary et to_json

summary(normalize=False, decimals=5, embeddings=False) renvoie une liste de dictionnaires simples, une ligne par détection, segment, point ou région selon les emplacements définis. to_json(**kwargs) transmet ses arguments à summary et renvoie la chaîne JSON.

plot() affiche toutes les charges utiles de tâche. Les superpositions d'image utilisent des tableaux BGR par défaut ; pil=True demande une image PIL. Les cartes de profondeur, de normales, de contours et d'albédo, les cuboïdes 3D et les séquences d'actions renvoient par défaut une image PIL ; pil=False renvoie le tableau.

Boxes3D

Boxes3D(data, orig_shape=None, intrinsics=None) contient des lignes (N, 14) : centre xyz, dimensions wlh, quaternion wxyz, score de classement, identifiant de classe, confiance 2D et confiance 3D. Les coordonnées sont en mètres dans le repère caméra, avec x vers la droite, y vers le bas et z vers l'avant ; aucun repère monde n'est implicite. Les paramètres intrinsèques 3x3 correspondent au canevas d'origine. Les lignes sont alignées avec Results.boxes.

AlbedoMap

AlbedoMap(data, orig_shape=None) contient du RGB linéaire. La conversion d'affichage produit du sRGB ; la validation quantitative de l'albédo utilise les valeurs linéaires d'origine.

Actions

Actions(data, orig_shape=None, names=None, fps=None, instruction=None) représente une séquence d'actions float32 (T, D). first renvoie la première ligne ; le découpage sélectionne les pas de temps. Les valeurs restent dans les unités du dataset de la politique. names décrit les dimensions des actions, fps la cadence de contrôle et instruction le texte de conditionnement.

GeneratedImage

GeneratedImage(data, orig_shape=None, *, prompt=None, seed=None, params=None) contient une image synthétisée, (H, W, 3) uint8 RGB. array renvoie la vue numpy et image une PIL.Image. prompt est le texte qui a produit l'image et seed l'entier qui la reproduit avec le même modèle et les mêmes réglages ; params consigne le reste de l'appel : model, imgsz et chaque réglage de famille en vigueur. save(path) écrit l'image, et un PNG stocke aussi to_dict(), la forme, le prompt, la seed et les params, sous forme de JSON dans un chunk texte libreyolo.

Sur un résultat généré, Results.boxes et Results.path valent None, orig_shape est le (H, W) propre à l'image, et len(result) vaut 1. Results.save(path) écrit l'image, plot() la renvoie sous forme d'image PIL, et summary() renvoie une ligne avec l'enregistrement de la charge utile.

Gaussians

Gaussians(xyz, scales, rotations, opacities, sh, *, camera=None, seed=None, params=None, input_image=None) contient un objet 3D généré sous forme de splats gaussiens, dans le repère propre à l'objet : z vers le haut, centré dans le cube [-0.5, 0.5]^3. Chaque ligne est une gaussienne.

len(gaussians) vaut N, et gaussians[gaussians.opacities > 0.1] renvoie un nouvel objet Gaussians contenant les lignes sélectionnées. save(path) écrit selon l'extension. .ply est la disposition standard du 3D Gaussian Splatting, avec des échelles en log et des opacités en logit, orientée y vers le haut comme les visionneuses de splats l'attendent, et une ligne d'en-tête comment libreyolo qui contient la seed, la caméra et les params en JSON. Une charge utile avec une couleur d'ordre supérieur (K > 1) lève NotImplementedError pour .ply. .splat est le format web compact, 32 octets par gaussienne. render(size=512, background=(0, 0, 0)) renvoie un rendu en points depuis la vue d'entrée inférée sous forme de PIL.Image, un aperçu rapide plutôt qu'une rastérisation gaussienne.

Sur un résultat 3D généré, Results.boxes vaut None ; path, orig_shape et orig_img décrivent l'image source, et len(result) vaut 1. Results.save(path) écrit l'objet, plot() renvoie ce rendu en points, et summary() renvoie une ligne avec l'enregistrement de la charge utile.