EasyMetrics 0.1.0__py3-none-any.whl

easyMetrics/__init__.py

@@ -0,0 +1,4 @@
+"""
+EasyMetrics: A simple and extensible metrics evaluation platform.
+"""
+__version__ = "0.1.0"

easyMetrics/core/__init__.py

@@ -0,0 +1 @@
+from .base import Metric

easyMetrics/core/base.py

@@ -0,0 +1,37 @@
+from abc import ABC, abstractmethod
+from typing import Any, Dict, List, Optional
+
+class Metric(ABC):
+    """
+    所有指标的抽象基类。
+    """
+    def __init__(self):
+        self.reset()
+
+    @abstractmethod
+    def reset(self):
+        """
+        重置指标的内部状态。
+        """
+        pass
+
+    @abstractmethod
+    def update(self, preds: Any, target: Any):
+        """
+        使用新的预测值和真实值更新指标状态。
+        
+        参数:
+            preds: 模型的预测结果。
+            target: 真实标签 (Ground Truth)。
+        """
+        pass
+
+    @abstractmethod
+    def compute(self) -> Any:
+        """
+        计算最终的指标值。
+        
+        返回:
+            计算出的指标值。
+        """
+        pass

easyMetrics/tasks/__init__.py

@@ -0,0 +1 @@
+from .detection import MeanAveragePrecision

easyMetrics/tasks/detection/__init__.py

@@ -0,0 +1,2 @@
+from .map import MeanAveragePrecision
+from .interface import evaluate_detection

easyMetrics/tasks/detection/format_converter.py

@@ -0,0 +1,277 @@
+from typing import Any, Dict, List, Optional, Tuple
+import numpy as np
+
+class DetectionFormatConverter:
+    """
+    检测格式转换器，支持多种常见的目标检测格式转换为内部统一格式。
+    
+    支持的格式：
+    - coco: COCO 格式，{"boxes": [[x1, y1, x2, y2]], "scores": [0.9], "labels": [0]}
+    - voc: VOC 格式，支持列表形式 [[x1, y1, x2, y2, class_id]]
+    - yolo: YOLO 格式，[[class_id, x, y, w, h, confidence]]，其中 x,y,w,h 是归一化值
+    - custom: 自定义格式，需要提供转换函数
+    """
+    
+    @staticmethod
+    def convert(
+        preds: List[Any], 
+        targets: List[Any], 
+        format: str = "coco",
+        pred_format: Optional[str] = None,
+        target_format: Optional[str] = None,
+        **kwargs
+    ) -> Tuple[List[Dict[str, Any]], List[Dict[str, Any]]]:
+        """
+        将输入数据转换为内部统一格式。
+        
+        参数:
+            preds: 预测结果，可以是不同格式的数据。
+            targets: 真实标签，可以是不同格式的数据。
+            format: 输入数据的格式，当 pred_format 和 target_format 未指定时使用。
+                    支持 "coco", "voc", "yolo", "custom"。
+            pred_format: 预测结果的格式，优先级高于 format。
+            target_format: 真实标签的格式，优先级高于 format。
+            **kwargs: 额外的转换参数。
+                - image_size: YOLO 格式需要的图像尺寸 (width, height)
+                - custom_converter: 自定义格式的转换函数
+                
+        返回:
+            Tuple[List[Dict[str, Any]], List[Dict[str, Any]]]: 转换后的预测结果和真实标签。
+        """
+        # 确定最终使用的格式
+        final_pred_format = pred_format or format
+        final_target_format = target_format or format
+        
+        # 转换预测结果
+        if final_pred_format == "coco":
+            converted_preds = DetectionFormatConverter._convert_coco_preds(preds)
+        elif final_pred_format == "voc":
+            converted_preds = DetectionFormatConverter._convert_voc_preds(preds)
+        elif final_pred_format == "yolo":
+            image_size = kwargs.get("image_size", (640, 640))
+            converted_preds = DetectionFormatConverter._convert_yolo_preds(preds, image_size)
+        elif final_pred_format == "custom":
+            custom_converter = kwargs.get("custom_converter")
+            if not custom_converter:
+                raise ValueError("custom format requires custom_converter function")
+            # 对于自定义格式，先转换整体，然后提取预测部分
+            temp_preds, _ = custom_converter(preds, [], **kwargs)
+            converted_preds = temp_preds
+        else:
+            raise ValueError(f"Unsupported pred_format: {final_pred_format}")
+        
+        # 转换真实标签
+        if final_target_format == "coco":
+            converted_targets = DetectionFormatConverter._convert_coco_targets(targets)
+        elif final_target_format == "voc":
+            converted_targets = DetectionFormatConverter._convert_voc_targets(targets)
+        elif final_target_format == "yolo":
+            image_size = kwargs.get("image_size", (640, 640))
+            converted_targets = DetectionFormatConverter._convert_yolo_targets(targets, image_size)
+        elif final_target_format == "custom":
+            custom_converter = kwargs.get("custom_converter")
+            if not custom_converter:
+                raise ValueError("custom format requires custom_converter function")
+            # 对于自定义格式，先转换整体，然后提取标签部分
+            _, temp_targets = custom_converter([], targets, **kwargs)
+            converted_targets = temp_targets
+        else:
+            raise ValueError(f"Unsupported target_format: {final_target_format}")
+        
+        return converted_preds, converted_targets
+    
+    @staticmethod
+    def _convert_coco_preds(coco_preds: List[Any]) -> List[Dict[str, Any]]:
+        """
+        转换 COCO 格式的预测结果。
+        COCO 格式示例: [{"image_id": 0, "category_id": 0, "bbox": [0, 0, 100, 100], "score": 0.9}]
+        """
+        # 按 image_id 分组
+        grouped_preds = {}
+        for pred in coco_preds:
+            image_id = pred.get('image_id', 0)
+            if image_id not in grouped_preds:
+                grouped_preds[image_id] = {
+                    "boxes": [],
+                    "scores": [],
+                    "labels": []
+                }
+            # COCO bbox 格式: [x, y, width, height]，转换为 [x1, y1, x2, y2]
+            x, y, width, height = pred['bbox']
+            boxes = [x, y, x + width, y + height]
+            grouped_preds[image_id]["boxes"].append(boxes)
+            grouped_preds[image_id]["scores"].append(pred['score'])
+            grouped_preds[image_id]["labels"].append(pred['category_id'])
+        
+        # 转换为列表格式
+        converted = list(grouped_preds.values())
+        return converted
+    
+    @staticmethod
+    def _convert_coco_targets(coco_targets: List[Any]) -> List[Dict[str, Any]]:
+        """
+        转换 COCO 格式的真实标签。
+        COCO 格式示例: [{"image_id": 0, "category_id": 0, "bbox": [0, 0, 100, 100], "area": 10000, "iscrowd": 0}]
+        """
+        # 按 image_id 分组
+        grouped_targets = {}
+        for target in coco_targets:
+            image_id = target.get('image_id', 0)
+            if image_id not in grouped_targets:
+                grouped_targets[image_id] = {
+                    "boxes": [],
+                    "labels": []
+                }
+            # COCO bbox 格式: [x, y, width, height]，转换为 [x1, y1, x2, y2]
+            x, y, width, height = target['bbox']
+            boxes = [x, y, x + width, y + height]
+            grouped_targets[image_id]["boxes"].append(boxes)
+            grouped_targets[image_id]["labels"].append(target['category_id'])
+        
+        # 转换为列表格式
+        converted = list(grouped_targets.values())
+        return converted
+    
+    @staticmethod
+    def _convert_voc_preds(voc_preds: List[Any]) -> List[Dict[str, Any]]:
+        """
+        转换 VOC 格式的预测结果。
+        VOC 格式示例: [[x1, y1, x2, y2, class_id, confidence]]
+        """
+        converted = []
+        for pred in voc_preds:
+            if isinstance(pred, list):
+                # 单张图片的预测
+                boxes = []
+                scores = []
+                labels = []
+                for item in pred:
+                    if len(item) >= 6:
+                        # [x1, y1, x2, y2, class_id, confidence]
+                        boxes.append(item[:4])
+                        scores.append(item[5])
+                        labels.append(int(item[4]))
+                    elif len(item) == 5:
+                        # [x1, y1, x2, y2, class_id]
+                        boxes.append(item[:4])
+                        scores.append(1.0)  # 默认置信度
+                        labels.append(int(item[4]))
+                converted.append({
+                    "boxes": boxes,
+                    "scores": scores,
+                    "labels": labels
+                })
+            elif isinstance(pred, dict):
+                # 已经是 COCO 格式
+                converted.append(pred)
+        return converted
+    
+    @staticmethod
+    def _convert_voc_targets(voc_targets: List[Any]) -> List[Dict[str, Any]]:
+        """
+        转换 VOC 格式的真实标签。
+        VOC 格式示例: [[x1, y1, x2, y2, class_id]]
+        """
+        converted = []
+        for target in voc_targets:
+            if isinstance(target, list):
+                # 单张图片的标签
+                boxes = []
+                labels = []
+                for item in target:
+                    if len(item) >= 5:
+                        # [x1, y1, x2, y2, class_id]
+                        boxes.append(item[:4])
+                        labels.append(int(item[4]))
+                converted.append({
+                    "boxes": boxes,
+                    "labels": labels
+                })
+            elif isinstance(target, dict):
+                # 已经是 COCO 格式
+                converted.append(target)
+        return converted
+    
+    @staticmethod
+    def _convert_yolo_preds(yolo_preds: List[Any], image_size: Tuple[int, int]) -> List[Dict[str, Any]]:
+        """
+        转换 YOLO 格式的预测结果。
+        YOLO 格式示例: [[class_id, x, y, w, h, confidence]]
+        其中 x, y, w, h 是归一化值 (0-1)
+        """
+        converted = []
+        width, height = image_size
+        
+        for pred in yolo_preds:
+            if isinstance(pred, list):
+                # 单张图片的预测
+                boxes = []
+                scores = []
+                labels = []
+                for item in pred:
+                    if len(item) >= 6:
+                        # [class_id, x, y, w, h, confidence]
+                        class_id, x, y, w, h, conf = item
+                        # 转换为 [x1, y1, x2, y2]
+                        x1 = (x - w/2) * width
+                        y1 = (y - h/2) * height
+                        x2 = (x + w/2) * width
+                        y2 = (y + h/2) * height
+                        boxes.append([x1, y1, x2, y2])
+                        scores.append(conf)
+                        labels.append(int(class_id))
+                    elif len(item) == 5:
+                        # [class_id, x, y, w, h]
+                        class_id, x, y, w, h = item
+                        # 转换为 [x1, y1, x2, y2]
+                        x1 = (x - w/2) * width
+                        y1 = (y - h/2) * height
+                        x2 = (x + w/2) * width
+                        y2 = (y + h/2) * height
+                        boxes.append([x1, y1, x2, y2])
+                        scores.append(1.0)  # 默认置信度
+                        labels.append(int(class_id))
+                converted.append({
+                    "boxes": boxes,
+                    "scores": scores,
+                    "labels": labels
+                })
+            elif isinstance(pred, dict):
+                # 已经是 COCO 格式
+                converted.append(pred)
+        return converted
+    
+    @staticmethod
+    def _convert_yolo_targets(yolo_targets: List[Any], image_size: Tuple[int, int]) -> List[Dict[str, Any]]:
+        """
+        转换 YOLO 格式的真实标签。
+        YOLO 格式示例: [[class_id, x, y, w, h]]
+        其中 x, y, w, h 是归一化值 (0-1)
+        """
+        converted = []
+        width, height = image_size
+        
+        for target in yolo_targets:
+            if isinstance(target, list):
+                # 单张图片的标签
+                boxes = []
+                labels = []
+                for item in target:
+                    if len(item) >= 5:
+                        # [class_id, x, y, w, h]
+                        class_id, x, y, w, h = item[:5]
+                        # 转换为 [x1, y1, x2, y2]
+                        x1 = (x - w/2) * width
+                        y1 = (y - h/2) * height
+                        x2 = (x + w/2) * width
+                        y2 = (y + h/2) * height
+                        boxes.append([x1, y1, x2, y2])
+                        labels.append(int(class_id))
+                converted.append({
+                    "boxes": boxes,
+                    "labels": labels
+                })
+            elif isinstance(target, dict):
+                # 已经是 COCO 格式
+                converted.append(target)
+        return converted

easyMetrics/tasks/detection/interface.py

@@ -0,0 +1,67 @@
+from typing import Any, Dict, List, Optional, Tuple
+from .map import MeanAveragePrecision
+from .format_converter import DetectionFormatConverter
+
+def evaluate_detection(
+    preds: List[Any], 
+    targets: List[Any], 
+    metrics: Optional[List[str]] = None,
+    n_jobs: int = 1,
+    score_criteria: Optional[List[Tuple[float, float]]] = None,
+    format: str = "coco",
+    pred_format: Optional[str] = None,
+    target_format: Optional[str] = None,
+    progress: bool = True,
+    **kwargs
+) -> Dict[str, float]:
+    """
+    使用 COCO 风格的指标评估目标检测结果。
+
+    参数:
+        preds (List[Any]): 每张图片的预测结果列表。
+        targets (List[Any]): 每张图片的真实标签列表。
+        metrics (Optional[List[str]]): 需要返回的特定指标列表。
+        n_jobs (int): 并行计算线程数。默认为 1。-1 表示使用所有核心。
+        score_criteria (Optional[List[Tuple[float, float]]]): 
+            计算指定 IoU 和 精度下的最佳置信度阈值。
+            格式: [(iou_thresh, min_precision), ...]
+            例如: [(0.5, 0.9)]
+        format (str): 输入数据的格式，当 pred_format 和 target_format 未指定时使用。
+                    支持 "coco", "voc", "yolo", "custom"。
+        pred_format (Optional[str]): 预测结果的格式，优先级高于 format。
+        target_format (Optional[str]): 真实标签的格式，优先级高于 format。
+        progress (bool): 是否显示进度条。默认为 True。
+        **kwargs: 额外的转换参数。
+            - image_size: YOLO 格式需要的图像尺寸 (width, height)
+            - custom_converter: 自定义格式的转换函数
+
+    返回:
+        Dict[str, float]: 包含计算指标的字典。
+    """
+    # 转换输入格式
+    converted_preds, converted_targets = DetectionFormatConverter.convert(
+        preds, targets, 
+        format=format,
+        pred_format=pred_format,
+        target_format=target_format,
+        **kwargs
+    )
+    
+    # 初始化指标计算器
+    metric = MeanAveragePrecision()
+    
+    # 更新数据
+    metric.update(converted_preds, converted_targets)
+    
+    # 计算所有指标
+    all_results = metric.compute(n_jobs=n_jobs, score_criteria=score_criteria, progress=progress)
+    
+    # 如果请求了特定指标，进行筛选
+    if metrics:
+        filtered_results = {}
+        for k in metrics:
+            if k in all_results:
+                filtered_results[k] = all_results[k]
+        return filtered_results
+    
+    return all_results

easyMetrics/tasks/detection/map.py

@@ -0,0 +1,413 @@
+from typing import Any, Dict, List, Optional, Tuple
+import numpy as np
+from concurrent.futures import ThreadPoolExecutor
+from easyMetrics.core.base import Metric
+from .utils import calculate_iou, compute_ap_coco
+from .matcher import BaseMatcher, GreedyIoUMatcher
+
+class MeanAveragePrecision(Metric):
+    """
+    计算目标检测的平均精度 (mAP) 和平均召回率 (AR)。
+    与 COCO 评估指标对齐。
+    """
+    def __init__(self, 
+                 iou_thresholds: Optional[List[float]] = None,
+                 rec_thresholds: Optional[List[float]] = None,
+                 max_detection_thresholds: Optional[List[int]] = None,
+                 matcher: Optional[BaseMatcher] = None):
+        super().__init__()
+        # COCO 默认 IoU 阈值: 0.50 到 0.95，步长 0.05
+        self.iou_thresholds = iou_thresholds or np.linspace(0.5, 0.95, 10)
+        # COCO 默认召回率阈值: 0 到 1，共 101 个点
+        self.rec_thresholds = rec_thresholds or np.linspace(0.0, 1.00, 101)
+        # COCO 默认 AR 计算的最大检测数: 1, 10, 100
+        self.max_detection_thresholds = max_detection_thresholds or [1, 10, 100]
+        # 匹配策略
+        self.matcher = matcher or GreedyIoUMatcher()
+        
+        self.preds = []
+        self.targets = []
+
+    def reset(self):
+        self.preds = []
+        self.targets = []
+
+    def _ensure_numpy_array(self, data, dtype=None):
+        """
+        确保输入数据是 numpy 数组，如果不是则转换为 numpy 数组。
+        
+        参数:
+            data: 输入数据，可以是列表、numpy 数组或其他可转换类型。
+            dtype: 目标数据类型，默认为 None（自动推断）。
+            
+        返回:
+            numpy.ndarray: 转换后的 numpy 数组。
+        """
+        import numpy as np
+        if isinstance(data, np.ndarray):
+            if dtype is not None and data.dtype != dtype:
+                return data.astype(dtype)
+            return data
+        elif data is None:
+            return np.array([], dtype=dtype)
+        else:
+            return np.array(data, dtype=dtype)
+
+    def update(self, preds: List[Dict[str, Any]], target: List[Dict[str, Any]]):
+        """
+        参数:
+            preds: 字典列表。每个字典包含 'boxes', 'scores', 'labels'。
+            target: 字典列表。每个字典包含 'boxes', 'labels'。
+        """
+        # 自动转换 preds 中的数据类型
+        converted_preds = []
+        for pred in preds:
+            converted_pred = {
+                'boxes': self._ensure_numpy_array(pred['boxes'], dtype=float),
+                'scores': self._ensure_numpy_array(pred['scores'], dtype=float),
+                'labels': self._ensure_numpy_array(pred['labels'], dtype=int)
+            }
+            converted_preds.append(converted_pred)
+        
+        # 自动转换 targets 中的数据类型
+        converted_targets = []
+        for tgt in target:
+            converted_target = {
+                'boxes': self._ensure_numpy_array(tgt['boxes'], dtype=float),
+                'labels': self._ensure_numpy_array(tgt['labels'], dtype=int)
+            }
+            converted_targets.append(converted_target)
+        
+        self.preds.extend(converted_preds)
+        self.targets.extend(converted_targets)
+
+    def compute(self, n_jobs: int = 1, score_criteria: Optional[List[Tuple[float, float]]] = None, progress: bool = True) -> Dict[str, float]:
+        """
+        计算 mAP 和 AR 指标。
+        
+        参数:
+            n_jobs: 并行计算的线程数。默认为 1 (串行)。设置为 -1 表示使用所有可用 CPU。
+            score_criteria: 可选。计算指定 IoU 和 精度下的最佳置信度阈值。
+                            格式为列表: [(iou_thresh, min_precision), ...]
+                            例如 [(0.5, 0.9)] 表示寻找 IoU=0.5 时精度至少为 0.9 的最低置信度。
+            progress: 是否显示进度条。默认为 True。
+            
+        返回包含以下键的字典:
+            - mAP, mAP_50, mAP_75...
+            - BestScore_IoU{iou}_P{prec}_{cls_id}: 满足条件的最佳置信度
+        """
+        # 1. 识别所有唯一类别
+        unique_classes = set()
+        for t in self.targets:
+            unique_classes.update(t['labels'].tolist())
+        for p in self.preds:
+            unique_classes.update(p['labels'].tolist())
+        
+        sorted_classes = sorted(list(unique_classes))
+        
+        # 定义尺度范围 (COCO 标准)
+        area_rngs = {
+            'all': (0, 1e10),
+            'small': (0, 32 ** 2),
+            'medium': (32 ** 2, 96 ** 2),
+            'large': (96 ** 2, 1e10)
+        }
+        
+        results = {}
+        cls_id_to_idx = {cls_id: i for i, cls_id in enumerate(sorted_classes)}
+        
+        # 内部函数：计算单个类别的统计信息
+        def _process_class(cls_id, area_rng):
+            # score_criteria 仅在 'all' 尺度下计算，避免混淆
+            criteria = score_criteria if area_name == 'all' else None
+            return cls_id, self._compute_class_stats(cls_id, area_rng, criteria)
+
+        # 对每个尺度分别进行评估
+        for area_name, area_rng in area_rngs.items():
+            # 初始化聚合器
+            aps = np.zeros((len(sorted_classes), len(self.iou_thresholds)))
+            ars = np.zeros((len(sorted_classes), len(self.iou_thresholds), len(self.max_detection_thresholds)))
+            
+            # 收集额外的分数指标
+            class_score_results = {} 
+
+            # 初始化进度条
+            progress_bar = None
+            if progress and len(sorted_classes) > 0:
+                try:
+                    from tqdm import tqdm
+                    progress_bar = tqdm(total=len(sorted_classes), desc=f"评估 {area_name}")
+                except ImportError:
+                    # 如果没有 tqdm，使用简单的打印
+                    print(f"开始评估 {area_name}...")
+
+            # 并行或串行处理
+            if n_jobs == 1:
+                for cls_id in sorted_classes:
+                    idx = cls_id_to_idx[cls_id]
+                    # score_criteria 仅在 'all' 尺度下计算
+                    criteria = score_criteria if area_name == 'all' else None
+                    cls_stats = self._compute_class_stats(cls_id, area_rng, criteria)
+                    
+                    # 解包结果
+                    if criteria:
+                        cls_aps, cls_ars, cls_scores = cls_stats
+                        class_score_results[cls_id] = cls_scores
+                    else:
+                        cls_aps, cls_ars = cls_stats
+                        
+                    aps[idx, :] = cls_aps
+                    ars[idx, :, :] = cls_ars
+                    
+                    # 更新进度条
+                    if progress_bar:
+                        progress_bar.update(1)
+            else:
+                max_workers = None if n_jobs == -1 else n_jobs
+                with ThreadPoolExecutor(max_workers=max_workers) as executor:
+                    futures = [executor.submit(_process_class, cls_id, area_rng) for cls_id in sorted_classes]
+                    for future in futures:
+                        cls_id, cls_stats = future.result()
+                        idx = cls_id_to_idx[cls_id]
+                        
+                        # score_criteria 仅在 'all' 尺度下计算
+                        criteria = score_criteria if area_name == 'all' else None
+                        if criteria:
+                            cls_aps, cls_ars, cls_scores = cls_stats
+                            class_score_results[cls_id] = cls_scores
+                        else:
+                            cls_aps, cls_ars = cls_stats
+                            
+                        aps[idx, :] = cls_aps
+                        ars[idx, :, :] = cls_ars
+                        
+                        # 更新进度条
+                        if progress_bar:
+                            progress_bar.update(1)
+            
+            # 关闭进度条
+            if progress_bar:
+                progress_bar.close()
+
+            # 计算聚合指标
+            if aps.size > 0:
+                mean_ap = float(np.mean(aps))
+                
+                if area_name == 'all':
+                    results['mAP'] = mean_ap
+                    
+                    # mAP @ 0.5
+                    idx_50 = np.where(np.isclose(self.iou_thresholds, 0.5))[0]
+                    if len(idx_50) > 0:
+                        results['mAP_50'] = float(np.mean(aps[:, idx_50[0]]))
+                        
+                    # mAP @ 0.75
+                    idx_75 = np.where(np.isclose(self.iou_thresholds, 0.75))[0]
+                    if len(idx_75) > 0:
+                        results['mAP_75'] = float(np.mean(aps[:, idx_75[0]]))
+                        
+                    # 特定类别的 AP (仅在 'all' 尺度下报告)
+                    for cls_id in sorted_classes:
+                        idx = cls_id_to_idx[cls_id]
+                        results[f'AP_{cls_id}'] = float(np.mean(aps[idx, :]))
+                        
+                        # 添加 AP@50 和 AP@75 的类别细分
+                        if len(idx_50) > 0:
+                            results[f'AP_50_{cls_id}'] = float(aps[idx, idx_50[0]])
+                        if len(idx_75) > 0:
+                            results[f'AP_75_{cls_id}'] = float(aps[idx, idx_75[0]])
+                            
+                        # 添加最佳置信度指标
+                        if cls_id in class_score_results:
+                            for k, v in class_score_results[cls_id].items():
+                                results[f'{k}_{cls_id}'] = v
+                        
+                    # 计算 AR (仅在 'all' 尺度下报告 AR_1, AR_10, AR_100)
+                    if ars.size > 0:
+                        mean_ars = np.mean(ars, axis=(0, 1)) # [NumMaxDets]
+                        for i, max_det in enumerate(self.max_detection_thresholds):
+                            results[f'AR_{max_det}'] = float(mean_ars[i])
+
+                elif area_name == 'small':
+                    results['mAP_s'] = mean_ap
+                elif area_name == 'medium':
+                    results['mAP_m'] = mean_ap
+                elif area_name == 'large':
+                    results['mAP_l'] = mean_ap
+            else:
+                if area_name == 'all':
+                    results['mAP'] = 0.0
+
+        return results
+
+    def _prepare_data(self, cls_id: int, area_rng: Tuple[float, float]) -> Tuple[List[Tuple], Dict, int]:
+        """
+        准备特定类别和面积范围的数据。
+        """
+        min_area, max_area = area_rng
+        class_preds = [] 
+        class_gt = {}    
+        n_pos = 0
+
+        # 收集 GT
+        for img_idx, target in enumerate(self.targets):
+            mask = target['labels'] == cls_id
+            boxes = target['boxes'][mask]
+            
+            areas = (boxes[:, 2] - boxes[:, 0]) * (boxes[:, 3] - boxes[:, 1])
+            valid_area_mask = (areas >= min_area) & (areas < max_area)
+            valid_boxes = boxes[valid_area_mask]
+            
+            n_pos += len(valid_boxes)
+            class_gt[img_idx] = {
+                'boxes': valid_boxes,
+                'used': np.zeros(len(valid_boxes), dtype=bool)
+            }
+
+        # 收集预测值
+        limit_dets = max(self.max_detection_thresholds) if self.max_detection_thresholds else 100
+        
+        for img_idx, pred in enumerate(self.preds):
+            mask = pred['labels'] == cls_id
+            scores = pred['scores'][mask]
+            boxes = pred['boxes'][mask]
+            
+            areas = (boxes[:, 2] - boxes[:, 0]) * (boxes[:, 3] - boxes[:, 1])
+            valid_area_mask = (areas >= min_area) & (areas < max_area)
+            
+            scores = scores[valid_area_mask]
+            boxes = boxes[valid_area_mask]
+            
+            if len(scores) > 0:
+                order = np.argsort(-scores)
+                scores = scores[order][:limit_dets]
+                boxes = boxes[order][:limit_dets]
+                ranks = np.arange(len(scores))
+            else:
+                scores, boxes, ranks = [], [], []
+            
+            for s, b, r in zip(scores, boxes, ranks):
+                class_preds.append((s, img_idx, b, r))
+        
+        # 全局按分数排序
+        class_preds.sort(key=lambda x: x[0], reverse=True)
+        
+        return class_preds, class_gt, n_pos
+
+    def _match_predictions(self, class_preds: List[Tuple], class_gt: Dict, pred_gt_ious: List[np.ndarray], iou_thresh: float) -> Tuple[np.ndarray, np.ndarray]:
+        """
+        在特定 IoU 阈值下进行贪婪匹配。
+        """
+        tp = np.zeros(len(class_preds))
+        fp = np.zeros(len(class_preds))
+        
+        # 重置 GT 使用状态
+        for img_data in class_gt.values():
+            img_data['used'][:] = False
+            
+        for i, ious in enumerate(pred_gt_ious):
+            if len(ious) == 0:
+                fp[i] = 1
+                continue
+            
+            # 找到最佳匹配
+            best_gt_idx = np.argmax(ious)
+            best_iou = ious[best_gt_idx]
+            
+            img_idx = class_preds[i][1]
+            
+            if best_iou >= iou_thresh:
+                if not class_gt[img_idx]['used'][best_gt_idx]:
+                    tp[i] = 1
+                    class_gt[img_idx]['used'][best_gt_idx] = True
+                else:
+                    fp[i] = 1 # 重复检测
+            else:
+                fp[i] = 1
+                
+        return tp, fp
+
+    def _compute_class_stats(self, cls_id: int, area_rng: Tuple[float, float], 
+                             score_criteria: Optional[List[Tuple[float, float]]] = None) -> Any:
+        """
+        计算特定类别在所有阈值下的 AP 和 Recall。
+        如果提供了 score_criteria，则返回 (aps, recalls, scores_dict)
+        否则返回 (aps, recalls)
+        """
+        # 1. 准备数据
+        class_preds, class_gt, n_pos = self._prepare_data(cls_id, area_rng)
+
+        num_iou = len(self.iou_thresholds)
+        num_dets = len(self.max_detection_thresholds)
+        
+        # 结果初始化
+        aps = np.zeros(num_iou)
+        recs = np.zeros((num_iou, num_dets))
+        scores_result = {} # key: "BestScore_IoU{}_P{}"
+
+        if n_pos == 0 or len(class_preds) == 0:
+            if score_criteria:
+                return aps, recs, scores_result
+            return aps, recs
+        
+        # 提取排名以供快速过滤
+        pred_ranks = np.array([p[3] for p in class_preds])
+        # 提取分数 (class_preds 已经是按分数降序排列)
+        pred_scores = np.array([p[0] for p in class_preds])
+
+        # 2. 预计算 IoU
+        pred_gt_ious = []
+        for _, img_idx, pred_box, _ in class_preds:
+            gt_boxes = class_gt[img_idx]['boxes']
+            if len(gt_boxes) == 0:
+                pred_gt_ious.append(np.array([]))
+            else:
+                ious = calculate_iou(pred_box[None, :], gt_boxes)[0]
+                pred_gt_ious.append(ious)
+
+        # 3. 遍历阈值
+        for t_idx, iou_thresh in enumerate(self.iou_thresholds):
+            tp, fp = self.matcher.match(class_preds, class_gt, pred_gt_ious, iou_thresh)
+            
+            # 计算 AP
+            cum_tp = np.cumsum(tp)
+            cum_fp = np.cumsum(fp)
+            
+            recall = cum_tp / n_pos
+            precision = cum_tp / (cum_tp + cum_fp)
+            
+            aps[t_idx] = compute_ap_coco(recall, precision)
+            
+            # 计算最佳置信度 (如果需要)
+            if score_criteria:
+                for (crit_iou, crit_prec) in score_criteria:
+                    # 使用 isclose 比较浮点数
+                    if np.isclose(iou_thresh, crit_iou):
+                        # 找到满足 precision >= crit_prec 的所有索引
+                        valid_mask = precision >= crit_prec
+                        if np.any(valid_mask):
+                            # 我们想要最大的 recall，即 valid_mask 中最后一个 True 的位置
+                            # 因为 class_preds 是按 score 降序 (recall 升序) 排列的
+                            # 最后一个满足条件的点对应最低的 score (但在满足精度的前提下 recall 最大)
+                            best_idx = np.where(valid_mask)[0][-1]
+                            best_score = pred_scores[best_idx]
+                            
+                            key = f"BestScore_IoU{crit_iou:.2f}_P{crit_prec:.2f}"
+                            scores_result[key] = float(best_score)
+
+            # 计算 AR (针对每个 max_det 阈值)
+            for d_idx, max_det in enumerate(self.max_detection_thresholds):
+                valid_mask = pred_ranks < max_det
+                tp_sum = np.sum(tp[valid_mask])
+                recs[t_idx, d_idx] = tp_sum / n_pos
+
+        if score_criteria:
+            return aps, recs, scores_result
+        return aps, recs
+
+    def _match_predictions(self, *args, **kwargs):
+        """
+        [已弃用] 请使用 self.matcher.match
+        为了兼容性暂时保留，但会抛出错误
+        """
+        raise DeprecationWarning("Please use self.matcher.match instead of _match_predictions")

easyMetrics/tasks/detection/matcher.py

@@ -0,0 +1,73 @@
+from abc import ABC, abstractmethod
+from typing import List, Dict, Tuple, Any
+import numpy as np
+
+class BaseMatcher(ABC):
+    """
+    匹配策略的抽象基类。
+    定义如何将预测框与真实框进行匹配。
+    """
+    
+    @abstractmethod
+    def match(self, 
+              class_preds: List[Tuple], 
+              class_gt: Dict, 
+              pred_gt_ious: List[np.ndarray], 
+              iou_thresh: float) -> Tuple[np.ndarray, np.ndarray]:
+        """
+        执行匹配逻辑。
+        
+        参数:
+            class_preds: 预测列表，每个元素为 (score, img_idx, box, rank)
+            class_gt: GT 字典，key 为 img_idx，value 为 {'boxes': [], 'used': []}
+            pred_gt_ious: 预计算的 IoU 列表，对应 class_preds 中的每个预测
+            iou_thresh: 当前的 IoU 阈值
+            
+        返回:
+            tp: (N,) 数组，1 表示 True Positive
+            fp: (N,) 数组，1 表示 False Positive
+        """
+        pass
+
+class GreedyIoUMatcher(BaseMatcher):
+    """
+    标准的贪婪 IoU 匹配策略 (COCO/VOC 标准)。
+    按分数从高到低，优先匹配 IoU 最大的 GT。
+    """
+    
+    def match(self, 
+              class_preds: List[Tuple], 
+              class_gt: Dict, 
+              pred_gt_ious: List[np.ndarray], 
+              iou_thresh: float) -> Tuple[np.ndarray, np.ndarray]:
+        
+        tp = np.zeros(len(class_preds))
+        fp = np.zeros(len(class_preds))
+        
+        # 重置 GT 使用状态
+        # 注意：这里会修改 class_gt 的内部状态，这是预期的副作用
+        for img_data in class_gt.values():
+            img_data['used'][:] = False
+            
+        for i, ious in enumerate(pred_gt_ious):
+            if len(ious) == 0:
+                fp[i] = 1
+                continue
+            
+            # 找到最佳匹配
+            best_gt_idx = np.argmax(ious)
+            best_iou = ious[best_gt_idx]
+            
+            img_idx = class_preds[i][1]
+            
+            if best_iou >= iou_thresh:
+                # 检查该 GT 是否已被匹配
+                if not class_gt[img_idx]['used'][best_gt_idx]:
+                    tp[i] = 1
+                    class_gt[img_idx]['used'][best_gt_idx] = True
+                else:
+                    fp[i] = 1 # 重复检测 (Duplicate)
+            else:
+                fp[i] = 1 # IoU 不足
+                
+        return tp, fp

easyMetrics/tasks/detection/utils.py

@@ -0,0 +1,77 @@
+import numpy as np
+
+def calculate_iou(boxes1: np.ndarray, boxes2: np.ndarray) -> np.ndarray:
+    """
+    计算两组边界框之间的交并比 (IoU)。
+    
+    参数:
+        boxes1: (N, 4) ndarray, 格式为 [x1, y1, x2, y2]
+        boxes2: (M, 4) ndarray, 格式为 [x1, y1, x2, y2]
+        
+    返回:
+        iou: (N, M) ndarray, 表示 boxes1 和 boxes2 之间的重叠程度
+    """
+    if boxes1.size == 0 or boxes2.size == 0:
+        return np.zeros((boxes1.shape[0], boxes2.shape[0]))
+
+    # 确保输入是 2D 的
+    if boxes1.ndim == 1:
+        boxes1 = boxes1[np.newaxis, :]
+    if boxes2.ndim == 1:
+        boxes2 = boxes2[np.newaxis, :]
+
+    # 计算面积
+    area1 = (boxes1[:, 2] - boxes1[:, 0]) * (boxes1[:, 3] - boxes1[:, 1])  # (N,)
+    area2 = (boxes2[:, 2] - boxes2[:, 0]) * (boxes2[:, 3] - boxes2[:, 1])  # (M,)
+
+    # 广播计算交集区域的左上角和右下角坐标
+    lt = np.maximum(boxes1[:, None, :2], boxes2[None, :, :2])  # (N, M, 2) [x1, y1]
+    rb = np.minimum(boxes1[:, None, 2:], boxes2[None, :, 2:])  # (N, M, 2) [x2, y2]
+
+    # 计算交集宽高，clip(0) 确保无重叠时为 0
+    wh = np.clip(rb - lt, 0, None)  # (N, M, 2) [w, h]
+    inter = wh[:, :, 0] * wh[:, :, 1]  # (N, M)
+
+    # 计算并集面积
+    union = area1[:, None] + area2[None, :] - inter
+
+    # 避免除以零
+    union = np.maximum(union, 1e-6)
+
+    iou = inter / union
+    return iou
+
+def compute_ap_coco(recall: np.ndarray, precision: np.ndarray) -> float:
+    """
+    使用 COCO 风格的 101 点插值法计算平均精度 (Average Precision)。
+    
+    参数:
+        recall: (N,) ndarray, 召回率数组，需单调递增
+        precision: (N,) ndarray, 对应的精度数组
+        
+    返回:
+        ap: float, 计算得到的 AP 值
+    """
+    # 在开头和结尾添加哨兵值
+    # 注意: COCO 不严格要求开头为 0，但要求覆盖 [0, 1] 区间
+    # 我们采用类似的包络线方法，但进行固定采样
+    mrec = np.concatenate(([0.0], recall, [1.0]))
+    mpre = np.concatenate(([0.0], precision, [0.0]))
+
+    # 计算精度包络线 (单调递减)
+    # 对于每个 recall 值，取其右侧最大的 precision
+    for i in range(mpre.size - 1, 0, -1):
+        mpre[i - 1] = np.maximum(mpre[i - 1], mpre[i])
+
+    # 生成从 0.0 到 1.00 的 101 个召回率阈值
+    rec_thresholds = np.linspace(0.0, 1.00, 101)
+    
+    # 对于每个阈值 t，我们需要找到 recall >= t 时的最大 precision
+    # 由于 mpre[i] 已经是 recall >= mrec[i] 时的最大 precision，
+    # 我们只需要找到 mrec 中第一个大于等于 t 的位置。
+    inds = np.searchsorted(mrec, rec_thresholds, side='left')
+    
+    # 获取包络线上的值
+    q = mpre[inds]
+    
+    return float(np.mean(q))

easymetrics-0.1.0.dist-info/METADATA

@@ -0,0 +1,136 @@
+Metadata-Version: 2.4
+Name: EasyMetrics
+Version: 0.1.0
+Summary: 轻量级、零依赖的机器学习指标评估平台
+Author-email: EasyMetrics Team <team@easymetrics.example>
+License: MIT License
+        
+        Copyright (c) 2026 EasyMetrics Team
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: homepage, https://github.com/easymetrics/easymetrics
+Project-URL: documentation, https://easymetrics.readthedocs.io
+Project-URL: repository, https://github.com/easymetrics/easymetrics
+Project-URL: issues, https://github.com/easymetrics/easymetrics/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Provides-Extra: progress
+Requires-Dist: tqdm; extra == "progress"
+Dynamic: license-file
+
+# EasyMetrics
+
+一个轻量级、零依赖的机器学习指标评估平台，基于 `numpy` 从零构建，专注于提供简单易用且准确的模型评估工具。
+
+## ✨ 核心特性
+- **零依赖**: 仅需 Python 和 Numpy，无需安装大型深度学习框架
+- **易于扩展**: 模块化设计，通过继承 `Metric` 基类即可添加新任务
+- **功能强大**: 完美支持目标检测任务的全方位评估
+  - 标准 COCO 指标: mAP、mAP_50、mAP_75、mAP_s/m/l
+  - 平均召回率 (AR) 指标
+  - 每类别独立评估
+  - **独家功能**: 自动计算满足特定精度要求的最佳置信度阈值
+
+## � 目录结构
+```
+easyMetrics/
+├── easyMetrics/         # 核心代码
+│   ├── core/             # 抽象基类
+│   │   └── base.py
+│   └── tasks/            # 任务实现
+│       └── detection/    # 目标检测
+│           ├── interface.py # 对外接口
+│           ├── map.py     # mAP 核心逻辑
+│           ├── matcher.py # 匹配策略
+│           ├── utils.py   # 辅助函数
+│           └── format_converter.py # 格式转换器
+├── docs/                 # 文档
+│   ├── 使用指南.md
+│   └── 指标详解.md
+├── demo.py               # 使用示例
+└── README.md
+```
+
+## 🚀 快速上手
+
+### 目标检测评估
+
+使用 `evaluate_detection` 函数，一行代码完成评估：
+
+```python
+import numpy as np
+from easyMetrics.tasks.detection import evaluate_detection
+
+# 准备数据 - 每张图片一个字典
+preds = [{
+    'boxes': np.array([[10, 10, 50, 50]]),  # [x1, y1, x2, y2] 格式
+    'scores': np.array([0.9]),              # 置信度分数
+    'labels': np.array([0])                 # 类别索引
+}]
+targets = [{
+    'boxes': np.array([[10, 10, 50, 50]]),  # 真实边界框
+    'labels': np.array([0])                 # 真实类别
+}]
+
+# 1. 计算标准 COCO 指标
+results = evaluate_detection(preds, targets)
+print(f"mAP: {results['mAP']:.4f}")
+print(f"mAP_50: {results['mAP_50']:.4f}")
+
+# 2. 寻找最佳置信度阈值
+# 场景: IoU=0.5 时精度至少达到 90%
+results = evaluate_detection(
+    preds, targets, 
+    score_criteria=[(0.5, 0.9)]
+)
+print(f"推荐阈值: {results.get('BestScore_IoU0.50_P0.90_0')}")
+```
+
+### 并行加速
+
+对于大规模数据集，启用多核并行计算：
+
+```python
+# 使用 4 个核心
+results = evaluate_detection(preds, targets, n_jobs=4)
+
+# 使用所有可用核心
+results = evaluate_detection(preds, targets, n_jobs=-1)
+```
+
+## 🔧 扩展新任务
+
+添加新指标（例如分类任务的准确率）：
+
+1. 在 `easyMetrics/tasks/` 下创建新目录（如 `classification`）
+2. 继承 `easyMetrics.core.Metric` 基类
+3. 实现 `reset()`, `update()` 和 `compute()` 方法
+
+---
+*Created with ❤️ by EasyMetrics Team*

easymetrics-0.1.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+easyMetrics/__init__.py,sha256=QRWXyUWj4TDlsR-fmXUNs2Nu7VTuaU64OKk9AbPiCAA,100
+easyMetrics/core/__init__.py,sha256=L-JsvnYEbmJZPzf8oBbldRA-B6Oni3AtJaZZJEuDOwA,25
+easyMetrics/core/base.py,sha256=pMRZCl_SJtfCo-_fzuGijkYMSq1DDIZegI96EWxUX6k,789
+easyMetrics/tasks/__init__.py,sha256=Cwc3WM7ZgblWq1jfIjrHt_bBrJRobx4q_WbHn3LaN68,44
+easyMetrics/tasks/detection/__init__.py,sha256=74SsA-fJbamX7WGIWJJmeTXjjHnogYU1jwYse65d45U,80
+easyMetrics/tasks/detection/format_converter.py,sha256=EhGz-8j46bf5higaKyJmtqwILp8V2NtpiK0i-gOAgdE,11700
+easyMetrics/tasks/detection/interface.py,sha256=ZbR9aJVXsRiSNGrhcVZAEGkfH2SFX0kJi0XY_rUEbMA,2568
+easyMetrics/tasks/detection/map.py,sha256=F2qVDTQR1qr1SHEf3w3Xg7yvUytzfQtxXdF6p25CcwA,17471
+easyMetrics/tasks/detection/matcher.py,sha256=C-4hEVBJseQKgcHupBLlaDNFGhKxOxN-YdPNnpuit9I,2443
+easyMetrics/tasks/detection/utils.py,sha256=jNDPHxWzGo7478QDI1f8uVGK6HUlwvHlPbfwzEk-H0A,2770
+easymetrics-0.1.0.dist-info/licenses/LICENSE,sha256=Z-thSEoGCfxHrpC8rpgrqY-LSoJuyHbgPj5Gt8BuG_0,1073
+easymetrics-0.1.0.dist-info/METADATA,sha256=dHEOCgWpY4ECOtByCGk-0fJYz4lFYSq18oYnMCte4Eg,5265
+easymetrics-0.1.0.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+easymetrics-0.1.0.dist-info/top_level.txt,sha256=2ytZxZ9LMTdKpeZunCE1rpvkpDAhWeQLiiXTrFy9niw,12
+easymetrics-0.1.0.dist-info/RECORD,,

easymetrics-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.10.2)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

easymetrics-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 EasyMetrics Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

easymetrics-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+easyMetrics