pytorchcocotools

Unofficial APIs for the MS-COCO dataset using PyTorch. Uses the official repository of the pycocotools packages as reference.

The file format is explained in the official documentation and nicely summarized here.

[!WARNING] This is work in progress, feel free to contribute!

Features

• Strongly typed COCO data format represetation
• Drop-in compatible COCO and COCOeval classes
• (Almost) drop-in compatible mask methods
• Pure torch implementation
• torchvision data set using the latest transformation API
• fully unit tested and documented

Installation

With pip:

python -m pip install pytorchcocotools

With uv:

uv add pytorchcocotools

How to use it

Pretty much all you need to do is to change the import statement from pycocotools to pytorchcocotools:

-import pycocotools
+import pytorchcocotools

So all imports look like this:

from pytorchcocotools.coco import COCO
from pytorchcocotools.cocoeval import COCOeval

...

API

[!WARNING] While the API is mostly compatible with the original pycocotools package, there are some differences. For some methods you need to adapt the handling of the return type. See the examples below.

[!NOTE] All methods are documented with detailed type hints.

mask

All methods now have a optional device and requires_grad parameters that allows to specify the device on which the masks should be created and whether gradients are required. This is useful for acceleration.

[!IMPORTANT] > decode, encode, toBbox and frPyObjects now always return the batch/channel dimension implementation as opposed to a single return element if only a single element was passed. This was done to make the API more consistent by providing single, defined return types, but is open for further discussion.

COCO

One major difference is that the COCO class now uses a strongly typed data structure to represent the COCO data format. This makes it easier to work with the data and to understand the structure of the data, but also might cause problems with data sources that do not strictly follow the data format.

COCOeval

Strongly typed as well. Includes also minor fixes, e.g. the __str__ now also returns the stats.

Other additions

• pytorchcocotools.utils.coco.download.CocoDownloader: While gsutils rsync is the officially recommended way to download the data, this allows you to trigger the download from Python.
• The logger property in both all classes from the logging module replaces the print command, so you can fully customize it.
• pytorchcocotools.torch.dataset.CocoDetection: A drop-in replacement for the dataset from torchvision, now strongly typed using the new transforms.v2 api.

Docs

uv run mkdocs build -f ./mkdocs.yml -d ./_build/

Update template

copier update --trust -A --vcs-ref=HEAD

Credits

This project was generated with