COCO Format

​

Overview

• Path type: JSON file (.json)
• Lossiness: Conditional (see below)
• Bbox format: Pixel-space XYWH [x, y, width, height]
• Use case: Industry standard, model training, benchmarking

​

Key Features

​

Bounding Box Format

"bbox": [x, y, width, height]

• x: Top-left X coordinate in pixels
• y: Top-left Y coordinate in pixels
• width: Box width in pixels
• height: Box height in pixels

​

Example

"bbox": [10.0, 20.0, 90.0, 60.0]

• xmin = x = 10.0
• ymin = y = 20.0
• xmax = x + width = 10.0 + 90.0 = 100.0
• ymax = y + height = 20.0 + 60.0 = 80.0

​

Structure

{
  "info": {
    "year": 2024,
    "version": "1.0",
    "description": "Sample COCO dataset",
    "contributor": "Your Name",
    "url": "https://example.com",
    "date_created": "2024-01-15"
  },
  "licenses": [
    {
      "id": 1,
      "name": "CC BY 4.0",
      "url": "https://creativecommons.org/licenses/by/4.0/"
    }
  ],
  "images": [
    {
      "id": 1,
      "width": 640,
      "height": 480,
      "file_name": "image001.jpg",
      "license": 1,
      "date_captured": "2024-01-15T10:30:00Z"
    }
  ],
  "categories": [
    {
      "id": 1,
      "name": "person",
      "supercategory": "human"
    }
  ],
  "annotations": [
    {
      "id": 1,
      "image_id": 1,
      "category_id": 1,
      "bbox": [10.0, 20.0, 90.0, 60.0],
      "area": 5400.0,
      "iscrowd": 0,
      "segmentation": [],
      "score": 0.95
    }
  ]
}

​

Lossiness Details

​

Preserved ✓

• Dataset info (year, version, description, contributor, url, date_created)
• Licenses (id, name, url)
• Image metadata (id, width, height, file_name, license, date_captured)
• Categories (id, name, supercategory)
• Bounding boxes (XYWH ↔ XYXY conversion)
• Confidence (score ↔ IR confidence)
• Area and iscrowd (stored as annotation attributes)

​

Not Preserved ✗

• Custom annotation attributes (except iscrowd and area)
• Custom image attributes
• Segmentation data (accepted on read but dropped)

​

Reader Behavior

• Accepts standard COCO JSON structure
• Converts XYWH bboxes to IR XYXY via bbox helpers
• Maps score field to IR confidence
• Stores iscrowd as annotation attribute "iscrowd"
• Stores area as annotation attribute "area" (for round-trip preservation)
• Accepts segmentation but ignores/drops it

​

Writer Behavior

• Produces deterministic output (sorted by ID)
• Converts IR XYXY to COCO XYWH
• Maps IR confidence to score
• Retrieves iscrowd from annotation attributes (default: 0)
• Retrieves area from annotation attributes (falls back to computed bbox area)
• Emits segmentation as empty array []
• Sorts all lists by ID for stable output

​

Confidence/Score Mapping

"score": 0.95  →  IR confidence: 0.95

IR confidence: 0.95  →  "score": 0.95

​

Usage

​

Read COCO

panlabel convert annotations.json output-dir/ --input-format coco --output-format yolo

​

Write COCO

panlabel convert dataset/ output.json --input-format yolo --output-format coco

​

Auto-detection

panlabel convert annotations.json output.json

​

Round-trip Behavior

• All standard COCO fields
• Bbox coordinates (within floating-point precision)
• IDs, category names, image metadata
• area and iscrowd values

​

See Also