EG/plugins/user/pathfinding_algorithms/README.md

# 路径规划算法插件

一个功能完整的路径规划算法系统插件，为EG引擎提供多种经典和现代路径规划算法的实现。

## 功能特性

### 核心算法
- **A*算法**: 经典的启发式搜索算法，支持多种启发式函数和优化选项
- **Dijkstra算法**: 保证最短路径的搜索算法
- **BFS算法**: 广度优先搜索，适用于无权图
- **DFS算法**: 深度优先搜索，可能更快找到任意路径
- **JPS算法**: Jump Point Search，针对网格地图优化的A*算法，性能比传统A*快数倍

### 算法管理
- **统一接口**: 所有算法通过统一接口访问
- **参数配置**: 支持算法参数配置和调整
- **性能统计**: 自动收集和分析算法性能数据
- **批量测试**: 支持批量测试多个算法和场景
- **算法推荐**: 根据场景特点自动推荐最适合的算法
- **基准测试**: 对算法进行性能基准测试

### 可视化功能
- **网格显示**: 可视化显示网格地图，区分可通行区域和障碍物
- **路径绘制**: 实时绘制计算出的路径，支持动画效果
- **交互编辑**: 通过可视化界面编辑地图
- **场景切换**: 支持多种预设场景
- **节点可视化**: 可视化已访问节点和开放列表节点
- **动画支持**: 支持路径查找过程的动画演示

### 编辑器功能
- **可视化编辑**: 图形化界面编辑路径规划场景
- **多种工具**: 选择、添加障碍、移除障碍、设置起点终点等工具
- **场景生成**: 自动生成多种类型的测试场景
- **算法比较**: 直接在编辑器中比较不同算法性能

### 高级特性
- **性能优化**: 多种算法优化技术，包括启发式权重调整、Tie Breaker等
- **复杂度分析**: 提供各算法的时间和空间复杂度信息
- **数据验证**: 自动验证输入数据的有效性
- **报告生成**: 生成详细的算法性能报告
- **缓存机制**: 缓存性能数据以供后续分析

## 使用方法

### 快捷键操作
- **F1**: 切换路径规划编辑器显示
- **F2**: 切换可视化显示
- **F3**: 运行演示
- **F4**: 清除可视化
- **F5**: 比较算法性能
- **F6**: 显示统计信息
- **F7**: 生成算法报告
- **F8**: 优化路径
- **F9**: 生成随机场景
- **F10**: 切换动画
- **F11**: 显示算法信息
- **F12**: 导出详细报告

### GUI界面操作
插件会在屏幕左上角创建控制面板，右上角创建编辑器面板，可以通过按钮直接操作路径规划功能。

### 编程接口
```python
# 获取插件实例
pathfinding_plugin = world.plugin_manager.get_plugin("pathfinding_algorithms")

# 创建网格
grid = [[0, 0, 0, 1, 0],
        [0, 1, 0, 1, 0],
        [0, 1, 0, 0, 0],
        [0, 0, 0, 1, 0],
        [0, 0, 0, 0, 0]]

# 设置起点和终点
start = (0, 0)
goal = (4, 4)

# 使用A*算法查找路径
path, stats = pathfinding_plugin.find_path("astar", grid, start, goal)

if path:
    print(f"找到路径，长度: {len(path)}")
    print(f"访问节点数: {stats['nodes_visited']}")
    print(f"耗时: {stats['time_taken']}秒")
else:
    print("未找到路径")

# 可视化路径
pathfinding_plugin.visualize_path(path, grid)

# 获取可用算法列表
algorithms = pathfinding_plugin.get_available_algorithms()
print("可用算法:", algorithms)

# 设置算法参数
pathfinding_plugin.set_algorithm_parameter("astar", "heuristic", "euclidean")

# 获取算法参数
parameters = pathfinding_plugin.get_algorithm_parameters("astar")
print("A*算法参数:", parameters)

# 添加自定义算法
class CustomAlgorithm:
    def find_path(self, grid, start, goal):
        # 实现自定义算法
        pass

pathfinding_plugin.add_algorithm("custom", CustomAlgorithm, "自定义算法描述")

# 比较算法性能
pathfinding_plugin.compare_algorithms()

# 生成报告
report = pathfinding_plugin.generate_report()
print("算法报告:", report)

# 设置可视化参数
pathfinding_plugin.set_visualization_settings({
    'grid_color': LColor(0.7, 0.7, 0.7, 1.0),
    'path_color': LColor(1.0, 0.5, 0.0, 1.0)
})

# 获取可视化参数
settings = pathfinding_plugin.get_visualization_settings()
print("可视化设置:", settings)

# 启用动画
pathfinding_plugin.enable_visualization_animation(True)

# 批量测试算法
test_cases = [
    {'grid': grid, 'start': (0, 0), 'goal': (4, 4), 'name': 'test1'},
    {'grid': grid, 'start': (1, 1), 'goal': (3, 3), 'name': 'test2'}
]
results = pathfinding_plugin.batch_test_algorithms(['astar', 'bfs'], test_cases)

# 详细比较算法
detailed_results = pathfinding_plugin.compare_algorithms_detailed(
    ['astar', 'jps'], grid, start, goal)

# 获取缓存的性能数据
performance_data = pathfinding_plugin.get_cached_performance_data('astar')

# 清除性能缓存
pathfinding_plugin.clear_performance_cache()

# 重置统计信息
pathfinding_plugin.reset_statistics()

# 验证网格数据
validation_result = pathfinding_plugin.validate_grid_data(grid)
print("网格验证结果:", validation_result)

# 获取算法复杂度信息
complexity = pathfinding_plugin.get_algorithm_complexity('astar')
print("A*算法复杂度:", complexity)

# 基准测试算法
benchmark_results = pathfinding_plugin.benchmark_algorithm('astar', grid, start, goal, 1000)
print("基准测试结果:", benchmark_results)

# 为特定网格优化算法
pathfinding_plugin.optimize_algorithm_for_grid('jps', grid)
```

## 核心组件

### 算法管理器
负责各种路径规划算法的注册、配置和执行。

主要功能：
- 算法注册和管理
- 参数配置和调整
- 统一接口访问
- 性能统计和分析
- 批量测试支持
- 算法推荐系统

### 可视化管理器
负责路径规划算法的可视化显示。

主要功能：
- 网格地图可视化
- 路径绘制和显示
- 起点终点标记
- 可视化参数配置
- 节点可视化（已访问节点、开放列表）
- 动画支持

### 路径规划编辑器
提供可视化编辑路径规划场景的功能。

主要功能：
- 图形化界面编辑
- 多种编辑工具
- 场景生成和管理
- 算法性能比较

## 算法说明

### A*算法
A*是一种启发式搜索算法，结合了Dijkstra算法的准确性和贪心最佳优先搜索的效率。

特点：
- 通过启发式函数指导搜索方向
- 保证找到最优解（在启发式函数可接受的情况下）
- 适用于静态环境
- 支持多种启发式函数（曼哈顿距离、欧几里得距离、切比雪夫距离等）
- 支持对角线移动和角落切割
- 支持Tie Breaker优化

### Dijkstra算法
Dijkstra算法是一种用于计算单源最短路径的经典算法。

特点：
- 保证找到最短路径
- 适用于权重图
- 时间复杂度较高
- 不需要启发式函数

### BFS算法
广度优先搜索算法，保证找到最短路径（在无权图中）。

特点：
- 保证找到最短路径
- 适用于无权图
- 内存使用较多
- 实现简单

### DFS算法
深度优先搜索算法，不保证找到最短路径，但可能更快找到任意路径。

特点：
- 可能更快找到路径
- 不保证最优解
- 内存使用较少
- 支持深度限制

### JPS算法
Jump Point Search是一种优化的A*算法，专门用于网格地图。

特点：
- 针对网格地图优化
- 比传统A*更快
- 保持A*的最优性
- 利用网格特性跳过大量不必要的节点
- 适用于大型网格地图

## 场景生成

### 简单场景
空的网格地图，适用于基本测试。

### 迷宫场景
使用深度优先搜索算法生成的迷宫。

### 房间场景
包含多个房间和走廊的复杂场景。

### 随机场景
随机生成障碍物的场景。

### 隧道场景
多条曲折隧道的场景。

## 性能优化

### 算法优化
- **启发式函数**: 多种启发式函数可选，适应不同场景
- **启发式权重**: 可调整权重平衡搜索速度和最优性
- **对角线移动**: 支持对角线移动提高效率
- **Tie Breaker**: 使用tie breaker优化打破平局
- **JPS优化**: 利用跳点搜索跳过大量节点

### 内存管理
- **对象复用**: 减少对象创建和销毁开销
- **批量处理**: 提高大量数据处理效率
- **缓存机制**: 缓存性能数据供后续分析

### 渲染优化
- **LOD支持**: 根据距离调整显示细节
- **视锥剔除**: 只渲染可见区域
- **批处理**: 合并相似的渲染调用
- **透明度优化**: 优化透明节点的渲染

## 扩展开发

### 添加新的路径规划算法
1. 在[algorithms](file:///home/hello/EG/plugins/user/pathfinding_algorithms/algorithms)目录中创建新的算法文件
2. 实现算法类，确保有find_path方法
3. 在[algorithm_manager.py](file:///home/hello/EG/plugins/user/pathfinding_algorithms/core/algorithm_manager.py)中注册新算法

### 添加新的场景生成器
1. 在[utils/demo_scenarios.py](file:///home/hello/EG/plugins/user/pathfinding_algorithms/utils/demo_scenarios.py)中实现新的场景生成函数
2. 在编辑器中添加对应的生成选项

### 添加新的可视化效果
1. 在[visualization_manager.py](file:///home/hello/EG/plugins/user/pathfinding_algorithms/visualization/visualization_manager.py)中实现新的可视化方法
2. 在编辑器中添加对应的控制选项

## 故障排除

### 路径查找失败
1. 检查起点和终点是否在可通行区域内
2. 确认网格数据格式是否正确
3. 检查算法参数设置
4. 使用数据验证功能检查网格有效性

### 性能问题
1. 使用算法比较功能分析性能瓶颈
2. 调整启发式权重优化搜索效率
3. 简化网格结构
4. 对于大型网格考虑使用JPS算法

### 可视化问题
1. 确认GUI系统是否正常工作
2. 检查可视化参数设置
3. 重新启用插件尝试

## API参考

### Plugin类主要方法

#### 初始化和控制
- `initialize()` - 初始化插件
- `enable()` - 启用插件
- `disable()` - 禁用插件
- `finalize()` - 清理插件资源
- `update(dt)` - 更新插件状态

#### 路径查找
- `find_path(algorithm, grid, start, goal)` - 查找路径
- `add_algorithm(name, algorithm_class, description)` - 添加新算法
- `remove_algorithm(name)` - 移除算法
- `get_available_algorithms()` - 获取可用算法列表
- `get_algorithm_description(algorithm)` - 获取算法描述
- `set_algorithm_parameter(algorithm, parameter, value)` - 设置算法参数
- `get_algorithm_parameters(algorithm)` - 获取算法参数

#### 可视化
- `visualize_path(path, grid)` - 可视化路径
- `visualize_grid(grid)` - 可视化网格
- `visualize_visited_nodes(visited_nodes)` - 可视化已访问节点
- `visualize_open_list(open_list)` - 可视化开放列表
- `clear_path_visualization()` - 清除路径可视化
- `set_visualization_settings(settings)` - 设置可视化参数
- `get_visualization_settings()` - 获取可视化参数
- `enable_visualization_animation(enable)` - 启用可视化动画

#### 性能和统计
- `compare_algorithms()` - 比较算法性能
- `show_stats()` - 显示统计信息
- `generate_report()` - 生成报告
- `batch_test_algorithms(algorithms, test_cases)` - 批量测试算法
- `compare_algorithms_detailed(algorithms, grid, start, goal)` - 详细比较算法
- `get_cached_performance_data(algorithm)` - 获取缓存的性能数据
- `clear_performance_cache()` - 清除性能缓存
- `reset_statistics()` - 重置统计信息
- `validate_grid_data(grid)` - 验证网格数据
- `get_algorithm_complexity(algorithm)` - 获取算法复杂度信息
- `benchmark_algorithm(algorithm, grid, start, goal, iterations)` - 基准测试算法
- `optimize_algorithm_for_grid(algorithm, grid)` - 为特定网格优化算法

#### 编辑器功能
- `toggle_editor()` - 切换编辑器显示
- `toggle_visualization()` - 切换可视化显示
- `run_demo()` - 运行演示
- `clear_visualization()` - 清除可视化
- `generate_random_scenario()` - 生成随机场景
- `toggle_animation()` - 切换动画
- `show_algorithm_info()` - 显示算法信息
- `export_detailed_report()` - 导出详细报告

## 性能调优建议

### 算法选择
1. 对于需要最优解的场景，使用A*或Dijkstra算法
2. 对于只需要找到任意路径的场景，使用BFS或DFS算法
3. 对于大型网格地图，使用JPS算法
4. 根据场景特点使用算法推荐功能

### 参数调整
1. 合理设置启发式权重（通常1.0为最佳）
2. 根据场景特点选择合适的启发式函数
3. 对于DFS算法，合理设置深度限制
4. 对于A*算法，考虑启用Tie Breaker优化

### 场景优化
1. 简化不必要的障碍物
2. 减小网格尺寸
3. 使用分层路径规划处理大场景
4. 对于静态环境，考虑预计算路径

## 版本信息

- 版本: 1.0.0
- 作者: EG Team
- 发布日期: 2024年

## 许可证

本插件遵循EG引擎许可证协议。