🇷🇺 Read in Russian

AnnotationParser is a universal Python library that parses annotation files from various formats (LabelMe, COCO, VOC, etc.) and converts them into a single, unified Shape type. This approach allows you to read, filter, and save shapes using the same interface, regardless of the original annotation format.

Note: Currently only the LabelMe format is fully implemented and tested. Other formats are planned for future releases (see Limitations & Roadmap).

• Features
• Usage Examples
• Command-Line Interface (CLI)
• Supported Formats
• Limitations & Roadmap
• Contributing
• Development & Testing
• FAQ / Common Issues
• Author
• License

• Unified API for reading, saving, and filtering shapes in annotation files
• Converts any supported format into a universal Shape type for downstream processing
• Extensible adapter system for multiple formats (LabelMe, COCO, VOC, ...)
• Functional and OOP usage styles
• High-level filtering and transformation functions for shape objects
• Clean, type-safe, and well-documented codebase

Python 3.10+ required

Install with pip (recommended for most users):

pip install annotation-parser

Or, if you have the source code locally:

pip install -e .

from annotation_parser import create, get_shapes_by_label file = "tests/labelme/labelme_test.json" parser = create(file, "labelme") shapes = parser.parse() # tuple of Shape # Get all shapes with label "person" persons = get_shapes_by_label(shapes, "person") print(persons)

from annotation_parser import save_labelme save_labelme(shapes, "result.json", backup=True)

from annotation_parser import get_shapes_by_wz_number, get_shapes_by_number, filter_shapes # Filter by working zone (wz_number) zone2 = get_shapes_by_wz_number(shapes, wz_number=2) # Filter by instance/group number group_1 = get_shapes_by_number(shapes, number=1) # Filter with any condition (lambda) big_shapes = filter_shapes(shapes, lambda s: hasattr(s, "coords") and len(s.coords) > 3)

from annotation_parser import create parser = create("tests/labelme/labelme_test.json", "labelme") shapes = parser.parse() # You can call parser.save(), parser.parse(), parser.filter_shapes() if needed

from annotation_parser import parse_labelme shapes = parse_labelme("tests/labelme/labelme_test.json")

Experimental! Not fully tested. See cli.py for current options.

python cli.py parse --file tests/labelme/labelme_test.json --adapter labelme python cli.py save --file tests/labelme/labelme_test.json --adapter labelme --out result.json --backup python cli.py filter --file tests/labelme/labelme_test.json --adapter labelme --label crop

💡 Want to see your annotation format supported? Open an issue or PR — or help me implement a new adapter! Any contribution or feedback on new formats is very welcome.

• LabelMe format is currently the only one fully implemented and tested.
• Adapters for other formats (COCO, Pascal VOC, YOLO, etc.) are planned, not yet implemented.
• Standard logging (with configurable log levels and error handling) will be added in future releases.
• The command-line interface (cli.py) is experimental and not fully tested; improvements needed.

• PRs, bug reports, and suggestions are welcome!
• For new formats, contribute an adapter in src/annotation_parser/adapters/
• All code should be type-checked (mypy), formatted (black), and covered by tests (pytest).

• Install dev dependencies:

  poetry install --with dev

• Run tests:

  pytest

Q: Why do only LabelMe files work? A: Only the LabelMe adapter is currently implemented. COCO/VOC support is planned.

Q: CLI throws errors or doesn't work as expected? A: cli.py is not fully tested. Check Limitations & Roadmap and use the Python API for production.

Project: github.com/omigutin/annotation_parser Project Tracker: annotation_parser Project Board Contact: migutin83@yandex.ru

MIT License. See LICENSE for details.