# 自动驾驶评估系统

## 系统概述

本系统是一个模块化的自动驾驶评估框架，用于对自动驾驶系统的各项性能指标进行全面评估。系统采用组件化设计，支持内置指标和自定义指标的灵活配置，能够并行处理多种评估任务，并生成结构化的评估报告。

## 系统架构

系统由以下核心组件构成：

### 1. 配置管理器 (ConfigManager)

负责加载、解析和合并配置文件，支持内置指标配置和自定义指标配置的智能合并。主要功能包括：
- 配置文件加载与解析
- 内置配置与自定义配置的合并
- 配置拆分（从全量配置中提取自定义部分）

**配置管理特性：**
- **自动拆分功能**：能够从全量配置文件(all_metrics_config.yaml)中自动提取出自定义指标部分，生成独立的自定义配置文件(custom_metrics_config.yaml)
- **智能合并策略**：采用三级合并策略，确保自定义指标配置能够正确覆盖或扩展内置指标配置
- **结构完整性保障**：在拆分过程中保留指标的name和priority等关键属性，确保配置结构完整

### 2. 指标加载器 (MetricLoader)

负责动态加载内置和自定义评估指标模块。主要功能包括：
- 内置指标模块的动态加载
- 自定义指标脚本的发现与加载
- 指标模块的验证与注册

### 3. 评估引擎 (EvaluationEngine)

系统的核心组件，负责协调各个指标模块执行评估任务。主要功能包括：
- 并行执行多个评估指标（内置与自定义指标均支持并行处理）
- 收集和整合评估结果，包括内置指标和自定义指标的统计结果
- 处理评估过程中的异常
- 支持整体评估结果统计（如 overall_result、threshold_checks 等），并将其集成到最终报告中
- 评分统计逻辑通过调用 Score 评分模块实现，自动根据配置权重和阈值计算各级别得分

### 4. 日志管理器 (LoggingManager)

负责系统日志的配置和管理，支持多级日志记录。主要功能包括：
- 日志系统初始化
- 多级日志记录
- 日志文件管理

### 5. 数据处理器 (DataProcessor)

负责加载和预处理评估所需的数据。主要功能包括：
- 数据文件的加载与验证
- 数据格式转换与预处理
- 提供统一的数据访问接口

### 6. 评估流水线 (EvaluationPipeline)

整个系统的控制器，负责协调各个组件完成评估流程。主要功能包括：
- 组件初始化与配置
- 评估流程的执行与监控（包括内置与自定义指标的并行评估）
- 自动调用评分统计逻辑，整合各类评估结果
- 评估报告的生成与输出，报告中包含整体统计结果和各项指标详细信息

### 7. 图表生成器 (ChartGenerator)

负责生成各类评估指标的可视化图表。主要功能包括：
- 功能指标图表生成
- 舒适性指标图表生成
- 安全性指标图表生成
- 交通指标图表生成
- 支持多种图表类型（折线图、散点图、双轴图等）
- 高质量图表输出（支持自定义DPI）

## 目录结构

```
├── scripts/
│   └── evaluator_enhanced.py    # 评估引擎主程序
├── modules/
│   ├── lib/
│   │   ├── metric_registry.py   # 指标注册系统
│   │   ├── data_process.py      # 数据处理模块
│   │   ├── score.py             # 评分计算模块
│   │   ├── common.py            # 通用工具函数
│   │   ├── chart_generator.py   # 图表生成模块
│   │   └── log_manager.py       # 日志管理模块
│   └── metric/
│       ├── safety.py            # 安全性指标模块
│       ├── comfort.py           # 舒适性指标模块
│       ├── traffic.py           # 交通规则指标模块
│       ├── efficient.py         # 效率指标模块
│       └── function.py          # 功能指标模块
├── config/
│   ├── all_metrics_config.yaml  # 全量指标配置
│   └── custom_metrics_config.yaml # 自定义指标配置
├── templates/
│   ├── custom_metric_template.py  # 自定义指标模板
│   └── unified_custom_metric_template.py # 统一自定义指标模板
└── custom_metrics/                # 用户自定义指标目录
```

## 模块详细说明

### modules 目录

#### lib 子目录

- **metric_registry.py**: 提供指标注册基础设施，包含BaseMetric基类，所有自定义指标都需继承此类
- **data_process.py**: 负责数据预处理，提供统一的数据访问接口
- **score.py**: 实现评分计算逻辑，根据配置文件中的权重和阈值计算最终得分，支持整体评估结果（overall_result）与阈值检查（threshold_checks）等统计，并与评估引擎集成，自动输出到最终报告。
- **common.py**: 包含系统通用工具函数和辅助方法
- **chart_generator.py**: 实现各类评估指标的可视化图表生成功能
- **log_manager.py**: 提供集中式日志管理，支持多级日志记录和文件轮转

#### metric 子目录

- **safety.py**: 实现安全性相关指标，如TTC(碰撞时间)、碰撞风险等
- **comfort.py**: 实现舒适性相关指标，如加速度平滑度、抖动指标等
- **traffic.py**: 实现交通规则相关指标，如车道保持、信号灯遵守等
- **efficient.py**: 实现效率相关指标，如行程时间、能耗等
- **function.py**: 实现功能性指标，如感知准确度、决策合理性等

### custom_metrics 目录

用于存放用户自定义的指标实现脚本。系统会自动扫描此目录下符合命名规范的Python脚本，并将其作为自定义指标加载。

**命名规范**：
- 文件名必须以`metric_`开头
- 后跟三级指标名称，如`metric_safety_safeTime_CustomTTC.py`
- 三级指标名称必须在自定义配置文件中有对应配置

**实现方式**：
- 基于类的实现：继承BaseMetric基类，实现calculate方法
- 基于函数的实现：提供evaluate函数

### templates 目录

包含自定义指标开发的模板文件，用户可以基于这些模板快速开发自己的指标。

- **custom_metric_template.py**: 基础自定义指标模板，提供完整的类结构和注释
- **unified_custom_metric_template.py**: 统一风格的自定义指标模板，包含更多标准化实现

## 运行流程

### 1. 初始化阶段

1. 解析命令行参数，获取配置文件路径、数据路径、报告路径等
2. 初始化日志管理器，配置日志系统
3. 初始化配置管理器，加载并合并内置和自定义配置
4. 初始化指标加载器，加载内置指标模块和自定义指标脚本
5. 初始化评估引擎和数据处理器

### 2. 评估阶段

1. 数据处理器验证并加载评估数据
2. 评估引擎并行执行各个指标模块的评估任务
3. 收集内置指标和自定义指标的评估结果
4. 处理和合并评估结果

### 3. 报告生成阶段

1. 整合评估结果，添加元数据信息
2. 生成JSON格式的评估报告
3. 将报告保存到指定目录

## 使用方法

### 基本用法

```bash
python scripts/evaluator_enhanced.py --configPath config/all_metrics_config.yaml --dataPath data_dir --reportPath report_dir --logPath logs
```

### 参数说明

- `--configPath`: 指标配置文件路径
- `--dataPath`: 评估数据目录路径
- `--reportPath`: 评估报告输出目录
- `--logPath`: 日志文件路径
- `--customMetricsPath`: 自定义指标脚本目录（可选）
- `--customConfigPath`: 自定义指标配置文件路径（可选）

## 自定义指标开发指南

### 概述

本系统支持用户自定义评估指标，您可以通过编写Python脚本来实现自己的指标计算逻辑，并将其集成到评估系统中。

### 开发步骤

1. 在`custom_metrics`目录下创建新的Python脚本，遵循命名规范
2. 基于模板实现自定义指标逻辑
3. 在自定义配置文件中添加对应的配置项
4. 运行评估系统，指定自定义指标目录和配置文件

### 示例

```python
from modules.lib.metric_registry import BaseMetric

class MyCustomMetric(BaseMetric):
    def __init__(self, data):
        super().__init__(data)
    
    def calculate(self):
        # 实现您的计算逻辑
        return {
            "value": 42.0,
            "score": 85,
            "details": {"max": 100, "min": 0}
        }
```

### 使用自定义指标

```bash
python scripts/evaluator_enhanced.py --configPath config/all_metrics_config.yaml --dataPath data_dir --reportPath report_dir --logPath logs --customMetricsPath custom_metrics --customConfigPath config/custom_metrics_config.yaml
```

## 扩展性设计

### 1. 新增内置指标
   
- 在对应类别模块中添加新方法
- 系统会自动注册和识别

### 2. 添加自定义指标
   
- 基于模板创建新的指标脚本
- 放置在自定义指标目录
- 无需修改核心代码

### 3. 新增指标类别
   
- 创建新的类别模块
- 在注册系统中添加类别支持

## 系统优势

1. **模块化设计**: 系统各组件职责明确，便于维护和扩展
2. **灵活配置**: 可以根据配置选择性运行指标，提高效率
3. **可扩展性**: 支持用户自定义指标，无需修改核心代码
4. **并行处理**: 多指标并行评估，提高处理效率
5. **异常处理**: 完善的异常捕获和日志记录机制，提高系统稳定性