Registry / ai-ml / faster-coco-eval

faster-coco-eval

JSON →
library1.7.2pypypi✓ verified 87d ago

Faster-COCO-Eval is a Python library that provides a highly optimized C++ implementation for COCO evaluation, offering significantly faster performance (3-4x speedup) compared to the standard pycocotools. It acts as a drop-in replacement, providing extended metrics, support for new IoU types, compatibility with various datasets (e.g., CrowdPose, LVIS), and advanced visualization tools. The library is actively maintained and continuously updated with new features and bug fixes, currently at version 1.7.2.

pip install faster-coco-eval
INSTALL
IMPORT
SIG · FASTER-COCO-EVAL
F
faster-coco-eval
ai-mlpythonv1.7.2
Install
8.0s avg
Import
351ms
Disk
89MB
Pass rate
5/ 10
Env Coverage5 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v1.7.2 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.940 runs
build_error
glibc
py 3.103.940 runs
installs and imports cleanly · install 8.0s · import 0.351s · 87MB
89MB installed
● package 89MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

COCO
from faster_coco_eval import COCO
Main class for loading COCO annotations.
COCOeval
from faster_coco_eval import COCOeval
Standard COCO evaluation class (faster implementation).
COCOeval_faster
from faster_coco_eval import COCOeval_faster
Explicitly use the faster evaluation class.
init_as_pycocotools
import faster_coco_eval faster_coco_eval.init_as_pycocotools()
Activates faster-coco-eval as a drop-in replacement for pycocotools, allowing existing pycocotools import statements to use the faster backend.
Curves
from faster_coco_eval.extra import Curves
Utility for plotting precision-recall and other metric curves.

This quickstart demonstrates two ways to use `faster-coco-eval`. The first method utilizes `faster_coco_eval.init_as_pycocotools()` to replace `pycocotools` imports with the faster implementation, allowing for seamless integration into existing code. The second method shows direct usage of `faster_coco_eval`'s `COCO` and `COCOeval_faster` classes. You will need COCO-formatted ground truth annotation and prediction JSON files.

import os import faster_coco_eval # Option 1: Use faster_coco_eval as a drop-in replacement for pycocotools faster_coco_eval.init_as_pycocotools() from pycocotools.coco import COCO from pycocotools.cocoeval import COCOeval # Create dummy COCO JSON files (replace with your actual paths) # Example structure based on common COCO format expectations # In a real scenario, you'd load these from actual files. anno_json_path = "annotations_val2017.json" # Path to your ground truth annotations pred_json_path = "results_predictions.json" # Path to your model's predictions # Simulate creating dummy JSON files for demonstration # In practice, these files would already exist. if not os.path.exists(anno_json_path): with open(anno_json_path, 'w') as f: f.write('{"images": [], "annotations": [], "categories": []}') if not os.path.exists(pred_json_path): with open(pred_json_path, 'w') as f: f.write('[]') # Load annotations and predictions # For a real run, ensure your JSON files contain actual data. try: coco_gt = COCO(anno_json_path) coco_dt = coco_gt.loadRes(pred_json_path) # Evaluate bounding boxes coco_eval = COCOeval(coco_gt, coco_dt, "bbox") coco_eval.evaluate() coco_eval.accumulate() coco_eval.summarize() print("COCO evaluation (bbox) summarized.") # Option 2: Directly use faster_coco_eval classes (alternative to init_as_pycocotools) from faster_coco_eval import COCO as FasterCOCO, COCOeval_faster # Load annotations and predictions coco_gt_f = FasterCOCO(anno_json_path) coco_dt_f = coco_gt_f.loadRes(pred_json_path) # Evaluate segmentation masks coco_eval_f = COCOeval_faster(coco_gt_f, coco_dt_f, "segm") coco_eval_f.evaluate() coco_eval_f.accumulate() coco_eval_f.summarize() print("Faster COCO evaluation (segm) summarized.") except Exception as e: print(f"An error occurred during COCO evaluation: {e}") print("Please ensure your annotation and prediction JSON files are valid and contain data.") # Clean up dummy files os.remove(anno_json_path) os.remove(pred_json_path)
Debug
Known issues
breakingIn version 1.2.2, the library removed its own precision-recall calculation implementation and switched to the COCO eval's method, leading to a loss of backward compatibility for related functionalities.
fix
Review any custom logic relying on older precision-recall calculation methods and update to align with the standard COCO eval approach.
affects: >=1.2.2
breakingVersion 1.4.2 introduced several breaking changes including `COCO.load_json` becoming a static function, the `in_percent` argument in `display_matrix` being replaced by `normalize`, and a rework of drawing functions.
fix
Update calls to `COCO.load_json` to use it as a static method, adjust `display_matrix` arguments, and review usage of drawing functions for API changes.
affects: >=1.4.2
gotchaAs of version 1.5.6, the `COCOevalEvaluateAccumulate` function was introduced to combine `COCOevalEvaluateImages` and `COCOevalAccumulate`. The `separate_eval` parameter, which defaults to `False`, controls this behavior. This changes the default evaluation flow.
fix
Be aware of the combined evaluation flow. If you require separate evaluation steps, explicitly set `separate_eval=True` when initializing `COCOeval_faster` or `COCOeval`.
affects: >=1.5.6
gotchaSupport for `numpy>=2` was explicitly added in version 1.6.4. Older versions of `numpy` (e.g., `numpy<2`) might lead to compatibility issues, especially with Python 3.9+.
fix
Ensure `numpy` is updated to version 2.0 or higher, particularly when using newer Python versions (3.9+).
affects: <1.6.4
gotchaPrior to version 1.7.2, the `extended_metrics` functionality could raise a `ValueError` if an `IoU` threshold of `0.50` was not explicitly present in the `iouThrs` list.
fix
Ensure that `0.50` is included in your `iouThrs` list if using `extended_metrics` on older versions, or update to version 1.7.2 or later.
affects: <1.7.2
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'faster_coco_eval'
The 'faster-coco-eval' library is not installed in the current Python environment or the environment variables are not correctly set up.
fix
Install the library using pip: `pip install faster-coco-eval` (for core functionality) or `pip install faster-coco-eval[extra]` (for full functionality including visualization tools).
ImportError: cannot import name COCO from pycocotools.coco
This error occurs when attempting to use 'faster-coco-eval' as a drop-in replacement for 'pycocotools' but `faster_coco_eval.init_as_pycocotools()` has not been called to patch the imports.
fix
Add `import faster_coco_eval; faster_coco_eval.init_as_pycocotools()` at the beginning of your script, before any `from pycocotools.coco import COCO` or similar imports.
TypeError: _evaluate_predictions_on_coco() got an unexpected keyword argument 'use_fast_impl'
This error typically arises when integrating with frameworks like Detectron2, which may pass a 'use_fast_impl' argument to COCO evaluation functions, but the underlying 'pycocotools' (or an incompatible version) does not support it, even when 'faster-coco-eval' is intended for use.
fix
Ensure that `faster_coco_eval.init_as_pycocotools()` is called before evaluation, and if the issue persists, check for framework-specific configurations or update 'detectron2' to a compatible version that handles 'faster-coco-eval' integration correctly.
ValueError: IoU threshold 0.50 not found in iouThrs list
Prior to version 1.7.2, using `extended_metrics` without explicitly including `0.50` in the `iouThrs` list would raise this error.
fix
Ensure your `iouThrs` list includes `0.50` (e.g., `iouThrs=[0.50, 0.75, 0.90]`) or update `faster-coco-eval` to version 1.7.2 or later.
Upgrade
Version history
1.7.2latest on PyPI · released Feb 22, 2026
Audit
Dependencies
numpyrequiredFundamental package for scientific computing in Python, used throughout for array operations.
pycocotoolsrequiredAlthough faster-coco-eval is a replacement, pycocotools is listed as a required dependency on PyPI, suggesting it provides underlying structures or format compatibility.
plotlyoptionalRequired for advanced visualization features like metric curves. Included with '[extra]' installation.
opencv-python-headlessoptionalPotentially used for mask API backends and other image processing utilities. Included with '[extra]' installation.
Agent activity
20 hits · last 30 days
node
18
Amazon
1
OpenAI (training)
1
Resources