仿真平台接口定义

MSRS仿真平台接口定义及决策文件调用说明 目 录 11 仿真系统中比赛环境定义(比赛) 1.1 三对三模式中，比赛环境定义 1 1.2 五对五模式中，比赛环境定义 1 1.3 十一对十一模式中，比赛环境定义 1 2 用于数据交换的数据结构定义(C#) 2 2.1 三对三模式中，足球机器人状态数据结构体的定义(C#) 2 2.2 五对五模式中，足球机器人状态数据结构体的定义(C#) 3 2.3 十一对十一模式中，足球机器人状态数据结构体的定义(C#) 4 3 用于数据交换的数据结构说明 6 3.1 坐标系统定义 6 3.2 结构体变量说明 6 4 DLL决策文件加载接口(C#) 7 5 DLL决策文件接口函数说明 8 6 注意事项 9 7 决策文件样例（C++） 9 1 仿真系统中比赛环境定义(标准比赛) 1.1 三对三模式中，比赛环境定义 1) 场地尺寸 赛场为黑色长方形场地，其尺寸是150cm×130cm，带有5cm 高，2.5cm 厚的围墙。在场地的四角固定四个7cm×7cm 的等腰三角形以避免球进入角落。 2) 场地标记 中圈半径是20cm。作为门区的一部分的圆弧沿球门线长20cm，垂直于球门线5cm。主要直线/圆弧（中线、门区边界线和中圈）均为白色，3mm 宽。争球时机器人的站位（圆）标记为灰色。 3) 球门 球门宽40cm，没有横梁和网。 4) 门线和门区 门线是恰好位于球门前长40cm 的直线。门区包括位于球门前尺寸为70cm×15cm 的长方形区域，弧形区域平行于球门线长度为20cm，垂直于球门线高度为5cm。 5) 球 直径42.7mm，重46g。 1.2 五对五模式中，比赛环境定义 1) 场地尺寸 赛场为黑色长方形场地，其尺寸是220cm×180cm ，带有5cm 高，2.5cm 厚的围墙。在场地的四角固定四个7cm×7cm 的等腰三角形以避免球进入角落。 2) 场地标记 中圈半径是25cm。作为门区的一部分的圆弧沿球门线长25cm ，垂直于球门线5cm。主要直线/圆弧（中线、门区边界线和中圈）均为白色，3mm 宽。争球时机器人的站位（圆）标记为灰色。 3) 球门 球门宽40cm，没有横梁和网。 4) 门线与门区 门线是恰好位于球门前长40cm 的直线。门区包括位于球门前尺寸为50cm×15cm 的长方形区域。 5) 罚球区 罚球区球门前尺寸为80cm×35cm 的长方形区域，弧形区域平行于球门线长度为25cm ，垂直于球门线高度为5cm。 6) 球 直径42.7mm，重46g。 1.3 十一对十一模式中，比赛环境定义 1) 场地尺寸 赛场为黑色长方形场地，其尺寸是440㎝×280㎝，带有5㎝ 高，2.5㎝ 厚的围墙，在场地的四角固定四个7㎝×7㎝的等腰三角形以避免球进入角落。 2) 场地标记 中圈半径是75cm。主要直线/圆弧（中线、门区边界线和中圈）均为白色，3㎜ 宽。争球时机器人的站位（圆）标记为灰色。 3) 球门 球门宽60cm，没有横梁和网。 4) 门线与门区 门线是恰好位于球门前长60cm 的直线。门区包括位于球门前尺寸为85×25㎝ 的长方形区域。 5) 罚球区 罚球区球门前尺寸为120cm×70cm 的长方形区域，罚球点距球门中心50㎝，与两球门柱等距，罚球区包括门区。 6) 球 直径42.7mm，重46g。 2 用于数据交换的数据结构定义(C#) 仿真平台定义了结构体数据结构用来和决策文件进行数据交换，从而为决策提供必要的足球机器人及其环境的信息，同时将决策结果返回到仿真平台中，实现对仿真环境中足球机器人的控制。现给出用于数据交换结构体在仿真系统中的定义。 2.1 三对三模式中，足球机器人状态数据结构体的定义(C#) 三对三比赛模式中，用于数据交换结构体在仿真系统中的定义如下： struct Environment3 { public double home0_pos_x; public double home0_pos_y; public double home0_rotation; public double home0_velocityLeft; public double home0_velocityRight; public double home1_pos_x; public double home1_pos_y; public double home1_rotation; public double home1_velocityLeft; public double home1_velocityRight; public double home2_pos_x; public double home2_pos_y; public double home2_rotation; public double home2_velocityLeft; public double home2_velocityRight; public double opponent0_pos_x; public double opponent0_pos_y; public double opponent0_rotation; public double opponent1_pos_x; public double opponent1_pos_y; public double opponent1_rotation; public double opponent2_pos_x; public double opponent2_pos_y; public double opponent2_rotation; public double currentBall_x; public double currentBall_y; public int kickOffStyle; public int whoseBall; public int halfArea; public int pointer; } ; 2.2 五对五模式中，足球机器人状态数据结构体的定义(C#) 五对五比赛模式中，用于数据交换结构体在仿真系统中的定义如下： struct Environment5 { public double home0_pos_x; public double home0_pos_y; public double home0_rotation; public double home0_velocityLeft; public double home0_velocityRight; public double home1_pos_x; public double home1_pos_y; public double home1_rotation; public double home1_velocityLeft; public double home1_velocityRight; public double home2_pos_x; public double home2_pos_y; public double home2_rotation; public double home2_velocityLeft; public double home2_velocityRight; public double home3_pos_x; public double home3_pos_y; public double home3_rotation; public double home3_velocityLeft; public double home3_velocityRight; public double home4_pos_x; public double home4_pos_y; public double home4_rotation; public double home4_velocityLeft; public double home4_velocityRight; public double opponent0_pos_x; public double opponent0_pos_y; public double opponent0_rotation; public double opponent1_pos_x; public double opponent1_pos_y; public double opponent1_rotation; public double opponent2_pos_x; public double opponent2_pos_y; public double opponent2_rotation; public double opponent3_pos_x; public double opponent3_pos_y; public double opponent3_rotation; public double opponent4_pos_x; public double opponent4_pos_y; public double opponent4_rotation; public double currentBall_x; public double currentBall_y; public int kickOffStyle; public int whoseBall; public int halfArea; public int pointer; } ; 2.3 十一对十一模式中，足球机器人状态数据结构体的定义(C#) 十一对十一比赛模式中，用于数据交换结构体在仿真系统中的定义如下： struct Environment11 { public double home0_pos_x; public double home0_pos_y; public double home0_rotation; public double home0_velocityLeft; public double home0_velocityRight; public double home1_pos_x; public double home1_pos_y; public double home1_rotation; public double home1_velocityLeft; public double home1_velocityRight; public double home2_pos_x; public double home2_pos_y; public double home2_rotation; public double home2_velocityLeft; public double home2_velocityRight; public double home3_pos_x; public double home3_pos_y; public double home3_rotation; public double home3_velocityLeft; public double home3_velocityRight; public double home4_pos_x; public double home4_pos_y; public double home4_rotation; public double home4_velocityLeft; public double home4_velocityRight; public double home5_pos_x; public double home5_pos_y; public double home5_rotation; public double home5_velocityLeft; public double home5_velocityRight; public double home6_pos_x; public double home6_pos_y; public double home6_rotation; public double home6_velocityLeft; public double home6_velocityRight; public double home7_pos_x; public double home7_pos_y; public double home7_rotation; public double home7_velocityLeft; public double home7_velocityRight; public double home8_pos_x; public double home8_pos_y; public double home8_rotation; public double home8_velocityLeft; public double home8_velocityRight; public double home9_pos_x; public double home9_pos_y; public double home9_rotation; public double home9_velocityLeft; public double home9_velocityRight; public double home10_pos_x; public double home10_pos_y; public double home10_rotation; public double home10_velocityLeft; public double home10_velocityRight; public double opponent0_pos_x; public double opponent0_pos_y; public double opponent0_rotation; public double opponent1_pos_x; public double opponent1_pos_y; public double opponent1_rotation; public double opponent2_pos_x; public double opponent2_pos_y; public double opponent2_rotation; public double opponent3_pos_x; public double opponent3_pos_y; public double opponent3_rotation; public double opponent4_pos_x; public double opponent4_pos_y; public double opponent4_rotation; public double opponent5_pos_x; public double opponent5_pos_y; public double opponent5_rotation; public double opponent6_pos_x; public double opponent6_pos_y; public double opponent6_rotation; public double opponent7_pos_x; public double opponent7_pos_y; public double opponent7_rotation; public double opponent8_pos_x; public double opponent8_pos_y; public double opponent8_rotation; public double opponent9_pos_x; public double opponent9_pos_y; public double opponent9_rotation; public double opponent10_pos_x; public double opponent10_pos_y; public double opponent10_rotation; public double currentBall_x; public double currentBall_y; public int kickOffStyle; public int whoseBall; public int halfArea; public int pointer; } ; 3 用于数据交换的数据结构说明 3.1 坐标系统定义 1) 位置坐标的原点在场地围墙内左上角，俯视图中X轴正向水平向右，Y轴正向水平向下； 2) 长度单位为厘米，比例为1：1，取值范围取决于场地的大小； 3) 角度坐标的零方向为X轴正向，逆时针为正； 4) 角度单位为度数，比例为1：1，取值范围为(-180,180]。 3.2 结构体变量说明 1) 本方足球机器人队员状态数据 a) public double home0_pos_x：0号足球机器人的X坐标，取值范围取决于场地的长度； b) public double home0_pos_y：0号足球机器人的Ｙ坐标，取值范围取决于场地的宽度； c) public double home0_rotation：0号足球机器人正向与Ｘ轴正向的夹角，逆时针为正向，取值范围为(-180,180]； d) public double home0_velocityLeft：0号足球机器人的左轮轮速，取值范围为[-100,100]； e) public double home0_velocityRight：0号足球机器人的右轮轮速，取值范围为[-100,100]； 本方其它队员的相应值依次类推，其中零号为守门员。 2) 对方足球机器人队员状态数据 a) public double opponent0_pos_x：0号足球机器人的X坐标，取值范围取决于场地的长度； b) public double opponent0_pos_y：0号足球机器人的Ｙ坐标，取值范围取决于场地的宽度； c) public double opponent0_rotation：0号足球机器人正向与Ｘ轴正向的夹角，逆时针为正向，取值范围为(-180,180]； 对方其它队员的相应值依次类推，其中零号为守门员。 3) 球状态数据 a) public double currentBall_x：球的X坐标，取值范围取决于场地的长度； b) public double currentBall_y：球的Ｙ坐标，取值范围取决于场地的宽度； 4) 比赛状态数据 a) public int kickOffStyle：用来指示开球方式，裁判设置后更新一次，之后由决策文件维护（0正常开球，1争球，2点球，3任意球，4门球）； b) public int whoseBall：决定本方是否开球（0任意，1本方开球，2对方开球）； c) public int halfArea：决定本方半场（0左半场黄队，1右半场蓝队）； d) public int pointer：针对需要分配资源的编程语言，保存资源的指针。 4 DLL决策文件加载接口(C#) 仿真平台决策文件的动态加载是通过调用操作系统API实现的，现给出仿真平台中动态加载动态链接库的部分的实现代码。 1) 加载系统API部分的实现 internal static class NativeMethods { //系统API引用声明 [DllImport("kernel32.dll")] internal static extern IntPtr LoadLibrary(string lpLibFileName); [DllImport("kernel32.dll")] internal static extern IntPtr GetProcAddress(IntPtr hModule, string lpProcName); [DllImport("kernel32.dll")] internal static extern bool FreeLibrary(IntPtr hLibModule); } 2) 加载系统决策DLL部分的实现(以黄队决策加载为例) //保存调用函数接口的指针 IntPtr vProcAddress = new IntPtr(); if (0 != vYellowLibraryHandle.ToInt32()) { //首先卸载已经加载的决策文件 NativeMethods.FreeLibrary(vYellowLibraryHandle); vYellowLibraryHandle = new IntPtr(0); } //加载决策文件 vYellowLibraryHandle = NativeMethods.LoadLibrary(StrategyFileName); try { //获取决策文件相应函数的入口点 vProcAddress = NativeMethods.GetProcAddress(vYellowLibraryHandle, "StrategyInit"); YellowStrategyInit = Marshal.GetDelegateForFunctionPointer(vProcAddress, typeof(Delegate_Strategy)) as Delegate_Strategy; vProcAddress = NativeMethods.GetProcAddress(vYellowLibraryHandle, "StrategyStep"); YellowStrategyStep = Marshal.GetDelegateForFunctionPointer(vProcAddress, typeof(Delegate_Strategy)) as Delegate_Strategy; vProcAddress = NativeMethods.GetProcAddress(vYellowLibraryHandle, "StrategyDrop"); YellowStrategyDrop = Marshal.GetDelegateForFunctionPointer(vProcAddress, typeof(Delegate_Strategy)) as Delegate_Strategy; vProcAddress = NativeMethods.GetProcAddress(vYellowLibraryHandle, "SetForm"); YellowSetForm = Marshal.GetDelegateForFunctionPointer(vProcAddress, typeof(Delegate_Strategy)) as Delegate_Strategy; vProcAddress = NativeMethods.GetProcAddress(vYellowLibraryHandle, "Author"); YellowAuthor = Marshal.GetDelegateForFunctionPointer(vProcAddress, typeof(Delegate_Author)) as Delegate_Author; } catch (Exception e) { //没有正确加载决策文件时会给出此提示信息 MatchFormUI.Message(MatchForm.MessageType.MsgBox, "Error to load:" + StrategyFileName + "\nPlease check if it is valid!"); } 5 DLL决策文件接口函数说明 1) StrategyInit函数 C原型：extern "C" __declspec(dllexport) void StrategyInit ( Environment *env ) 功能：分配决策DLL文件中的资源，并将其地址赋值给pointer。 调用周期：仅在加载DLL时调用一次。 2) StrategyStep函数 C原型：extern "C" __declspec(dllexport) void StrategyStep ( Environment *env ) 功能：实现控制决策，根据传入的状态数据决策出左右轮速，设置状态数据中的相应变量，实现足球机器人的控制。 调用周期：5ms 3) StrategyDrop函数 C原型：extern "C" __declspec(dllexport) void StrategyDrop ( Environment *env ) 功能：实现控制决策，根据传入的状态数据决策出左右轮速，设置状态数据中的相应变量，实现足球机器人的控制。 调用周期：仅在卸载DLL时调用一次。 4) SetForm函数 C原型：extern "C" __declspec(dllexport) void SetForm ( Environment *env ) 功能：完成本方队形的设置。 调用周期：在设置队形时调用一次。 5) Author函数 C原型：extern "C" __declspec(dllexport) void Author ( char *env ) 功能：提取表征作者身份的唯一标识，将被显示在控制面板上。 调用周期：仅在加载DLL时调用一次。 6 注意事项 1) 考虑不同语言兼容性，状态数据结构体的定义没有采用数组。 2) 不同语言之间传递数据时，请注意数据类型的匹配关系，相同的数据类型在不同语言的实现一般是不同的（不同的存储长度，不同的运算规则等），如C#的int型基本数据类型对应C++语言的long基本数据类型。仿真系统是基于C#语言开发的，希望在接口设计的时候充分考虑已经给出数据传输部分的实现。 3) 仿真平台是基于DotNet2.0开发的，请在开发决策文件的过程中充分考虑平台的兼容性。 4) 决策文件的调用周期是5ms。 5) 在接口设计的时候，平台充分考虑了决策文件版权问题。因为平台采用的是DLL外部决策文件，平台设计了Author接口识别不同参赛队的决策文件，希望注意决策文件的保密工作。 6) 请考虑坐标系统的特殊性。 7) C++语言实现的接口DLL函数请以extern "C"声明。 8) kickOffStyle信号量仅在裁判更改开球方式后仅被更新－次，之后将由决策文件维护，直到新的开球方式被裁判选择。 9) 请注意接口数据结构变量的取值范围和单位。 7 决策文件样例（C++） 见附件。 PAGE 1