EasyMetrics 0.3.0__py3-none-any.whl → 0.4.0__py3-none-any.whl

easyMetrics/tasks/detection/map.py

@@ -139,9 +139,78 @@ class MeanAveragePrecision(Metric):
         # 1. 识别所有唯一类别
         unique_classes = set()
         for t in self.targets:
-            unique_classes.update(t['labels'].tolist())
+            labels = t['labels']
+            # 处理不同类型的 labels 输入
+            try:
+                if isinstance(labels, list):
+                    # 处理列表情况
+                    for label in labels:
+                        if isinstance(label, list):
+                            # 处理嵌套列表情况
+                            for l in label:
+                                unique_classes.add(l)
+                        else:
+                            unique_classes.add(label)
+                else:
+                    try:
+                        # 假设是 numpy 数组
+                        label_list = labels.tolist()
+                        if isinstance(label_list, list):
+                            for label in label_list:
+                                if isinstance(label, list):
+                                    # 处理嵌套列表情况
+                                    for l in label:
+                                        unique_classes.add(l)
+                                else:
+                                    unique_classes.add(label)
+                        else:
+                            # 处理标量情况
+                            unique_classes.add(label_list)
+                    except AttributeError:
+                        # 处理标量情况
+                        unique_classes.add(labels)
+            except Exception as e:
+                # 捕获所有异常，确保程序不会崩溃
+                print(f"处理 labels 时出错: {e}")
+                print(f"labels 类型: {type(labels)}")
+                print(f"labels 值: {labels}")
+        
         for p in self.preds:
-            unique_classes.update(p['labels'].tolist())
+            labels = p['labels']
+            # 处理不同类型的 labels 输入
+            try:
+                if isinstance(labels, list):
+                    # 处理列表情况
+                    for label in labels:
+                        if isinstance(label, list):
+                            # 处理嵌套列表情况
+                            for l in label:
+                                unique_classes.add(l)
+                        else:
+                            unique_classes.add(label)
+                else:
+                    try:
+                        # 假设是 numpy 数组
+                        label_list = labels.tolist()
+                        if isinstance(label_list, list):
+                            for label in label_list:
+                                if isinstance(label, list):
+                                    # 处理嵌套列表情况
+                                    for l in label:
+                                        unique_classes.add(l)
+                                else:
+                                    unique_classes.add(label)
+                        else:
+                            # 处理标量情况
+                            unique_classes.add(label_list)
+                    except AttributeError:
+                        # 处理标量情况
+                        unique_classes.add(labels)
+            except Exception as e:
+                # 捕获所有异常，确保程序不会崩溃
+                print(f"处理 labels 时出错: {e}")
+                print(f"labels 类型: {type(labels)}")
+                print(f"labels 值: {labels}")
         
         sorted_classes = sorted(list(unique_classes))
         
@@ -291,71 +360,170 @@ class MeanAveragePrecision(Metric):
 
         # 收集 GT
         for img_idx, target in enumerate(self.targets):
-            mask = target['labels'] == cls_id
-            boxes = target['boxes'][mask]
-            
-            # 检查 boxes 是否为空
-            if len(boxes) == 0:
-                n_pos += 0
+            try:
+                labels = target['labels']
+                boxes = target['boxes']
+                
+                # 处理 labels 是标量的情况
+                if np.isscalar(labels):
+                    if labels == cls_id:
+                        # 如果是标量且匹配，使用所有 boxes
+                        mask = True
+                    else:
+                        # 如果是标量且不匹配，使用空 mask
+                        mask = False
+                else:
+                    # 处理 labels 是二维数组的情况
+                    if labels.ndim == 2:
+                        # 展平二维数组为一维
+                        labels = labels.flatten()
+                    # 正常情况，labels 是一维数组
+                    mask = labels == cls_id
+                
+                # 应用 mask
+                if isinstance(mask, bool):
+                    if mask:
+                        # 如果是 True，使用所有 boxes
+                        filtered_boxes = boxes
+                    else:
+                        # 如果是 False，使用空 boxes
+                        filtered_boxes = np.array([])
+                else:
+                    # 正常情况，mask 是数组
+                    filtered_boxes = boxes[mask]
+                
+                # 检查 filtered_boxes 是否为空
+                if len(filtered_boxes) == 0:
+                    n_pos += 0
+                    class_gt[img_idx] = {
+                        'boxes': np.array([]),
+                        'used': np.array([], dtype=bool)
+                    }
+                    continue
+                
+                # 确保 filtered_boxes 是二维数组
+                if filtered_boxes.ndim == 1:
+                    if len(filtered_boxes) == 4:
+                        # 如果是一维数组且长度为 4，说明是单个边界框
+                        filtered_boxes = filtered_boxes.reshape(1, 4)
+                    else:
+                        # 如果是一维数组且长度不为 4，说明是空的或者格式不对，跳过
+                        n_pos += 0
+                        class_gt[img_idx] = {
+                            'boxes': np.array([]),
+                            'used': np.array([], dtype=bool)
+                        }
+                        continue
+                
+                areas = (filtered_boxes[:, 2] - filtered_boxes[:, 0]) * (filtered_boxes[:, 3] - filtered_boxes[:, 1])
+                valid_area_mask = (areas >= min_area) & (areas < max_area)
+                valid_boxes = filtered_boxes[valid_area_mask]
+                
+                n_pos += len(valid_boxes)
                 class_gt[img_idx] = {
-                    'boxes': np.array([]),
-                    'used': np.array([], dtype=bool)
+                    'boxes': valid_boxes,
+                    'used': np.zeros(len(valid_boxes), dtype=bool)
                 }
-                continue
-            
-            # 确保 boxes 是二维数组
-            if boxes.ndim == 1:
-                # 如果是一维数组，说明是空的或者格式不对，跳过
+            except Exception as e:
+                # 捕获所有异常，确保程序不会崩溃
+                print(f"处理 GT 数据时出错: {e}")
+                print(f"img_idx: {img_idx}")
+                print(f"labels 类型: {type(labels)}")
+                print(f"labels 值: {labels}")
+                print(f"boxes 类型: {type(boxes)}")
+                print(f"boxes 值: {boxes}")
+                # 使用空数据继续
                 n_pos += 0
                 class_gt[img_idx] = {
                     'boxes': np.array([]),
                     'used': np.array([], dtype=bool)
                 }
                 continue
-            
-            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]
-            
-            # 检查 boxes 是否为空
-            if len(boxes) == 0:
-                continue
-            
-            # 确保 boxes 是二维数组
-            if boxes.ndim == 1:
-                # 如果是一维数组，说明是空的或者格式不对，跳过
+            try:
+                labels = pred['labels']
+                scores = pred['scores']
+                boxes = pred['boxes']
+                
+                # 处理 labels 是标量的情况
+                if np.isscalar(labels):
+                    if labels == cls_id:
+                        # 如果是标量且匹配，使用所有 scores 和 boxes
+                        mask = True
+                    else:
+                        # 如果是标量且不匹配，使用空 mask
+                        mask = False
+                else:
+                    # 处理 labels 是二维数组的情况
+                    if labels.ndim == 2:
+                        # 展平二维数组为一维
+                        labels = labels.flatten()
+                    # 正常情况，labels 是一维数组
+                    mask = labels == cls_id
+                
+                # 应用 mask
+                if isinstance(mask, bool):
+                    if mask:
+                        # 如果是 True，使用所有 scores 和 boxes
+                        filtered_scores = scores
+                        filtered_boxes = boxes
+                    else:
+                        # 如果是 False，使用空 scores 和 boxes
+                        filtered_scores = np.array([])
+                        filtered_boxes = np.array([])
+                else:
+                    # 正常情况，mask 是数组
+                    filtered_scores = scores[mask]
+                    filtered_boxes = boxes[mask]
+                
+                # 检查 filtered_boxes 是否为空
+                if len(filtered_boxes) == 0:
+                    continue
+                
+                # 确保 filtered_boxes 是二维数组
+                if filtered_boxes.ndim == 1:
+                    if len(filtered_boxes) == 4:
+                        # 如果是一维数组且长度为 4，说明是单个边界框
+                        filtered_boxes = filtered_boxes.reshape(1, 4)
+                        # 确保 filtered_scores 也是一维数组
+                        if np.isscalar(filtered_scores):
+                            filtered_scores = np.array([filtered_scores])
+                    else:
+                        # 如果是一维数组且长度不为 4，说明是空的或者格式不对，跳过
+                        continue
+                
+                areas = (filtered_boxes[:, 2] - filtered_boxes[:, 0]) * (filtered_boxes[:, 3] - filtered_boxes[:, 1])
+                valid_area_mask = (areas >= min_area) & (areas < max_area)
+                
+                filtered_scores = filtered_scores[valid_area_mask]
+                filtered_boxes = filtered_boxes[valid_area_mask]
+                
+                if len(filtered_scores) > 0:
+                    order = np.argsort(-filtered_scores)
+                    sorted_scores = filtered_scores[order][:limit_dets]
+                    sorted_boxes = filtered_boxes[order][:limit_dets]
+                    ranks = np.arange(len(sorted_scores))
+                else:
+                    sorted_scores, sorted_boxes, ranks = [], [], []
+                
+                for s, b, r in zip(sorted_scores, sorted_boxes, ranks):
+                    class_preds.append((s, img_idx, b, r))
+            except Exception as e:
+                # 捕获所有异常，确保程序不会崩溃
+                print(f"处理预测值时出错: {e}")
+                print(f"img_idx: {img_idx}")
+                print(f"labels 类型: {type(labels)}")
+                print(f"labels 值: {labels}")
+                print(f"scores 类型: {type(scores)}")
+                print(f"scores 值: {scores}")
+                print(f"boxes 类型: {type(boxes)}")
+                print(f"boxes 值: {boxes}")
+                # 跳过这个预测，继续处理下一个
                 continue
-            
-            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)

easymetrics-0.4.0.dist-info/METADATA

@@ -0,0 +1,561 @@
+Metadata-Version: 2.4
+Name: EasyMetrics
+Version: 0.4.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
+
+一个轻量级、零依赖的机器学习指标评估平台，专注于提供简单易用且准确的模型评估工具。
+
+## ✨ 核心特性
+
+### 🔧 设计理念
+- **零依赖**: 仅依赖 Python 和 numpy，无需安装大型深度学习框架
+- **模块化架构**: 清晰的代码结构，易于扩展和定制
+- **用户友好**: 简洁的 API 设计，一行代码完成评估
+- **性能优化**: 支持并行计算，大幅提升评估速度
+
+### 📊 功能特性
+
+#### 目标检测评估
+- **完整的 COCO 指标支持**:
+  - mAP (IoU 0.5:0.95) - 综合评估指标
+  - mAP_50 (IoU 0.5) - 宽松条件下的性能
+  - mAP_75 (IoU 0.75) - 严格条件下的性能
+  - mAP_s/m/l - 不同尺度目标的性能
+  - AR_1, AR_10, AR_100 - 不同最大检测数下的召回率
+- **每类别独立评估**: 详细的类别级指标
+- **独家功能**: 自动计算满足特定精度要求的最佳置信度阈值
+
+#### 数据格式支持
+- **多种输入格式**: 支持 COCO、VOC、YOLO 等常见格式
+- **自动类型转换**: 支持标量、列表、numpy 数组等多种输入类型
+- **灵活的格式指定**: 可分别指定预测值和真值的格式
+- **智能格式检测**: 自动识别常见的数据格式
+
+#### 用户体验
+- **进度条功能**: 直观展示评估进度，可选择禁用
+- **并行计算**: 支持多核并行加速，可指定线程数
+- **详细的指标解释**: 提供清晰的指标含义说明
+- **丰富的示例代码**: 覆盖各种使用场景
+- **错误处理**: 完善的边界情况处理和错误提示
+
+### 🎯 技术优势
+- **高精度计算**: 采用 COCO 标准的 101 点插值法，计算更准确
+- **多尺度评估**: 支持对不同大小目标的独立评估
+- **内存优化**: 高效的内存管理，支持大规模数据集
+- **扩展性强**: 模块化设计，易于添加新的评估任务
+
+## 📋 参数详解
+
+### evaluate_detection 函数参数说明
+
+#### 核心参数
+
+| 参数名 | 类型 | 默认值 | 说明 |
+| :--- | :--- | :--- | :--- |
+| **preds** | List[Any] | 必填 | 每张图片的预测结果列表。支持多种格式，具体取决于 `format` 或 `pred_format` 参数。 |
+| **targets** | List[Any] | 必填 | 每张图片的真实标签列表。支持多种格式，具体取决于 `format` 或 `target_format` 参数。 |
+| **metrics** | Optional[List[str]] | None | 需要返回的特定指标列表。如果为 None，则返回所有计算的指标。 |
+| **n_jobs** | int | 1 | 并行计算线程数。1 表示串行计算，-1 表示使用所有可用 CPU 核心。 |
+| **score_criteria** | Optional[List[Tuple[float, float]]] | None | 计算指定 IoU 和精度下的最佳置信度阈值。格式为 `[(iou_thresh, min_precision), ...]`，例如 `[(0.5, 0.9)]` 表示寻找 IoU=0.5 时精度至少为 0.9 的最低置信度。 |
+| **progress** | bool | True | 是否显示进度条。默认为 True，在计算过程中显示评估进度。 |
+
+#### 格式参数
+
+| 参数名 | 类型 | 默认值 | 说明 |
+| :--- | :--- | :--- | :--- |
+| **format** | str | "coco" | 输入数据的默认格式，当 `pred_format` 和 `target_format` 未指定时使用。支持 "coco", "voc", "yolo", "custom"。 |
+| **pred_format** | Optional[str] | None | 预测结果的格式，优先级高于 `format`。 |
+| **target_format** | Optional[str] | None | 真实标签的格式，优先级高于 `format`。 |
+
+#### 额外参数（**kwargs）
+
+| 参数名 | 类型 | 默认值 | 说明 |
+| :--- | :--- | :--- | :--- |
+| **image_size** | Tuple[int, int] | (640, 640) | YOLO 格式需要的图像尺寸 (width, height)，用于将归一化坐标转换为绝对坐标。 |
+| **custom_converter** | Callable | None | 自定义格式的转换函数，当 `format` 为 "custom" 时使用。 |
+
+## 📦 安装方法
+
+### 从 PyPI 安装 (推荐)
+
+```bash
+pip install EasyMetrics
+```
+
+### 从 GitHub 安装
+
+```bash
+pip install git+https://github.com/Lucidyn/EasyMetrics.git
+```
+
+### 依赖项
+- **核心依赖**: numpy >= 1.17.0
+- **可选依赖**: tqdm (用于进度条)
+
+## 🚀 快速上手
+
+### 基本用法
+
+一行代码完成目标检测评估：
+
+```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.95]),              # 置信度分数
+    'labels': np.array([0])                 # 类别索引
+}]
+
+targets = [{
+    'boxes': np.array([[10, 10, 50, 50]]),  # 真实边界框
+    'labels': np.array([0])                 # 真实类别
+}]
+
+# 执行评估
+results = evaluate_detection(preds, targets)
+
+# 查看结果
+print(f"mAP (IoU 0.5:0.95): {results['mAP']:.4f}")
+print(f"mAP_50 (IoU 0.5): {results['mAP_50']:.4f}")
+print(f"mAP_75 (IoU 0.75): {results['mAP_75']:.4f}")
+print(f"AR_100 (MaxDets=100): {results['AR_100']:.4f}")
+```
+
+### 完整示例
+
+下面是一个更完整的示例，包含多个图片的评估：
+
+```python
+import numpy as np
+from easyMetrics.tasks.detection import evaluate_detection
+
+# 准备数据 - 假设有 2 张图片
+
+# 图片 1: 预测完全正确
+preds_1 = {
+    'boxes': np.array([[10, 10, 50, 50]]),
+    'scores': np.array([0.95]),
+    'labels': np.array([0])
+}
+targets_1 = {
+    'boxes': np.array([[10, 10, 50, 50]]),
+    'labels': np.array([0])
+}
+
+# 图片 2: 有一个误检 (FP) 和一个漏检 (FN)
+preds_2 = {
+    'boxes': np.array([[100, 100, 150, 150], [0, 0, 20, 20]]),
+    'scores': np.array([0.9, 0.6]),
+    'labels': np.array([0, 0])
+}
+targets_2 = {
+    'boxes': np.array([[100, 100, 150, 150], [200, 200, 250, 250]]),
+    'labels': np.array([0, 0])
+}
+
+preds = [preds_1, preds_2]
+targets = [targets_1, targets_2]
+
+# 执行评估
+results = evaluate_detection(preds, targets)
+
+# 查看结果
+print(f"mAP (IoU 0.5:0.95): {results['mAP']:.4f}")
+print(f"mAP_50 (IoU 0.5): {results['mAP_50']:.4f}")
+print(f"mAP_75 (IoU 0.75): {results['mAP_75']:.4f}")
+print(f"AR_100 (MaxDets=100): {results['AR_100']:.4f}")
+```
+
+### 并行计算
+
+对于大规模数据集，启用并行计算加速：
+
+```python
+# 使用 4 个核心
+results = evaluate_detection(preds, targets, n_jobs=4)
+
+# 使用所有可用核心
+results = evaluate_detection(preds, targets, n_jobs=-1)
+```
+
+### 寻找最佳阈值
+
+自动计算满足特定精度要求的最佳置信度阈值：
+
+```python
+# 场景: IoU=0.5 时精度至少达到 90%
+results = evaluate_detection(
+    preds, targets,
+    score_criteria=[(0.5, 0.9)]  # 格式: [(iou阈值, 最低精度要求)]
+)
+
+# 获取类别 0 的最佳阈值
+best_thresh = results.get('BestScore_IoU0.50_P0.90_0')
+print(f"类别 0 的推荐阈值: {best_thresh}")
+
+# 场景: 多个精度要求
+results = evaluate_detection(
+    preds, targets,
+    score_criteria=[(0.5, 0.9), (0.75, 0.8)]
+)
+
+# 获取不同要求下的阈值
+best_thresh_50 = results.get('BestScore_IoU0.50_P0.90_0')
+best_thresh_75 = results.get('BestScore_IoU0.75_P0.80_0')
+print(f"IoU=0.5, P>=0.9 阈值: {best_thresh_50}")
+print(f"IoU=0.75, P>=0.8 阈值: {best_thresh_75}")
+```
+
+### 自定义指标筛选
+
+只计算你关心的指标，减少输出干扰，提高计算效率：
+
+```python
+# 只计算 mAP 和 mAP_50
+results = evaluate_detection(preds, targets, metrics=['mAP', 'mAP_50'])
+print(results)
+
+# 只计算召回率相关指标
+results = evaluate_detection(preds, targets, metrics=['AR_100'])
+print(results)
+```
+
+### 多种数据格式
+
+支持多种输入格式，包括 COCO、VOC、YOLO 等：
+
+```python
+# VOC 格式示例
+preds_voc = [[10, 10, 50, 50, 0, 0.95]]  # [x1, y1, x2, y2, class_id, confidence]
+targets_voc = [[10, 10, 50, 50, 0]]  # [x1, y1, x2, y2, class_id]
+
+results = evaluate_detection(
+    [preds_voc], [targets_voc],
+    pred_format="voc",
+    target_format="voc"
+)
+print(f"VOC 格式评估结果: {results['mAP']:.4f}")
+
+# YOLO 格式示例
+# YOLO 格式: [class_id, x_center, y_center, width, height, confidence]
+# 注意: 坐标是归一化的 (0-1)
+preds_yolo = [[0, 0.5, 0.5, 0.2, 0.2, 0.95]]
+targets_yolo = [[0, 0.5, 0.5, 0.2, 0.2]]
+
+results = evaluate_detection(
+    [preds_yolo], [targets_yolo],
+    pred_format="yolo",
+    target_format="yolo",
+    image_size=(640, 640)  # YOLO 格式需要的图像尺寸
+)
+print(f"YOLO 格式评估结果: {results['mAP']:.4f}")
+
+# 混合格式示例
+# 预测值使用 YOLO 格式，真值使用 VOC 格式
+results = evaluate_detection(
+    [preds_yolo], [targets_voc],
+    pred_format="yolo",
+    target_format="voc",
+    image_size=(640, 640)
+)
+print(f"混合格式评估结果: {results['mAP']:.4f}")
+```
+
+### 灵活的输入格式
+
+支持标量、列表等多种输入类型：
+
+```python
+# 标量输入示例 (单目标情况)
+preds_scalar = {'boxes': [10, 10, 50, 50], 'scores': 0.95, 'labels': 0}
+targets_scalar = {'boxes': [10, 10, 50, 50], 'labels': [0]}
+
+results = evaluate_detection([preds_scalar], [targets_scalar])
+print(f"标量输入评估结果: {results['mAP']:.4f}")
+
+# 列表输入示例
+preds_list = {
+    'boxes': [[10, 10, 50, 50], [100, 100, 150, 150]],
+    'scores': [0.95, 0.9],
+    'labels': [0, 0]
+}
+targets_list = {
+    'boxes': [[10, 10, 50, 50], [100, 100, 150, 150]],
+    'labels': [0, 0]
+}
+
+results = evaluate_detection([preds_list], [targets_list])
+print(f"列表输入评估结果: {results['mAP']:.4f}")
+```
+
+### 进度条控制
+
+控制是否显示评估进度条：
+
+```python
+# 启用进度条 (默认)
+results = evaluate_detection(preds, targets, progress=True)
+
+# 禁用进度条
+results = evaluate_detection(preds, targets, progress=False)
+```
+
+### 多类别评估
+
+评估包含多个类别的检测结果：
+
+```python
+# 多类别示例
+preds_multi = [{
+    'boxes': np.array([[10, 10, 50, 50], [100, 100, 150, 150]]),
+    'scores': np.array([0.95, 0.9]),
+    'labels': np.array([0, 1])  # 两个不同的类别
+}]
+targets_multi = [{
+    'boxes': np.array([[10, 10, 50, 50], [100, 100, 150, 150]]),
+    'labels': np.array([0, 1])  # 两个不同的类别
+}]
+
+results = evaluate_detection(preds_multi, targets_multi)
+print(f"多类别评估 mAP: {results['mAP']:.4f}")
+print(f"类别 0 的 AP: {results['AP_0']:.4f}")
+print(f"类别 1 的 AP: {results['AP_1']:.4f}")
+```
+
+## 📋 目录结构
+
+```
+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             # 项目概述
+├── pyproject.toml        # 项目配置
+└── LICENSE               # 许可证
+```
+
+## 📚 详细文档
+
+- **使用指南.md**: 详细的安装、配置和使用说明，包含各种功能的完整示例
+- **指标详解.md**: 详细介绍各种评估指标的计算原理和含义
+- **demo.py**: 完整的代码示例，覆盖所有主要功能
+
+## � 指标详解
+
+### 平均精度 (Average Precision, AP)
+
+AP 是目标检测中最重要的指标，它综合了**精度 (Precision)** 和 **召回率 (Recall)**。
+
+- **Precision (查准率)**: 预测为正样本中，真正正确的比例。 $P = \frac{TP}{TP + FP}$
+- **Recall (查全率)**: 所有真实正样本中，被正确预测出的比例。 $R = \frac{TP}{TP + FN}$
+
+我们使用 **IoU (Intersection over Union)** 来判定预测框是否正确。如果 `IoU(Pred, GT) >= 阈值`，则视为 TP (True Positive)。
+
+### 主要指标
+
+| 指标键名 | 含义 | 详细解释 |
+| :--- | :--- | :--- |
+| **mAP** | **平均 AP** | **最重要的综合指标**。它是在 IoU 阈值从 0.50 到 0.95（步长 0.05）共 10 个阈值下计算出的 AP 的平均值，并且对所有类别取平均。它反映了模型在不同严格程度下的综合表现。在 COCO 竞赛中简称为 AP。 |
+| **mAP_50** | IoU=0.50 的 mAP | PASCAL VOC 竞赛的标准指标。只要求 IoU > 0.5 就算正确，相对宽松。 |
+| **mAP_75** | IoU=0.75 的 mAP | 严格模式下的指标。要求检测框与真值重叠度很高才算正确。 |
+| **AP_<class_id>** | 特定类别的 AP | 该类别的 Average Precision (IoU 0.5:0.95)。 |
+| **AP_50_<class_id>** | 特定类别的 AP@50 | 该类别在 IoU=0.50 下的 AP。 |
+| **AP_75_<class_id>** | 特定类别的 AP@75 | 该类别在 IoU=0.75 下的 AP。 |
+
+### 不同尺度的 AP
+
+为了分析模型对不同大小物体的检测能力，我们将物体按面积（像素数）分为三类：
+
+| 指标键名 | 含义 | 定义 (面积 = 宽 × 高) |
+| :--- | :--- | :--- |
+| **mAP_s** | 小目标 mAP | 面积 < $32^2$ (小于 1024 像素) |
+| **mAP_m** | 中目标 mAP | $32^2 \le$ 面积 < $96^2$ (1024 ~ 9216 像素) |
+| **mAP_l** | 大目标 mAP | 面积 $\ge 96^2$ (大于 9216 像素) |
+
+通常小目标检测 (mAP_s) 是最难的。
+
+### 平均召回率 (Average Recall, AR)
+
+AR 反映了模型发现目标的能力，不考虑分数的排序，主要关注有多少真值被覆盖了。
+
+EasyMetrics 按照每张图片允许的最大检测数 (Max Dets) 来计算 AR：
+
+| 指标键名 | 含义 | 详细解释 |
+| :--- | :--- | :--- |
+| **AR_1** | MaxDets=1 的 AR | 每张图只取置信度最高的 1 个框来计算召回率。 |
+| **AR_10** | MaxDets=10 的 AR | 每张图取前 10 个框计算召回率。 |
+| **AR_100** | MaxDets=100 的 AR | 每张图取前 100 个框计算召回率。通常接近模型能达到的召回率上限。 |
+
+### 计算细节
+
+1. **101点插值法**:
+   我们在计算 AP 时，采用 COCO 标准的 101 点插值法。即在 recall = [0.00, 0.01, ..., 1.00] 这 101 个点上取对应的最大 precision 并求平均。这比传统的 11 点插值法更精确。
+
+2. **多尺度评估逻辑**:
+   - 计算 `mAP_s` 时，我们只保留真实面积在 `[0, 32^2)` 范围内的 GT，并且只考虑面积在该范围内的预测框。
+   - 如果某张图片没有该尺度的目标，则不参与该尺度的计算。
+
+### 最佳阈值推荐 (Best Score Suggestion)
+
+EasyMetrics 支持根据指定的精度 (Precision) 要求，自动寻找最佳的置信度阈值。这对于实际部署模型时设定阈值非常有帮助。
+
+| 指标键名 | 含义 | 详细解释 |
+| :--- | :--- | :--- |
+| **BestScore_IoU0.50_P0.90_<class_id>** | 满足精度要求的最低阈值 | 在 IoU=0.50 的评估标准下，为了让该类别的预测精度达到 90%，建议设置的最低置信度阈值。 |
+
+### 如何选择评估指标
+
+- **如果只看一个数**: 关注 **mAP**。
+- **如果定位精度很重要**: 关注 **mAP_75**。
+- **如果漏检代价很大** (如自动驾驶): 关注 **AR_100**。
+- **如果发现小物体检测很差**: 关注 **mAP_s**，可能需要调整数据增强或模型结构。
+
+## � 扩展与定制
+
+### 添加新任务
+
+要添加新的评估任务（如分类、分割等）：
+
+1. 在 `easyMetrics/tasks/` 下创建新目录
+2. 创建评估接口文件
+3. 继承 `easyMetrics.core.Metric` 基类
+4. 实现 `reset()`, `update()` 和 `compute()` 方法
+
+### 自定义匹配策略
+
+EasyMetrics 支持自定义匹配策略，详情请参考源码中的 `matcher.py` 文件。
+
+## 🎯 版本历史
+
+### v0.4.0 (2026-02-05)
+- **增强批量处理能力**: 支持批量 YOLO 格式数据的处理
+- **修复标签处理**: 完善对二维标签数组的处理
+- **提升鲁棒性**: 增强对各种边缘情况的处理能力
+- **优化性能**: 改进并行计算效率
+- **完善文档**: 添加批量 YOLO 格式数据示例
+
+### v0.3.0 (2026-02-05)
+- **增强类型兼容性**: 支持标量、列表、numpy 数组等多种输入类型
+- **修复边界情况**: 优化空数据、只有预测/目标等特殊情况的处理
+- **提升稳定性**: 修复索引错误和类型转换错误
+- **增强格式支持**: 完善对不同输入格式的处理
+- **改进用户体验**: 添加进度条功能，可选择禁用
+- **完善文档**: 更新使用指南和指标详解
+
+### v0.2.0 (2026-02-05)
+- **修复类型转换**: 解决标量输入的处理问题
+- **提升稳定性**: 优化类型转换逻辑
+- **添加格式支持**: 支持 COCO、VOC、YOLO 等多种输入格式
+- **添加并行计算**: 支持多核并行加速
+
+### v0.1.0 (2026-02-05)
+- **初始版本**: 发布核心功能
+- **目标检测评估**: 支持完整的 COCO 指标
+- **最佳阈值计算**: 支持自动计算最佳置信度阈值
+- **基础格式支持**: 支持 COCO 格式输入
+
+## 💡 实用技巧
+
+1. **数据预处理**：确保输入的边界框坐标格式正确（`[x1, y1, x2, y2]`），且为浮点数类型。
+
+2. **类别索引**：确保预测结果和真实标签使用相同的类别索引体系。
+
+3. **性能优化**：
+   - 对于大规模数据集，使用 `n_jobs=-1` 启用并行计算
+   - 使用 `metrics` 参数只计算需要的指标
+
+4. **结果分析**：
+   - 关注 `mAP_50` 指标评估模型在宽松条件下的性能
+   - 关注 `mAP_75` 指标评估模型在严格条件下的性能
+   - 使用 `AR_100` 评估模型的召回能力
+   - 使用 `mAP_s`/`mAP_m`/`mAP_l` 分析模型对不同尺度目标的表现
+
+5. **格式选择**：
+   - 对于标准场景，使用默认的 COCO 格式
+   - 对于与其他框架集成，可选择 VOC 或 YOLO 格式
+   - 对于特殊需求，可使用自定义格式转换函数
+
+## 🤝 贡献指南
+
+欢迎贡献代码和提出建议！
+
+1. **Fork 项目**
+2. **创建特性分支**
+3. **提交更改**
+4. **发起 Pull Request**
+
+### 开发规范
+
+- **代码风格**：遵循 PEP 8 规范
+- **测试**：为新功能添加测试用例
+- **文档**：更新相关文档
+- **提交信息**：清晰、简洁的提交信息
+
+## 📄 许可证
+
+EasyMetrics 使用 MIT 许可证，详见 LICENSE 文件。
+
+## 📞 联系我们
+
+如有问题或建议，欢迎通过 GitHub Issues 提出。
+
+---
+
+*Created with ❤️ by EasyMetrics Team*

{easymetrics-0.3.0.dist-info → easymetrics-0.4.0.dist-info}/RECORD

@@ -5,11 +5,11 @@ easyMetrics/tasks/__init__.py,sha256=Cwc3WM7ZgblWq1jfIjrHt_bBrJRobx4q_WbHn3LaN68
 easyMetrics/tasks/detection/__init__.py,sha256=74SsA-fJbamX7WGIWJJmeTXjjHnogYU1jwYse65d45U,80
 easyMetrics/tasks/detection/format_converter.py,sha256=80vM8B3exuH6EHlmYwvMrpslTDm-FMWzuccQKka42dc,12632
 easyMetrics/tasks/detection/interface.py,sha256=ZbR9aJVXsRiSNGrhcVZAEGkfH2SFX0kJi0XY_rUEbMA,2568
-easyMetrics/tasks/detection/map.py,sha256=UhdBkuGMCq0Bib6hvxFXidLSn3aV9lu_thPMgPSGdVQ,20052
+easyMetrics/tasks/detection/map.py,sha256=9n5m-XzKKHLNY8JIwrXK4qoDnKiANu9Wfx5wbzwfeKM,28346
 easyMetrics/tasks/detection/matcher.py,sha256=C-4hEVBJseQKgcHupBLlaDNFGhKxOxN-YdPNnpuit9I,2443
 easyMetrics/tasks/detection/utils.py,sha256=jNDPHxWzGo7478QDI1f8uVGK6HUlwvHlPbfwzEk-H0A,2770
-easymetrics-0.3.0.dist-info/licenses/LICENSE,sha256=Z-thSEoGCfxHrpC8rpgrqY-LSoJuyHbgPj5Gt8BuG_0,1073
-easymetrics-0.3.0.dist-info/METADATA,sha256=dmxyFGewhHcYNhnZPCPYUN4U6QjsRHnhS7Wnqo5WRso,5265
-easymetrics-0.3.0.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
-easymetrics-0.3.0.dist-info/top_level.txt,sha256=2ytZxZ9LMTdKpeZunCE1rpvkpDAhWeQLiiXTrFy9niw,12
-easymetrics-0.3.0.dist-info/RECORD,,
+easymetrics-0.4.0.dist-info/licenses/LICENSE,sha256=Z-thSEoGCfxHrpC8rpgrqY-LSoJuyHbgPj5Gt8BuG_0,1073
+easymetrics-0.4.0.dist-info/METADATA,sha256=1itPd_H84kueDwaJY_dx3_1ByHbRc8ycOKVlAGPFL8k,21146
+easymetrics-0.4.0.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+easymetrics-0.4.0.dist-info/top_level.txt,sha256=2ytZxZ9LMTdKpeZunCE1rpvkpDAhWeQLiiXTrFy9niw,12
+easymetrics-0.4.0.dist-info/RECORD,,

easymetrics-0.3.0.dist-info/METADATA

@@ -1,136 +0,0 @@
-Metadata-Version: 2.4
-Name: EasyMetrics
-Version: 0.3.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*