EasyMetrics 0.1.0__tar.gz

easymetrics-0.1.0/EasyMetrics.egg-info/PKG-INFO

@@ -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/EasyMetrics.egg-info/SOURCES.txt

@@ -0,0 +1,22 @@
+LICENSE
+MANIFEST.in
+README.md
+pyproject.toml
+EasyMetrics.egg-info/PKG-INFO
+EasyMetrics.egg-info/SOURCES.txt
+EasyMetrics.egg-info/dependency_links.txt
+EasyMetrics.egg-info/requires.txt
+EasyMetrics.egg-info/top_level.txt
+docs/使用指南.md
+docs/指标详解.md
+easyMetrics/__init__.py
+easyMetrics/core/__init__.py
+easyMetrics/core/base.py
+easyMetrics/tasks/__init__.py
+easyMetrics/tasks/detection/__init__.py
+easyMetrics/tasks/detection/format_converter.py
+easyMetrics/tasks/detection/interface.py
+easyMetrics/tasks/detection/map.py
+easyMetrics/tasks/detection/matcher.py
+easyMetrics/tasks/detection/utils.py
+test/test_package.py

easymetrics-0.1.0/EasyMetrics.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

easymetrics-0.1.0/EasyMetrics.egg-info/requires.txt

@@ -0,0 +1,4 @@
+numpy
+
+[progress]
+tqdm

easymetrics-0.1.0/EasyMetrics.egg-info/top_level.txt

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

easymetrics-0.1.0/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/MANIFEST.in

@@ -0,0 +1,4 @@
+include README.md
+include LICENSE
+recursive-include docs *
+recursive-exclude *.pyc __pycache__/

easymetrics-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,90 @@
+# 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/docs//344/275/277/347/224/250/346/214/207/345/215/227.md

@@ -0,0 +1,253 @@
+# EasyMetrics 使用指南
+
+EasyMetrics 是一个轻量级、零依赖的机器学习指标评估平台，专注于提供简单易用且准确的模型评估工具。
+
+## 📦 安装与配置
+
+### 快速安装
+只需将 `easy_metrics` 文件夹复制到你的项目中，并确保安装了 `numpy`：
+
+```bash
+pip install numpy
+```
+
+## 🚀 核心功能使用
+
+### 1. 目标检测评估
+
+#### 基本用法
+
+```python
+import numpy as np
+from easyMetrics.tasks.detection import evaluate_detection
+
+# 准备数据 - 每张图片一个字典
+preds = [{
+    'boxes': np.array([[100, 100, 200, 200]]),  # [x1, y1, x2, y2] 格式
+    'scores': np.array([0.9]),                  # 置信度分数
+    'labels': np.array([0])                     # 类别索引
+}]
+targets = [{
+    'boxes': np.array([[100, 100, 200, 200]]),  # 真实边界框
+    'labels': np.array([0])                     # 真实类别
+}]
+
+# 评估并获取结果
+results = evaluate_detection(preds, targets)
+
+# 打印关键指标
+print(f"mAP: {results['mAP']:.4f}")
+print(f"mAP_50: {results['mAP_50']:.4f}")
+print(f"mAP_75: {results['mAP_75']:.4f}")
+print(f"AR_100: {results['AR_100']:.4f}")
+```
+
+#### 高级功能
+
+##### 1.1 寻找最佳置信度阈值
+
+**功能说明**：自动计算满足特定精度要求的最佳置信度阈值，帮助你确定模型上线时的阈值设置。
+
+**使用场景**：
+- 要求模型在 IoU=0.5 时精度至少达到 90%
+- 需要为不同类别设置不同的阈值
+
+**示例代码**：
+
+```python
+# 场景 1: 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}")
+
+# 场景 2: 多个精度要求
+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')
+```
+
+##### 1.2 并行加速计算
+
+**功能说明**：对于大规模数据集，启用多核并行计算以提高评估速度。
+
+**使用方法**：
+
+```python
+# 使用 4 个核心进行评估
+results = evaluate_detection(preds, targets, n_jobs=4)
+
+# 使用所有可用核心
+results = evaluate_detection(preds, targets, n_jobs=-1)
+```
+
+##### 1.3 自定义指标筛选
+
+**功能说明**：只计算你关心的指标，减少输出干扰，提高计算效率。
+
+**使用示例**：
+
+```python
+# 只计算 mAP 和 mAP_50
+results = evaluate_detection(preds, targets, metrics=['mAP', 'mAP_50'])
+print(results)
+
+# 只计算召回率相关指标
+results = evaluate_detection(preds, targets, metrics=['AR_100', 'AR_1000'])
+print(results)
+```
+
+## 📊 数据格式详解
+
+### 预测结果 (preds)
+
+`preds` 是一个列表，每个元素对应一张图片的预测结果，格式为字典：
+
+| 键名 | 类型 | 形状 | 说明 |
+|------|------|------|------|
+| `boxes` | numpy.ndarray | (N, 4) | 预测的边界框，格式为 `[x1, y1, x2, y2]` |
+| `scores` | numpy.ndarray | (N,) | 每个预测框的置信度分数 |
+| `labels` | numpy.ndarray | (N,) | 每个预测框的类别索引 (整数) |
+
+### 真实标签 (targets)
+
+`targets` 是一个列表，每个元素对应一张图片的真实标签，格式为字典：
+
+| 键名 | 类型 | 形状 | 说明 |
+|------|------|------|------|
+| `boxes` | numpy.ndarray | (M, 4) | 真实的边界框，格式为 `[x1, y1, x2, y2]` |
+| `labels` | numpy.ndarray | (M,) | 真实的类别索引 (整数) |
+
+### 数据格式示例
+
+```python
+# 两张图片的示例数据
+preds = [
+    # 图片 1 的预测
+    {
+        'boxes': np.array([[10, 10, 50, 50], [100, 100, 150, 150]]),
+        'scores': np.array([0.95, 0.8]),
+        'labels': np.array([0, 1])
+    },
+    # 图片 2 的预测
+    {
+        'boxes': np.array([[200, 200, 250, 250]]),
+        'scores': np.array([0.9]),
+        'labels': np.array([0])
+    }
+]
+
+targets = [
+    # 图片 1 的真实标签
+    {
+        'boxes': np.array([[10, 10, 50, 50], [100, 100, 150, 150]]),
+        'labels': np.array([0, 1])
+    },
+    # 图片 2 的真实标签
+    {
+        'boxes': np.array([[200, 200, 250, 250], [300, 300, 350, 350]]),
+        'labels': np.array([0, 1])
+    }
+]
+```
+
+## 🔧 扩展与定制
+
+### 添加新任务
+
+要添加新的评估任务（如分类、分割等）：
+
+1. 在 `easyMetrics/tasks/` 下创建新目录（例如 `classification`）
+2. 创建评估接口文件（例如 `interface.py`）
+3. 继承 `easyMetrics.core.Metric` 基类
+4. 实现 `reset()`, `update()` 和 `compute()` 方法
+
+### 自定义匹配策略
+
+EasyMetrics 支持自定义匹配策略，详情请参考源码中的 `matcher.py` 文件。
+
+## 📋 参数详解
+
+### 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" 时使用。 |
+
+#### 示例用法
+
+```python
+# 基本用法
+evaluate_detection(preds, targets)
+
+# 指定并行计算线程数
+evaluate_detection(preds, targets, n_jobs=4)
+
+# 只计算特定指标
+evaluate_detection(preds, targets, metrics=['mAP', 'mAP_50'])
+
+# 计算最佳置信度阈值
+evaluate_detection(preds, targets, score_criteria=[(0.5, 0.9)])
+
+# 使用不同格式的输入
+evaluate_detection(
+    preds, targets,
+    pred_format="yolo",    # 预测值使用 YOLO 格式
+    target_format="voc",    # 真值使用 VOC 格式
+    image_size=(640, 480)    # YOLO 格式需要的图像尺寸
+)
+
+# 禁用进度条
+evaluate_detection(preds, targets, progress=False)
+```
+
+## 💡 实用技巧
+
+1. **数据预处理**：确保输入的边界框坐标格式正确（`[x1, y1, x2, y2]`），且为浮点数类型。
+
+2. **类别索引**：确保预测结果和真实标签使用相同的类别索引体系。
+
+3. **性能优化**：
+   - 对于大规模数据集，使用 `n_jobs=-1` 启用并行计算
+   - 使用 `metrics` 参数只计算需要的指标
+
+4. **结果分析**：
+   - 关注 `mAP_50` 指标评估模型在宽松条件下的性能
+   - 关注 `mAP_75` 指标评估模型在严格条件下的性能
+   - 使用 `AR_100` 评估模型的召回能力
+
+## 📚 相关文档
+
+- **指标详解.md**：详细介绍各种评估指标的计算原理
+- **README.md**：项目概述和快速开始指南