---

name: annotation-data description: "Helps read, validate, summarize, repair, and generate labelme Annotation Files, Shapes, Flags, groups, and mask data without relying on unstable labelme internals." disable-model-invocation: true metadata: disco-role: operating license: GPL 3.0

Annotation Data

Use this route when the task is about labelme JSON Annotation Files, Shape/Flag/Group semantics, mask rasterization, image-data round trips, or safe headless validation of existing annotations.

Workflow

1. Read references/data-formats.md for the semantic model and file layout.
2. Use scripts/validate_labelme_json.py to validate or summarize a JSON file before touching conversion code or downstream dataset consumers.
3. Use the shared JSON helper as the self-contained parser/rasterizer when working outside the GUI.
4. When the task is to recover from a malformed annotation file, read references/troubleshooting.md first so you know which errors are repairable and which ones indicate missing image data or invalid Shape fields.
5. For public API details and exact signatures, prefer the installed package inspection evidence in references/api-reference.md over source guesses.

What this route covers

• One Image per Annotation File.
• Image-level Flags and per-Shape Flags.
• shape_type handling for polygon, rectangle, circle, line, linestrip, oriented_rectangle, point, points, and mask.
• Embedded imageData versus external imagePath.
• Windows-path normalization during load.
• imageHeight / imageWidth consistency checks.
• Mask Shape bbox clipping and canvas placement.
• Shape grouping through group_id.
• Lossless round-trips for extra top-level keys when they are not reserved.

What this route does not cover

• Launching the GUI or choosing CLI flags: use ../cli-and-config/SKILL.md.
• Converting annotations to training artifacts: use ../dataset-export/SKILL.md.
• AI-assisted prompting or model compatibility: use ../ai-assisted-annotation/SKILL.md.
• Source/repo maintenance: use ../repo-development/SKILL.md.

Practical checks

• scripts/validate_labelme_json.py file.json applies the current codec invariants (required shape_type, shape-specific point counts, finite coordinates, flags, groups, and mask dimensionality) and reports unknown labels when a vocabulary is supplied.
• scripts/validate_labelme_json.py --json file.json produces machine-readable summaries for downstream automation.
• --allow-missing-image-file relaxes only external-image resolution when imageData is null; it does not skip JSON or Shape validation.
• Keep downstream dataset code headless: labelme JSON parsing does not require Qt or a display.

References

• Read references/data-formats.md for the data model and file fields.
• Read references/api-reference.md for verified signatures and object shapes.
• Read references/troubleshooting.md for malformed file recovery and mask-related edge cases.