Skip to content

api_reference.md

Latest commit

 

History

History
1319 lines (874 loc) · 22.4 KB

api_reference.md

File metadata and controls

1319 lines (874 loc) · 22.4 KB
Raw

ABU2026 API参考文档

目录

  1. 核心数据结构
  2. 路径规划算法
  3. 多机器人协调
  4. 环境感知处理
  5. GUI界面组件
  6. 工具函数

核心数据结构

RobotState 类

机器人状态管理类，用于存储和管理机器人的实时状态信息。

构造函数

obj = RobotState(position, orientation, velocity)

参数:

  • position (double[1,2]): 机器人位置坐标 [x, y]
  • orientation (double): 机器人朝向角度（弧度）
  • velocity (double[1,2]): 机器人速度向量 [vx, vy]

示例:

% 创建机器人状态
robot = RobotState([5.0, 3.0], pi/4, [1.0, 0.5]);

主要方法

updatePosition

更新机器人位置信息。

updatePosition(obj, newPosition)

参数:

  • newPosition (double[1,2]): 新的位置坐标

示例:

robot.updatePosition([6.0, 4.0]);
updateVelocity

更新机器人速度信息。

updateVelocity(obj, newVelocity)

参数:

  • newVelocity (double[1,2]): 新的速度向量
getDistanceTo

计算到目标点的距离。

distance = getDistanceTo(obj, targetPosition)

参数:

  • targetPosition (double[1,2]): 目标位置坐标

返回值:

  • distance (double): 欧几里得距离

EnvironmentMap 类

环境地图管理类，用于创建和管理机器人工作环境的地图信息。

构造函数

obj = EnvironmentMap(width, height, resolution)

参数:

  • width (double): 地图宽度（米）
  • height (double): 地图高度（米）
  • resolution (double): 地图分辨率（米/像素）

示例:

% 创建20x20米的地图，分辨率0.1米/像素
map = EnvironmentMap(20, 20, 0.1);

主要方法

addObstacle

向地图中添加矩形障碍物。

addObstacle(obj, bottomLeft, topRight)

参数:

  • bottomLeft (double[1,2]): 障碍物左下角坐标
  • topRight (double[1,2]): 障碍物右上角坐标

示例:

% 添加一个2x2米的障碍物
map.addObstacle([5, 5], [7, 7]);
addCircularObstacle

向地图中添加圆形障碍物。

addCircularObstacle(obj, center, radius)

参数:

  • center (double[1,2]): 圆心坐标
  • radius (double): 半径
isOccupied

检查指定位置是否被障碍物占用。

occupied = isOccupied(obj, position)

参数:

  • position (double[1,2]): 检查位置坐标

返回值:

  • occupied (logical): true表示被占用，false表示空闲
visualize

可视化显示地图。

visualize(obj)

PathPoint 类

路径点数据结构，用于表示路径中的单个点信息。

构造函数

obj = PathPoint(position, orientation, velocity)

参数:

  • position (double[1,2]): 路径点位置坐标
  • orientation (double): 期望朝向角度
  • velocity (double): 期望速度

路径规划算法

AStarPlanner 类

A*全局路径规划算法实现。

构造函数

obj = AStarPlanner()

主要方法

planPath

执行A*路径规划。

path = planPath(obj, start, goal, map)

参数:

  • start (double[1,2]): 起始位置坐标
  • goal (double[1,2]): 目标位置坐标
  • map (EnvironmentMap): 环境地图对象

返回值:

  • path (double[n,2]): 规划的路径点序列

示例:

planner = AStarPlanner();
path = planner.planPath([0, 0], [10, 10], environmentMap);
setHeuristic

设置启发式函数类型。

setHeuristic(obj, heuristicType)

参数:

  • heuristicType (string): 启发式函数类型 ('manhattan', 'euclidean', 'diagonal')

示例:

planner.setHeuristic('euclidean');

RRTStarPlanner 类

RRT*全局路径规划算法实现。

构造函数

obj = RRTStarPlanner()

主要方法

planPath

执行RRT*路径规划。

path = planPath(obj, start, goal, map)

参数:

  • start (double[1,2]): 起始位置坐标
  • goal (double[1,2]): 目标位置坐标
  • map (EnvironmentMap): 环境地图对象

返回值:

  • path (double[n,2]): 规划的路径点序列
setParameters

设置RRT*算法参数。

setParameters(obj, maxIterations, stepSize, goalRadius)

参数:

  • maxIterations (int): 最大迭代次数
  • stepSize (double): 步长
  • goalRadius (double): 目标区域半径

DWAPlanner 类

Dynamic Window Approach局部路径规划算法。

构造函数

obj = DWAPlanner()

主要方法

planPath

执行DWA局部路径规划。

[velocity, path] = planPath(obj, currentState, goal, obstacles)

参数:

  • currentState (RobotState): 当前机器人状态
  • goal (double[1,2]): 局部目标点
  • obstacles (double[n,2]): 障碍物位置列表

返回值:

  • velocity (double[1,2]): 最优速度指令 [v, w]
  • path (double[n,2]): 预测轨迹

多机器人协调

MultiRobotCoordinator 类

多机器人协调控制核心类。

构造函数

obj = MultiRobotCoordinator()

主要方法

addRobot

添加机器人到协调系统。

addRobot(obj, robotId, initialState)

参数:

  • robotId (string): 机器人唯一标识符
  • initialState (RobotState): 机器人初始状态
assignTask

为机器人分配任务。

assignTask(obj, robotId, task)

参数:

  • robotId (string): 机器人ID
  • task (struct): 任务结构体，包含目标位置和任务类型
detectConflicts

检测机器人间的冲突。

conflicts = detectConflicts(obj)

返回值:

  • conflicts (cell): 冲突列表，每个元素包含冲突的机器人ID对
resolveConflicts

解决机器人间的冲突。

resolveConflicts(obj, conflicts)

参数:

  • conflicts (cell): 需要解决的冲突列表

环境感知处理

SensorDataProcessor 类

传感器数据处理类。

构造函数

obj = SensorDataProcessor()

主要方法

processLidarData

处理激光雷达数据。

obstacles = processLidarData(obj, lidarData, robotPose)

参数:

  • lidarData (double[n,2]): 激光雷达扫描数据
  • robotPose (double[1,3]): 机器人位姿 [x, y, theta]

返回值:

  • obstacles (double[n,2]): 检测到的障碍物位置
updateEnvironmentMap

更新环境地图。

updateEnvironmentMap(obj, sensorData, map)

参数:

  • sensorData (struct): 传感器数据结构
  • map (EnvironmentMap): 待更新的环境地图

GUI界面组件

MainControlGUI 类

主控制界面类。

构造函数

obj = MainControlGUI()

主要方法

initialize

初始化GUI界面。

initialize(obj)
updateRobotDisplay

更新机器人显示。

updateRobotDisplay(obj, robotStates)

参数:

  • robotStates (cell): 机器人状态列表
updateMapDisplay

更新地图显示。

updateMapDisplay(obj, map)

参数:

  • map (EnvironmentMap): 环境地图对象

RemoteControlInterface 类

遥控操作界面类。

构造函数

obj = RemoteControlInterface(robotId)

参数:

  • robotId (string): 控制的机器人ID

主要方法

sendVelocityCommand

发送速度控制指令。

sendVelocityCommand(obj, linearVel, angularVel)

参数:

  • linearVel (double): 线速度 (m/s)
  • angularVel (double): 角速度 (rad/s)
emergencyStop

紧急停止机器人。

emergencyStop(obj)

工具函数

GeometryUtils 类

几何计算工具类。

静态方法

calculateDistance

计算两点间距离。

distance = GeometryUtils.calculateDistance(point1, point2)

参数:

  • point1 (double[1,2]): 第一个点坐标
  • point2 (double[1,2]): 第二个点坐标

返回值:

  • distance (double): 欧几里得距离
calculateAngle

计算两点间角度。

angle = GeometryUtils.calculateAngle(point1, point2)

参数:

  • point1 (double[1,2]): 起始点坐标
  • point2 (double[1,2]): 目标点坐标

返回值:

  • angle (double): 角度值 (弧度)
isPointInPolygon

判断点是否在多边形内。

inside = GeometryUtils.isPointInPolygon(point, polygon)

参数:

  • point (double[1,2]): 测试点坐标
  • polygon (double[n,2]): 多边形顶点坐标

返回值:

  • inside (logical): true表示在多边形内
transformCoordinates

坐标系转换工具。

transformed_points = GeometryUtils.transformCoordinates(points, transform_matrix)

参数:

  • points (double[n,2]): 原始坐标点矩阵
  • transform_matrix (double[3,3]): 3×3变换矩阵

返回值:

  • transformed_points (double[n,2]): 变换后的坐标点

示例:

points = [1, 0; 0, 1];
% 旋转90度的变换矩阵
T = [0, -1, 0; 1, 0, 0; 0, 0, 1];
transformed = GeometryUtils.transformCoordinates(points, T);
calculatePolygonArea

计算多边形面积。

area = GeometryUtils.calculatePolygonArea(polygon)

参数:

  • polygon (double[n,2]): 多边形顶点坐标矩阵

返回值:

  • area (double): 多边形面积

示例:

% 计算正方形面积
square = [0, 0; 1, 0; 1, 1; 0, 1];
area = GeometryUtils.calculatePolygonArea(square);
% area = 1.0

PathUtils 类

路径处理工具类。

静态方法

smoothPath

平滑路径。

smoothedPath = PathUtils.smoothPath(path, smoothingFactor)

参数:

  • path (double[n,2]): 原始路径
  • smoothingFactor (double): 平滑因子 (0-1)

返回值:

  • smoothedPath (double[n,2]): 平滑后的路径
calculatePathLength

计算路径长度。

length = PathUtils.calculatePathLength(path)

参数:

  • path (double[n,2]): 路径点序列

返回值:

  • length (double): 路径总长度
interpolatePath

路径插值。

interpolatedPath = PathUtils.interpolatePath(path, resolution)

参数:

  • path (double[n,2]): 原始路径
  • resolution (double): 插值分辨率

返回值:

  • interpolatedPath (double[m,2]): 插值后的路径
validatePath

验证路径的有效性。

[is_valid, issues] = PathUtils.validatePath(path, map, robot_radius)

参数:

  • path (double[n,2]): 路径点矩阵
  • map (EnvironmentMap): 环境地图对象
  • robot_radius (double): 机器人半径

返回值:

  • is_valid (logical): 路径是否有效
  • issues (cell): 问题描述字符串数组

示例:

[valid, issues] = PathUtils.validatePath(path, map, 0.15);
if ~valid
    fprintf('路径验证失败:\n');
    for i = 1:length(issues)
        fprintf('  - %s\n', issues{i});
    end
end
optimizePath

优化路径，减少不必要的转弯和长度。

optimized_path = PathUtils.optimizePath(path, map, robot_radius)

参数:

  • path (double[n,2]): 原始路径点矩阵
  • map (EnvironmentMap): 环境地图对象
  • robot_radius (double): 机器人半径

返回值:

  • optimized_path (double[n,2]): 优化后的路径

示例:

optimized = PathUtils.optimizePath(original_path, map, 0.15);
fprintf('原始路径长度: %.2f米\n', PathUtils.calculatePathLength(original_path));
fprintf('优化后长度: %.2f米\n', PathUtils.calculatePathLength(optimized));

使用示例

基础路径规划示例

% 创建环境地图
map = EnvironmentMap(20, 20, 0.1);
map.addObstacle([5, 5], [7, 7]);
map.addCircularObstacle([12, 8], 2);

% 创建A*规划器
planner = AStarPlanner();
planner.setHeuristic('euclidean');

% 执行路径规划
start = [1, 1];
goal = [18, 18];
path = planner.planPath(start, goal, map);

% 可视化结果
map.visualize();
hold on;
plot(path(:,1), path(:,2), 'r-', 'LineWidth', 2);
plot(start(1), start(2), 'go', 'MarkerSize', 10);
plot(goal(1), goal(2), 'ro', 'MarkerSize', 10);
legend('地图', '路径', '起点', '终点');

多机器人协调示例

% 创建多机器人协调器
coordinator = MultiRobotCoordinator();

% 添加机器人
robot1 = RobotState([0, 0], 0, [0, 0]);
robot2 = RobotState([5, 5], pi/2, [0, 0]);
coordinator.addRobot('robot1', robot1);
coordinator.addRobot('robot2', robot2);

% 分配任务
task1 = struct('target', [10, 10], 'type', 'navigation');
task2 = struct('target', [15, 5], 'type', 'navigation');
coordinator.assignTask('robot1', task1);
coordinator.assignTask('robot2', task2);

% 检测和解决冲突
conflicts = coordinator.detectConflicts();
if ~isempty(conflicts)
    coordinator.resolveConflicts(conflicts);
end

GUI界面使用示例

% 启动主控制界面
mainGUI = MainControlGUI();
mainGUI.initialize();

% 启动遥控界面
remoteGUI = RemoteControlInterface('robot1');
remoteGUI.initialize();

% 发送控制指令
remoteGUI.sendVelocityCommand(1.0, 0.5);  % 前进并左转
pause(2);
remoteGUI.sendVelocityCommand(0, 0);     % 停止

path = planner.planPath([1, 1], [19, 19], map);


##### setHeuristic

设置启发式函数类型。

```matlab
setHeuristic(obj, heuristicType)

参数:

  • heuristicType (string): 启发式函数类型 ('manhattan', 'euclidean', 'diagonal')

RRTStarPlanner 类

RRT*全局路径规划算法实现。

构造函数

obj = RRTStarPlanner(maxIterations, stepSize)

参数:

  • maxIterations (int): 最大迭代次数
  • stepSize (double): 步长大小

主要方法

planPath

执行RRT*路径规划。

path = planPath(obj, start, goal, map)

DWAPlanner 类

动态窗口法（DWA）局部路径规划算法实现。

构造函数

obj = DWAPlanner(robotParams)

参数:

  • robotParams (struct): 机器人动力学参数
    • maxVel (double): 最大线速度
    • maxAngVel (double): 最大角速度
    • maxAcc (double): 最大线加速度
    • maxAngAcc (double): 最大角加速度

主要方法

planPath

执行DWA局部路径规划。

[velocity, path] = planPath(obj, robotState, goal, obstacles)

参数:

  • robotState (RobotState): 当前机器人状态
  • goal (double[1,2]): 局部目标点
  • obstacles (double[n,2]): 障碍物位置列表

返回值:

  • velocity (double[1,2]): 最优控制速度 [v, w]
  • path (double[m,2]): 预测路径

多机器人协调

MultiRobotCoordinator 类

多机器人协调控制核心类。

构造函数

obj = MultiRobotCoordinator(maxRobots)

参数:

  • maxRobots (int): 最大机器人数量

主要方法

addRobot

添加机器人到协调系统。

addRobot(obj, robotId, initialState, controlMode)

参数:

  • robotId (string): 机器人唯一标识符
  • initialState (RobotState): 初始状态
  • controlMode (string): 控制模式 ('manual', 'auto')
removeRobot

从协调系统中移除机器人。

removeRobot(obj, robotId)
assignTask

为机器人分配任务。

assignTask(obj, robotId, task)

参数:

  • robotId (string): 目标机器人ID
  • task (struct): 任务信息
    • type (string): 任务类型
    • startPos (double[1,2]): 起始位置
    • goalPos (double[1,2]): 目标位置
    • priority (int): 任务优先级
detectConflicts

检测机器人间的路径冲突。

conflicts = detectConflicts(obj)

返回值:

  • conflicts (cell): 冲突信息列表
resolveConflicts

解决检测到的路径冲突。

resolveConflicts(obj, conflicts)

TaskAllocator 类

任务分配器，负责将任务合理分配给各个机器人。

构造函数

obj = TaskAllocator(allocationStrategy)

参数:

  • allocationStrategy (string): 分配策略 ('nearest', 'balanced', 'priority')

主要方法

allocateTasks

执行任务分配。

allocation = allocateTasks(obj, tasks, robots)

参数:

  • tasks (cell): 任务列表
  • robots (cell): 可用机器人列表

返回值:

  • allocation (containers.Map): 任务分配结果

ConflictResolver 类

冲突解决器，处理多机器人间的路径和资源冲突。

构造函数

obj = ConflictResolver(resolutionMethod)

参数:

  • resolutionMethod (string): 解决方法 ('priority', 'negotiation', 'replanning')

主要方法

resolvePathConflict

解决路径冲突。

resolution = resolvePathConflict(obj, conflictInfo)

环境感知处理

SensorDataProcessor 类

传感器数据处理器，负责处理各种传感器数据。

构造函数

obj = SensorDataProcessor(sensorTypes)

参数:

  • sensorTypes (cell): 支持的传感器类型列表

主要方法

processLidarData

处理激光雷达数据。

processedData = processLidarData(obj, rawData)

参数:

  • rawData (struct): 原始激光雷达数据
    • ranges (double[n,1]): 距离测量值
    • angles (double[n,1]): 角度值
    • timestamp (datetime): 时间戳

返回值:

  • processedData (struct): 处理后的数据
processCameraData

处理摄像头数据。

processedData = processCameraData(obj, imageData)
fuseMultiSensorData

融合多传感器数据。

fusedData = fuseMultiSensorData(obj, sensorDataList)

EnvironmentMapProcessor 类

环境地图处理器，负责地图的创建、更新和维护。

构造函数

obj = EnvironmentMapProcessor(mapParams)

参数:

  • mapParams (struct): 地图参数
    • width (double): 地图宽度
    • height (double): 地图高度
    • resolution (double): 分辨率

主要方法

updateMap

使用传感器数据更新地图。

updateMap(obj, sensorData, robotPose)

参数:

  • sensorData (struct): 传感器数据
  • robotPose (double[1,3]): 机器人位姿 [x, y, theta]
getOccupancyGrid

获取占用栅格地图。

grid = getOccupancyGrid(obj)

返回值:

  • grid (double[m,n]): 占用栅格矩阵

FuzzyEnvironmentProcessor 类

模糊环境处理器，处理不确定性环境信息。

构造函数

obj = FuzzyEnvironmentProcessor(fuzzyParams)

主要方法

processUncertainty

处理环境不确定性。

fuzzyMap = processUncertainty(obj, sensorData, uncertainty)
makeFuzzyDecision

基于模糊逻辑做出决策。

decision = makeFuzzyDecision(obj, inputs)

GUI界面组件

MainControlGUI 类

主控制界面类，系统的主要用户界面。

构造函数

obj = MainControlGUI()

主要方法

initialize

初始化GUI界面。

initialize(obj)
updateDisplay

更新界面显示。

updateDisplay(obj, systemState)
setCallbacks

设置界面回调函数。

setCallbacks(obj, callbackFunctions)

RemoteControlInterface 类

遥控操作界面类。

构造函数

obj = RemoteControlInterface(robotId)

主要方法

enableManualControl

启用手动控制模式。

enableManualControl(obj)
sendControlCommand

发送控制指令。

sendControlCommand(obj, command)

参数:

  • command (struct): 控制指令
    • type (string): 指令类型
    • velocity (double[1,2]): 速度指令
    • duration (double): 执行时间

MonitorDisplayGUI 类

监控显示界面类。

构造函数

obj = MonitorDisplayGUI()

主要方法

updateRobotStatus

更新机器人状态显示。

updateRobotStatus(obj, robotId, status)
updateSystemMetrics

更新系统性能指标。

updateSystemMetrics(obj, metrics)
addLogEntry

添加日志条目。

addLogEntry(obj, logLevel, message)

工具函数

几何计算函数

calculateDistance

计算两点间距离。

distance = calculateDistance(point1, point2)

calculateAngle

计算两点间角度。

angle = calculateAngle(point1, point2)

isPointInPolygon

判断点是否在多边形内。

inside = isPointInPolygon(point, polygon)

路径处理函数

smoothPath

路径平滑处理。

smoothedPath = smoothPath(path, smoothingFactor)

interpolatePath

路径插值。

interpolatedPath = interpolatePath(path, resolution)

validatePath

路径有效性验证。

isValid = validatePath(path, map)

数据转换函数

cartesianToPolar

直角坐标转极坐标。

[r, theta] = cartesianToPolar(x, y)

polarToCartesian

极坐标转直角坐标。

[x, y] = polarToCartesian(r, theta)

配置管理函数

loadConfiguration

加载配置文件。

config = loadConfiguration(configFile)

saveConfiguration

保存配置文件。

saveConfiguration(config, configFile)

validateConfiguration

验证配置有效性。

isValid = validateConfiguration(config)

错误处理

异常类型

系统定义了以下异常类型：

  • PathPlanningException: 路径规划相关异常
  • RobotStateException: 机器人状态异常
  • CommunicationException: 通信异常
  • ConfigurationException: 配置异常
  • SensorException: 传感器异常

异常处理示例

try
    path = planner.planPath(start, goal, map);
catch ME
    if strcmp(ME.identifier, 'PathPlanning:NoSolution')
        warning('无法找到可行路径，使用备用策略');
        path = backupPlanner.planPath(start, goal, map);
    else
        rethrow(ME);
    end
end

性能优化建议

内存管理

  1. 及时清理不需要的大型数据结构
  2. 使用对象池管理频繁创建的对象
  3. 避免在循环中创建大型临时变量

计算优化

  1. 使用向量化操作替代循环
  2. 预分配数组大小
  3. 使用并行计算工具箱加速计算密集型任务

实时性优化

  1. 合理设置更新频率
  2. 使用异步处理避免界面阻塞
  3. 实现数据缓存机制减少重复计算

版本兼容性

本API文档适用于ABU2026系统v1.0及以上版本。不同版本间的主要变化：

  • v1.0: 初始版本
  • v1.1: 增加模糊环境处理功能
  • v1.2: 优化多机器人协调算法
  • v2.0: 重构GUI界面系统

使用时请注意检查版本兼容性。