Aumentación de Bbox en Albumentations: formatos y errores

Aumentación de Bounding Box en Albumentations: Parámetros y Manejo de Errores

En tareas de detección de objetos, las caídas en mAP suelen provenir no de problemas en la arquitectura del modelo, sino de inconsistencias en los bounding box después de las aumentaciones. Las transformaciones espaciales requieren actualizaciones sincronizadas tanto de las coordenadas de los objetos como de la imagen misma. Albumentations maneja esto de forma impecable mediante A.BboxParams, que soporta cinco formatos de coordenadas: pascal_voc, albumentations, coco, yolo y cxcywh.

Un coord_format incorrecto puede desplazar las cajas de forma silenciosa sin generar errores en el código. Para una imagen de 640×480 con una caja desde (98,345) hasta (420,462) en distintos formatos:

• pascal_voc: [98, 345, 420, 462]
• albumentations: [0.153, 0.719, 0.656, 0.962]
• coco: [98, 345, 322, 117]
• yolo: [0.405, 0.841, 0.503, 0.244]
• cxcywh: [259, 403.5, 322, 117]

Construyendo un Pipeline de Detección

import albumentations as A
import cv2
import numpy as np

train_transform = A.Compose([
    A.RandomCrop(width=450, height=450, p=1.0),
    A.HorizontalFlip(p=0.5),
    A.RandomBrightnessContrast(p=0.2),
], bbox_params=A.BboxParams(
    coord_format='coco',
    label_fields=['class_labels'],
), seed=137)

Las aumentaciones basadas en píxeles (brillo, contraste) dejan los bboxes intactos. Las geométricas (volteo, recorte, rotación) actualizan automáticamente las coordenadas. Así se aplica:

image = cv2.imread("image.jpg")
image = cv2.cvtColor(image, cv2.COLOR_BGR2RGB)

bboxes = np.array([
    [23, 74, 295, 388],
    [377, 294, 252, 161],
    [333, 421, 49, 49],
], dtype=np.float32)

class_labels = np.array(['dog', 'cat', 'sports ball'])

result = train_transform(image=image, bboxes=bboxes, class_labels=class_labels)

augmented_image = result['image']
augmented_bboxes = result['bboxes']
augmented_labels = result['class_labels']

La librería filtra automáticamente las cajas que quedan fuera de los límites o se vuelven demasiado pequeñas.

Adjuntando Metadatos a los Bounding Box

Usando label_fields

Pasa clases y datos extra como arrays separados:

bbox_params = A.BboxParams(
    coord_format='pascal_voc',
    label_fields=['class_labels', 'difficult_flags'],
)

result = transform(
    image=image,
    bboxes=bboxes,
    class_labels=['dog', 'cat', 'ball'],
    difficult_flags=[0, 0, 1],
)

Casos de uso soportados:

• Anotaciones de video: frame_ids para rastrear el origen de las cajas
• Segmentación de instancias: instance_ids para vincular con máscaras
• Seguimiento: class_id + track_id en campos extra

El filtrado sincroniza todos los arrays automáticamente.

Metadatos Embebidos

Para datos numéricos, agrega columnas al array de bbox:

bboxes = np.array([
    [23, 74, 295, 388, 1, 17],  # + class_id, track_id
    [377, 294, 252, 161, 2, 23],
], dtype=np.float32)

bbox_params = A.BboxParams(coord_format='coco')

A.BboxParams para Control de Calidad

Configuraciones clave:

| Parámetro | Descripción | Valor por defecto |

|----------|-------------|-------------------|

| coord_format | Formato de coordenadas | Requerido |

| label_fields | Metadatos | [] |

| min_area | Área mínima en píxeles | 0.0 |

| min_visibility | Fracción visible mínima | 0.0 |

| min_width/height | Umbrales de tamaño | 0.0 |

| clip_bboxes_on_input | Recortar antes de aumentar | False |

| filter_invalid_bboxes | Eliminar cajas inválidas | False |

| max_accept_ratio | Relación de aspecto máxima | None |

Para anotaciones imperfectas:

bbox_params = A.BboxParams(
    coord_format='yolo',
    label_fields=['class_labels'],
    clip_bboxes_on_input=True,
    filter_invalid_bboxes=True,
)

min_visibility=0.3 elimina cajas con muy poca área visible tras el recorte. min_area=100 excluye fragmentos diminutos.

Estrategias de Recorte y Errores Comunes

RandomCrop puede generar cajas con área útil nula. Mejores prácticas:

• Establece min_visibility > 0 para preservar la señal
• Usa p < 1.0 en recortes para evitar sobre-filtrado
• Verifica distribuciones de tamaños de bbox antes/después del pipeline

Problemas comunes:

• Formato de coordenadas equivocado (YOLO necesita 'yolo')
• Falta label_fields para clases
• Omitir clip/filtro en datasets desordenados
• Parámetros min_ en cero entrena con basura

Lecciones Clave

• coord_format es obligatorio: pascal_voc para la mayoría de datasets, yolo para Ultralytics
• label_fields sincroniza etiquetas durante el filtrado
• clip + filter limpia anotaciones antes del entrenamiento
• min_visibility 0.3–0.5 funciona mejor en recortes
• Inspecciona visualmente los primeros lotes tras el pipeline

— Editorial Team