Implementation:Obss Sahi Evaluate

Knowledge Sources	SAHI SAHI Docs pycocotools
Domains	Object_Detection, Evaluation, Metrics
Last Updated	2026-02-08 12:00 GMT

Overview

Concrete tool for running COCO-standard object detection evaluation with extended metrics provided by the SAHI library.

Description

evaluate() is the high-level entry point for COCO evaluation in SAHI. It:

1. Imports pycocotools.coco.COCO and pycocotools.cocoeval.COCOeval (raising a helpful error if not installed)
2. Delegates to evaluate_core() which handles all computation
3. evaluate_core() loads ground truth via COCO(dataset_path) and predictions via cocoGt.loadRes(results)
4. Configures custom area ranges, max detections, and IoU thresholds on the COCOeval.params object
5. Runs cocoEval.evaluate() and cocoEval.accumulate()
6. Computes 12 metrics via _cocoeval_summarize(): mAP, mAP50, mAP75, mAP_s/m/l, mAP50_s/m/l, AR_s/m/l
7. Optionally computes per-category AP when classwise=True and displays results as ASCII tables
8. Exports results to eval.json in the output directory

Usage

Use this function after generating COCO-format prediction results (e.g., via PredictionResult.to_coco_annotations() and save_json()). Can be invoked programmatically or via CLI: sahi coco evaluate.

Code Reference

Source Location

• Repository: sahi
• File: sahi/scripts/coco_evaluation.py
• Lines: L353-398 (evaluate), L62-350 (evaluate_core), L15-59 (_cocoeval_summarize)

Signature

def evaluate(
    dataset_json_path: str,
    result_json_path: str,
    out_dir: str | None = None,
    type: Literal["bbox", "segm"] = "bbox",
    classwise: bool = False,
    max_detections: int = 500,
    iou_thrs: list[float] | float | None = None,
    areas: list[int] = [1024, 9216, 10000000000],
    return_dict: bool = False,
):
    """Evaluate detection predictions against ground truth.

    Args:
        dataset_json_path: Path to COCO ground truth JSON
        result_json_path: Path to COCO prediction results JSON
        out_dir: Directory to save eval.json results
        type: "bbox" or "segm" evaluation
        classwise: Compute per-category AP
        max_detections: Max detections per image (default 500)
        iou_thrs: IoU thresholds (default 0.50:0.05:0.95)
        areas: Area boundaries [small, medium, large] in pixels^2
        return_dict: Return results dict if True
    """

Import

from sahi.scripts.coco_evaluation import evaluate

I/O Contract

Inputs

Name	Type	Required	Description
dataset_json_path	str	Yes	Path to COCO ground truth annotation JSON
result_json_path	str	Yes	Path to COCO prediction results JSON
out_dir	str	No	Output directory for eval.json (default: same as result dir)
type	str	No	"bbox" or "segm" (default "bbox")
classwise	bool	No	Compute per-category AP (default False)
max_detections	int	No	Max detections per image (default 500)
iou_thrs	list[float]	No	IoU thresholds (default 0.50 to 0.95 step 0.05)
areas	list[int]	No	Area boundaries [small, medium, large] (default [1024, 9216, 10^10])
return_dict	bool	No	Return results dict (default False)

Outputs

Name	Type	Description
eval_results	dict (if return_dict=True)	OrderedDict with keys like bbox_mAP, bbox_mAP50, bbox_mAP75, etc.
export_path	str (if return_dict=True)	Path to exported eval.json file
console output	text	Printed AP/AR metrics table

Usage Examples

Basic Evaluation

from sahi.scripts.coco_evaluation import evaluate

# Evaluate bbox predictions
result = evaluate(
    dataset_json_path="ground_truth.json",
    result_json_path="predictions.json",
    out_dir="./eval_output/",
    type="bbox",
    return_dict=True,
)

print(f"mAP: {result['eval_results']['bbox_mAP']:.3f}")
print(f"mAP50: {result['eval_results']['bbox_mAP50']:.3f}")
print(f"mAP_s: {result['eval_results']['bbox_mAP_s']:.3f}")

Per-Class Evaluation with Custom Areas

from sahi.scripts.coco_evaluation import evaluate

result = evaluate(
    dataset_json_path="ground_truth.json",
    result_json_path="predictions.json",
    type="bbox",
    classwise=True,         # per-category AP table
    max_detections=1000,     # more detections for dense scenes
    areas=[512, 4096, 10000000000],  # custom size boundaries
    return_dict=True,
)

CLI Usage

sahi coco evaluate \
    --dataset_json_path ground_truth.json \
    --result_json_path predictions.json \
    --type bbox \
    --classwise

Related Pages

Implements Principle

• Principle:Obss_Sahi_COCO_Evaluation

Requires Environment

• Environment:Obss_Sahi_Python_Pycocotools