Environment:Obss Sahi Python Pycocotools

Knowledge Sources	obss/sahi pycocotools
Domains	Computer_Vision, Evaluation, Infrastructure
Last Updated	2026-02-08 12:00 GMT

Overview

Python 3.8+ environment with pycocotools, matplotlib, terminaltables, and NumPy for COCO evaluation metrics and error analysis.

Description

This environment provides the evaluation and analysis runtime required by SAHI's COCO evaluation and error analysis scripts. It wraps the official pycocotools (COCO API) for computing standard AP/AR metrics and extends it with TIDE-style error decomposition. The `pycocotools` package is a CI/test dependency (not a core dependency) — it is required specifically for the evaluation and error analysis workflows.

Usage

Use this environment for any workflow that performs COCO evaluation (`evaluate`, `evaluate_core`) or COCO error analysis (`analyse`, `_analyse_results`). This is the mandatory prerequisite for running the COCO Evaluation workflow.

System Requirements

Category	Requirement	Notes
OS	Linux, macOS, Windows	All platforms supported
Hardware	CPU	No GPU required for evaluation
Python	>= 3.8, <= 3.13	All supported Python versions
Disk	~100MB	pycocotools and matplotlib

Dependencies

System Packages

C compiler (for building pycocotools from source if no wheel available)

Python Packages

`pycocotools` >= 2.0.7
`matplotlib` (used for error analysis plots)
`terminaltables` (used for formatted console output)
`numpy` (transitive dependency)
`scikit-image` (used in CI tests for evaluation)

Credentials

No credentials required for evaluation operations.

Quick Install

# Install evaluation dependencies
pip install "pycocotools>=2.0.7" matplotlib terminaltables scikit-image

# Or install SAHI core + evaluation deps
pip install sahi "pycocotools>=2.0.7" matplotlib

Code Evidence

pycocotools usage from `sahi/scripts/coco_evaluation.py:1-10`:

from pycocotools.coco import COCO
from pycocotools.cocoeval import COCOeval

Custom COCO evaluation summarization from `sahi/scripts/coco_evaluation.py:29-80`:

def _cocoeval_summarize(cocoeval, catId=None, iouThr=None, areaRng="all", maxDets=100):
    """Custom summarize function for COCOeval that supports per-category evaluation."""
    p = cocoeval.params
    aind = [i for i, aRng in enumerate(p.areaRngLbl) if aRng == areaRng]
    mind = [i for i, mDet in enumerate(p.maxDets) if mDet == maxDets]
    ...

Error analysis matplotlib usage from `sahi/scripts/coco_error_analysis.py:20-25`:

import matplotlib.pyplot as plt
import numpy as np
from pycocotools.coco import COCO
from pycocotools.cocoeval import COCOeval
from terminaltables import AsciiTable

Area range configuration from `sahi/scripts/coco_evaluation.py:346-351`:

def evaluate(
    dataset_json_path,
    result_json_path,
    type="bbox",
    classwise=False,
    max_detections=500,
    areas=None,
    ...
):

Common Errors

Error Message	Cause	Solution
`ModuleNotFoundError: No module named 'pycocotools'`	pycocotools not installed	`pip install pycocotools>=2.0.7`
`ImportError: No module named 'matplotlib'`	matplotlib not installed for error analysis plots	`pip install matplotlib`
`AssertionError: Results is empty`	Empty predictions JSON passed to COCO evaluation	Ensure prediction JSON contains at least one detection result
`KeyError: 'annotations'`	Malformed COCO JSON missing annotations field	Verify COCO JSON has `images`, `annotations`, and `categories` fields

Compatibility Notes

pycocotools: Requires C compilation on some platforms. Use `pycocotools>=2.0.7` which has pre-built wheels for common platforms.
matplotlib: Only required for error analysis (`analyse`). Pure metric evaluation (`evaluate`) uses `terminaltables` for console output.
Large datasets: pycocotools loads the entire dataset into memory. For very large COCO datasets (>100K images), ensure sufficient RAM.

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment