COCO Category IDs: Verify the Class Map Before Accepting an Export
· Annotation Quality
Dataset category IDs and model class indices can be different. Preserve and test the explicit mapping rather than using list position or subtracting one.
A dataset category ID and a model's contiguous class index can refer to the same class using different numbers. Before accepting a COCO-format annotation export or conversion, verify an explicit map from source category ID to class meaning and target index, then check the reverse mapping used for evaluation or re-export.
This guide is for annotation buyers reviewing deliveries. It does not advertise jobs, eligibility or pay. Data Annotation Companies is independent and is not affiliated with Detectron2 or its maintainers.
What does the documented loader distinguish?
The Detectron2 custom-dataset documentation describes its standard instance category IDs as indices from zero to the number of categories minus one. It separately documents a map from dataset class IDs to contiguous IDs, which its COCO loader sets. These are related representations, not a rule that every original COCO category number already equals the model index.
Use the documentation and configuration for the actual loader version. A conversion accepted by software can still assign the wrong class meaning. Neither a zero-based convention nor a matching number of classes proves that names, annotations and evaluator metadata agree.
Which mapping evidence should the delivery include?
Keep the approved label policy and export version with the mapping. Confirm each source category ID against its defined class name, then trace the target index through the actual conversion configuration. Do not use the category list's current display order as an undocumented substitute for an ID map.
| Map field | Evidence to retain |
|---|---|
| Source ID | Category identifier from the delivered dataset |
| Class meaning | Approved name and label-policy revision |
| Target index | Explicit contiguous index required by the selected loader |
| Reverse map | Original ID used for evaluation or re-export |
| Conversion version | Actual configuration and reviewed output |
This is an original acceptance aid, not an additional mandatory COCO file. Agree its delivery form with the provider. If a class is merged, renamed or excluded, record that as a separate approved policy change; it is not merely a harmless renumbering.
How can valid-looking numbers carry the wrong meaning?
Illustrative example. A fictional two-class dataset defines source category 3 as valve and source category 17 as panel. Its approved model representation assigns valve to index 0 and panel to index 1. The required map is therefore 3 to 0 and 17 to 1, with a reverse map of 0 to 3 and 1 to 17.
| Source | Meaning | Target |
|---|---|---|
| 3 | valve | 0 |
| 17 | panel | 1 |
Subtracting one from each source ID would produce 2 and 16, which are not the approved indices for this two-class exercise. Reversing an unrelated displayed class list could instead swap the names attached to 0 and 1. A total of 12 objects, assumed here to contain five valves and seven panels, can remain 12 even after a class swap. The total alone cannot reveal the semantic error.
The IDs, labels and counts are invented. They are not the official COCO class list or a promised quality threshold. The example explains why a mapping needs explicit evidence; it does not prescribe a loader's ordering algorithm.
How should the buyer check the converted delivery?
Preserve the original annotations and the converted version. Reconcile per-class counts by approved meaning through the map, inspect representative objects from each class, and verify that evaluation or reverse export restores the intended source IDs. Include a check that changes to list presentation do not silently change class meaning under the chosen process.
Keep missing classes, duplicate IDs, unmapped labels and intentional exclusions visible for adjudication. Do not silently compress the class list to make an import succeed. After an authorised correction, retain the changed map and recheck the affected annotations and outputs.
Frequently asked questions
Can I always subtract one from a source category ID?
No. Use the explicit map for the actual source IDs and target representation.
Does an unchanged object total prove the class map is correct?
No. Wrong class meanings can preserve the total count.
Is a label rename just a number conversion?
Not necessarily. A semantic change needs its own approved policy and review.
Use the label-cardinality review to establish how many labels each item may carry, and the bounding-box export checklist to check coordinates separately. Browse the company directory and ask providers to demonstrate their actual mapping, conversion and acceptance evidence.