Migrating from pycocotools¶

hotcoco is a drop-in replacement for pycocotools. This guide covers the two migration paths and the few differences to be aware of.

Option 1: Change your imports¶

If you control the code that imports pycocotools, swap the import paths:

# Before
from pycocotools.coco import COCO
from pycocotools.cocoeval import COCOeval
from pycocotools import mask as mask_util

# After
from hotcoco import COCO, COCOeval
from hotcoco import mask as mask_util

Everything else stays the same.

Option 2: Zero-code drop-in¶

If pycocotools is imported by a library you don't control, such as mmdet or detectron2, call init_as_pycocotools() once at startup:

from hotcoco import init_as_pycocotools
init_as_pycocotools()

# All pycocotools imports now resolve to hotcoco
from pycocotools.coco import COCO          # → hotcoco.COCO
from pycocotools.cocoeval import COCOeval  # → hotcoco.COCOeval
from pycocotools import mask               # → hotcoco.mask

How the patch works, where to call it, and per-framework notes are in Framework integrations.

Method naming¶

Both camelCase and snake_case names are supported:

The same applies to Params properties: maxDets / max_dets, catIds / cat_ids, imgIds / img_ids, iouThrs / iou_thrs, recThrs / rec_thrs, areaRng / area_rng, areaRngLbl / area_rng_lbl, useCats / use_cats. OKS sigmas have one spelling, kpt_oks_sigmas — pycocotools also spells that attribute in snake_case.

And mask functions: toBbox / to_bbox, frPoly / fr_poly, frBbox / fr_bbox, frPyObjects / fr_py_objects.

Return types¶

hotcoco returns plain Python dicts and lists, matching pycocotools:

coco = COCO("instances_val2017.json")
anns = coco.load_anns([101])
print(type(anns[0]))  # <class 'dict'>

Annotation dicts carry the same keys — id, image_id, category_id, bbox, area, segmentation, iscrowd — plus any custom fields your dataset defines.

Argument types¶

The pycocotools-named functions accept the argument types pycocotools accepts:

• COCO() takes a str or any os.PathLike, such as a pathlib.Path — see the constructor.
• Id-list arguments of the query and load methods take an int or any iterable of ints, such as a set or dict.keys() — see Methods.
• getAnnIds takes iscrowd=0/1 and areaRng=[] — see get_ann_ids.
• mask.merge takes intersect=1 — see merge.
• mask.iou takes boxes as well as RLEs, so a COCOeval subclass whose computeIoU calls maskUtils.iou on boxes works under init_as_pycocotools() — see iou.

get_ann_ids and hotcoco.primitives keep stricter, typed signatures.

Getters return copies — assign back to apply¶

The data lives in Rust, so coco.dataset returns a copy on each access, and ev.coco_gt and ev.coco_dt return a new object that shares the evaluator's data without copying it; an edit to that object, through dataset or update_anns, lands on a private copy and never reaches the evaluator. Attribute assignment (ev.params.cat_ids = [...]) works — the setter routes the change back to Rust — but mutating a container inside a copy is a no-op:

ev.params.cat_ids = [1, 2, 3]       # applied — attribute assignment works
ev.params.maxDets.append(200)       # no-op — mutates a temporary list

md = ev.params.maxDets              # instead: pull, edit, assign back
md.append(200)
ev.params.maxDets = md

The same idiom applies to the dataset dict. pycocotools' in-memory construction flow works because assigning coco.dataset re-indexes:

d = coco.dataset
d["annotations"].append(new_ann)
coco.dataset = d                    # replaces contents and rebuilds the index
coco.createIndex()                  # supported, but a formality after assignment

Editing annotations that are already there does not need the whole dataset:

coco.update_anns([{"id": ann_id, "area": mask_area}])   # the keys you pass, by id

See update_anns for what it raises and when it re-indexes.

Known differences¶

Metric parity¶

Every COCO metric matches pycocotools to floating-point precision — the measured differences on COCO val2017, and a script to check your own data, are in Metric parity.

Rust: module paths renamed in 1.0¶

For Rust users upgrading from 0.x, these module paths moved (crate-root re-exports like hotcoco::COCOeval and hotcoco::Hierarchy are unchanged, so most code needs no edits):

There are no compatibility aliases for the old module paths. The Python API is unaffected.