Pycocotools

2.0.11 · active · verified Thu Apr 09

Pycocotools provides the official APIs for the Microsoft COCO (Common Objects in Context) dataset. It facilitates loading, parsing, and visualizing COCO annotations, as well as evaluating object detection, segmentation, and keypoint detection results. The current version is 2.0.11, and it is actively maintained with bug fixes and packaging improvements over the original COCO API.

Warnings

gotcha Windows users frequently encounter compilation errors requiring 'Microsoft Visual C++ Build Tools'. These tools must be installed (specifically 'Desktop development with C++' workload) before `pip install pycocotools` can succeed.
Fix: Install 'Desktop development with C++' workload from Visual Studio Build Tools. For Python 3.9+, ensure compatibility with the installed C++ compiler version.
breaking The `useSegm` parameter in `COCOeval` has been deprecated and replaced by the `iouType` parameter. Attempting to use `useSegm` will likely result in an error or unexpected behavior.
Fix: Replace `E.params.useSegm = True/False` with `E.params.iouType = 'segm'` or `E.params.iouType = 'bbox'` respectively.
gotcha C-extension compilation can fail if `numpy` or `cython` are not correctly installed or if there are environment-specific compiler issues. Although `pycocotools` lists them as dependencies, explicit pre-installation can sometimes resolve issues.
Fix: Ensure `pip install cython numpy` is run before `pip install pycocotools`. For persistent issues, verify your C/C++ compiler setup (e.g., GCC on Linux, Visual C++ Build Tools on Windows).

Install

pip install pycocotools Standard installation
pip install cython numpy && pip install pycocotools Installation with explicit dependencies (if issues arise)

Imports

COCO
```
from pycocotools.coco import COCO
```

COCOeval

from pycocotools.cocoeval import COCOeval

maskUtils

from pycocotools import mask as maskUtils

Quickstart

This quickstart demonstrates how to initialize the COCO API, load an annotation file, and retrieve basic information such as image and category IDs, and annotations for a specific image. It requires a downloaded COCO annotation JSON file.

import os
from pycocotools.coco import COCO

# NOTE: You need to download COCO annotations first.
# For example, 'instances_val2017.json' can be found at:
# http://images.cocodataset.org/annotations/annotations_trainval2017.zip

# Placeholder for annotation file path. Replace with actual path.
annFile = os.environ.get('COCO_ANN_FILE', 'path/to/instances_val2017.json')

# Initialize COCO API for instance annotations
try:
    coco = COCO(annFile)
    print(f"Successfully loaded COCO annotations from {annFile}")

    # Get all image IDs
    imgIds = coco.getImgIds()
    print(f"Total images: {len(imgIds)}")

    # Get category IDs
    catIds = coco.getCatIds(catNms=['person', 'dog', 'cat'])
    print(f"Categories found: {coco.loadCats(catIds)}")

    # Pick an image and display some info
    img = coco.loadImgs(imgIds[0])[0]
    print(f"First image info: {img}")

    # Get annotations for the image
    annIds = coco.getAnnIds(imgIds=img['id'], catIds=catIds, iscrowd=None)
    anns = coco.loadAnns(annIds)
    print(f"Annotations for image {img['id']}: {len(anns)} found")

except Exception as e:
    print(f"Error loading COCO annotations or processing: {e}")
    print("Please ensure the annotation file path is correct and accessible.")

view raw JSON →