faster-coco-eval 1.7.1__tar.gz → 1.7.2__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 (63) hide show
  1. faster_coco_eval-1.7.2/PKG-INFO +276 -0
  2. faster_coco_eval-1.7.2/README.md +229 -0
  3. {faster_coco_eval-1.7.1 → faster_coco_eval-1.7.2}/faster_coco_eval/core/faster_eval_api.py +91 -24
  4. {faster_coco_eval-1.7.1 → faster_coco_eval-1.7.2}/faster_coco_eval/version.py +1 -1
  5. faster_coco_eval-1.7.2/faster_coco_eval.egg-info/PKG-INFO +276 -0
  6. {faster_coco_eval-1.7.1 → faster_coco_eval-1.7.2}/faster_coco_eval.egg-info/SOURCES.txt +1 -0
  7. {faster_coco_eval-1.7.1 → faster_coco_eval-1.7.2}/tests/test_basic.py +127 -0
  8. faster_coco_eval-1.7.2/tests/test_extensive_pycocotools_comparison.py +567 -0
  9. {faster_coco_eval-1.7.1 → faster_coco_eval-1.7.2}/tests/test_simple_extra.py +57 -0
  10. faster_coco_eval-1.7.1/PKG-INFO +0 -189
  11. faster_coco_eval-1.7.1/README.md +0 -142
  12. faster_coco_eval-1.7.1/faster_coco_eval.egg-info/PKG-INFO +0 -189
  13. {faster_coco_eval-1.7.1 → faster_coco_eval-1.7.2}/LICENSE +0 -0
  14. {faster_coco_eval-1.7.1 → faster_coco_eval-1.7.2}/MANIFEST.in +0 -0
  15. {faster_coco_eval-1.7.1 → faster_coco_eval-1.7.2}/csrc/faster_eval_api/coco_eval/cocoeval.cpp +0 -0
  16. {faster_coco_eval-1.7.1 → faster_coco_eval-1.7.2}/csrc/faster_eval_api/coco_eval/cocoeval.h +0 -0
  17. {faster_coco_eval-1.7.1 → faster_coco_eval-1.7.2}/csrc/faster_eval_api/coco_eval/dataset.cpp +0 -0
  18. {faster_coco_eval-1.7.1 → faster_coco_eval-1.7.2}/csrc/faster_eval_api/coco_eval/dataset.h +0 -0
  19. {faster_coco_eval-1.7.1 → faster_coco_eval-1.7.2}/csrc/faster_eval_api/coco_eval/types.h +0 -0
  20. {faster_coco_eval-1.7.1 → faster_coco_eval-1.7.2}/csrc/faster_eval_api/faster_eval_api.cpp +0 -0
  21. {faster_coco_eval-1.7.1 → faster_coco_eval-1.7.2}/csrc/mask_api/mask_api.cpp +0 -0
  22. {faster_coco_eval-1.7.1 → faster_coco_eval-1.7.2}/csrc/mask_api/src/mask.cpp +0 -0
  23. {faster_coco_eval-1.7.1 → faster_coco_eval-1.7.2}/csrc/mask_api/src/mask.h +0 -0
  24. {faster_coco_eval-1.7.1 → faster_coco_eval-1.7.2}/csrc/mask_api/src/rle.cpp +0 -0
  25. {faster_coco_eval-1.7.1 → faster_coco_eval-1.7.2}/faster_coco_eval/__init__.py +0 -0
  26. {faster_coco_eval-1.7.1 → faster_coco_eval-1.7.2}/faster_coco_eval/core/__init__.py +0 -0
  27. {faster_coco_eval-1.7.1 → faster_coco_eval-1.7.2}/faster_coco_eval/core/coco.py +0 -0
  28. {faster_coco_eval-1.7.1 → faster_coco_eval-1.7.2}/faster_coco_eval/core/cocoeval.py +0 -0
  29. {faster_coco_eval-1.7.1 → faster_coco_eval-1.7.2}/faster_coco_eval/core/mask.py +0 -0
  30. {faster_coco_eval-1.7.1 → faster_coco_eval-1.7.2}/faster_coco_eval/extra/__init__.py +0 -0
  31. {faster_coco_eval-1.7.1 → faster_coco_eval-1.7.2}/faster_coco_eval/extra/curves.py +0 -0
  32. {faster_coco_eval-1.7.1 → faster_coco_eval-1.7.2}/faster_coco_eval/extra/display.py +0 -0
  33. {faster_coco_eval-1.7.1 → faster_coco_eval-1.7.2}/faster_coco_eval/extra/draw.py +0 -0
  34. {faster_coco_eval-1.7.1 → faster_coco_eval-1.7.2}/faster_coco_eval/extra/extra.py +0 -0
  35. {faster_coco_eval-1.7.1 → faster_coco_eval-1.7.2}/faster_coco_eval/extra/utils.py +0 -0
  36. {faster_coco_eval-1.7.1 → faster_coco_eval-1.7.2}/faster_coco_eval/utils/__init__.py +0 -0
  37. {faster_coco_eval-1.7.1 → faster_coco_eval-1.7.2}/faster_coco_eval/utils/pytorch/__init__.py +0 -0
  38. {faster_coco_eval-1.7.1 → faster_coco_eval-1.7.2}/faster_coco_eval/utils/pytorch/coco_dataset.py +0 -0
  39. {faster_coco_eval-1.7.1 → faster_coco_eval-1.7.2}/faster_coco_eval/utils/pytorch/coco_eval.py +0 -0
  40. {faster_coco_eval-1.7.1 → faster_coco_eval-1.7.2}/faster_coco_eval.egg-info/dependency_links.txt +0 -0
  41. {faster_coco_eval-1.7.1 → faster_coco_eval-1.7.2}/faster_coco_eval.egg-info/requires.txt +0 -0
  42. {faster_coco_eval-1.7.1 → faster_coco_eval-1.7.2}/faster_coco_eval.egg-info/top_level.txt +0 -0
  43. {faster_coco_eval-1.7.1 → faster_coco_eval-1.7.2}/pyproject.toml +0 -0
  44. {faster_coco_eval-1.7.1 → faster_coco_eval-1.7.2}/requirements/docs.txt +0 -0
  45. {faster_coco_eval-1.7.1 → faster_coco_eval-1.7.2}/requirements/extra.txt +0 -0
  46. {faster_coco_eval-1.7.1 → faster_coco_eval-1.7.2}/requirements/runtime.txt +0 -0
  47. {faster_coco_eval-1.7.1 → faster_coco_eval-1.7.2}/requirements/tests.txt +0 -0
  48. {faster_coco_eval-1.7.1 → faster_coco_eval-1.7.2}/setup.cfg +0 -0
  49. {faster_coco_eval-1.7.1 → faster_coco_eval-1.7.2}/setup.py +0 -0
  50. {faster_coco_eval-1.7.1 → faster_coco_eval-1.7.2}/tests/test_boundary.py +0 -0
  51. {faster_coco_eval-1.7.1 → faster_coco_eval-1.7.2}/tests/test_coco_metric.py +0 -0
  52. {faster_coco_eval-1.7.1 → faster_coco_eval-1.7.2}/tests/test_cocoapi_fake_data.py +0 -0
  53. {faster_coco_eval-1.7.1 → faster_coco_eval-1.7.2}/tests/test_crowdpose.py +0 -0
  54. {faster_coco_eval-1.7.1 → faster_coco_eval-1.7.2}/tests/test_dataset.py +0 -0
  55. {faster_coco_eval-1.7.1 → faster_coco_eval-1.7.2}/tests/test_extra_draw.py +0 -0
  56. {faster_coco_eval-1.7.1 → faster_coco_eval-1.7.2}/tests/test_extra_utils.py +0 -0
  57. {faster_coco_eval-1.7.1 → faster_coco_eval-1.7.2}/tests/test_init_pycocotools.py +0 -0
  58. {faster_coco_eval-1.7.1 → faster_coco_eval-1.7.2}/tests/test_keypoints.py +0 -0
  59. {faster_coco_eval-1.7.1 → faster_coco_eval-1.7.2}/tests/test_lvis_metric.py +0 -0
  60. {faster_coco_eval-1.7.1 → faster_coco_eval-1.7.2}/tests/test_mask_api.py +0 -0
  61. {faster_coco_eval-1.7.1 → faster_coco_eval-1.7.2}/tests/test_ranges.py +0 -0
  62. {faster_coco_eval-1.7.1 → faster_coco_eval-1.7.2}/tests/test_torchmetrics.py +0 -0
  63. {faster_coco_eval-1.7.1 → faster_coco_eval-1.7.2}/tests/test_world_evalutor.py +0 -0
@@ -0,0 +1,276 @@
1
+ Metadata-Version: 2.4
2
+ Name: faster-coco-eval
3
+ Version: 1.7.2
4
+ Summary: Faster interpretation of the original COCOEval
5
+ Home-page: https://github.com/MiXaiLL76/faster_coco_eval
6
+ Author: MiXaiLL76
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.7
12
+ Classifier: Programming Language :: Python :: 3.8
13
+ Classifier: Programming Language :: Python :: 3.9
14
+ Classifier: Programming Language :: Python :: 3.10
15
+ Classifier: Programming Language :: Python :: 3.11
16
+ Classifier: Programming Language :: Python :: 3.12
17
+ Classifier: Programming Language :: Python :: 3.13
18
+ Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
19
+ Requires-Python: >=3.7
20
+ Description-Content-Type: text/markdown
21
+ License-File: LICENSE
22
+ Requires-Dist: numpy
23
+ Provides-Extra: extra
24
+ Requires-Dist: numpy; extra == "extra"
25
+ Requires-Dist: opencv-python-headless; extra == "extra"
26
+ Requires-Dist: pandas; extra == "extra"
27
+ Requires-Dist: plotly; extra == "extra"
28
+ Requires-Dist: Pillow; extra == "extra"
29
+ Provides-Extra: tests
30
+ Requires-Dist: numpy; extra == "tests"
31
+ Requires-Dist: numpy; extra == "tests"
32
+ Requires-Dist: pycocotools; python_version < "3.13" and extra == "tests"
33
+ Requires-Dist: pytest; extra == "tests"
34
+ Requires-Dist: pytest-cov; extra == "tests"
35
+ Requires-Dist: parameterized; extra == "tests"
36
+ Dynamic: author
37
+ Dynamic: author-email
38
+ Dynamic: classifier
39
+ Dynamic: description
40
+ Dynamic: description-content-type
41
+ Dynamic: home-page
42
+ Dynamic: license-file
43
+ Dynamic: provides-extra
44
+ Dynamic: requires-dist
45
+ Dynamic: requires-python
46
+ Dynamic: summary
47
+
48
+ # Faster-COCO-Eval
49
+
50
+ **The Fastest, Most Reliable COCO Evaluation Library for Computer Vision**
51
+
52
+ [![PyPI](https://img.shields.io/pypi/v/faster-coco-eval)](https://pypi.org/project/faster-coco-eval)
53
+ [![PyPI Downloads](https://img.shields.io/pypi/dm/faster-coco-eval.svg?label=PyPI%20downloads)](https://pypi.org/project/faster-coco-eval/)
54
+ [![Conda Version](https://img.shields.io/conda/vn/conda-forge/faster-coco-eval.svg)](https://anaconda.org/conda-forge/faster-coco-eval)
55
+ [![Conda Platforms](https://img.shields.io/conda/pn/conda-forge/faster-coco-eval.svg)](https://anaconda.org/conda-forge/faster-coco-eval)
56
+ [![docs](https://img.shields.io/badge/docs-latest-blue)](https://github.com/MiXaiLL76/faster_coco_eval/wiki)
57
+ [![license](https://img.shields.io/github/license/MiXaiLL76/faster_coco_eval.svg)](https://github.com/MiXaiLL76/faster_coco_eval/blob/main/LICENSE)
58
+ [![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)
59
+
60
+ ## Replace pycocotools with Faster-COCO-Eval Today
61
+
62
+ | Aspect | pycocotools | **faster-coco-eval** |
63
+ | ------------------------------ | ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
64
+ | **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. |
65
+ | **Transparency & Reliability** | Lacks comprehensive testing, making updates risky and results less predictable. | Emphasizes extensive test coverage and code quality, ensuring trustworthy and reliable results. |
66
+ | **Performance** | Significantly slower, especially on large datasets or distributed workloads. | **3-4x faster** due to C++ optimizations and modern algorithms. |
67
+ | **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. |
68
+ | **Ease of Use** | Requires manual installation, often with compilation issues. | Simple `pip install`, no compilation required, and drop-in replacement API. |
69
+ | **Visualization** | Basic plotting capabilities. | Advanced error visualization, annotation display, and comprehensive metric analysis tools. |
70
+
71
+ ---
72
+
73
+ **Key Benefits of Faster-COCO-Eval:**
74
+
75
+ ✅ **Blazing Fast Performance** - Evaluate large datasets in minutes instead of hours
76
+ ✅ **Reliable & Trusted** - Extensive test coverage ensures consistent, reproducible results
77
+ ✅ **Modern Features** - Support for latest CV tasks, IoU types, and dataset formats
78
+ ✅ **Easy to Use** - Drop-in replacement for pycocotools with enhanced API
79
+ ✅ **Comprehensive Visualization** - Understand your model's performance with beautiful, informative plots
80
+
81
+ **Join thousands of computer vision researchers and engineers who have already switched to Faster-COCO-Eval!**
82
+
83
+ ## Quick Installation
84
+
85
+ ### Option 1: Basic (Drop-in Replacement)
86
+
87
+ Get started in seconds with the core evaluation functionality:
88
+
89
+ ```bash
90
+ pip install faster-coco-eval
91
+ ```
92
+
93
+ ### Option 2: Full Installation (with Visualization)
94
+
95
+ For complete functionality including advanced visualization tools:
96
+
97
+ ```bash
98
+ pip install faster-coco-eval[extra]
99
+ ```
100
+
101
+ ### Option 3: Conda Installation
102
+
103
+ If you use Anaconda/Miniconda:
104
+
105
+ ```bash
106
+ conda install conda-forge::faster-coco-eval
107
+ ```
108
+
109
+ ## 🚀 Quick Start: Drop-in Replacement
110
+
111
+ Replace pycocotools with Faster-COCO-Eval in **2 lines of code**:
112
+
113
+ ```python
114
+ import faster_coco_eval
115
+
116
+ # This single line replaces pycocotools with faster-coco-eval
117
+ faster_coco_eval.init_as_pycocotools()
118
+
119
+ # Now use the familiar pycocotools API
120
+ from pycocotools.coco import COCO
121
+ from pycocotools.cocoeval import COCOeval
122
+
123
+ # Load annotations and predictions
124
+ anno = COCO(str(anno_json)) # Annotations file
125
+ pred = anno.loadRes(str(pred_json)) # Predictions file
126
+
127
+ # Evaluate bounding boxes
128
+ val = COCOeval(anno, pred, "bbox")
129
+ val.evaluate()
130
+ val.accumulate()
131
+ val.summarize()
132
+
133
+ # Or evaluate segmentation masks
134
+ val = COCOeval(anno, pred, "segm")
135
+ val.evaluate()
136
+ val.accumulate()
137
+ val.summarize()
138
+ ```
139
+
140
+ **That's it! Your existing code will run 3-4x faster with no changes.**
141
+
142
+ ## ⚡ Blazing Fast Performance
143
+
144
+ Faster-COCO-Eval is built on top of a highly optimized C++ implementation, providing **3-4x faster evaluation** than the standard pycocotools.
145
+
146
+ ### Real-World Performance Benchmark
147
+
148
+ Tested on 5000 images from the COCO validation dataset using mmdetection framework:
149
+
150
+ | Evaluation Type | Faster-COCO-Eval (sec) | pycocotools (sec) | Speedup |
151
+ |-----------------|------------------------|-------------------|---------|
152
+ | Bounding Boxes | 5.812 | 22.72 | **3.9x** |
153
+ | Segmentation | 7.413 | 24.434 | **3.3x** |
154
+
155
+ **For large datasets, this means hours saved on evaluation time!**
156
+
157
+ ### Colab Examples
158
+
159
+ See the performance in action:
160
+
161
+ - [mmdetection comparison](https://nbviewer.org/github/MiXaiLL76/faster_coco_eval/blob/main/examples/comparison/mmdet/colab_example.ipynb)
162
+ - [ultralytics comparison](https://nbviewer.org/github/MiXaiLL76/faster_coco_eval/blob/main/examples/comparison/ultralytics/colab_example.ipynb)
163
+
164
+ ## 🎯 Powerful Features
165
+
166
+ Faster-COCO-Eval goes beyond basic evaluation with these advanced capabilities:
167
+
168
+ ### Core Evaluation
169
+ - **Drop-in pycocotools replacement** - No code changes needed
170
+ - **Support for all COCO metric types**: bbox, segm, keypoints
171
+ - **LVIS (Large Vocabulary Instance Segmentation) evaluation**
172
+ - **CrowdPose and custom keypoint datasets**
173
+ - **Multiple IoU types**: standard, rotated, and custom IoU definitions
174
+
175
+ ### Advanced Visualization
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
+ - **PyTorch/TorchVision compatibility**
184
+ - **Seamless integration with mmdetection, Detectron2, and YOLO frameworks**
185
+ - **Distributed evaluation support**
186
+ - **Memory optimized for large datasets**
187
+
188
+ ### Additional Tools
189
+ - **Boundary evaluation for segmentation tasks**
190
+ - **Custom dataset support**
191
+ - **Comprehensive API documentation**
192
+ - **Extensive test coverage and reliability**
193
+
194
+ ## ✅ Testing & Reliability
195
+
196
+ Faster-COCO-Eval prioritizes **correctness and reliability** through extensive testing:
197
+
198
+ ### Comprehensive Test Suite
199
+
200
+ - **90+ automated tests** covering all functionality
201
+ - **Exact equality validation** against pycocotools across all metrics
202
+ - **Continuous integration** on Python 3.9-3.13
203
+ - **Edge case coverage** including boundary conditions and error handling
204
+
205
+ ### Extensive PyCocoTools Comparison
206
+
207
+ New comprehensive tests validate **exact numerical equality** with pycocotools:
208
+
209
+ - **Object Detection**: Tests with 10-100 images, hundreds to thousands of annotations
210
+ - **Instance Segmentation**: RLE mask encoding and pixel-level IoU validation
211
+ - **Keypoint Detection**: 17-keypoint pose estimation with varied visibility
212
+ - **Multiple Scenarios**: Small/medium/large objects, various confidence distributions
213
+ - **Edge Cases**: Perfect predictions, low-confidence detections, mixed object sizes
214
+
215
+ All tests confirm **bit-for-bit identical results** between faster_coco_eval and pycocotools, giving you confidence to use this library as a drop-in replacement while gaining 3-4x performance improvements.
216
+
217
+ See [tests/README.md](tests/README.md) for detailed test documentation.
218
+
219
+ ## 📚 Comprehensive Documentation
220
+
221
+ ### Usage Examples
222
+
223
+ Explore practical, runnable examples in Jupyter notebooks:
224
+
225
+ - [Basic Evaluation](https://mixaill76.github.io/faster_coco_eval/examples/eval_example.html) - Get started with COCO evaluation
226
+ - [Metric Curves](https://mixaill76.github.io/faster_coco_eval/examples/curve_example.html) - Precision-recall and metric visualization
227
+ - [LVIS Evaluation](https://mixaill76.github.io/faster_coco_eval/examples/lvis_example.html) - Large vocabulary instance segmentation
228
+ - [CrowdPose Evaluation](https://mixaill76.github.io/faster_coco_eval/examples/crowdpose_example.html) - Keypoint detection for crowded scenes
229
+ - [Custom Keypoints](https://mixaill76.github.io/faster_coco_eval/examples/ced_example.html) - Extend to custom keypoint datasets
230
+ - [Annotation Visualization](https://mixaill76.github.io/faster_coco_eval/examples/show_example.html) - Display and analyze annotations
231
+
232
+ ### Detailed Documentation
233
+
234
+ - [Official Wiki](https://github.com/MiXaiLL76/faster_coco_eval/wiki) - Complete API reference and guides
235
+ - [Changelog](https://mixaill76.github.io/faster_coco_eval/history.html) - Latest updates and improvements
236
+ - [API Documentation](https://github.com/MiXaiLL76/faster_coco_eval/wiki) - Detailed function documentation
237
+
238
+ ## ⭐ Star History
239
+
240
+ [![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)
241
+
242
+ ## 📄 License
243
+
244
+ 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.
245
+
246
+ ## 📚 Citation
247
+
248
+ If you use Faster-COCO-Eval in your research, please cite:
249
+
250
+ ```bibtex
251
+ @article{faster-coco-eval,
252
+ title = {{Faster-COCO-Eval}: Faster and Enhanced COCO Evaluation Library},
253
+ author = {MiXaiLL76},
254
+ year = {2024}
255
+ }
256
+ ```
257
+
258
+ ## 🤝 Contributing
259
+
260
+ 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.
261
+
262
+ ## 🐛 Issues and Support
263
+
264
+ If you encounter any issues or have questions:
265
+
266
+ 1. Check the [Wiki](https://github.com/MiXaiLL76/faster_coco_eval/wiki) for common solutions
267
+ 2. Search existing [issues](https://github.com/MiXaiLL76/faster_coco_eval/issues)
268
+ 3. Open a new issue with detailed information about your problem
269
+
270
+ ## 🚀 Get Started Today
271
+
272
+ ```bash
273
+ pip install faster-coco-eval[extra]
274
+ ```
275
+
276
+ **Replace pycocotools with Faster-COCO-Eval and experience evaluation at lightning speed!**
@@ -0,0 +1,229 @@
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. | **3-4x faster** due to C++ optimizations and modern algorithms. |
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`, no compilation required, and drop-in replacement API. |
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 = COCO(str(anno_json)) # Annotations file
78
+ pred = anno.loadRes(str(pred_json)) # Predictions file
79
+
80
+ # Evaluate bounding boxes
81
+ val = COCOeval(anno, pred, "bbox")
82
+ val.evaluate()
83
+ val.accumulate()
84
+ val.summarize()
85
+
86
+ # Or evaluate segmentation masks
87
+ val = COCOeval(anno, pred, "segm")
88
+ val.evaluate()
89
+ val.accumulate()
90
+ val.summarize()
91
+ ```
92
+
93
+ **That's it! Your existing code will run 3-4x faster with no changes.**
94
+
95
+ ## ⚡ Blazing Fast Performance
96
+
97
+ Faster-COCO-Eval is built on top of a highly optimized C++ implementation, providing **3-4x faster evaluation** than the standard pycocotools.
98
+
99
+ ### Real-World Performance Benchmark
100
+
101
+ Tested on 5000 images from the COCO validation dataset using mmdetection framework:
102
+
103
+ | Evaluation Type | Faster-COCO-Eval (sec) | pycocotools (sec) | Speedup |
104
+ |-----------------|------------------------|-------------------|---------|
105
+ | Bounding Boxes | 5.812 | 22.72 | **3.9x** |
106
+ | Segmentation | 7.413 | 24.434 | **3.3x** |
107
+
108
+ **For large datasets, this means hours saved on evaluation time!**
109
+
110
+ ### Colab Examples
111
+
112
+ See the performance in action:
113
+
114
+ - [mmdetection comparison](https://nbviewer.org/github/MiXaiLL76/faster_coco_eval/blob/main/examples/comparison/mmdet/colab_example.ipynb)
115
+ - [ultralytics comparison](https://nbviewer.org/github/MiXaiLL76/faster_coco_eval/blob/main/examples/comparison/ultralytics/colab_example.ipynb)
116
+
117
+ ## 🎯 Powerful Features
118
+
119
+ Faster-COCO-Eval goes beyond basic evaluation with these advanced capabilities:
120
+
121
+ ### Core Evaluation
122
+ - **Drop-in pycocotools replacement** - No code changes needed
123
+ - **Support for all COCO metric types**: bbox, segm, keypoints
124
+ - **LVIS (Large Vocabulary Instance Segmentation) evaluation**
125
+ - **CrowdPose and custom keypoint datasets**
126
+ - **Multiple IoU types**: standard, rotated, and custom IoU definitions
127
+
128
+ ### Advanced Visualization
129
+ - **Error visualization**: See where your model is making mistakes
130
+ - **Annotation display**: Visualize ground truth and predictions together
131
+ - **Metric curves**: Precision-recall curves, class-wise performance
132
+ - **Confusion matrices and error analysis**
133
+ - **Interactive Jupyter notebook examples**
134
+
135
+ ### Modern Integrations
136
+ - **PyTorch/TorchVision compatibility**
137
+ - **Seamless integration with mmdetection, Detectron2, and YOLO frameworks**
138
+ - **Distributed evaluation support**
139
+ - **Memory optimized for large datasets**
140
+
141
+ ### Additional Tools
142
+ - **Boundary evaluation for segmentation tasks**
143
+ - **Custom dataset support**
144
+ - **Comprehensive API documentation**
145
+ - **Extensive test coverage and reliability**
146
+
147
+ ## ✅ Testing & Reliability
148
+
149
+ Faster-COCO-Eval prioritizes **correctness and reliability** through extensive testing:
150
+
151
+ ### Comprehensive Test Suite
152
+
153
+ - **90+ automated tests** covering all functionality
154
+ - **Exact equality validation** against pycocotools across all metrics
155
+ - **Continuous integration** on Python 3.9-3.13
156
+ - **Edge case coverage** including boundary conditions and error handling
157
+
158
+ ### Extensive PyCocoTools Comparison
159
+
160
+ New comprehensive tests validate **exact numerical equality** with pycocotools:
161
+
162
+ - **Object Detection**: Tests with 10-100 images, hundreds to thousands of annotations
163
+ - **Instance Segmentation**: RLE mask encoding and pixel-level IoU validation
164
+ - **Keypoint Detection**: 17-keypoint pose estimation with varied visibility
165
+ - **Multiple Scenarios**: Small/medium/large objects, various confidence distributions
166
+ - **Edge Cases**: Perfect predictions, low-confidence detections, mixed object sizes
167
+
168
+ All tests confirm **bit-for-bit identical results** between faster_coco_eval and pycocotools, giving you confidence to use this library as a drop-in replacement while gaining 3-4x performance improvements.
169
+
170
+ See [tests/README.md](tests/README.md) for detailed test documentation.
171
+
172
+ ## 📚 Comprehensive Documentation
173
+
174
+ ### Usage Examples
175
+
176
+ Explore practical, runnable examples in Jupyter notebooks:
177
+
178
+ - [Basic Evaluation](https://mixaill76.github.io/faster_coco_eval/examples/eval_example.html) - Get started with COCO evaluation
179
+ - [Metric Curves](https://mixaill76.github.io/faster_coco_eval/examples/curve_example.html) - Precision-recall and metric visualization
180
+ - [LVIS Evaluation](https://mixaill76.github.io/faster_coco_eval/examples/lvis_example.html) - Large vocabulary instance segmentation
181
+ - [CrowdPose Evaluation](https://mixaill76.github.io/faster_coco_eval/examples/crowdpose_example.html) - Keypoint detection for crowded scenes
182
+ - [Custom Keypoints](https://mixaill76.github.io/faster_coco_eval/examples/ced_example.html) - Extend to custom keypoint datasets
183
+ - [Annotation Visualization](https://mixaill76.github.io/faster_coco_eval/examples/show_example.html) - Display and analyze annotations
184
+
185
+ ### Detailed Documentation
186
+
187
+ - [Official Wiki](https://github.com/MiXaiLL76/faster_coco_eval/wiki) - Complete API reference and guides
188
+ - [Changelog](https://mixaill76.github.io/faster_coco_eval/history.html) - Latest updates and improvements
189
+ - [API Documentation](https://github.com/MiXaiLL76/faster_coco_eval/wiki) - Detailed function documentation
190
+
191
+ ## ⭐ Star History
192
+
193
+ [![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)
194
+
195
+ ## 📄 License
196
+
197
+ 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.
198
+
199
+ ## 📚 Citation
200
+
201
+ If you use Faster-COCO-Eval in your research, please cite:
202
+
203
+ ```bibtex
204
+ @article{faster-coco-eval,
205
+ title = {{Faster-COCO-Eval}: Faster and Enhanced COCO Evaluation Library},
206
+ author = {MiXaiLL76},
207
+ year = {2024}
208
+ }
209
+ ```
210
+
211
+ ## 🤝 Contributing
212
+
213
+ 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.
214
+
215
+ ## 🐛 Issues and Support
216
+
217
+ If you encounter any issues or have questions:
218
+
219
+ 1. Check the [Wiki](https://github.com/MiXaiLL76/faster_coco_eval/wiki) for common solutions
220
+ 2. Search existing [issues](https://github.com/MiXaiLL76/faster_coco_eval/issues)
221
+ 3. Open a new issue with detailed information about your problem
222
+
223
+ ## 🚀 Get Started Today
224
+
225
+ ```bash
226
+ pip install faster-coco-eval[extra]
227
+ ```
228
+
229
+ **Replace pycocotools with Faster-COCO-Eval and experience evaluation at lightning speed!**
@@ -229,33 +229,99 @@ class COCOeval_faster(COCOevalBase):
229
229
  Notes:
230
230
  - Uses COCO-style evaluation results (precision and scores arrays).
231
231
  - Filters out classes with NaN results in any metric.
232
- - The best F1-score across recall thresholds is used to select macro precision and recall.
232
+ - The best F1-score across confidence thresholds is used to select macro precision and recall.
233
+ - Precision and recall are computed from actual (non-interpolated) detection data to avoid
234
+ over-estimating precision when false positives exist below the recall ceiling.
233
235
  """
234
- # Extract IoU and recall thresholds from parameters
235
- iou_thrs, rec_thrs = self.params.iouThrs, self.params.recThrs
236
+ # Extract IoU thresholds from parameters
237
+ iou_thrs = self.params.iouThrs
236
238
 
237
239
  # Indices for IoU=0.50, first area, and last max dets
238
- iou50_idx, area_idx, maxdet_idx = (np.argwhere(np.isclose(iou_thrs, 0.50)).item(), 0, -1)
240
+ _iou50_hits = np.where(np.isclose(iou_thrs, 0.50))[0]
241
+ if len(_iou50_hits) == 0:
242
+ raise ValueError(
243
+ "extended_metrics requires IoU threshold 0.50, "
244
+ f"but it is not present in params.iouThrs={iou_thrs.tolist()}."
245
+ )
246
+ iou50_idx, area_idx, maxdet_idx = (int(_iou50_hits[0]), 0, -1)
239
247
  P = self.eval["precision"]
240
- S = self.eval["scores"]
241
-
242
- # Get precision for IoU=0.50, area, and max dets
243
- prec_raw = P[iou50_idx, :, :, area_idx, maxdet_idx]
244
- prec = prec_raw.copy().astype(float)
245
- prec[prec < 0] = np.nan
246
-
247
- # Compute F1 score for each class and recall threshold
248
- f1_cls = 2 * prec * rec_thrs[:, None] / (prec + rec_thrs[:, None])
249
- f1_macro = np.nanmean(f1_cls, axis=1)
250
- best_j = int(f1_macro.argmax())
251
248
 
252
- # Macro precision and recall at the best F1 score
253
- macro_precision = float(np.nanmean(prec[best_j]))
254
- macro_recall = float(rec_thrs[best_j])
249
+ # --- Compute actual (non-interpolated) precision/recall by sweeping confidence thresholds ---
250
+ # Build set of TP detection IDs: detections matched to a GT with actual IoU >= 0.50
251
+ tp_dt_ids = {
252
+ int(k.split("_")[0])
253
+ for k, iou in self.eval["matched"].items()
254
+ if iou >= 0.5
255
+ }
255
256
 
256
- # Score vector for the best recall threshold
257
- score_vec = S[iou50_idx, best_j, :, area_idx, maxdet_idx].astype(float)
258
- score_vec[prec_raw[best_j] < 0] = np.nan
257
+ cat_ids_eval = self.params.catIds if self.params.useCats else list(
258
+ {ann["category_id"] for ann in self.cocoDt.anns.values()}
259
+ )
260
+
261
+ # Per-class: build sorted (descending) score arrays and cumulative TP counts
262
+ class_arrays = {} # cat_id -> (scores_desc, cum_tp)
263
+ class_items: dict = {}
264
+ for dt_id, ann in self.cocoDt.anns.items():
265
+ cat_id = ann["category_id"]
266
+ class_items.setdefault(cat_id, []).append((float(ann["score"]), int(dt_id in tp_dt_ids)))
267
+ for cat_id, items in class_items.items():
268
+ items.sort(key=lambda x: -x[0])
269
+ scores = np.array([s for s, _ in items])
270
+ is_tp = np.array([t for _, t in items])
271
+ class_arrays[cat_id] = (scores, np.cumsum(is_tp))
272
+
273
+ # Total non-crowd GTs per class
274
+ total_gts: dict = {}
275
+ for ann in self.cocoGt.anns.values():
276
+ if not ann.get("iscrowd", 0):
277
+ total_gts[ann["category_id"]] = total_gts.get(ann["category_id"], 0) + 1
278
+
279
+ # Candidate thresholds: all unique detection scores, ascending
280
+ # Iterating ascending ensures the FIRST threshold reaching the maximum macro-F1
281
+ # is the most inclusive one (lowest confidence → highest recall).
282
+ all_thresholds = sorted({float(ann["score"]) for ann in self.cocoDt.anns.values()})
283
+
284
+ best_macro_f1 = -np.inf
285
+ # best_class_metrics is populated inside the loop when a better macro-F1 is found.
286
+ # If no threshold produces valid metrics (e.g., no detections at all), it stays
287
+ # empty and per-class precision/recall will be reported as NaN (and filtered out).
288
+ best_class_metrics: dict = {}
289
+ macro_precision = 0.0
290
+ macro_recall = 0.0
291
+
292
+ for threshold in all_thresholds:
293
+ cat_precs, cat_recs, cat_f1s, cat_ids_valid = [], [], [], []
294
+ for cat_id in cat_ids_eval:
295
+ n_gt = total_gts.get(cat_id, 0)
296
+ if n_gt == 0:
297
+ continue
298
+ if cat_id in class_arrays:
299
+ scores, cum_tp = class_arrays[cat_id]
300
+ # Count detections with score >= threshold using binary search
301
+ n_above = int(np.searchsorted(-scores, -threshold, side="right"))
302
+ tp = int(cum_tp[n_above - 1]) if n_above > 0 else 0
303
+ prec = tp / n_above if n_above > 0 else 0.0
304
+ rec = tp / n_gt
305
+ else:
306
+ prec, rec = 0.0, 0.0
307
+ f1 = 2.0 * prec * rec / (prec + rec) if (prec + rec) > 0.0 else 0.0
308
+ cat_precs.append(prec)
309
+ cat_recs.append(rec)
310
+ cat_f1s.append(f1)
311
+ cat_ids_valid.append(cat_id)
312
+
313
+ if not cat_f1s:
314
+ continue
315
+
316
+ macro_f1 = float(np.mean(cat_f1s))
317
+ if macro_f1 > best_macro_f1:
318
+ best_macro_f1 = macro_f1
319
+ macro_precision = float(np.mean(cat_precs))
320
+ macro_recall = float(np.mean(cat_recs))
321
+ best_class_metrics = {
322
+ cid: {"precision": p, "recall": r}
323
+ for cid, p, r in zip(cat_ids_valid, cat_precs, cat_recs)
324
+ }
259
325
 
260
326
  per_class = []
261
327
  if self.params.useCats:
@@ -263,7 +329,7 @@ class COCOeval_faster(COCOevalBase):
263
329
  cat_ids = self.params.catIds
264
330
  cat_id_to_name = {c["id"]: c["name"] for c in self.cocoGt.loadCats(cat_ids)}
265
331
  for k, cid in enumerate(cat_ids):
266
- # Precision per category
332
+ # AP per category (unchanged: uses interpolated P for mAP, which is correct)
267
333
  p_slice = P[:, :, k, area_idx, maxdet_idx]
268
334
  valid = p_slice > -1
269
335
  ap_50_95 = float(p_slice[valid].mean()) if valid.any() else float("nan")
@@ -273,8 +339,9 @@ class COCOeval_faster(COCOevalBase):
273
339
  else float("nan")
274
340
  )
275
341
 
276
- pc = float(prec[best_j, k]) if prec_raw[best_j, k] > -1 else float("nan")
277
- rc = macro_recall
342
+ class_m = best_class_metrics.get(int(cid), {})
343
+ pc = class_m.get("precision", float("nan"))
344
+ rc = class_m.get("recall", float("nan"))
278
345
 
279
346
  # Filter out dataset class if any metric is NaN
280
347
  if np.isnan(ap_50_95) or np.isnan(ap_50) or np.isnan(pc) or np.isnan(rc):
@@ -1,2 +1,2 @@
1
- __version__ = "1.7.1"
1
+ __version__ = "1.7.2"
2
2
  __author__ = "MiXaiLL76"