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界面操作

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

编程接口

# 获取插件实例
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目录中创建新的算法文件
2. 实现算法类，确保有find_path方法
3. 在algorithm_manager.py中注册新算法

添加新的场景生成器

1. 在utils/demo_scenarios.py中实现新的场景生成函数
2. 在编辑器中添加对应的生成选项

添加新的可视化效果

1. 在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引擎许可证协议。