Exporting COCO

A COCO export is a .zip containing annotations/instances_default.json and images/default/. Category ids come from the full label list and start at 1, boxes are absolute [x, y, width, height], polygons are written to segmentation, and turning on dataset splits produces three annotation files with matching image folders.

Archive layout

Standard export

export.zip
├── annotations/
│   └── instances_default.json
└── images/
    └── default/
        ├── img_0001.jpg
        └── img_0002.jpg

With dataset splits turned on

export.zip
├── annotations/
│   ├── instances_train.json
│   ├── instances_val.json
│   └── instances_test.json
└── images/
    ├── train/…
    ├── val/…
    └── test/…

In split mode all three annotation files are written even if a subset is empty, so downstream configuration never points at a missing path. The three files share identical category ids, because ids always come from the full label list rather than from the labels that happen to appear in that subset.

Keypoint projects use the COCO person-keypoints naming instead: person_keypoints_default.json, and person_keypoints_train.json and friends in split mode.

What is in the JSON

Field	What AnnotateIt writes
info.description	The project name
images[]	id, file_name, width and height — real decoded dimensions, not assumptions
categories[]	One per project label, id starting at 1, in label order
annotations[].bbox	Absolute pixels, [x, y, width, height] — the shape’s axis-aligned bounds
annotations[].area	A mask’s exact pixel count; the polygon’s own area (shoelace formula) for polygons; width × height of the box otherwise
annotations[].iscrowd	The object’s crowd flag — a first-class COCO field lifted out of the attributes, 0 unless the annotation sets it
annotations[].segmentation	Native run-length encoding ({ counts, size }) for a pixel mask; a single polygon ring [[x1, y1, x2, y2, …]] for a polygon, and for a polyline written as its stroke ribbon; an empty array for boxes, circles and poses
annotations[].attributes	Any other per-object attributes (the CVAT dialect of COCO); omitted entirely when the object has none, so an attribute-free export stays byte-identical to plain COCO

Masks, polygons and polylines all reach the segmentation field; a box, a circle or a pose is written with its bounding box and an empty segmentation, because COCO has nowhere else to put them. That is documented behaviour rather than silent data loss — if you need a round trip that preserves everything, export Datumaro, or re-import the COCO archive AnnotateIt wrote (it carries an annotateit-metadata.json sidecar that restores the exact shapes).

Keypoint exports

For a keypoint project the export follows the COCO person-keypoints convention: a single category carries a keypoints array of position names and a skeleton array of 1-based index pairs describing the edges of your template. Each annotation carries a flat keypoints array of x, y, visibility triples plus num_keypoints, and a bounding box derived from the placed points.

Filenames

File names are made unique across the whole archive before anything is written. In COCO, file_name is what ties an annotation record to the image bytes, so two images with the same name — or names differing only by extension — would corrupt that pairing as well as overwrite each other. The exporter renames rather than lets that happen.

When to pick something else

Format	Pick it when
COCO	Your training code reads COCO JSON — the common default for detection and segmentation
YOLO	You train with an Ultralytics-style pipeline; split mode writes the folder layout and data.yaml
Pascal VOC	You need per-image XML annotations
Datumaro	You want the most faithful round trip back into AnnotateIt, or a dataset that mixes images and video
Supervisely Video	The dataset is video and the target tool expects that format
MOT Challenge	The dataset is video with object tracks and you need the MOTChallenge gt/gt.txt layout
KITTI	Your pipeline reads KITTI label_2 files, or you need truncated/occluded encoded KITTI-style
MOTS	The dataset is instance-segmentation video and you need MOTSChallenge masks with track ids
Plain ZIP	You only want the media, with no annotation files

Every annotated export also carries an annotateit-metadata.json sidecar. It sits alongside the standard files (which stay fully valid for any third-party COCO tool) and lets AnnotateIt restore, on re-import, the things the standard has no field for — exact shapes, attribute definitions and values, text prompts, label colours and hierarchy, the project task schema and the keypoint template. See “Dataset formats and the exact round trip”.