Formato COCO Format Guide

Specification

El formato de anotación COCO (Common Objects in Context) es un estándar de anotación integral basado en JSON desarrollado por Microsoft Research para el dataset y benchmark COCO. Se ha convertido en uno de los formatos de anotación más ampliamente adoptados en visión por computadora, soportando detección de objetos, segmentación de instancias, detección de puntos clave, segmentación panóptica, subtitulado de imágenes y estimación de pose densa. A diferencia del formato YOLO más simple, COCO almacena todas las anotaciones de un dataset completo en un único archivo JSON con una estructura relacional rica.

El formato COCO usa un modelo de datos relacional con cuatro entidades principales: images (con id, file_name, width, height), annotations (con id, image_id, category_id, bbox, segmentation, area, iscrowd), categories (con id, name, supercategory) y opcionalmente licenses e info como metadatos. Los bounding boxes se almacenan en formato [x_min, y_min, width, height] usando coordenadas absolutas en píxeles (no normalizadas como YOLO). Las máscaras de segmentación se almacenan como listas de vértices de polígonos o RLE comprimido (Run-Length Encoding) para máscaras binarias.

La estructura relacional permite consultas potentes — encontrar todas las anotaciones para una imagen específica, todas las instancias de una categoría específica, o filtrar por atributos de anotación como área o estado de multitud. La biblioteca pycocotools proporciona una API de Python (clase COCO) para cargar, consultar y evaluar contra datasets en formato COCO. Las métricas de evaluación COCO (AP, AP50, AP75, AP_small, AP_medium, AP_large) se han convertido en los benchmarks estándar para la evaluación de modelos de detección de objetos y segmentación.

When to Use Formato COCO

Usa el formato COCO cuando entrenes modelos con frameworks que esperan anotaciones estilo COCO, incluyendo Detectron2, MMDetection, DETR y muchos modelos de visión de Hugging Face. El formato COCO es el estándar para papers de investigación académica y comparaciones de benchmarks — si estás publicando resultados o comparando contra líneas base publicadas, el formato COCO y las métricas de evaluación son lo esperado. También es la mejor opción cuando tus anotaciones incluyen máscaras de segmentación, puntos clave o subtítulos junto con bounding boxes.

Elige el formato COCO sobre el formato YOLO cuando necesites metadatos de anotación ricos (área, flags iscrowd, polígonos de segmentación), cuando trabajes con tareas de segmentación panóptica que requieran anotaciones tanto de "stuff" como de "thing", o cuando tu flujo de evaluación use las métricas estándar de COCO. El formato COCO también es preferido cuando tienes múltiples tipos de anotación por imagen (bounding boxes más segmentación más puntos clave) que necesitan almacenarse en un formato unificado.

El formato COCO es menos conveniente cuando tu dataset es muy grande y quieres versionar anotaciones individuales de imágenes (un solo archivo JSON puede ser difícil de comparar y fusionar). También es más complejo de parsear y generar que el formato YOLO, requiriendo la biblioteca pycocotools o manipulación cuidadosa de JSON. Para tareas simples de detección con solo bounding boxes entrenadas con modelos YOLO, el formato YOLO es más simple e igualmente efectivo.

Schema / Structure

{
  "info": {
    "year": 2026,
    "version": "1.0",
    "description": "Custom object detection dataset",
    "contributor": "Ertas",
    "date_created": "2026-03-15"
  },
  "licenses": [
    {"id": 1, "name": "CC BY 4.0", "url": "https://creativecommons.org/licenses/by/4.0/"}
  ],
  "categories": [
    {"id": 1, "name": "car", "supercategory": "vehicle"},
    {"id": 2, "name": "person", "supercategory": "human"}
  ],
  "images": [
    {"id": 1, "file_name": "img001.jpg", "width": 1920, "height": 1080}
  ],
  "annotations": [
    {
      "id": 1,
      "image_id": 1,
      "category_id": 1,
      "bbox": [100.0, 200.0, 300.0, 150.0],
      "area": 45000.0,
      "segmentation": [[100,200, 400,200, 400,350, 100,350]],
      "iscrowd": 0
    }
  ]
}

Example Data

from pycocotools.coco import COCO
import json

# Load and query a COCO dataset
coco = COCO("annotations/instances_train.json")

# Get all images containing 'car'
car_id = coco.getCatIds(catNms=["car"])[0]
car_img_ids = coco.getImgIds(catIds=[car_id])
print(f"Found {len(car_img_ids)} images with cars")

# Get annotations for a specific image
img_info = coco.loadImgs(car_img_ids[0])[0]
ann_ids = coco.getAnnIds(imgIds=img_info["id"])
anns = coco.loadAnns(ann_ids)
for ann in anns:
    cat = coco.loadCats(ann["category_id"])[0]
    print(f"  {cat['name']}: bbox={ann['bbox']}, area={ann['area']}")

# Create a COCO dataset programmatically
dataset = {
    "info": {"version": "1.0", "description": "My dataset"},
    "categories": [
        {"id": 1, "name": "dog", "supercategory": "animal"},
        {"id": 2, "name": "cat", "supercategory": "animal"},
    ],
    "images": [
        {"id": 1, "file_name": "photo_001.jpg", "width": 640, "height": 480},
    ],
    "annotations": [
        {"id": 1, "image_id": 1, "category_id": 1,
         "bbox": [50, 100, 200, 180], "area": 36000, "iscrowd": 0,
         "segmentation": [[50,100, 250,100, 250,280, 50,280]]},
    ],
}
with open("annotations.json", "w") as f:
    json.dump(dataset, f, indent=2)