IR JSON Format

Panlabel’s canonical lossless intermediate representation

The IR JSON format is Panlabel’s canonical intermediate representation. It preserves all dataset information without loss and serves as the bridge between all other formats.

Overview

• Path type: JSON file (.json)
• Lossiness: Lossless
• Bbox format: Pixel-space XYXY [xmin, ymin, xmax, ymax]
• Use case: Canonical storage, lossless conversion chains

Key Features

✓ Preserves dataset info and metadata
✓ Preserves licenses
✓ Preserves image metadata and attributes
✓ Preserves annotation confidence scores
✓ Preserves custom attributes on annotations and images
✓ Deterministic output (sorted by IDs)
✓ Supports images without annotations

Structure

The IR JSON format mirrors COCO’s structure but uses XYXY bbox coordinates:

{
  "info": {
    "name": "My Dataset",
    "version": "1.0",
    "description": "Sample dataset",
    "url": "https://example.com",
    "year": 2024,
    "contributor": "Your Name",
    "date_created": "2024-01-15"
  },
  "licenses": [
    {
      "id": 1,
      "name": "CC BY 4.0",
      "url": "https://creativecommons.org/licenses/by/4.0/"
    }
  ],
  "images": [
    {
      "id": 1,
      "file_name": "image001.jpg",
      "width": 640,
      "height": 480,
      "license_id": 1,
      "date_captured": "2024-01-15T10:30:00Z",
      "attributes": {}
    }
  ],
  "categories": [
    {
      "id": 1,
      "name": "person",
      "supercategory": "human"
    }
  ],
  "annotations": [
    {
      "id": 1,
      "image_id": 1,
      "category_id": 1,
      "bbox": [100.0, 150.0, 300.0, 400.0],
      "confidence": 0.95,
      "attributes": {}
    }
  ]
}

Bounding Box Format

Bboxes are stored as pixel-space XYXY:

"bbox": [xmin, ymin, xmax, ymax]

• xmin: Left edge in pixels
• ymin: Top edge in pixels
• xmax: Right edge in pixels
• ymax: Bottom edge in pixels

Example

"bbox": [10.0, 20.0, 100.0, 80.0]

Represents a box from (10, 20) to (100, 80) in pixel coordinates.

Schema Details

DatasetInfo

{
  "name": "string (optional)",
  "version": "string (optional)",
  "description": "string (optional)",
  "url": "string (optional)",
  "year": "integer (optional)",
  "contributor": "string (optional)",
  "date_created": "string (optional)"
}

License

{
  "id": "integer (required)",
  "name": "string (required)",
  "url": "string (optional)"
}

Image

{
  "id": "integer (required)",
  "file_name": "string (required)",
  "width": "integer (required)",
  "height": "integer (required)",
  "license_id": "integer (optional)",
  "date_captured": "string (optional)",
  "attributes": "object (optional, default: {})"
}

Category

{
  "id": "integer (required)",
  "name": "string (required)",
  "supercategory": "string (optional)"
}

Annotation

{
  "id": "integer (required)",
  "image_id": "integer (required)",
  "category_id": "integer (required)",
  "bbox": "[xmin, ymin, xmax, ymax] (required)",
  "confidence": "float (optional)",
  "attributes": "object (optional, default: {})"
}

Attributes

Both Image and Annotation support custom attributes as string key-value pairs:

{
  "id": 1,
  "image_id": 1,
  "category_id": 1,
  "bbox": [10.0, 20.0, 100.0, 80.0],
  "attributes": {
    "occluded": "1",
    "truncated": "0",
    "custom_field": "custom_value"
  }
}

Format-specific attributes are preserved during conversion (e.g., cvat_image_id, ls_rotation_deg).

Deterministic Output

When writing IR JSON, Panlabel produces deterministic output:

• All lists are sorted by ID
• Ensures reproducible builds
• Enables meaningful git diffs

Usage

Read IR JSON

panlabel convert input.json output-dir/ --input-format ir-json --output-format yolo

Write IR JSON

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

When to Use IR JSON

Use IR JSON when:

• You need lossless conversion between formats
• You want to preserve all metadata and attributes
• You’re building conversion pipelines
• You need deterministic, version-controllable output

Use other formats when:

• Training models (use YOLO, COCO, etc.)
• Integrating with specific tools (use their native format)
• Working with legacy systems (use VOC, TFOD, etc.)

See Also

COCO Format

Similar structure but uses XYWH bbox format

Format Overview

Compare all supported formats