Implementation:NVIDIA DALI COCO Dataset

Knowledge Sources	NVIDIA_DALI
Domains	Vision, Training
Last Updated	2026-02-08 16:00 GMT

Overview

Provides a Python API for loading, parsing, and accessing Microsoft COCO dataset annotations for use in the Single Shot Detector (SSD) training example.

Description

This module is a customized version of the pycocotools COCO API (v2.0, originally by Piotr Dollar and Tsung-Yi Lin) bundled within the DALI SSD example. The central COCO class loads COCO-format JSON annotation files and builds efficient index structures for querying annotations by image ID, category ID, or area range. It creates bidirectional mappings between images and annotations (imgToAnns) and between categories and images (catToImgs) during initialization.

The class provides a comprehensive API: getAnnIds, getCatIds, and getImgIds for filtered queries; loadAnns, loadCats, and loadImgs for fetching objects by ID; showAnns for matplotlib-based visualization of segmentation polygons, masks, and keypoints; loadRes for loading algorithm results and creating a result API object for evaluation; download for fetching images from the COCO server; and annToMask/annToRLE for converting segmentation annotations to binary masks using pycocotools mask utilities.

The module supports instance annotations (bounding boxes, segmentations, keypoints), caption annotations, and handles both polygon and RLE-encoded segmentation formats. It is used as the ground truth data interface in the SSD training pipeline alongside DALI-accelerated data loading.

Usage

Use this module to load and query COCO annotations when working with the SSD object detection example. Create a COCO instance with the path to an annotation JSON file, then use the query methods to retrieve annotations for specific images or categories.

Code Reference

Source Location

• Repository: NVIDIA_DALI
• File: docs/examples/use_cases/pytorch/single_stage_detector/src/coco.py
• Lines: 1-433

Signature

class COCO:
    def __init__(self, annotation_file=None): ...
    def createIndex(self): ...
    def info(self): ...
    def getAnnIds(self, imgIds=[], catIds=[], areaRng=[], iscrowd=None): ...
    def getCatIds(self, catNms=[], supNms=[], catIds=[]): ...
    def getImgIds(self, imgIds=[], catIds=[]): ...
    def loadAnns(self, ids=[]): ...
    def loadCats(self, ids=[]): ...
    def loadImgs(self, ids=[]): ...
    def showAnns(self, anns): ...
    def loadRes(self, resFile): ...
    def download(self, tarDir=None, imgIds=[]): ...
    def loadNumpyAnnotations(self, data): ...
    def annToRLE(self, ann): ...
    def annToMask(self, ann): ...

Import

from src.coco import COCO

I/O Contract

Inputs (COCO.__init__)

Name	Type	Required	Description
annotation_file	str	No	Path to a COCO-format JSON annotation file. If None, creates an empty COCO instance.

Outputs (COCO object attributes)

Name	Type	Description
dataset	dict	The raw loaded JSON dataset dictionary.
anns	dict	Annotation ID to annotation mapping.
cats	dict	Category ID to category mapping.
imgs	dict	Image ID to image info mapping.
imgToAnns	dict	Image ID to list of annotations mapping.
catToImgs	dict	Category ID to list of image IDs mapping.

Inputs (getAnnIds)

Name	Type	Required	Description
imgIds	int or list[int]	No	Filter by image IDs.
catIds	int or list[int]	No	Filter by category IDs.
areaRng	list[float]	No	Filter by annotation area range [min, max].
iscrowd	bool	No	Filter by crowd label.

Outputs (getAnnIds)

Name	Type	Description
ids	list[int]	List of annotation IDs matching the filter criteria.

Usage Examples

Loading and querying COCO annotations

from src.coco import COCO

# Load annotation file
coco = COCO("/data/coco/annotations/instances_train2017.json")

# Get all image IDs containing 'person' category
cat_ids = coco.getCatIds(catNms=["person"])
img_ids = coco.getImgIds(catIds=cat_ids)
print(f"Found {len(img_ids)} images with people")

# Load annotations for a specific image
ann_ids = coco.getAnnIds(imgIds=[img_ids[0]])
anns = coco.loadAnns(ann_ids)
print(f"Image has {len(anns)} annotations")

Converting annotations to masks

from src.coco import COCO

coco = COCO("instances_val2017.json")
ann_ids = coco.getAnnIds(imgIds=[139])
anns = coco.loadAnns(ann_ids)

# Convert first annotation to binary mask
mask = coco.annToMask(anns[0])
print(f"Mask shape: {mask.shape}")

Related Pages

• Environment:NVIDIA_DALI_CUDA_GPU_Environment