# kaiwu-comp-2026-juesai

**Repository Path**: script2000/kaiwu-comp-2026-juesai

## Basic Information

- **Project Name**: kaiwu-comp-2026-juesai
- **Description**: 决赛，无人机
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-09
- **Last Updated**: 2026-05-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

## clone repo

```sh
git clone https://gitee.com/script2000/kaiwu-comp-2026-juesai.git --filter=blob:none drone_obstacle_nav
```

## 任务目标

控制一架 Crazyflie 四旋翼无人机，从封闭空间一端的起点出发，自主避开随机生成的柱状障碍物群，途中收集路径上的途径点，到达另一端终点并稳定悬停。

任务由导航阶段和悬停阶段两段组成：

- 导航阶段：无人机从起点出发，避开障碍物、通过可选途径点，到达终点区域。
- 悬停阶段：进入终点区域后，连续悬停指定步数并保持位置精度。

## 环境介绍

基于 NVIDIA Isaac Sim（OmniDrones）构建的无人机三维飞行仿真环境。被控对象为与 Crazyflie 2.1 物理参数对齐的四旋翼无人机模型，采用 PIDrate（CTBR：Collective Thrust + Body Rate）控制模式。

<table border="1" cellpadding="8" cellspacing="0" style="border-collapse: collapse; font-family: sans-serif;">
  <thead>
    <tr>
      <th style="text-align: left; width: 120px;">参数</th>
      <th style="text-align: left;">说明</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>仿真平台</td>
      <td>NVIDIA Isaac Sim + OmniDrones</td>
    </tr>
    <tr>
      <td>机型</td>
      <td>四旋翼（对齐 Crazyflie 物理参数）</td>
    </tr>
    <tr>
      <td>控制模式</td>
      <td>CTBR 角速率指令 → PIDRateController → 电机推力</td>
    </tr>
    <tr>
      <td>动作空间</td>
      <td>4 维连续 [-1, 1]（roll/pitch/yaw 角速度 + 推力比）</td>
    </tr>
    <tr>
      <td>观测空间</td>
      <td>95 维 float32（全局观测）</td>
    </tr>
    <tr>
      <td>仿真步长</td>
      <td>dt = 0.02s</td>
    </tr>
  </tbody>
</table>

## 地图
封闭长方体空间（5m × 5m × 3m），四面墙壁 + 天花板 + 地面，无人机不得飞出边界。

起点：空间一端固定位置
终点：空间另一端固定位置
初始姿态：yaw = 0°（朝向 +x 方向，即终点方向），零速度悬停起飞

## 元素介绍
<table border="1" cellpadding="8" cellspacing="0" style="border-collapse: collapse; font-family: sans-serif;">
  <thead>
    <tr>
      <th style="text-align: left; width: 80px;">元素</th>
      <th style="text-align: left;">说明</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>无人机</td>
      <td>四旋翼飞行器（对齐 Crazyflie 物理参数），质量约 27g，动作空间为 4 维连续 CTBR 指令（3 维角速度 + 1 维推力比）</td>
    </tr>
    <tr>
      <td>障碍物</td>
      <td>从地面延伸至天花板的圆柱体，随机数量（2~5）和随机半径（离散 5 档：0.15~0.35m），位置随机生成</td>
    </tr>
    <tr>
      <td>起点</td>
      <td>空间一端固定位置 [0.5, 2.5, 0.15]，无人机初始放置于此</td>
    </tr>
    <tr>
      <td>终点</td>
      <td>空间另一端固定位置 [4.5, 2.5, 1.5]（虚拟点，无物理实体），到达判定半径 0.2m</td>
    </tr>
    <tr>
      <td>途径点</td>
      <td>空间中虚拟点（无物理实体），可选加分项，随机数量（0~5），触达判定半径 0.2m</td>
    </tr>
  </tbody>
</table>

## 计分规则
### 评分公式
每个任务的评分由导航分、悬停分和 途径分三个子项相加，满分 100 分。

总分 = nav_score + hover_score + wp_score

### 子分计算

nav_score（导航分）

```
nav_score = nav_coeff × w_nav × (0.5 × time_norm + 0.5 × smooth_norm) × 100
```

- nav_coeff：计分资格标记，到达终点区域为 1，否则为 0
- w_nav = 0.25：导航分权重
- time_norm：导航时间归一化子项，越快越高
- smooth_norm：飞行平滑度归一化子项，越平稳越高

hover_score（悬停分）
```
hover_score = nav_coeff × hover_coeff × w_hover × clamp(1 - avg_position_error / 0.5, 0, 1) × 100
```

- nav_coeff：计分资格标记，到达终点区域为 1，否则为 0
- hover_coeff：悬停计分标记，成功完成悬停为 1，否则为 0
- w_hover = 0.35：悬停分权重
- avg_position_error：悬停期间的平均位置偏移

wp_score（途径点分）
```
wp_score = nav_coeff × w_wp × (visited_count / total_waypoints) × 100
```

- nav_coeff：计分资格标记，到达终点区域为 1，否则为 0
- w_wp = 0.40：途径点分权重
- visited_count：已收集的 Waypoint 数
- total_waypoints：当局总 Waypoint 数

任务失败
以下情况 episode 立即终止，总分 = 0：

- 无人机飞出封闭空间边界
- 碰撞次数达到 max_collisions（测评锁定为 1）

## 环境配置

在智能体和环境的交互中，首先会调用env.reset方法，该方法接受一个usr_conf参数，这个参数通过读取train_env_conf.toml文件的内容来实现定制化的环境配置。因此，用户可以通过修改train_env_conf.toml文件中的内容来调整环境配置。
```
# usr_conf为用户传入的环境配置
env_obs = env.reset(usr_conf=usr_conf)
```
train_env_conf.toml中包含以下配置信息：

### 关键参数说明
<table border="1" cellpadding="8" cellspacing="0" style="border-collapse: collapse; font-family: sans-serif;">
  <thead>
    <tr>
      <th style="text-align: left;">配置项</th>
      <th style="text-align: left;">类型</th>
      <th style="text-align: left;">默认值</th>
      <th style="text-align: left;">取值范围</th>
      <th style="text-align: left;">说明</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td><code>num_envs</code></td>
      <td>int</td>
      <td>2048</td>
      <td>&gt; 0</td>
      <td>并行环境数量（Isaac Sim GPU 并行仿真实例数）</td>
    </tr>
    <tr>
      <td><code>num_obstacles_range</code></td>
      <td>int[2]</td>
      <td>[2, 5]</td>
      <td>min ≥ 2, max ≤ 5</td>
      <td>每局障碍物数量采样范围</td>
    </tr>
    <tr>
      <td><code>radius_choices</code></td>
      <td>float[]</td>
      <td>[0.15, 0.20, 0.25, 0.30, 0.35]</td>
      <td>预定义离散值的非空子集</td>
      <td>障碍物半径离散档位（米），同一 episode 内所有障碍物共用</td>
    </tr>
    <tr>
      <td><code>nav_max_steps</code></td>
      <td>int</td>
      <td>1500</td>
      <td>[100, 3000]</td>
      <td>导航阶段最大步数，超过未到达终点判定超时（测评使用 1500）</td>
    </tr>
    <tr>
      <td><code>hover_max_steps</code></td>
      <td>int</td>
      <td>150</td>
      <td>[50, 500]</td>
      <td>悬停阶段固定步数</td>
    </tr>
    <tr>
      <td><code>max_collisions</code></td>
      <td>int</td>
      <td>5</td>
      <td>[1, 5]</td>
      <td>碰撞上限，达到则 episode 终止（测评锁定为 1）</td>
    </tr>
    <tr>
      <td><code>num_waypoints_range</code></td>
      <td>int[2]</td>
      <td>[0, 5]</td>
      <td>min ≥ 0, max ≤ 5</td>
      <td>每局 Waypoint 数量采样范围，设为 0 可退化为纯导航+悬停训练</td>
    </tr>
  </tbody>
</table>

### 奖励配置说明

奖励实现归属 agent_ppo/feature/reward_process.py，每个 [rewards.<name>] 段对应一个 _reward_<name>() 方法。weight 用于控制该项是否参与最终求和以及参与强度（设为 0.0 可禁用某项）。

<table border="1" cellpadding="8" cellspacing="0" style="border-collapse: collapse; font-family: sans-serif;">
  <thead>
    <tr>
      <th style="text-align: left;">奖励项</th>
      <th style="text-align: left; width: 60px;">类别</th>
      <th style="text-align: left;">说明</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td><code>target_progress</code></td>
      <td>导航</td>
      <td>当前导航目标距离进展奖励：有未访问 waypoint 时跟踪 waypoint，清空后跟踪终点</td>
    </tr>
    <tr>
      <td><code>goal_reached</code></td>
      <td>导航</td>
      <td>首次到达终点并切入悬停阶段的一次性奖励；仅在 waypoint 已全部完成时生效（默认 100.0）</td>
    </tr>
    <tr>
      <td><code>in_arena</code></td>
      <td>安全</td>
      <td>场内存活奖励 / 出界惩罚（默认出界 -100.0）</td>
    </tr>
    <tr>
      <td><code>obstacle_proximity</code></td>
      <td>安全</td>
      <td>接近障碍安全距离阈值时的惩罚（默认单步 -2.0）</td>
    </tr>
    <tr>
      <td><code>collision</code></td>
      <td>安全</td>
      <td>发生碰撞接触时的惩罚（默认单步 -20.0）</td>
    </tr>
    <tr>
      <td><code>stall</code></td>
      <td>导航</td>
      <td>目标距离无进展时的停滞惩罚（默认 -0.1）</td>
    </tr>
    <tr>
      <td><code>waypoint_visit</code></td>
      <td>路径点</td>
      <td>基于“新增已访问 waypoint 数量”增量的路径点访问奖励（可配置时间衰减，每个 waypoint 仅奖励一次）</td>
    </tr>
    <tr>
      <td><code>hover_stability</code></td>
      <td>悬停</td>
      <td>悬停阶段鼓励低位置误差与低速度；离开终点区域与高速漂移会额外扣分</td>
    </tr>
    <tr>
      <td><code>action_smoothness</code></td>
      <td>控制</td>
      <td>惩罚动作一阶/二阶误差，提升飞行平滑度</td>
    </tr>
    <tr>
      <td><code>energy_efficiency</code></td>
      <td>控制</td>
      <td>惩罚控制能耗，鼓励低能耗轨迹</td>
    </tr>
    <tr>
      <td><code>hover_precision</code></td>
      <td>悬停</td>
      <td>悬停阶段按位置误差精度给出正向奖励</td>
    </tr>
    <tr>
      <td><code>collision_exceeded</code></td>
      <td>终止</td>
      <td>碰撞超限时的额外终止惩罚</td>
    </tr>
    <tr>
      <td><code>timeout</code></td>
      <td>终止</td>
      <td>导航超时时的额外终止惩罚</td>
    </tr>
  </tbody>
</table>

>💡 补充说明：
> train_env_conf.toml文件中的配置仅在训练时生效，请按上表数据描述进行配置。若配置错误，训练任务会变为"失败"状态，此时可以通过查看env模块的错误日志进行排查。
> 若需调整模型评估任务时的配置，用户需要通过腾讯开悟平台创建评估任务并完成环境配置，详细参数见智能体模型评估模式。
> baseline 默认已提供导航、安全、路径点、悬停与终止相关的多项奖励。用户仍可按需继续扩展，在 reward_process.py 中新增 _reward_<name>() 方法，并在 toml 中追加对应 [rewards.<name>] 段启用。

### 环境信息
<table border="1" cellpadding="8" cellspacing="0" style="border-collapse: collapse; font-family: sans-serif;">
  <thead>
    <tr>
      <th style="text-align: left;">数据名</th>
      <th style="text-align: left;">数据类型</th>
      <th style="text-align: left;">数据描述</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td><code>frame_no</code></td>
      <td>int</td>
      <td>当前环境实例运行时的帧号</td>
    </tr>
    <tr>
      <td><code>observation</code></td>
      <td>Observation</td>
      <td>环境实例的观测信息（95维 float32 张量）</td>
    </tr>
    <tr>
      <td><code>terminated</code></td>
      <td>int</td>
      <td>当前环境实例是否结束（出界/碰撞超限/悬停完成）</td>
    </tr>
    <tr>
      <td><code>truncated</code></td>
      <td>int</td>
      <td>当前环境实例是否异常或中断</td>
    </tr>
    <tr>
      <td><code>extra_info</code></td>
      <td>ExtraInfo</td>
      <td>环境实例的可选额外信息</td>
    </tr>
  </tbody>
</table>

### 观测信息（observation）
观测为 95 维 float32 张量，shape [num_envs, 1, 95]，包含无人机自身状态、障碍物信息、目标点信息和时间编码：

<table border="1" cellpadding="8" cellspacing="0" style="border-collapse: collapse; font-family: sans-serif;">
  <thead>
    <tr>
      <th style="text-align: left;">字段名</th>
      <th style="text-align: left;">索引</th>
      <th style="text-align: left;">类型</th>
      <th style="text-align: left;">说明</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td><code>target_rpos</code></td>
      <td>[0:3]</td>
      <td>float32[3]</td>
      <td>终点相对位置（基于加噪位置计算）</td>
    </tr>
    <tr>
      <td><code>obstacle_rpos</code></td>
      <td>[3:27]</td>
      <td>float32[8×3]</td>
      <td>8 个障碍物相对位置展平，未激活槽位全 0</td>
    </tr>
    <tr>
      <td><code>linear_velocity</code></td>
      <td>[27:30]</td>
      <td>float32[3]</td>
      <td>机体线速度</td>
    </tr>
    <tr>
      <td><code>angular_velocity</code></td>
      <td>[30:33]</td>
      <td>float32[3]</td>
      <td>机体角速度</td>
    </tr>
    <tr>
      <td><code>rotation_matrix</code></td>
      <td>[33:42]</td>
      <td>float32[9]</td>
      <td>旋转矩阵展平（3×3），取值 [-1, 1]</td>
    </tr>
    <tr>
      <td><code>hover_timer</code></td>
      <td>[42:43]</td>
      <td>float32[1]</td>
      <td>悬停阶段累计时长（秒），导航阶段为 0</td>
    </tr>
    <tr>
      <td><code>obstacle_radii</code></td>
      <td>[43:51]</td>
      <td>float32[8]</td>
      <td>8 个障碍物半径，未激活为 0</td>
    </tr>
    <tr>
      <td><code>start_rpos</code></td>
      <td>[51:54]</td>
      <td>float32[3]</td>
      <td>起点相对位置</td>
    </tr>
    <tr>
      <td><code>goal_rpos</code></td>
      <td>[54:57]</td>
      <td>float32[3]</td>
      <td>终点相对位置</td>
    </tr>
    <tr>
      <td><code>phase_onehot</code></td>
      <td>[57:59]</td>
      <td>float32[2]</td>
      <td>导航/悬停阶段 one-hot（[1,0]=导航，[0,1]=悬停）</td>
    </tr>
    <tr>
      <td><code>waypoint_rpos</code></td>
      <td>[59:83]</td>
      <td>float32[8×3]</td>
      <td>8 个 Waypoint 相对位置展平</td>
    </tr>
    <tr>
      <td><code>waypoint_visited</code></td>
      <td>[83:91]</td>
      <td>float32[8]</td>
      <td>0=待访问，1=已访问或槽位未启用</td>
    </tr>
    <tr>
      <td><code>time_encoding</code></td>
      <td>[91:95]</td>
      <td>float32[4]</td>
      <td>归一化进度编码</td>
    </tr>
  </tbody>
</table>

> 注意：target_rpos 与 goal_rpos 当前实现相同，均为终点相对位置。若需要"当前最近途径点"信息，请在 agent 侧自行根据 waypoint_rpos 和 waypoint_visited 计算。

## 得分信息
score_info 是在当前状态下执行动作 action 所获得的分数，分数的计算详见[计分规则](#计分规则)。

> 注意：得分用于衡量模型在环境中的表现，也作为衡量强化学习训练产出模型的评价指标，与强化学习里的奖励reward 要区别开。

### 额外信息（extra_info）
<table border="1" cellpadding="8" cellspacing="0" style="border-collapse: collapse; font-family: sans-serif;">
  <thead>
    <tr>
      <th style="text-align: left;">字段名</th>
      <th style="text-align: left;">类型</th>
      <th style="text-align: left;">说明</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td><code>result_code</code></td>
      <td>int</td>
      <td>0=正常；-1=reset异常；-2=step异常</td>
    </tr>
    <tr>
      <td><code>result_message</code></td>
      <td>str</td>
      <td>错误详情或 "OK"</td>
    </tr>
    <tr>
      <td><code>stats</code></td>
      <td>dict[str, np.ndarray]</td>
      <td>环境监控与评分字段（key 集合固定，每个 value shape 为 [N, 1]）</td>
    </tr>
  </tbody>
</table>

stats 关键字段：

<table border="1" cellpadding="8" cellspacing="0" style="border-collapse: collapse; font-family: sans-serif;">
  <thead style="background-color: #f2f2f2;">
    <tr>
      <th style="text-align: left;">字段名</th>
      <th style="text-align: left;">类型</th>
      <th style="text-align: left;">说明</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td><code>success</code></td>
      <td>np.ndarray[N,1]</td>
      <td>最终是否完成任务</td>
    </tr>
    <tr>
      <td><code>timeout</code></td>
      <td>np.ndarray[N,1]</td>
      <td>是否导航超时</td>
    </tr>
    <tr>
      <td><code>collision_exceeded</code></td>
      <td>np.ndarray[N,1]</td>
      <td>是否碰撞超限</td>
    </tr>
    <tr>
      <td><code>arrival_success</code></td>
      <td>np.ndarray[N,1]</td>
      <td>是否进入过终点区域</td>
    </tr>
    <tr>
      <td><code>hover_success</code></td>
      <td>np.ndarray[N,1]</td>
      <td>是否完成悬停</td>
    </tr>
    <tr>
      <td><code>hover_failed</code></td>
      <td>np.ndarray[N,1]</td>
      <td>是否悬停阶段失败</td>
    </tr>
    <tr>
      <td><code>total_score</code></td>
      <td>np.ndarray[N,1]</td>
      <td>最终比赛总分</td>
    </tr>
    <tr>
      <td><code>nav_coeff</code></td>
      <td>np.ndarray[N,1]</td>
      <td>导航计分资格标记</td>
    </tr>
    <tr>
      <td><code>hover_coeff</code></td>
      <td>np.ndarray[N,1]</td>
      <td>悬停计分标记</td>
    </tr>
    <tr>
      <td><code>nav_score_raw</code></td>
      <td>np.ndarray[N,1]</td>
      <td>导航归一化子分</td>
    </tr>
    <tr>
      <td><code>hover_score_raw</code></td>
      <td>np.ndarray[N,1]</td>
      <td>悬停归一化子分</td>
    </tr>
    <tr>
      <td><code>wp_score_raw</code></td>
      <td>np.ndarray[N,1]</td>
      <td>Waypoint 归一化子分</td>
    </tr>
    <tr>
      <td><code>time_norm</code></td>
      <td>np.ndarray[N,1]</td>
      <td>导航时间归一化子项</td>
    </tr>
    <tr>
      <td><code>smooth_norm</code></td>
      <td>np.ndarray[N,1]</td>
      <td>平滑度归一化子项</td>
    </tr>
    <tr>
      <td><code>waypoints_visited</code></td>
      <td>np.ndarray[N,1]</td>
      <td>已访问 Waypoint 数</td>
    </tr>
    <tr>
      <td><code>waypoints_total</code></td>
      <td>np.ndarray[N,1]</td>
      <td>总 Waypoint 数</td>
    </tr>
    <tr>
      <td><code>collision_count</code></td>
      <td>np.ndarray[N,1]</td>
      <td>累计碰撞次数</td>
    </tr>
    <tr>
      <td><code>hover_precision</code></td>
      <td>np.ndarray[N,1]</td>
      <td>最终悬停精度</td>
    </tr>
  </tbody>
</table>

## 动作空间
动作为 4 维连续向量。底层控制模式为 PIDrate（CTBR：Collective Thrust + Body Rate）：策略网络输出经 tanh 压缩到 [-1, 1] 后，送入 PID 速率控制器转换为电机推力指令。

<table border="1" cellpadding="8" cellspacing="0" style="border-collapse: collapse; font-family: sans-serif;">
  <thead>
    <tr>
      <th style="text-align: left;">维度</th>
      <th style="text-align: left;">策略归一化范围</th>
      <th style="text-align: left;">物理含义</th>
      <th style="text-align: left;">底层映射</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td><code>action[0]</code></td>
      <td>[-1, 1]</td>
      <td>目标 roll 角速度</td>
      <td>线性映射到 [-180°/s, +180°/s]</td>
    </tr>
    <tr>
      <td><code>action[1]</code></td>
      <td>[-1, 1]</td>
      <td>目标 pitch 角速度</td>
      <td>线性映射到 [-180°/s, +180°/s]</td>
    </tr>
    <tr>
      <td><code>action[2]</code></td>
      <td>[-1, 1]</td>
      <td>目标 yaw 角速度</td>
      <td>线性映射到 [-180°/s, +180°/s]</td>
    </tr>
    <tr>
      <td><code>action[3]</code></td>
      <td>[-1, 1]</td>
      <td>目标推力比</td>
      <td>重映射为 (x+1)/2 并 clamp 到 [0.0, 1.0]</td>
    </tr>
  </tbody>
</table>

### 合法动作
本任务为连续动作空间，不存在离散合法动作过滤。所有 4 维动作值均有效，经 tanh 激活后天然约束在 [-1, 1] 范围内。

### 时间信息
步(step)和帧(frame)存在一定映射关系。

步是强化学习环境中的一个时间单位，表示智能体(agent)在环境中执行一个动作并接收反馈的过程。在每一步中，智能体选择一个动作，环境根据该动作更新状态，并返回新的状态、奖励和终止信号。

帧是场景的一个时间单位，表示场景的一个完整更新周期。在每一帧中，场景的所有元素都会根据当前的状态和输入进行更新。

本任务中每一步对应一帧，即 step : frame = 1 : 1。episode 实际最大总步数 = nav_max_steps + hover_max_steps（默认 1500 + 150 = 1650 步）。