Tipos de Results

El objeto Results

Un Results describe una imagen. Una fuente de una sola imagen devuelve uno, una fuente de tipo lista o un directorio devuelve una lista, y stream=True devuelve un generador que los va produciendo.

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

Slots de payload

Cada slot es None salvo que el modelo lo haya producido. El slot que rellena cada familia lo decide su tarea.

result.normals es un alias de lectura y escritura de result.normal_map.

Puede haber más de un slot relleno a la vez. Un modelo de segmentación rellena tanto boxes como masks; un modelo de gaze rellena boxes con los bounding boxes de las caras y gaze con los ángulos; un modelo de mesh rellena boxes con los bounding boxes de las personas y meshes alineado por filas con ellos.

Boxes

Bounding boxes de detección de una imagen.

with_id(id) y with_orig_shape(orig_shape) devuelven un Boxes nuevo con ese campo sustituido.

Masks

Máscaras de instancia de una imagen. data es el tensor de máscaras; xy devuelve los contornos por instancia en píxeles y xyn los devuelve normalizados.

Keypoints

Keypoints de pose, alineados por filas con boxes. xy es el par de coordenadas por keypoint y xyn el par normalizado. conf es el tercer canal cuando los datos lo llevan, y None en caso contrario. has_visible es un array de booleanos, verdadero donde conf > 0, y todo verdadero cuando no hay canal de confianza.

Points

Localización de puntos de una imagen. data tiene forma (N, 4) con filas x, y, class, confidence. Las coordenadas son píxeles absolutos; xy, cls y conf reparten las columnas, y xyn normaliza las coordenadas.

Probs

Puntuaciones de clasificación. top1 es el índice ganador, top5 los cinco mejores índices, y top1conf y top5conf sus puntuaciones.

OBB

Bounding boxes orientados. data contiene 7 u 8 valores por fila: xywhr, un ID de track opcional, y después la confianza y la clase.

Gaze

Ángulos de mirada por cara en radianes, forma (N, 2), alineados por filas con los bounding boxes de las caras de boxes. La columna 0 es el pitch y la columna 1 el yaw, según la convención L2CS: un yaw positivo gira la mirada hacia la izquierda del sujeto y un pitch positivo la gira hacia abajo. pitch_deg y yaw_deg convierten a grados, y direction_3d devuelve el vector de dirección unitario.

SemanticMask

Mapa semántico denso, forma (H, W) de IDs de clase enteros sobre el lienzo de la imagen original. 255 es el valor de ignorar y nunca cuenta como clase (SemanticMask.IGNORE_INDEX). classes lista los IDs de clase presentes, y class_mask(class_id) devuelve la máscara booleana de una clase.

PanopticSegmentation

Cada píxel recibe exactamente un segmento sin solapamientos, unificando las regiones de stuff y las instancias de thing. data es un mapa (H, W) entero de IDs de segmento; el ID de segmento 0 es sin etiquetar (PanopticSegmentation.IGNORE_INDEX). segments_info es una lista de dicts, uno por segmento, cada uno con al menos {"id": int, "category_id": int}, donde id coincide con un valor del mapa y category_id indexa names. segment_ids lista los IDs presentes y segment_mask(segment_id) devuelve la máscara booleana de un segmento.

La distinción thing/stuff es una propiedad de la categoría, no del segmento. Un payload puede desnormalizarla en cada segmento como "isthing": bool, y cuando lo hace, el valor debe coincidir con el mapa a nivel de categoría.

DepthMap

Mapa denso de profundidad inversa relativa, forma (H, W) de floats sobre el lienzo de la imagen original. Los valores más altos significan más cerca de la cámara. Los valores son relativos, no metros métricos. min, max y mean se calculan sobre los valores finitos, y normalized() reescala el mapa a [0, 1].

DepthMap(data, orig_shape=None, encoding="inverse_depth") también acepta encoding="depth" y encoding="log_depth". Los validadores lo interpretan antes de la alineación. Los valores de profundidad relativa siguen sin garantizar una escala métrica.

NormalMap

Campo denso de normales de superficie, float32 (H, W, 3) sobre el lienzo de la imagen original, en el sistema de cámara de OpenCV: +x a la derecha, +y hacia abajo, +z hacia el interior de la escena. Las normales apuntan a la cámara, así que una superficie fronto-paralela es (0, 0, -1). Cada píxel es un vector unitario. assert_normalized(atol=1e-4) comprueba esa invariante.

EdgeMap

Mapa denso de probabilidad de borde, float32 (H, W) sobre el lienzo de la imagen original, donde 0 es no-borde y 1 es borde. El mapa continuo se conserva para que el umbral siga siendo decisión de quien llama: binary(threshold=0.5) aplica uno, y array devuelve la vista numpy.

RestoredImage

La imagen RGB restaurada, (H, W, 3) uint8. En superresolución el lienzo es Results.restore_scale veces la entrada. array devuelve la vista numpy y save(path) escribe la imagen.

Matte

Matte de opacidad suave, float32 (H, W) en [0, 1] sobre el lienzo de la imagen original. 1 es primer plano completo y 0 fondo completo. Un matte suave engloba una máscara dura de eliminación de fondo, umbralizada en 0.5, y conserva los bordes con antialiasing que una máscara binaria descarta. array devuelve la vista numpy.

En un resultado de matte, Results.cutout(image=None) devuelve un array RGBA (H, W, 4) uint8 cuyo cuarto canal es el matte, y Results.save(path, image=None) escribe ese recorte como un PNG con fondo transparente. Ambos toman el RGB de image cuando se les pasa, y si no lo recargan desde Results.path.

OCRRegions

Texto localizado con sus transcripciones. data son polígonos float (N, 4, 2) en píxeles de la imagen original, ordenados arriba-izquierda, arriba-derecha, abajo-derecha, abajo-izquierda, y las regiones vienen en orden de lectura, de arriba abajo y luego de izquierda a derecha. texts es la lista de N transcripciones. conf es la puntuación de reconocimiento por región y det_conf la de detección, ambas (N,).

Los cuadriláteros de detección son polígonos de verdad, así que no rellenan Results.boxes. xyxy da las envolventes alineadas con los ejes.

Embeddings

Vectores normalizados con L2 de la tarea embed, siempre de forma (N, D). Un resultado de imagen completa lleva una sola fila y ningún box; los embeddings de región están alineados por filas con boxes. Como cada fila está normalizada, la similitud coseno es un producto escalar.

Identities

Coincidencias con nombre de la galería, alineadas por filas con embeddings. Se producen cuando se pasa una Gallery a una predicción embed. name es una lista en la que una entrada es None por debajo del umbral de coincidencia, y nunca se adivina el nombre más cercano que queda por debajo del umbral. score es el array de puntuaciones de coincidencia y data los empareja.

Meshes

Mallas paramétricas de cuerpo humano, alineadas por filas con los bounding boxes de personas de boxes. Todo está en el sistema de cámara de la imagen original. transl es métrico en metros con +z apuntando en dirección contraria a la cámara; vertices y joints3d son métricos y ya incluyen transl; joints2d está en píxeles sobre el lienzo de la imagen original, no sobre el recorte que vio la red. Ningún campo lleva un sistema de mundo ni de gravedad.

La disposición de los parámetros cambia según el modelo de cuerpo, así que nada de las formas está hard-codeado. body_model nombra la parametrización y los recuentos se leen de los propios tensores: num_vertices, num_joints, num_betas y has_vertices. params devuelve el dict de parámetros, y save_obj(path, index=0) escribe una malla. Los campos son global_orient, body_pose, betas, transl, vertices, faces, joints3d, joints2d, conf, focal_length y extras.

Con body_model="mhr" las rotaciones son ángulos de Euler en radianes en lugar de axis-angle, body_pose es un vector plano de parámetros por articulación en lugar de un triplete por articulación, y betas son coeficientes de blendshape de identidad. La escala del esqueleto, la pose de las manos y la expresión facial viven en extras.

Conversión y selección

Todos los payloads llevan to(*args, **kwargs), cpu(), cuda() y numpy(), y llamar a uno de ellos sobre el Results lo aplica de golpe a todos los slots rellenos.

from libreyolo import LibreYOLO, SAMPLE_IMAGE model = LibreYOLO("LibreYOLO9t.pt")result = model(SAMPLE_IMAGE) # Todos los payloads se mueven juntos.result = result.cpu().numpy() # Las filas, como dicts planos, y luego como JSON.print(result.summary()[:1])print(result.to_json())

result[idx] selecciona filas en todos los payloads alineados por filas. len(result) es el número de detecciones, o de puntos cuando no hay boxes. result.update(...) devuelve una copia con los slots indicados sustituidos; acepta todos los slots más track_id y restore_scale.

summary y to_json

summary(normalize=False, decimals=5, embeddings=False) devuelve una lista de dicts planos, una fila por detección, segmento, punto o región según qué slots estén rellenos. to_json(**kwargs) pasa sus argumentos a summary y devuelve la cadena JSON.

plot() renderiza los payloads de todas las tareas. Las superposiciones sobre imágenes usan arrays BGR por defecto; pil=True solicita PIL. Los mapas de profundidad, normales, bordes y albedo, los cuboides 3D y las secuencias de acciones devuelven una imagen PIL por defecto; pil=False devuelve el array.

Boxes3D

Boxes3D(data, orig_shape=None, intrinsics=None) contiene filas (N, 14): centro xyz, dimensiones wlh, cuaternión wxyz, puntuación de ordenación, ID de clase, confianza 2D y confianza 3D. Las coordenadas son metros en el sistema de cámara, con x hacia la derecha, y hacia abajo y z hacia delante; no se implica un sistema de mundo. Los parámetros intrínsecos 3x3 corresponden al lienzo original. Las filas se alinean con Results.boxes.

AlbedoMap

AlbedoMap(data, orig_shape=None) contiene RGB lineal. La conversión para visualización produce sRGB; la validación cuantitativa de albedo usa los valores lineales originales.

Actions

Actions(data, orig_shape=None, names=None, fps=None, instruction=None) representa una secuencia de acciones float32 (T, D). first devuelve la primera fila; el slicing selecciona pasos temporales. Los valores conservan las unidades del dataset de la política. names describe las dimensiones de acción, fps la frecuencia de control e instruction el texto de condicionamiento.

GeneratedImage

GeneratedImage(data, orig_shape=None, *, prompt=None, seed=None, params=None) contiene una imagen sintetizada, (H, W, 3) uint8 RGB. array devuelve la vista numpy e image una PIL.Image. prompt es el texto que produjo la imagen y seed el entero que la reproduce con el mismo modelo y los mismos ajustes; params registra el resto de la llamada: model, imgsz y cada ajuste de la familia vigente. save(path) escribe la imagen, y un PNG guarda además to_dict(), la forma, el prompt, la semilla y los params, como JSON en un chunk de texto libreyolo.

En un resultado generado, Results.boxes y Results.path son None, orig_shape es el (H, W) de la propia imagen y len(result) es 1. Results.save(path) escribe la imagen, plot() la devuelve como imagen PIL y summary() devuelve una fila con el registro del payload.

Gaussians

Gaussians(xyz, scales, rotations, opacities, sh, *, camera=None, seed=None, params=None, input_image=None) contiene un objeto 3D generado como splats gaussianos, en el sistema de coordenadas del propio objeto: z hacia arriba, centrado en el cubo [-0.5, 0.5]^3. Cada fila es una gaussiana.

len(gaussians) es N, y gaussians[gaussians.opacities > 0.1] devuelve un nuevo Gaussians con las filas seleccionadas. save(path) escribe según la extensión. .ply es el formato estándar de 3D Gaussian Splatting, con escalas en log y opacidades en logit, girado a y hacia arriba como esperan los visores de splats, y una línea de cabecera comment libreyolo con la semilla, la cámara y los params como JSON. Un payload con color de orden superior (K > 1) lanza NotImplementedError para .ply. .splat es el formato web compacto, de 32 bytes por gaussiana. render(size=512, background=(0, 0, 0)) devuelve un render de puntos desde la vista de entrada inferida como PIL.Image, un vistazo rápido y no una rasterización de gaussianas.

En un resultado 3D generado, Results.boxes es None; path, orig_shape y orig_img describen la imagen de origen, y len(result) es 1. Results.save(path) escribe el objeto, plot() devuelve ese render de puntos y summary() devuelve una fila con el registro del payload.