faster-coco-eval 1.7.1__tar.gz → 1.8.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (79) hide show
  1. faster_coco_eval-1.8.0/MANIFEST.in +5 -0
  2. faster_coco_eval-1.8.0/PKG-INFO +278 -0
  3. faster_coco_eval-1.8.0/README.md +234 -0
  4. {faster_coco_eval-1.7.1 → faster_coco_eval-1.8.0}/csrc/faster_eval_api/coco_eval/cocoeval.cpp +388 -140
  5. {faster_coco_eval-1.7.1 → faster_coco_eval-1.8.0}/csrc/faster_eval_api/coco_eval/dataset.cpp +6 -5
  6. {faster_coco_eval-1.7.1 → faster_coco_eval-1.8.0}/csrc/faster_eval_api/coco_eval/dataset.h +2 -2
  7. {faster_coco_eval-1.7.1 → faster_coco_eval-1.8.0}/csrc/mask_api/src/mask.cpp +212 -90
  8. {faster_coco_eval-1.7.1 → faster_coco_eval-1.8.0}/csrc/mask_api/src/mask.h +32 -2
  9. {faster_coco_eval-1.7.1 → faster_coco_eval-1.8.0}/csrc/mask_api/src/rle.cpp +34 -10
  10. {faster_coco_eval-1.7.1 → faster_coco_eval-1.8.0}/faster_coco_eval/core/coco.py +126 -84
  11. {faster_coco_eval-1.7.1 → faster_coco_eval-1.8.0}/faster_coco_eval/core/cocoeval.py +111 -81
  12. {faster_coco_eval-1.7.1 → faster_coco_eval-1.8.0}/faster_coco_eval/core/faster_eval_api.py +198 -39
  13. {faster_coco_eval-1.7.1 → faster_coco_eval-1.8.0}/faster_coco_eval/core/mask.py +12 -19
  14. {faster_coco_eval-1.7.1 → faster_coco_eval-1.8.0}/faster_coco_eval/extra/curves.py +40 -21
  15. {faster_coco_eval-1.7.1 → faster_coco_eval-1.8.0}/faster_coco_eval/extra/display.py +14 -13
  16. {faster_coco_eval-1.7.1 → faster_coco_eval-1.8.0}/faster_coco_eval/extra/draw.py +49 -34
  17. {faster_coco_eval-1.7.1 → faster_coco_eval-1.8.0}/faster_coco_eval/extra/extra.py +21 -22
  18. {faster_coco_eval-1.7.1 → faster_coco_eval-1.8.0}/faster_coco_eval/extra/utils.py +4 -1
  19. {faster_coco_eval-1.7.1 → faster_coco_eval-1.8.0}/faster_coco_eval/utils/pytorch/coco_dataset.py +7 -10
  20. {faster_coco_eval-1.7.1 → faster_coco_eval-1.8.0}/faster_coco_eval/utils/pytorch/coco_eval.py +19 -22
  21. faster_coco_eval-1.8.0/faster_coco_eval/version.py +2 -0
  22. faster_coco_eval-1.8.0/faster_coco_eval.egg-info/PKG-INFO +278 -0
  23. {faster_coco_eval-1.7.1 → faster_coco_eval-1.8.0}/faster_coco_eval.egg-info/SOURCES.txt +14 -1
  24. faster_coco_eval-1.8.0/history.md +228 -0
  25. {faster_coco_eval-1.7.1 → faster_coco_eval-1.8.0}/pyproject.toml +16 -4
  26. faster_coco_eval-1.8.0/requirements/docs.txt +6 -0
  27. {faster_coco_eval-1.7.1 → faster_coco_eval-1.8.0}/setup.py +5 -6
  28. faster_coco_eval-1.8.0/tests/test_annotation_id_zero.py +56 -0
  29. {faster_coco_eval-1.7.1 → faster_coco_eval-1.8.0}/tests/test_basic.py +151 -1
  30. {faster_coco_eval-1.7.1 → faster_coco_eval-1.8.0}/tests/test_boundary.py +5 -1
  31. faster_coco_eval-1.8.0/tests/test_coco_api_and_evaluator_regressions.py +562 -0
  32. {faster_coco_eval-1.7.1 → faster_coco_eval-1.8.0}/tests/test_coco_metric.py +3 -1
  33. faster_coco_eval-1.8.0/tests/test_compute_oks.py +69 -0
  34. faster_coco_eval-1.8.0/tests/test_core_low_regressions.py +105 -0
  35. faster_coco_eval-1.8.0/tests/test_cpp_safety_regressions.py +108 -0
  36. {faster_coco_eval-1.7.1 → faster_coco_eval-1.8.0}/tests/test_crowdpose.py +4 -1
  37. {faster_coco_eval-1.7.1 → faster_coco_eval-1.8.0}/tests/test_dataset.py +226 -0
  38. faster_coco_eval-1.8.0/tests/test_display_matrix_normalization.py +42 -0
  39. faster_coco_eval-1.8.0/tests/test_extensive_pycocotools_comparison.py +589 -0
  40. faster_coco_eval-1.8.0/tests/test_extra_curves.py +58 -0
  41. {faster_coco_eval-1.7.1 → faster_coco_eval-1.8.0}/tests/test_extra_draw.py +36 -8
  42. faster_coco_eval-1.8.0/tests/test_extra_regressions.py +92 -0
  43. {faster_coco_eval-1.7.1 → faster_coco_eval-1.8.0}/tests/test_extra_utils.py +42 -6
  44. {faster_coco_eval-1.7.1 → faster_coco_eval-1.8.0}/tests/test_keypoints.py +14 -4
  45. {faster_coco_eval-1.7.1 → faster_coco_eval-1.8.0}/tests/test_lvis_metric.py +2 -0
  46. {faster_coco_eval-1.7.1 → faster_coco_eval-1.8.0}/tests/test_mask_api.py +249 -0
  47. faster_coco_eval-1.8.0/tests/test_orphan_annotations.py +88 -0
  48. faster_coco_eval-1.8.0/tests/test_pytorch_coco_dataset.py +56 -0
  49. faster_coco_eval-1.8.0/tests/test_pytorch_coco_eval.py +68 -0
  50. {faster_coco_eval-1.7.1 → faster_coco_eval-1.8.0}/tests/test_simple_extra.py +146 -0
  51. {faster_coco_eval-1.7.1 → faster_coco_eval-1.8.0}/tests/test_torchmetrics.py +19 -8
  52. faster_coco_eval-1.8.0/tests/test_world_evaluator.py +124 -0
  53. faster_coco_eval-1.7.1/MANIFEST.in +0 -1
  54. faster_coco_eval-1.7.1/PKG-INFO +0 -189
  55. faster_coco_eval-1.7.1/README.md +0 -142
  56. faster_coco_eval-1.7.1/faster_coco_eval/version.py +0 -2
  57. faster_coco_eval-1.7.1/faster_coco_eval.egg-info/PKG-INFO +0 -189
  58. faster_coco_eval-1.7.1/requirements/docs.txt +0 -8
  59. faster_coco_eval-1.7.1/tests/test_world_evalutor.py +0 -84
  60. {faster_coco_eval-1.7.1 → faster_coco_eval-1.8.0}/LICENSE +0 -0
  61. {faster_coco_eval-1.7.1 → faster_coco_eval-1.8.0}/csrc/faster_eval_api/coco_eval/cocoeval.h +0 -0
  62. {faster_coco_eval-1.7.1 → faster_coco_eval-1.8.0}/csrc/faster_eval_api/coco_eval/types.h +0 -0
  63. {faster_coco_eval-1.7.1 → faster_coco_eval-1.8.0}/csrc/faster_eval_api/faster_eval_api.cpp +0 -0
  64. {faster_coco_eval-1.7.1 → faster_coco_eval-1.8.0}/csrc/mask_api/mask_api.cpp +0 -0
  65. {faster_coco_eval-1.7.1 → faster_coco_eval-1.8.0}/faster_coco_eval/__init__.py +0 -0
  66. {faster_coco_eval-1.7.1 → faster_coco_eval-1.8.0}/faster_coco_eval/core/__init__.py +0 -0
  67. {faster_coco_eval-1.7.1 → faster_coco_eval-1.8.0}/faster_coco_eval/extra/__init__.py +0 -0
  68. {faster_coco_eval-1.7.1 → faster_coco_eval-1.8.0}/faster_coco_eval/utils/__init__.py +0 -0
  69. {faster_coco_eval-1.7.1 → faster_coco_eval-1.8.0}/faster_coco_eval/utils/pytorch/__init__.py +0 -0
  70. {faster_coco_eval-1.7.1 → faster_coco_eval-1.8.0}/faster_coco_eval.egg-info/dependency_links.txt +0 -0
  71. {faster_coco_eval-1.7.1 → faster_coco_eval-1.8.0}/faster_coco_eval.egg-info/requires.txt +0 -0
  72. {faster_coco_eval-1.7.1 → faster_coco_eval-1.8.0}/faster_coco_eval.egg-info/top_level.txt +0 -0
  73. {faster_coco_eval-1.7.1 → faster_coco_eval-1.8.0}/requirements/extra.txt +0 -0
  74. {faster_coco_eval-1.7.1 → faster_coco_eval-1.8.0}/requirements/runtime.txt +0 -0
  75. {faster_coco_eval-1.7.1 → faster_coco_eval-1.8.0}/requirements/tests.txt +0 -0
  76. {faster_coco_eval-1.7.1 → faster_coco_eval-1.8.0}/setup.cfg +0 -0
  77. {faster_coco_eval-1.7.1 → faster_coco_eval-1.8.0}/tests/test_cocoapi_fake_data.py +0 -0
  78. {faster_coco_eval-1.7.1 → faster_coco_eval-1.8.0}/tests/test_init_pycocotools.py +0 -0
  79. {faster_coco_eval-1.7.1 → faster_coco_eval-1.8.0}/tests/test_ranges.py +0 -0
@@ -0,0 +1,5 @@
1
+ graft csrc
2
+ graft requirements
3
+ include README.md
4
+ include history.md
5
+ include LICENSE
@@ -0,0 +1,278 @@
1
+ Metadata-Version: 2.4
2
+ Name: faster-coco-eval
3
+ Version: 1.8.0
4
+ Summary: Faster interpretation of the original COCOEval
5
+ Home-page: https://github.com/MiXaiLL76/faster_coco_eval
6
+ Author: MiXaiLL76,Borda
7
+ Author-email: mike.milos@yandex.ru
8
+ Classifier: Development Status :: 4 - Beta
9
+ Classifier: Operating System :: OS Independent
10
+ Classifier: Programming Language :: Python :: 3
11
+ Classifier: Programming Language :: Python :: 3.10
12
+ Classifier: Programming Language :: Python :: 3.11
13
+ Classifier: Programming Language :: Python :: 3.12
14
+ Classifier: Programming Language :: Python :: 3.13
15
+ Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
16
+ Requires-Python: >=3.10
17
+ Description-Content-Type: text/markdown
18
+ License-File: LICENSE
19
+ Requires-Dist: numpy
20
+ Provides-Extra: extra
21
+ Requires-Dist: numpy; extra == "extra"
22
+ Requires-Dist: opencv-python-headless; extra == "extra"
23
+ Requires-Dist: pandas; extra == "extra"
24
+ Requires-Dist: plotly; extra == "extra"
25
+ Requires-Dist: Pillow; extra == "extra"
26
+ Provides-Extra: tests
27
+ Requires-Dist: numpy; extra == "tests"
28
+ Requires-Dist: numpy; extra == "tests"
29
+ Requires-Dist: pycocotools; python_version < "3.13" and extra == "tests"
30
+ Requires-Dist: pytest; extra == "tests"
31
+ Requires-Dist: pytest-cov; extra == "tests"
32
+ Requires-Dist: parameterized; extra == "tests"
33
+ Dynamic: author
34
+ Dynamic: author-email
35
+ Dynamic: classifier
36
+ Dynamic: description
37
+ Dynamic: description-content-type
38
+ Dynamic: home-page
39
+ Dynamic: license-file
40
+ Dynamic: provides-extra
41
+ Dynamic: requires-dist
42
+ Dynamic: requires-python
43
+ Dynamic: summary
44
+
45
+ # Faster-COCO-Eval
46
+
47
+ **The Fastest, Most Reliable COCO Evaluation Library for Computer Vision**
48
+
49
+ [![PyPI](https://img.shields.io/pypi/v/faster-coco-eval)](https://pypi.org/project/faster-coco-eval)
50
+ [![PyPI Downloads](https://img.shields.io/pypi/dm/faster-coco-eval.svg?label=PyPI%20downloads)](https://pypi.org/project/faster-coco-eval/)
51
+ [![Conda Version](https://img.shields.io/conda/vn/conda-forge/faster-coco-eval.svg)](https://anaconda.org/conda-forge/faster-coco-eval)
52
+ [![Conda Platforms](https://img.shields.io/conda/pn/conda-forge/faster-coco-eval.svg)](https://anaconda.org/conda-forge/faster-coco-eval)
53
+ [![docs](https://img.shields.io/badge/docs-latest-blue)](https://github.com/MiXaiLL76/faster_coco_eval/wiki)
54
+ [![license](https://img.shields.io/github/license/MiXaiLL76/faster_coco_eval.svg)](https://github.com/MiXaiLL76/faster_coco_eval/blob/main/LICENSE)
55
+ [![CI - Test](https://github.com/MiXaiLL76/faster_coco_eval/actions/workflows/unittest.yml/badge.svg)](https://github.com/MiXaiLL76/faster_coco_eval/actions/workflows/unittest.yml)
56
+
57
+ ## Replace pycocotools with Faster-COCO-Eval Today
58
+
59
+ | Aspect | pycocotools | **faster-coco-eval** |
60
+ | ------------------------------ | ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
61
+ | **Support & Development** | Outdated and not actively maintained. Issues and incompatibilities arise with new releases. | Actively maintained, continuously evolving, and regularly updated with new features and bug fixes. |
62
+ | **Transparency & Reliability** | Lacks comprehensive testing, making updates risky and results less predictable. | Emphasizes extensive test coverage and code quality, ensuring trustworthy and reliable results. |
63
+ | **Performance** | Significantly slower, especially on large datasets or distributed workloads. | Native C++ implementation with measured speedups that depend on the workload and hardware. |
64
+ | **Functionality** | Limited to basic COCO format evaluation. | Offers extended metrics, support for new IoU types, compatibility with more datasets (e.g., CrowdPose, LVIS), advanced visualizations, and seamless integration with PyTorch/TorchVision. |
65
+ | **Ease of Use** | Requires manual installation, often with compilation issues. | Simple `pip install` with pre-built wheels for common CPython/glibc Linux, macOS, and Windows platforms; source builds may be needed elsewhere. |
66
+ | **Visualization** | Basic plotting capabilities. | Advanced error visualization, annotation display, and comprehensive metric analysis tools. |
67
+
68
+ ______________________________________________________________________
69
+
70
+ **Key Benefits of Faster-COCO-Eval:**
71
+
72
+ ✅ **Blazing Fast Performance** - Evaluate large datasets in minutes instead of hours
73
+ ✅ **Reliable & Trusted** - Extensive test coverage ensures consistent, reproducible results
74
+ ✅ **Modern Features** - Support for latest CV tasks, IoU types, and dataset formats
75
+ ✅ **Easy to Use** - Drop-in replacement for pycocotools with enhanced API
76
+ ✅ **Comprehensive Visualization** - Understand your model's performance with beautiful, informative plots
77
+
78
+ **Join thousands of computer vision researchers and engineers who have already switched to Faster-COCO-Eval!**
79
+
80
+ ## Quick Installation
81
+
82
+ ### Option 1: Basic (Drop-in Replacement)
83
+
84
+ Get started in seconds with the core evaluation functionality:
85
+
86
+ ```bash
87
+ pip install faster-coco-eval
88
+ ```
89
+
90
+ ### Option 2: Full Installation (with Visualization)
91
+
92
+ For complete functionality including advanced visualization tools:
93
+
94
+ ```bash
95
+ pip install faster-coco-eval[extra]
96
+ ```
97
+
98
+ ### Option 3: Conda Installation
99
+
100
+ If you use Anaconda/Miniconda:
101
+
102
+ ```bash
103
+ conda install conda-forge::faster-coco-eval
104
+ ```
105
+
106
+ ## 🚀 Quick Start: Drop-in Replacement
107
+
108
+ Replace pycocotools with Faster-COCO-Eval in **2 lines of code**:
109
+
110
+ ```python
111
+ import faster_coco_eval
112
+
113
+ # This single line replaces pycocotools with faster-coco-eval
114
+ faster_coco_eval.init_as_pycocotools()
115
+
116
+ # Now use the familiar pycocotools API
117
+ from pycocotools.coco import COCO
118
+ from pycocotools.cocoeval import COCOeval
119
+
120
+ # Load annotations and predictions
121
+ anno_json = "path/to/annotations.json"
122
+ pred_json = "path/to/predictions.json"
123
+ anno = COCO(str(anno_json)) # Annotations file
124
+ pred = anno.loadRes(str(pred_json)) # Predictions file
125
+
126
+ # Evaluate bounding boxes
127
+ val = COCOeval(anno, pred, "bbox")
128
+ val.evaluate()
129
+ val.accumulate()
130
+ val.summarize()
131
+
132
+ # Or evaluate segmentation masks
133
+ val = COCOeval(anno, pred, "segm")
134
+ val.evaluate()
135
+ val.accumulate()
136
+ val.summarize()
137
+ ```
138
+
139
+ **That's it! Your existing code runs through the native evaluator with no API changes.**
140
+
141
+ ## ⚡ Blazing Fast Performance
142
+
143
+ Faster-COCO-Eval uses a native C++ implementation. The measured result below is one local reference point; real-world speedup varies with dataset size, metric, and hardware.
144
+
145
+ ### Real-World Performance Benchmark
146
+
147
+ Local reference measurement: 100 synthetic images, 15 ground-truth boxes and 100 detections per image, five categories, bbox evaluation, seven timed samples after two warmups. The measurement was run on 2026-08-23 on macOS 26.6.1 arm64, Python 3.10.11, and NumPy 2.2.6. The implementations' `eval["precision"]` arrays matched within the comparison tolerance.
148
+
149
+ | Evaluation Type | Faster-COCO-Eval (sec) | pycocotools (sec) | Speedup |
150
+ | --------------- | ----------------------- | ----------------------- | --------- |
151
+ | Bounding Boxes | 0.053977 (MAD 0.001883) | 0.296960 (MAD 0.001667) | **5.50x** |
152
+
153
+ This local measurement is hardware- and workload-dependent; it is not a universal performance guarantee.
154
+
155
+ ### Colab Examples
156
+
157
+ See the performance in action:
158
+
159
+ - [mmdetection comparison](https://nbviewer.org/github/MiXaiLL76/faster_coco_eval/blob/main/examples/comparison/mmdet/colab_example.ipynb)
160
+ - [ultralytics comparison](https://nbviewer.org/github/MiXaiLL76/faster_coco_eval/blob/main/examples/comparison/ultralytics/colab_example.ipynb)
161
+
162
+ ## 🎯 Powerful Features
163
+
164
+ Faster-COCO-Eval goes beyond basic evaluation with these advanced capabilities:
165
+
166
+ ### Core Evaluation
167
+
168
+ - **Drop-in pycocotools replacement** - No code changes needed
169
+ - **Support for all COCO metric types**: bbox, segm, keypoints
170
+ - **LVIS (Large Vocabulary Instance Segmentation) evaluation**
171
+ - **CrowdPose and custom keypoint datasets**
172
+ - **Multiple IoU types**: standard, rotated, and custom IoU definitions
173
+
174
+ ### Advanced Visualization
175
+
176
+ - **Error visualization**: See where your model is making mistakes
177
+ - **Annotation display**: Visualize ground truth and predictions together
178
+ - **Metric curves**: Precision-recall curves, class-wise performance
179
+ - **Confusion matrices and error analysis**
180
+ - **Interactive Jupyter notebook examples**
181
+
182
+ ### Modern Integrations
183
+
184
+ - **PyTorch/TorchVision compatibility**
185
+ - **Seamless integration with mmdetection and YOLO frameworks**
186
+ - **Distributed evaluation support**
187
+ - **Memory optimized for large datasets**
188
+
189
+ ### Additional Tools
190
+
191
+ - **Boundary evaluation for segmentation tasks**
192
+ - **Custom dataset support**
193
+ - **Comprehensive API documentation**
194
+ - **Extensive test coverage and reliability**
195
+
196
+ ## ✅ Testing & Reliability
197
+
198
+ Faster-COCO-Eval prioritizes **correctness and reliability** through extensive testing:
199
+
200
+ ### Comprehensive Test Suite
201
+
202
+ - **90+ automated tests** covering all functionality
203
+ - **Numerical parity checks** against pycocotools across the supported metrics
204
+ - **Continuous integration** on Python 3.10-3.13
205
+ - **Edge case coverage** including boundary conditions and error handling
206
+
207
+ ### Extensive PyCocoTools Comparison
208
+
209
+ New comprehensive tests validate **numerical parity within a strict tolerance** with pycocotools:
210
+
211
+ - **Object Detection**: Tests with 10-100 images, hundreds to thousands of annotations
212
+ - **Instance Segmentation**: RLE mask encoding and pixel-level IoU validation
213
+ - **Keypoint Detection**: 17-keypoint pose estimation with varied visibility
214
+ - **Multiple Scenarios**: Small/medium/large objects, various confidence distributions
215
+ - **Edge Cases**: Perfect predictions, low-confidence detections, mixed object sizes
216
+
217
+ The comparison suite checks numerical parity between faster_coco_eval and pycocotools, giving you confidence to use this library as a drop-in replacement. See the benchmark above for one measured bbox workload; it is not a universal performance guarantee.
218
+
219
+ See [tests/README.md](tests/README.md) for detailed test documentation.
220
+
221
+ ## 📚 Comprehensive Documentation
222
+
223
+ ### Usage Examples
224
+
225
+ Explore practical, runnable examples in Jupyter notebooks:
226
+
227
+ - [Basic Evaluation](https://mixaill76.github.io/faster_coco_eval/examples/eval_example.html) - Get started with COCO evaluation
228
+ - [Metric Curves](https://mixaill76.github.io/faster_coco_eval/examples/curve_example.html) - Precision-recall and metric visualization
229
+ - [LVIS Evaluation](https://mixaill76.github.io/faster_coco_eval/examples/lvis_example.html) - Large vocabulary instance segmentation
230
+ - [CrowdPose Evaluation](https://mixaill76.github.io/faster_coco_eval/examples/crowdpose_example.html) - Keypoint detection for crowded scenes
231
+ - [Custom Keypoints](https://mixaill76.github.io/faster_coco_eval/examples/ced_example.html) - Extend to custom keypoint datasets
232
+ - [Annotation Visualization](https://mixaill76.github.io/faster_coco_eval/examples/show_example.html) - Display and analyze annotations
233
+
234
+ ### Detailed Documentation
235
+
236
+ - [Official Wiki](https://github.com/MiXaiLL76/faster_coco_eval/wiki) - Complete API reference and guides
237
+ - [Changelog](https://mixaill76.github.io/faster_coco_eval/history.html) - Latest updates and improvements
238
+ - [API Documentation](https://github.com/MiXaiLL76/faster_coco_eval/wiki) - Detailed function documentation
239
+
240
+ ## ⭐ Star History
241
+
242
+ [![Star History Chart](https://api.star-history.com/svg?repos=MiXaiLL76/faster_coco_eval&type=Date)](https://star-history.com/#MiXaiLL76/faster_coco_eval&Date)
243
+
244
+ ## 📄 License
245
+
246
+ Faster-COCO-Eval is distributed under the Apache 2.0 license. See [LICENSE](https://github.com/MiXaiLL76/faster_coco_eval/blob/main/LICENSE) for more information.
247
+
248
+ ## 📚 Citation
249
+
250
+ If you use Faster-COCO-Eval in your research, please cite:
251
+
252
+ ```bibtex
253
+ @article{faster-coco-eval,
254
+ title = {{Faster-COCO-Eval}: Faster and Enhanced COCO Evaluation Library},
255
+ author = {MiXaiLL76},
256
+ year = {2024}
257
+ }
258
+ ```
259
+
260
+ ## 🤝 Contributing
261
+
262
+ We welcome contributions! Check out our [CONTRIBUTING.md](https://github.com/MiXaiLL76/faster_coco_eval/blob/main/CONTRIBUTING.md) for guidelines on how to get started.
263
+
264
+ ## 🐛 Issues and Support
265
+
266
+ If you encounter any issues or have questions:
267
+
268
+ 1. Check the [Wiki](https://github.com/MiXaiLL76/faster_coco_eval/wiki) for common solutions
269
+ 2. Search existing [issues](https://github.com/MiXaiLL76/faster_coco_eval/issues)
270
+ 3. Open a new issue with detailed information about your problem
271
+
272
+ ## 🚀 Get Started Today
273
+
274
+ ```bash
275
+ pip install faster-coco-eval[extra]
276
+ ```
277
+
278
+ **Replace pycocotools with Faster-COCO-Eval and experience evaluation at lightning speed!**
@@ -0,0 +1,234 @@
1
+ # Faster-COCO-Eval
2
+
3
+ **The Fastest, Most Reliable COCO Evaluation Library for Computer Vision**
4
+
5
+ [![PyPI](https://img.shields.io/pypi/v/faster-coco-eval)](https://pypi.org/project/faster-coco-eval)
6
+ [![PyPI Downloads](https://img.shields.io/pypi/dm/faster-coco-eval.svg?label=PyPI%20downloads)](https://pypi.org/project/faster-coco-eval/)
7
+ [![Conda Version](https://img.shields.io/conda/vn/conda-forge/faster-coco-eval.svg)](https://anaconda.org/conda-forge/faster-coco-eval)
8
+ [![Conda Platforms](https://img.shields.io/conda/pn/conda-forge/faster-coco-eval.svg)](https://anaconda.org/conda-forge/faster-coco-eval)
9
+ [![docs](https://img.shields.io/badge/docs-latest-blue)](https://github.com/MiXaiLL76/faster_coco_eval/wiki)
10
+ [![license](https://img.shields.io/github/license/MiXaiLL76/faster_coco_eval.svg)](https://github.com/MiXaiLL76/faster_coco_eval/blob/main/LICENSE)
11
+ [![CI - Test](https://github.com/MiXaiLL76/faster_coco_eval/actions/workflows/unittest.yml/badge.svg)](https://github.com/MiXaiLL76/faster_coco_eval/actions/workflows/unittest.yml)
12
+
13
+ ## Replace pycocotools with Faster-COCO-Eval Today
14
+
15
+ | Aspect | pycocotools | **faster-coco-eval** |
16
+ | ------------------------------ | ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
17
+ | **Support & Development** | Outdated and not actively maintained. Issues and incompatibilities arise with new releases. | Actively maintained, continuously evolving, and regularly updated with new features and bug fixes. |
18
+ | **Transparency & Reliability** | Lacks comprehensive testing, making updates risky and results less predictable. | Emphasizes extensive test coverage and code quality, ensuring trustworthy and reliable results. |
19
+ | **Performance** | Significantly slower, especially on large datasets or distributed workloads. | Native C++ implementation with measured speedups that depend on the workload and hardware. |
20
+ | **Functionality** | Limited to basic COCO format evaluation. | Offers extended metrics, support for new IoU types, compatibility with more datasets (e.g., CrowdPose, LVIS), advanced visualizations, and seamless integration with PyTorch/TorchVision. |
21
+ | **Ease of Use** | Requires manual installation, often with compilation issues. | Simple `pip install` with pre-built wheels for common CPython/glibc Linux, macOS, and Windows platforms; source builds may be needed elsewhere. |
22
+ | **Visualization** | Basic plotting capabilities. | Advanced error visualization, annotation display, and comprehensive metric analysis tools. |
23
+
24
+ ______________________________________________________________________
25
+
26
+ **Key Benefits of Faster-COCO-Eval:**
27
+
28
+ ✅ **Blazing Fast Performance** - Evaluate large datasets in minutes instead of hours
29
+ ✅ **Reliable & Trusted** - Extensive test coverage ensures consistent, reproducible results
30
+ ✅ **Modern Features** - Support for latest CV tasks, IoU types, and dataset formats
31
+ ✅ **Easy to Use** - Drop-in replacement for pycocotools with enhanced API
32
+ ✅ **Comprehensive Visualization** - Understand your model's performance with beautiful, informative plots
33
+
34
+ **Join thousands of computer vision researchers and engineers who have already switched to Faster-COCO-Eval!**
35
+
36
+ ## Quick Installation
37
+
38
+ ### Option 1: Basic (Drop-in Replacement)
39
+
40
+ Get started in seconds with the core evaluation functionality:
41
+
42
+ ```bash
43
+ pip install faster-coco-eval
44
+ ```
45
+
46
+ ### Option 2: Full Installation (with Visualization)
47
+
48
+ For complete functionality including advanced visualization tools:
49
+
50
+ ```bash
51
+ pip install faster-coco-eval[extra]
52
+ ```
53
+
54
+ ### Option 3: Conda Installation
55
+
56
+ If you use Anaconda/Miniconda:
57
+
58
+ ```bash
59
+ conda install conda-forge::faster-coco-eval
60
+ ```
61
+
62
+ ## 🚀 Quick Start: Drop-in Replacement
63
+
64
+ Replace pycocotools with Faster-COCO-Eval in **2 lines of code**:
65
+
66
+ ```python
67
+ import faster_coco_eval
68
+
69
+ # This single line replaces pycocotools with faster-coco-eval
70
+ faster_coco_eval.init_as_pycocotools()
71
+
72
+ # Now use the familiar pycocotools API
73
+ from pycocotools.coco import COCO
74
+ from pycocotools.cocoeval import COCOeval
75
+
76
+ # Load annotations and predictions
77
+ anno_json = "path/to/annotations.json"
78
+ pred_json = "path/to/predictions.json"
79
+ anno = COCO(str(anno_json)) # Annotations file
80
+ pred = anno.loadRes(str(pred_json)) # Predictions file
81
+
82
+ # Evaluate bounding boxes
83
+ val = COCOeval(anno, pred, "bbox")
84
+ val.evaluate()
85
+ val.accumulate()
86
+ val.summarize()
87
+
88
+ # Or evaluate segmentation masks
89
+ val = COCOeval(anno, pred, "segm")
90
+ val.evaluate()
91
+ val.accumulate()
92
+ val.summarize()
93
+ ```
94
+
95
+ **That's it! Your existing code runs through the native evaluator with no API changes.**
96
+
97
+ ## ⚡ Blazing Fast Performance
98
+
99
+ Faster-COCO-Eval uses a native C++ implementation. The measured result below is one local reference point; real-world speedup varies with dataset size, metric, and hardware.
100
+
101
+ ### Real-World Performance Benchmark
102
+
103
+ Local reference measurement: 100 synthetic images, 15 ground-truth boxes and 100 detections per image, five categories, bbox evaluation, seven timed samples after two warmups. The measurement was run on 2026-08-23 on macOS 26.6.1 arm64, Python 3.10.11, and NumPy 2.2.6. The implementations' `eval["precision"]` arrays matched within the comparison tolerance.
104
+
105
+ | Evaluation Type | Faster-COCO-Eval (sec) | pycocotools (sec) | Speedup |
106
+ | --------------- | ----------------------- | ----------------------- | --------- |
107
+ | Bounding Boxes | 0.053977 (MAD 0.001883) | 0.296960 (MAD 0.001667) | **5.50x** |
108
+
109
+ This local measurement is hardware- and workload-dependent; it is not a universal performance guarantee.
110
+
111
+ ### Colab Examples
112
+
113
+ See the performance in action:
114
+
115
+ - [mmdetection comparison](https://nbviewer.org/github/MiXaiLL76/faster_coco_eval/blob/main/examples/comparison/mmdet/colab_example.ipynb)
116
+ - [ultralytics comparison](https://nbviewer.org/github/MiXaiLL76/faster_coco_eval/blob/main/examples/comparison/ultralytics/colab_example.ipynb)
117
+
118
+ ## 🎯 Powerful Features
119
+
120
+ Faster-COCO-Eval goes beyond basic evaluation with these advanced capabilities:
121
+
122
+ ### Core Evaluation
123
+
124
+ - **Drop-in pycocotools replacement** - No code changes needed
125
+ - **Support for all COCO metric types**: bbox, segm, keypoints
126
+ - **LVIS (Large Vocabulary Instance Segmentation) evaluation**
127
+ - **CrowdPose and custom keypoint datasets**
128
+ - **Multiple IoU types**: standard, rotated, and custom IoU definitions
129
+
130
+ ### Advanced Visualization
131
+
132
+ - **Error visualization**: See where your model is making mistakes
133
+ - **Annotation display**: Visualize ground truth and predictions together
134
+ - **Metric curves**: Precision-recall curves, class-wise performance
135
+ - **Confusion matrices and error analysis**
136
+ - **Interactive Jupyter notebook examples**
137
+
138
+ ### Modern Integrations
139
+
140
+ - **PyTorch/TorchVision compatibility**
141
+ - **Seamless integration with mmdetection and YOLO frameworks**
142
+ - **Distributed evaluation support**
143
+ - **Memory optimized for large datasets**
144
+
145
+ ### Additional Tools
146
+
147
+ - **Boundary evaluation for segmentation tasks**
148
+ - **Custom dataset support**
149
+ - **Comprehensive API documentation**
150
+ - **Extensive test coverage and reliability**
151
+
152
+ ## ✅ Testing & Reliability
153
+
154
+ Faster-COCO-Eval prioritizes **correctness and reliability** through extensive testing:
155
+
156
+ ### Comprehensive Test Suite
157
+
158
+ - **90+ automated tests** covering all functionality
159
+ - **Numerical parity checks** against pycocotools across the supported metrics
160
+ - **Continuous integration** on Python 3.10-3.13
161
+ - **Edge case coverage** including boundary conditions and error handling
162
+
163
+ ### Extensive PyCocoTools Comparison
164
+
165
+ New comprehensive tests validate **numerical parity within a strict tolerance** with pycocotools:
166
+
167
+ - **Object Detection**: Tests with 10-100 images, hundreds to thousands of annotations
168
+ - **Instance Segmentation**: RLE mask encoding and pixel-level IoU validation
169
+ - **Keypoint Detection**: 17-keypoint pose estimation with varied visibility
170
+ - **Multiple Scenarios**: Small/medium/large objects, various confidence distributions
171
+ - **Edge Cases**: Perfect predictions, low-confidence detections, mixed object sizes
172
+
173
+ The comparison suite checks numerical parity between faster_coco_eval and pycocotools, giving you confidence to use this library as a drop-in replacement. See the benchmark above for one measured bbox workload; it is not a universal performance guarantee.
174
+
175
+ See [tests/README.md](tests/README.md) for detailed test documentation.
176
+
177
+ ## 📚 Comprehensive Documentation
178
+
179
+ ### Usage Examples
180
+
181
+ Explore practical, runnable examples in Jupyter notebooks:
182
+
183
+ - [Basic Evaluation](https://mixaill76.github.io/faster_coco_eval/examples/eval_example.html) - Get started with COCO evaluation
184
+ - [Metric Curves](https://mixaill76.github.io/faster_coco_eval/examples/curve_example.html) - Precision-recall and metric visualization
185
+ - [LVIS Evaluation](https://mixaill76.github.io/faster_coco_eval/examples/lvis_example.html) - Large vocabulary instance segmentation
186
+ - [CrowdPose Evaluation](https://mixaill76.github.io/faster_coco_eval/examples/crowdpose_example.html) - Keypoint detection for crowded scenes
187
+ - [Custom Keypoints](https://mixaill76.github.io/faster_coco_eval/examples/ced_example.html) - Extend to custom keypoint datasets
188
+ - [Annotation Visualization](https://mixaill76.github.io/faster_coco_eval/examples/show_example.html) - Display and analyze annotations
189
+
190
+ ### Detailed Documentation
191
+
192
+ - [Official Wiki](https://github.com/MiXaiLL76/faster_coco_eval/wiki) - Complete API reference and guides
193
+ - [Changelog](https://mixaill76.github.io/faster_coco_eval/history.html) - Latest updates and improvements
194
+ - [API Documentation](https://github.com/MiXaiLL76/faster_coco_eval/wiki) - Detailed function documentation
195
+
196
+ ## ⭐ Star History
197
+
198
+ [![Star History Chart](https://api.star-history.com/svg?repos=MiXaiLL76/faster_coco_eval&type=Date)](https://star-history.com/#MiXaiLL76/faster_coco_eval&Date)
199
+
200
+ ## 📄 License
201
+
202
+ Faster-COCO-Eval is distributed under the Apache 2.0 license. See [LICENSE](https://github.com/MiXaiLL76/faster_coco_eval/blob/main/LICENSE) for more information.
203
+
204
+ ## 📚 Citation
205
+
206
+ If you use Faster-COCO-Eval in your research, please cite:
207
+
208
+ ```bibtex
209
+ @article{faster-coco-eval,
210
+ title = {{Faster-COCO-Eval}: Faster and Enhanced COCO Evaluation Library},
211
+ author = {MiXaiLL76},
212
+ year = {2024}
213
+ }
214
+ ```
215
+
216
+ ## 🤝 Contributing
217
+
218
+ We welcome contributions! Check out our [CONTRIBUTING.md](https://github.com/MiXaiLL76/faster_coco_eval/blob/main/CONTRIBUTING.md) for guidelines on how to get started.
219
+
220
+ ## 🐛 Issues and Support
221
+
222
+ If you encounter any issues or have questions:
223
+
224
+ 1. Check the [Wiki](https://github.com/MiXaiLL76/faster_coco_eval/wiki) for common solutions
225
+ 2. Search existing [issues](https://github.com/MiXaiLL76/faster_coco_eval/issues)
226
+ 3. Open a new issue with detailed information about your problem
227
+
228
+ ## 🚀 Get Started Today
229
+
230
+ ```bash
231
+ pip install faster-coco-eval[extra]
232
+ ```
233
+
234
+ **Replace pycocotools with Faster-COCO-Eval and experience evaluation at lightning speed!**