# 简单拟真智能驾驶json测试用例生成器

**Repository Path**: walter-tang/Simple-Realistic-Autonomous-Driving-JSON-Test-Case-Generator

## Basic Information

- **Project Name**: 简单拟真智能驾驶json测试用例生成器
- **Description**: 一个用于生成智能驾驶简单JSON测试用例的开源工具，支持多种场景和条件，旨在帮助开发者快速构建自动驾驶系统验证系统。
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-02-20
- **Last Updated**: 2026-03-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 自动驾驶测试用例生成器 (Autonomous Driving Test Case Generator)

[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Python](https://img.shields.io/badge/python-3.8%2B-blue.svg)](https://www.python.org/)
[![Build Status](https://img.shields.io/badge/build-passing-brightgreen.svg)](BUILD)

## 项目概述

自动驾驶测试用例生成器是一个高保真、可扩展的系统，用于自动生成多样化的自动驾驶测试场景。该系统集成了智能危害评估、场景去重和多格式导出功能，专为自动驾驶算法测试工程师和质量保障团队设计。

系统能够自动生成包含各种环境条件、交通参与者行为和复杂交互场景的测试用例，并通过内置的危害评分系统对每个场景进行风险量化评估，帮助测试团队高效识别边缘案例和高风险场景。

## 核心功能

### 🌤️ 多环境条件组合生成
- **天气条件**：晴天、雨天、雾天、雪天（影响能见度和路面摩擦系数）
- **光照条件**：白天、夜间（影响感知能力）
- **道路类型**：高速公路、城市道路、乡村道路、施工区域（不同交通模式）

### ⚠️ 智能危害评分系统
采用加权多因子评估模型（0-100分制）：
- **参与者密度**（权重25%）：参与者的数量和集中程度
- **高风险行为**（权重30%）：紧急制动、突然出现、闯红灯等
- **环境严重性**（权重20%）：天气×光照组合效应
- **接近因子**（权重15%）：近距离接触、时间到碰撞考虑
- **道路复杂性**（权重10%）：施工区域、城市复杂度

### 🔍 自动风险等级分类
- **低风险**（0-30分）：简单场景，基础测试用例
- **中风险**（30-70分）：中等复杂度场景
- **高风险**（70-100分）：极限测试场景，边缘案例

### 🔁 可重现性保证
- 支持通过种子（seed）控制随机性
- 相同种子产生完全相同的测试结果
- 便于回归测试和问题复现

### 📤 多格式导出支持
- **JSON格式**：原始数据，完整场景信息
- **CSV格式**：表格化数据，便于分析统计
- **Analysis JSON**：统计分析报告，包含分布直方图和高频风险因素

## 目录结构说明

```
autonomous-driving-test-generator/
├── ad_test_generator/              # 主模块包
│   ├── __init__.py                 # 包初始化和导出定义
│   ├── models.py                   # 数据模型和枚举定义
│   │   ├── WeatherCondition        # 天气条件枚举
│   │   ├── LightingCondition       # 光照条件枚举
│   │   ├── RoadType               # 道路类型枚举
│   │   ├── VehicleActor           # 车辆参与者模型
│   │   ├── PedestrianActor        # 行人参与者模型
│   │   ├── BicycleActor           # 自行车参与者模型
│   │   └── ConeActor              # 锥桶/障碍物模型
│   ├── generators.py               # 核心生成器类实现
│   │   └── AutonomousDrivingTestGenerator  # 主生成器引擎
│   ├── scorer.py                   # 危害评分逻辑实现
│   │   └── HazardScorer           # 多因子风险评估系统
│   ├── deduplicator.py             # 场景去重机制
│   │   ├── ScenarioDeduplicator   # 基于哈希的去重系统
│   │   └── SemanticEquivalenceChecker  # 语义等价检查
│   ├── exporter.py                 # 导出功能实现
│   │   ├── JSONExporter           # JSON导出器
│   │   └── TestSuiteExporter      # 测试套件导出器
│   └── main.py                     # 命令行接口
├── tests/                          # 单元测试
│   ├── test_models.py              # 模型测试
│   ├── test_generator.py           # 生成器测试
│   └── test_scorer.py              # 评分器测试
├── examples/                       # 使用示例
│   └── sample_usage.py             # API调用示例集合
├── demo_output/                    # 示例输出文件
│   ├── basic_test_cases.json       # 基础测试用例
│   ├── low_risk.json               # 低风险场景（0-30分）
│   ├── medium_risk.json            # 中风险场景（30-70分）
│   ├── high_risk.json              # 高风险场景（70-100分）
│   ├── high_risk_scenarios.json    # 精选高风险案例详情
│   └── complete_analysis.json      # 完整统计分析报告
├── demo.py                         # 演示脚本
├── validate.py                     # 验证脚本
├── cli_test_cases.json             # 命令行生成示例
├── requirements.txt                # 依赖包列表
├── SOLUTION_SUMMARY.md             # 设计思路和技术亮点
└── README.md                       # 英文文档
```

## 安装与依赖

### 系统要求
- Python 3.8 或更高版本
- Windows/Linux/macOS 操作系统

### 安装步骤

1. 克隆项目仓库：
```bash
git clone https://gitee.com/walter-tang/Simple-Realistic-Autonomous-Driving-JSON-Test-Case-Generator.git
cd Simple-Realistic-Autonomous-Driving-JSON-Test-Case-Generator
```

2. 安装依赖包：
```bash
pip install -r requirements.txt
```

### 依赖包说明
```
numpy>=1.21.0              # 数值计算库
scipy>=1.7.0               # 科学计算库
jsonschema>=4.0.0          # JSON Schema验证
pytest>=6.2.0              # 测试框架
pytest-cov>=2.12.0         # 测试覆盖率工具
typing_extensions>=3.10.0  # 类型提示扩展
```

## 使用方法

### 命令行使用方式

通过 `main.py` 脚本可以使用丰富的命令行参数：

```bash
python -m ad_test_generator.main [选项]
```

#### 常用参数说明

| 参数 | 说明 | 示例 |
|------|------|------|
| `--count`, `-n` | 生成测试用例数量 | `--count 100` |
| `--all-combinations` | 生成所有可能的场景组合 | `--all-combinations` |
| `--seed` | 随机种子，保证结果可重现 | `--seed 42` |
| `--output`, `-o` | 输出文件名 | `--output scenarios.json` |
| `--output-dir` | 输出目录路径 | `--output-dir ./test_scenarios/` |
| `--formats` | 导出格式列表 | `--formats json,csv,analysis` |
| `--road-types` | 指定道路类型过滤 | `--road-types urban,highway` |
| `--weather` | 指定天气条件过滤 | `--weather clear,rain,fog` |
| `--lighting` | 指定光照条件过滤 | `--lighting day,night` |
| `--verbose`, `-v` | 显示详细生成进度 | `--verbose` |
| `--stats-only` | 仅显示统计信息，不生成文件 | `--stats-only` |

#### 命令行使用示例

```bash
# 生成100个随机测试用例
python -m ad_test_generator.main --count 100 --output test_cases.json

# 生成所有组合场景并分类导出
python -m ad_test_generator.main --all-combinations --output-dir ./scenarios/

# 生成特定条件下的测试用例
python -m ad_test_generator.main --count 50 --road-types urban,highway --weather rain,snow --formats json,csv

# 使用固定种子确保结果可重现
python -m ad_test_generator.main --count 25 --seed 12345 --output reproducible_tests.json
```

### Python API 调用方式

通过编程接口可以更灵活地控制生成过程：

#### 基础使用示例

```python
from ad_test_generator import AutonomousDrivingTestGenerator

# 初始化生成器
generator = AutonomousDrivingTestGenerator(seed=42)

# 生成测试用例
test_cases = generator.generate_test_cases(num_cases=50)

# 查看结果统计
print(f"生成了 {len(test_cases)} 个测试用例")
print(f"平均危害分数: {sum(tc.hazard_score for tc in test_cases)/len(test_cases):.2f}")
```

#### 高级过滤使用

```python
from ad_test_generator import (
    AutonomousDrivingTestGenerator,
    RoadType, WeatherCondition, LightingCondition
)

# 生成特定条件的高风险场景
generator = AutonomousDrivingTestGenerator()

high_risk_cases = generator.generate_test_cases(
    num_cases=30,
    road_types=[RoadType.URBAN, RoadType.CONSTRUCTION_ZONE],
    weather_conditions=[WeatherCondition.RAIN, WeatherCondition.FOG],
    lighting_conditions=[LightingCondition.NIGHT]
)

# 筛选真正高风险的案例
very_high_risk = [tc for tc in high_risk_cases if tc.hazard_score > 80]
print(f"极高风险案例数量: {len(very_high_risk)}")
```

#### 导出功能使用

```python
from ad_test_generator.exporter import JSONExporter, export_test_cases

# 导出为JSON格式
JSONExporter.export_to_json(test_cases, "output.json")

# 导出为CSV格式
JSONExporter.export_to_csv(test_cases, "output.csv")

# 生成详细分析报告
JSONExporter.export_hazard_analysis(test_cases, "analysis.json")

# 同时导出多种格式
exported_files = export_test_cases(
    test_cases, 
    "my_test_suite", 
    formats=['json', 'csv', 'analysis']
)
```

#### 创建自定义场景

```python
from ad_test_generator.models import (
    TestCase, VehicleActor, PedestrianActor, BicycleActor,
    WeatherCondition, LightingCondition, RoadType,
    LanePosition, VehicleBehavior, PedestrianLocation, PedestrianSpeed
)
from ad_test_generator.scorer import HazardScorer

# 创建自定义测试场景
custom_case = TestCase(
    case_id="CUSTOM_001",
    weather=WeatherCondition.RAIN,
    lighting=LightingCondition.NIGHT,
    road_type=RoadType.URBAN,
    actors=[
        VehicleActor(
            quantity=1,
            lane_position=LanePosition.SAME_LANE,
            speed_range_kmh=(40, 60),
            behavior=VehicleBehavior.DECELERATING,
            is_braking=True
        ),
        PedestrianActor(
            location_type=PedestrianLocation.GHOST_HEAD,
            speed_type=PedestrianSpeed.RUNNING,
            distance_m=8.5,
            speed_mps=4.2,
            appearance_timing="sudden"
        )
    ]
)

# 计算危害分数
scorer = HazardScorer()
score, factors = scorer.calculate_hazard_score(custom_case)
custom_case.hazard_score = score
custom_case.hazard_factors = factors

print(f"自定义场景危害分数: {custom_case.hazard_score}")
print(f"风险因素: {', '.join(custom_case.hazard_factors)}")
```

## 示例输出说明

### 输出文件类型

#### 1. 基础测试用例文件 (`basic_test_cases.json`)
包含随机生成的基础测试场景，适合一般性测试需求。

#### 2. 风险分级文件
- **`low_risk.json`**：风险评分低于30分的简单场景，主要用于基础功能验证
- **`medium_risk.json`**：风险评分30-70分的中等复杂度场景，用于常规测试
- **`high_risk.json`**：风险评分70分以上的高危场景，适用于极限测试和边缘案例验证

#### 3. 精选高风险案例 (`high_risk_scenarios.json`)
包含评分最高的典型案例，突出显示最具挑战性的测试场景。

#### 4. 完整分析报告 (`complete_analysis.json`)
提供全面的统计分析信息：
- 总体分布统计
- 按道路类型、天气条件的分布
- 危害分数直方图
- 高频风险因素排名
- 最高风险场景详情

### 输出格式示例

```json
{
  "case_id": "TC_0001",
  "weather": "rain",
  "lighting": "night",
  "road_type": "urban",
  "actors": [
    {
      "type": "vehicle",
      "quantity": 1,
      "lane_position": "same_lane",
      "speed_range_kmh": [40, 60],
      "behavior": "decelerating",
      "is_braking": true
    },
    {
      "type": "pedestrian",
      "location_type": "ghost_head",
      "speed_type": "running",
      "distance_m": 8.5,
      "speed_mps": 4.2,
      "appearance_timing": "sudden"
    }
  ],
  "hazard_score": 87.5,
  "hazard_factors": [
    "ghost_head_pedestrian",
    "running_pedestrian",
    "vehicle_emergency_braking",
    "rain_conditions",
    "night_vision_reduced"
  ],
  "scenario_hash": "a1b2c3d4e5f6..."
}
```

## 测试与验证

### 运行单元测试

项目包含完整的测试套件，确保系统稳定性和正确性：

```bash
# 运行所有测试
pytest tests/

# 运行特定测试文件
pytest tests/test_models.py
pytest tests/test_generator.py
pytest tests/test_scorer.py

# 运行测试并查看覆盖率
pytest tests/ --cov=ad_test_generator --cov-report=html
```

### 功能验证脚本

使用验证脚本来确认系统各项功能正常工作：

```bash
python validate.py
```

该脚本会执行以下验证：
- ✅ 基础测试用例生成
- ✅ 全组合场景生成
- ✅ 危害评分系统验证
- ✅ 去重系统功能
- ✅ JSON序列化/反序列化
- ✅ 参与者类型覆盖
- ✅ 统计分布有效性
- ✅ 可重现性验证

### 系统特性验证

#### 可重现性测试
```python
# 相同种子应该产生相同结果
gen1 = AutonomousDrivingTestGenerator(seed=42)
gen2 = AutonomousDrivingTestGenerator(seed=42)

cases1 = gen1.generate_test_cases(num_cases=10)
cases2 = gen2.generate_test_cases(num_cases=10)

# 验证场景一致性
assert all(c1.weather == c2.weather for c1, c2 in zip(cases1, cases2))
```

#### 去重功能测试
```python
generator = AutonomousDrivingTestGenerator()
many_cases = generator.generate_test_cases(num_cases=100)

# 检查唯一性比率
hashes = [tc.scenario_hash for tc in many_cases]
unique_ratio = len(set(hashes)) / len(hashes)
print(f"唯一性比率: {unique_ratio:.2f}")  # 应该 > 0.9
```

## 扩展性与设计亮点

### 🏗️ 模块化架构设计

系统采用清晰的模块化设计，各组件职责分明：

1. **数据模型层** (`models.py`)：定义所有场景元素的数据结构
2. **生成引擎层** (`generators.py`)：负责测试用例的核心创建逻辑
3. **评分系统层** (`scorer.py`)：实现多因子风险评估算法
4. **去重机制层** (`deduplicator.py`)：确保场景唯一性的智能系统
5. **导出接口层** (`exporter.py`)：标准化的数据输出功能
6. **用户接口层** (`main.py`)：命令行和API访问入口

### 🔧 可扩展性特点

#### 参与者类型扩展
```python
# 可通过继承现有基类来添加新的参与者类型
class AnimalActor:
    def __init__(self, species, behavior, speed_mps):
        self.species = species
        self.behavior = behavior
        self.speed_mps = speed_mps
    
    def to_dict(self):
        return {
            "type": "animal",
            "species": self.species,
            "behavior": self.behavior,
            "speed_mps": self.speed_mps
        }

# 注意：添加新参与者类型需要同时修改：
# 1. models.py 中的数据模型
# 2. generators.py 中的生成逻辑
# 3. scorer.py 中的风险评估规则
```

#### 评分因子定制
```python
# 可动态调整评分权重
scorer = HazardScorer()
scorer.weights['new_factor'] = 0.15  # 添加新因子权重
```

#### 导出格式扩展
```python
# 可通过继承或扩展现有导出器来支持新格式
class CustomExporter(JSONExporter):
    @staticmethod
    def export_to_xml(test_cases, filename):
        # 实现XML导出逻辑
        # 这需要自定义实现
        pass

# 使用示例：
# CustomExporter.export_to_xml(test_cases, "output.xml")
```

### 💡 技术创新亮点

#### 1. 智能场景去重
- 基于SHA-256哈希的语义去重机制
- 数值归一化防止微小差异导致重复
- 支持语义等价性判断（容忍度控制）

#### 2. 多维度危害评估
- 5大类风险因子的加权综合评估
- 特殊风险检测（"鬼探头"行人、紧急制动等）
- 环境条件组合效应建模

#### 3. 高效生成算法
- 概率驱动的参与者类型分配
- 系统化的场景组合策略
- 智能的边界条件处理

#### 4. 工业级输出标准
- 符合行业规范的JSON格式
- 完善的元数据信息
- 结构化的统计分析报告

### 🚀 性能优化特性

- **内存效率**：智能缓存和对象复用
- **计算优化**：批量处理和向量化操作
- **存储优化**：压缩哈希和精简表示
- **并发支持**：线程安全的生成器设计


## 开发指南

### 贡献流程
1. Fork 项目仓库
2. 创建功能分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 开启 Pull Request

---

*自动驾驶测试用例生成器*