Detección de objetos

Definición

La detección de objetos responde dónde está cada objeto y qué es. Entra una imagen y sale una fila por instancia: cuatro números para el rectángulo, un índice de clase y una puntuación. No incluye nada sobre la forma a nivel de píxel, la orientación ni las partes, que es lo que la separa de la segmentación de instancias, los bounding boxes orientados y la pose.

detect es la clave canónica de la tarea y la opción por defecto: un checkpoint cuyo nombre de archivo no lleva sufijo de tarea se carga como detector.

predict() rellena result.boxes. .xyxy da las esquinas en píxeles sobre el lienzo de la imagen original, .conf la puntuación y .cls el índice de clase dentro de result.names. .xywh, .xyxyn y .xywhn son vistas derivadas de las mismas filas, y .id lleva un id de seguimiento cuando hay un tracker acoplado. Iterar un objeto Boxes produce slices de una fila, así que box.cls, box.conf y box.xyxy funcionan por detección.

Modelos

Doce familias entrenan y predicen: YOLOv9, RF-DETR, EdgeCrafter, RT-DETR, D-FINE, DEIM, Dome-DETR, YOLO-NAS, YOLOX, YOLOv7, RTMDet y PicoDet. YOLOv9 y RF-DETR son las dos familias insignia, y las novedades llegan primero a ellas. RF-DETR necesita su propio extra, pip install "libreyolo[rfdetr]"; el resto funciona con el paquete base.

Once más predicen, validan y exportan, pero su train() lanza NotImplementedError: LW-DETR, DETR, Deformable DETR, DINO-DETR, Faster R-CNN, Mask R-CNN, FCOS, RetinaNet, SSD, CenterNet y EfficientDet.

El linaje Darknet, YOLOv1, YOLOv2, YOLOv3 y YOLOv4, se conserva como una pieza de museo congelada: predecir, validar y exportar funcionan; entrenar, no.

Un grupo aparte toma su lista de clases en tiempo de ejecución en lugar de tomarla del checkpoint, de modo que detecta nombres nunca vistos durante el entrenamiento: Grounding DINO, OWLv2, OMDet-Turbo y OV-DEIM, más las familias de visión y lenguaje Florence-2, Kosmos-2, Qwen3-VL, SmolVLM2, InternVL3, LFM2-VL, LocateAnything, SenseNova-Vision y LibreMODUS. Estas se cargan a través de su propia factory y sus extras; cada página de modelo lleva la llamada exacta.

Predicción

Los pesos se descargan de Hugging Face en el primer uso y se cachean localmente.

from libreyolo import LibreYOLO, SAMPLE_IMAGE model = LibreYOLO("LibreYOLO9t.pt")result = model(SAMPLE_IMAGE, save=True) for box in result.boxes:    print(result.names[int(box.cls)], float(box.conf), box.xyxy)

libreyolo predict model=LibreYOLO9t.pt save=True \  source=https://raw.githubusercontent.com/LibreYOLO/libreyolo/release/libreyolo/assets/parkour.jpg

from libreyolo import LibreYOLO, SAMPLE_IMAGE # La factory decide según el checkpoint, y todos los detectores devuelven# el mismo objeto Results, así que cambiar de familia es un cambio de una línea.model = LibreYOLO("LibreDFINEn.pt")result = model(SAMPLE_IMAGE) print(result.boxes.xyxy.shape)

from libreyolo import LibreYOLO model = LibreYOLO("LibreYOLO9t.pt") # Cualquier fuente que acepte la librería: archivo, carpeta, URL,# índice de webcam, stream RTSP o una lista .streams.for result in model.predict("clip.mp4", stream=True, save=True):    print(len(result.boxes))

conf fija el umbral de confianza y max_det limita el número de filas. iou es el umbral de NMS, así que solo tiene efecto en una familia que ejecute NMS; RF-DETR y la cabeza end-to-end de YOLOv9 decodifican un conjunto fijo de predicciones y lo ignoran. Consulta la predicción para las fuentes, el streaming y el manejo de resultados.

Formato del dataset

Un archivo de etiquetas .txt por imagen, que se localiza sustituyendo images por labels en la ruta de la imagen y cambiando la extensión.

dataset/
  data.yaml
  images/
    train/000001.jpg
    val/000101.jpg
  labels/
    train/000001.txt
    val/000101.txt

Cada fila tiene exactamente cinco campos, un índice de clase seguido de un bounding box normalizado de centro y tamaño:

<class_id> <cx> <cy> <w> <h>

Las coordenadas son floats en [0, 1], relativas al ancho y alto de la imagen original. w y h deben ser positivos. Un archivo de etiquetas ausente o vacío significa que la imagen no tiene objetos. Las filas no llevan confianza ni id de seguimiento.

El YAML nombra los splits y las clases:

path: dataset
train: images/train
val: images/val
names:
  0: person
  1: bicycle

train y val pueden ser directorios de imágenes, archivos .txt con listas de imágenes, o listas de cualquiera de los dos. nc es opcional y debe coincidir con names cuando está presente. El JSON nativo de COCO también funciona: añade un mapeo annotations de nombre de split a archivo JSON, y la ruta del split pasa entonces a indicar la raíz de las imágenes. Cuando names está presente define los ids de las etiquetas, así que los nombres de categoría del JSON tienen que coincidir con él.

Entrenamiento

from libreyolo import LibreYOLO model = LibreYOLO("LibreYOLO9t.pt") # coco128.yaml descarga una muestra de 128 imágenes en el primer uso.# Apunta data al YAML de tu propio dataset para un entrenamiento real.model.train(data="coco128.yaml", epochs=50, imgsz=640, batch=8)

libreyolo train model=LibreYOLO9t.pt data=coco128.yaml \  epochs=50 imgsz=640 batch=8

libreyolo train model=LibreYOLO9t.pt data=coco128.yaml \  epochs=50 device=0,1 batch=-1

epochs, imgsz, batch y lr0 son los argumentos que se tocan primero. lr0 es el que no se traslada entre familias: un valor que un detector convolucional tolera hará divergir a uno transformer, así que toma el valor de la página del modelo y no del ejemplo de otra familia. Una familia también puede ignorar un argumento por completo, y su página lista cuáles. Consulta el entrenamiento para los datasets, el aumento de datos, el multi-GPU y los loggers.

Validación

val() devuelve un diccionario plano de claves metrics/, calculadas con la evaluación COCO sobre el split que nombra val en el YAML del dataset.

from libreyolo import LibreYOLO model = LibreYOLO("LibreYOLO9t.pt") # val() devuelve un dict plano, no un objeto.metrics = model.val(data="coco128.yaml") print(metrics["metrics/mAP50-95"])print(metrics["metrics/mAP50"], metrics["metrics/mAP75"])print(metrics["metrics/AR100"])

libreyolo val model=LibreYOLO9t.pt data=coco128.yaml

metrics/mAP50-95 es la precisión media (mean average precision) promediada sobre umbrales de IoU de 0.50 a 0.95, y es la cifra principal. metrics/mAP50 y metrics/mAP75 son las versiones de umbral único. metrics/mAP_small, metrics/mAP_medium y metrics/mAP_large desglosan el mismo promedio por área del objeto, y metrics/AR1, metrics/AR10, metrics/AR100, metrics/AR_small, metrics/AR_medium y metrics/AR_large son las cifras equivalentes de recall promedio. metrics/AR_max_det y metrics/max_det registran el límite de detecciones que usó la ejecución.

Lee metrics/precision y metrics/recall con cuidado en esta tarea. Se mantienen por retrocompatibilidad y son alias, no un punto de operación: metrics/precision contiene el mismo valor que metrics/mAP50-95, y metrics/recall el mismo valor que metrics/AR100. Graficarlas como un par de precisión y recall reporta el mismo número dos veces. Cuatro claves también se repiten con el sufijo (B), de box, para que una clave de detección se lea igual en un modelo que también predice máscaras: metrics/mAP50-95(B), metrics/mAP50(B), metrics/precision(B) y metrics/recall(B).

Exportación

from libreyolo import LibreYOLO model = LibreYOLO("LibreYOLO9t.pt")model.export(format="onnx", imgsz=640)

libreyolo export model=LibreYOLO9t.pt format=onnx imgsz=640

from libreyolo import LibreYOLO, SAMPLE_IMAGE # La factory decide según la extensión del archivo, así que un artefacto# exportado se carga como un checkpoint y devuelve el mismo objeto Results.model = LibreYOLO("LibreYOLO9t.onnx")result = model(SAMPLE_IMAGE) print(result.boxes.xyxy)

Un artefacto exportado se vuelve a cargar a través de LibreYOLO() por la extensión del archivo, así que un archivo .onnx o .engine se comporta como un checkpoint y devuelve el mismo Results. La cobertura de formatos varía según la familia; la matriz de cada página de modelo se genera a partir del conjunto validado en lugar de escribirse a mano. Consulta exportación y despliegue para los formatos, sus extras y sus restricciones.