{"id":13645240,"url":"https://github.com/laclouis5/globox","last_synced_at":"2025-04-21T13:32:21.750Z","repository":{"id":40525753,"uuid":"394683340","full_name":"laclouis5/globox","owner":"laclouis5","description":"A package to read and convert object detection datasets (COCO, YOLO, PascalVOC, LabelMe, CVAT, OpenImage, ...) and evaluate them with COCO and PascalVOC metrics.","archived":false,"fork":false,"pushed_at":"2024-08-25T17:41:03.000Z","size":17849,"stargazers_count":172,"open_issues_count":0,"forks_count":21,"subscribers_count":6,"default_branch":"main","last_synced_at":"2024-09-26T18:35:13.330Z","etag":null,"topics":["annotation","average-precision","bounding-boxes","coco-api","cvat","dataset","labelme","mean-average-precision","metrics","object-detection","openimages","pascal-voc","yolo"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/laclouis5.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-08-10T14:24:51.000Z","updated_at":"2024-09-26T11:16:46.000Z","dependencies_parsed_at":"2024-04-15T22:34:46.378Z","dependency_job_id":"d0cfe494-b8c2-4699-87f1-36ea47205863","html_url":"https://github.com/laclouis5/globox","commit_stats":{"total_commits":217,"total_committers":4,"mean_commits":54.25,"dds":"0.032258064516129004","last_synced_commit":"bf26741a45940fe20cc2f4840fa52f1f4bb73f05"},"previous_names":[],"tags_count":23,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/laclouis5%2Fglobox","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/laclouis5%2Fglobox/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/laclouis5%2Fglobox/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/laclouis5%2Fglobox/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/laclouis5","download_url":"https://codeload.github.com/laclouis5/globox/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223867913,"owners_count":17216975,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["annotation","average-precision","bounding-boxes","coco-api","cvat","dataset","labelme","mean-average-precision","metrics","object-detection","openimages","pascal-voc","yolo"],"created_at":"2024-08-02T01:02:31.944Z","updated_at":"2024-11-09T18:30:35.452Z","avatar_url":"https://github.com/laclouis5.png","language":"Python","funding_links":[],"categories":["Object Detection Applications"],"sub_categories":[],"readme":"# Globox — Object Detection Toolbox\n\nThis framework can:\n\n* parse all kinds of object detection datasets (ImageNet, COCO, YOLO, PascalVOC, OpenImage, CVAT, LabelMe, etc.) and show statistics,\n* convert them to other formats (ImageNet, COCO, YOLO, PascalVOC, OpenImage, CVAT, LabelMe, etc.),\n* and evaluate predictions using standard object detection metrics such as $AP_{[.5:.05:.95]}$, $AP_{50}$, $mAP$, $AR_{1}$, $AR_{10}$, $AR_{100}$.\n\nThis framework can be used both as a library in your own code and as a command line tool. This tool is designed to be simple to use, fast and correct.\n\n## Install\n\nYou can install the package using pip:\n\n```shell\npip install globox\n```\n\n## Use as a Library\n\n### Parse Annotations\n\nThe library has three main components:\n\n* `BoundingBox`: represents a bounding box with a label and an optional confidence score\n* `Annotation`: represent the bounding boxes annotations for one image\n* `AnnotationSet`: represents annotations for a set of images (a database)\n\nThe `AnnotationSet` class contains static methods to read different dataset formats:\n\n```python\n# COCO\ncoco = AnnotationSet.from_coco(file_path=\"path/to/file.json\")\n\n# YOLOv5\nyolo = AnnotationSet.from_yolo_v5(\n    folder=\"path/to/files/\",\n    image_folder=\"path/to/images/\"\n)\n\n# Pascal VOC\npascal = AnnotationSet.from_pascal_voc(folder=\"path/to/files/\")\n```\n\n`Annotation` offers file-level granularity for compatible datasets:\n\n```python\nannotation = Annotation.from_labelme(file_path=\"path/to/file.xml\")\n```\n\nFor more specific implementations the `BoundingBox` class contains lots of utilities to parse bounding boxes in different formats, like the `create()` method.\n\n`AnnotationsSets` are set-like objects. They can be combined and annotations can be added:\n\n```python\ngts = coco | yolo\ngts.add(annotation)\n```\n\n### Inspect Datasets\n\nIterators and efficient lookup by `image_id`'s are easy to use:\n\n```python\nif annotation in gts:\n    print(\"This annotation is present.\")\n\nif \"image_123.jpg\" in gts.image_ids:\n    print(\"Annotation of image 'image_123.jpg' is present.\")\n\nfor box in gts.all_boxes:\n    print(box.label, box.area, box.is_ground_truth)\n\nfor annotation in gts:\n    nb_boxes = len(annotation.boxes)\n    print(f\"{annotation.image_id}: {nb_boxes} boxes\")\n```\n\nDatasets stats can printed to the console:\n\n```python\ncoco_gts.show_stats()\n```\n\n```text\n         Database Stats         \n┏━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━┓\n┃ Label       ┃ Images ┃ Boxes ┃\n┡━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━┩\n│ aeroplane   │     10 │    15 │\n│ bicycle     │      7 │    14 │\n│ bird        │      4 │     6 │\n│ boat        │      7 │    11 │\n│ bottle      │      9 │    13 │\n│ bus         │      5 │     6 │\n│ car         │      6 │    14 │\n│ cat         │      4 │     5 │\n│ chair       │      9 │    15 │\n│ cow         │      6 │    14 │\n│ diningtable │      7 │     7 │\n│ dog         │      6 │     8 │\n│ horse       │      7 │     7 │\n│ motorbike   │      3 │     5 │\n│ person      │     41 │    91 │\n│ pottedplant │      6 │     7 │\n│ sheep       │      4 │    10 │\n│ sofa        │     10 │    10 │\n│ train       │      5 │     6 │\n│ tvmonitor   │      8 │     9 │\n├─────────────┼────────┼───────┤\n│ Total       │    100 │   273 │\n└─────────────┴────────┴───────┘\n```\n\n### Convert and Save to Many Formats\n\nDatasets can be converted to and saved in other formats:\n\n```python\n# ImageNet\ngts.save_imagenet(save_dir=\"pascalVOC_db/\")\n\n# YOLO Darknet\ngts.save_yolo_darknet(\n    save_dir=\"yolo_train/\", \n    label_to_id={\"cat\": 0, \"dog\": 1, \"racoon\": 2}\n)\n\n# YOLOv5\ngts.save_yolo_v5(\n    save_dir=\"yolo_train/\", \n    label_to_id={\"cat\": 0, \"dog\": 1, \"racoon\": 2},\n)\n\n# CVAT\ngts.save_cvat(path=\"train.xml\")\n```\n\n### COCO Evaluation\n\nCOCO Evaluation is also supported:\n\n```python\nevaluator = COCOEvaluator(\n    ground_truths=gts, \n    predictions=dets\n)\n\nap = evaluator.ap()\nar_100 = evaluator.ar_100()\nap_75 = evaluator.ap_75()\nap_small = evaluator.ap_small()\n...\n```\n\nAll COCO standard metrics can be displayed in a pretty printed table with:\n\n```python\nevaluator.show_summary()\n```\n\nwhich outputs:\n\n```text\n                              COCO Evaluation\n┏━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━┳...┳━━━━━━━━┳━━━━━━━━┳━━━━━━━━┓\n┃ Label     ┃ AP 50:95 ┃  AP 50 ┃   ┃   AR S ┃   AR M ┃   AR L ┃\n┡━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━╇...╇━━━━━━━━╇━━━━━━━━╇━━━━━━━━┩\n│ airplane  │    22.7% │  25.2% │   │   nan% │  90.0% │   0.0% │\n│ apple     │    46.4% │  57.4% │   │  48.5% │   nan% │   nan% │\n│ backpack  │    54.8% │  85.1% │   │ 100.0% │  72.0% │   0.0% │\n│ banana    │    73.6% │  96.4% │   │   nan% │ 100.0% │  70.0% │\n.           .          .        .   .        .        .        .\n.           .          .        .   .        .        .        .\n.           .          .        .   .        .        .        .\n├───────────┼──────────┼────────┼...┼────────┼────────┼────────┤\n│ Total     │    50.3% │  69.7% │   │  65.4% │  60.3% │  55.3% │\n└───────────┴──────────┴────────┴...┴────────┴────────┴────────┘\n```\n\nThe array of results can be saved in CSV format:\n\n```python\nevaluator.save_csv(\"where/to/save/results.csv\")\n```\n\nCustom evaluations can be achieved with:\n\n```python\nevaluation = evaluator.evaluate(\n    iou_threshold=0.33,\n    max_detections=1_000,\n    size_range=(0.0, 10_000)\n)\n\nap = evaluation.ap()\ncat_ar = evaluation[\"cat\"].ar\n```\n\nEvaluations are cached by `(iou_threshold, max_detections, size_range)` keys. This means that repetead queries to the evaluator are fast!\n\n## Use in Command Line\n\nIf you only need to use Globox from the command line like an application, you can install the package through [pipx](https://pypa.github.io/pipx/):\n\n```shell\npipx install globox\n```\n\nGlobox will then be in your shell path and usable from anywhere.\n\n### Usage\n\nGet a summary of annotations for one dataset:\n\n```shell\nglobox summary /yolo/folder/ --format yolo\n```\n\nConvert annotations from one format to another one:\n\n```shell\nglobox convert input/yolo/folder/ output_coco_file_path.json --format yolo --save_fmt coco\n```\n\nEvaluate a set of detections with COCO metrics, display them and save them in a CSV file:\n\n```shell\nglobox evaluate groundtruths/ predictions.json --format yolo --format_dets coco -s results.csv\n```\n\nShow the help message for an exhaustive list of options:\n\n```shell\nglobox summary -h\nglobox convert -h\nglobox evaluate -h\n```\n\n## Run Tests\n\nClone the repo with its test data:\n\n```shell\ngit clone https://github.com/laclouis5/globox --recurse-submodules=tests/globox_test_data\ncd globox\n```\n\nInstall dependencies with [uv](https://github.com/astral-sh/uv):\n\n```shell\nuv sync --dev\n```\n\nRun the tests:\n\n```shell\nuv run pytest tests\n```\n\n## Speed Banchmarks\n\nSpeed benchmark can be executed with:\n\n```shell\nuv run python tests/benchmark.py -n 5\n```\n\nThe following speed test is performed using Python 3.11 and `timeit` with 5 iterations on a 2021 MacBook Pro 14\" (M1 Pro 8 Cores and 16 GB of RAM). The dataset is COCO 2017 Validation which comprises 5k images and 36 781 bounding boxes.\n\nTask   |COCO |CVAT |OpenImage|LabelMe|PascalVOC|YOLO |TXT\n-------|-----|-----|---------|-------|---------|-----|-----\nParsing|0.22s|0.12s|0.44s    |0.60s  |0.97s    |1.45s|1.12s\nSaving |0.32s|0.17s|0.14s    |1.06s  |1.08s    |0.91s|0.85s\n\n* `AnnotationSet.show_stats()`: 0.02 s\n* Evalaution: 0.30 s\n\n\u003c/details\u003e\n\n## Todo\n\n* [x] Basic data structures and utilities\n* [x] Parsers (ImageNet, COCO, YOLO, Pascal, OpenImage, CVAT, LabelMe)\n* [x] Parser tests\n* [x] Database summary and stats\n* [x] Database converters\n* [x] Visualization options\n* [x] COCO Evaluation\n* [x] Tests with a huge load (5k images)\n* [x] CLI interface\n* [x] Make `image_size` optional and raise err when required (bbox conversion)\n* [x] Make file saving atomic with a temporary to avoid file corruption\n* [x] Pip package!\n* [ ] PascalVOC Evaluation\n* [ ] Parsers for TFRecord and TensorFlow\n* [ ] UI interface?\n\n## Acknowledgement\n\nThis repo is based on the work of [Rafael Padilla](https://github.com/rafaelpadilla/review_object_detection_metrics).\n\n## Contribution\n\nFeel free to contribute, any help you can offer with this project is most welcome.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flaclouis5%2Fglobox","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flaclouis5%2Fglobox","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flaclouis5%2Fglobox/lists"}