it4lia/UAV_dataset

# UAV Testing Competition Dataset

Unmanned Aerial Vehicles (UAVs) equipped with onboard cameras and various sensors have already demonstrated the possibility of autonomous flights in real environments, leading to great interest in various application scenarios: crop monitoring, surveillance, medical and food delivery.

Over the years, support for UAV developers has increased with open-access projects for software and hardware, such as the autopilot support provided by [PX4](https://github.com/PX4/PX4-Autopilot) and [Ardupilot](https://github.com/ArduPilot/ardupilot).
However, despite the necessity of systematically testing such complex and automated systems to ensure their safe operation in real-world environments, there has been relatively limited investment in this direction so far.

The UAV Testing Competition organized jointly by the [International Conference on Software Testing, Verification and Validation (ICST)](https://conf.researchr.org/home/icst-2026) and [Search-Based and Fuzz Testing (SBFT) workshop](https://search-based-and-fuzz-testing.github.io/sbft26/) is an initiative designed to inspire and encourage the Software Testing Community to direct their attention toward UAVs as a rapidly emerging and crucial domain. The joint call is meant to help interested authors/participants reduce travel costs by selecting the most convenient and close venue.

## Files

| File | Description |
|------|-------------|
| `UAV.db` | SQLite database — all flight data |
| [`UAV_notebook.ipynb`](https://huggingface.co/datasets/it4lia/UAV_dataset/blob/main/UAV_notebook.ipynb) | Exploration notebook — visualizations, metrics, ML export, and tools to add new missions |
| [`Dataset_gen.ipynb`](https://huggingface.co/datasets/it4lia/UAV_dataset/blob/main/dataset_gen.ipynb) | Python pipeline — scans flight folders and populates the database |
| `requirements.txt` | Pinned library versions for reproducible environment setup |

Place all files in the same directory before running the notebook.

---

## What's in the database?

The database currently holds flights from PX4 simulations. Each flight contains two types of data:

**Dynamic data** — sensor time-series recorded during the flight, stored as ULog topics:
- `vehicle_local_position` — position in NED frame: x, y, z (meters) and velocity (m/s)
- `vehicle_attitude` — orientation as quaternion (w, x, y, z); dimensionless
- `sensor_combined` — raw IMU measurements: accelerometer (m/s²), gyroscope (rad/s)
- `vehicle_status` — flight mode and arming state

**Static data** — simulation conditions set before the flight:
- Wind parameters: mean velocity (m/s), direction (unit vector), gusts and variance (m/s)
- Obstacle positions (meters) and dimensions — height, length, width (meters) — up to N obstacles per flight
- PX4 flight controller parameters: navigation acceptance radius (meters), takeoff altitude (meters), etc.

### Database schema

```
missions
└── flights one row per simulation flight
├── flight_context static conditions (wind, obstacles, PX4 params)
└── topics ULog topics recorded during the flight
├── topic_fields field names and data types
└── topic_data time-series values (long format)
```

`topic_data` uses **long format** — each row is one `(topic_id, row_index, field_name, value)` tuple.
The notebook's `get_topic()` helper pivots this into a wide DataFrame automatically.

---

## Quickstart

### Requirements

Install dependencies using the provided `requirements.txt` to ensure version compatibility:

```bash
pip install -r requirements.txt
```

### Open the notebook

```bash
jupyter notebook UAV_notebook.ipynb
```

The notebook connects to `UAV.db` directly — no additional setup needed.

### Query the database directly

```python
import sqlite3
import pandas as pd

con = sqlite3.connect("UAV.db")

# All flights with duration
flights = pd.read_sql(
"SELECT iter_number, duration_s FROM flights ORDER BY iter_number", con
)

# Position time-series for flight iteration #2 (long → wide)
pos_raw = pd.read_sql("""
SELECT td.row_index, td.field_name, td.value
FROM topic_data td
JOIN topics t ON t.id = td.topic_id
JOIN flights f ON f.id = t.flight_id
WHERE f.iter_number = 2
AND t.name = 'vehicle_local_position'
ORDER BY td.row_index
""", con)

pos = pos_raw.pivot(index="row_index", columns="field_name", values="value")

# Simulation conditions for every flight (wide format)
context = pd.read_sql("""
SELECT f.iter_number, c.key, c.value
FROM flights f
JOIN flight_context c ON c.flight_id = f.id
""", con)

context_wide = context.pivot_table(
index="iter_number", columns="key", values="value"
).reset_index()
```

---

## ML export

Use `build_ml_dataset()` (or run Section 7 of the notebook) to export a flat Parquet file ready for training.
Every row is one timestep. Static features are repeated on all rows belonging to the same flight.

| Group | Example columns | Note |
|-------|-----------------|------|
| Time | `timestamp` | Microseconds; resampled to a uniform grid |
| Position | `vehicle_local_position__x/y/z` | NED frame (meters) — use `-z` for altitude |
| Attitude | `vehicle_attitude__q[0..3]` | Quaternion, scalar-first (w, x, y, z); dimensionless |
| Wind | `wind_velocity_mean`, `wind_dir_x/y/z` | Static per flight; velocity in m/s, direction as unit vector |
| Obstacles | `obs0_x/y/z/h/l/w`, `obs1_...` | Static per flight; position and dimensions in meters |
| PX4 params | `px4_NAV_ACC_RAD`, `px4_MIS_TAKEOFF_ALT` | Static per flight; distances in meters |
| Flight ID | `iter_number`, `iter_name` | Use to group or split by flight |

---

## Notebook
Inside the notebook you will find everything that can be useful for data science such as statistics, queries, and how the database is structured. There is also code showing how the database is constructed.

---

## Adding new flights

Section 8 of the notebook walks through the full import process. In short:

1. Organize your flights under a root folder (one subfolder per iteration, each containing a `.ulg` file and optionally a `.yaml` config)
2. Set `NEW_ROOT_DIR` in the notebook
3. Run the discovery cell to preview what will be imported
4. Run the pipeline cell to write to `UAV.db`

You can also call the pipeline directly from Python:

```python
from Dataset_gen import run_pipeline

run_pipeline(
root_dir = "./my_flights",
db_path = "UAV.db",
ml_topics = ["vehicle_local_position", "vehicle_attitude"],
resample_us = 100_000, # 10 Hz
downsample_factor = 10,
skip_existing = True,
)
```

---

## Notes

- **NED frame**: `z` points downward — use `-z` to get altitude above ground (meters)
- **Quaternion convention**: `q[0]` = scalar part (w), `q[1..3]` = vector part (x, y, z)
- `topic_data` stores values in long format; use `pivot()` or the `get_topic()` helper to work with it

## Full dataset
The full dataset can be found at the website here :
https://zenodo.org/records/18727376

## References

If you use this tool in your research, please cite the following papers:

- **Sajad Khatiri**, Sebastiano Panichella, and Paolo Tonella, "Simulation-based Testing of Unmanned Aerial Vehicles with Aerialist," *In 2024 International Conference on Software Engineering (ICSE)*. [Link](https://dl.acm.org/doi/10.1145/3639478.3640031).

````{code-block} bibtex
@inproceedings{icse2024Aerialist,
title={Simulation-based Testing of Unmanned Aerial Vehicles with Aerialist},
author={Khatiri, Sajad and Panichella, Sebastiano and Tonella, Paolo},
booktitle={International Conference on Software Engineering (ICSE)},
year={2024},
}
````

- **SBFT Tool competition report**
````{code-block} bibtex
@inproceedings{SBFT-UAV2026,
author = {Ramazan Erdem Uysal and Ali Javadi and Prakash Aryan and Aren Babikian and Dmytro Humeniuk and Sajad Mazraehkhatiri and Sebastiano Panichella},
title = {{SBFT} Tool Competition 2026 – UAV Testing Track},
booktitle = {International Workshop on Search-Based and Fuzz Testing,
SBFT@ICSE 2026},
year = {2026}
}
````

- **ICST Tool competition report**
````{code-block} bibtex
@inproceedings{ICST-UAV2026,
author = {Ramazan Erdem Uysal and Ali Javadi and Prakash Aryan and Aren Babikian and Dmytro Humeniuk and Sajad Mazraehkhatiri and Sebastiano Panichella},
title = {{ICST} Tool Competition 2026 – UAV Testing Track},
booktitle = {International Conference on Software Testing, Verification and Validation (ICST)},
year = {2026}
}
````

- **Sajad Khatiri**, Sebastiano Panichella, and Paolo Tonella, "Simulation-based Test Case Generation for Unmanned Aerial Vehicles in the Neighborhood of Real Flights," *In 2023 IEEE 16th International Conference on Software Testing, Verification and Validation (ICST)*. [Link](https://ieeexplore.ieee.org/document/10132225).

````{code-block} bibtex
@inproceedings{khatiri2023simulation,
title={Simulation-based test case generation for unmanned aerial vehicles in the neighborhood of real flights},
author={Khatiri, Sajad and Panichella, Sebastiano and Tonella, Paolo},
booktitle={2023 16th IEEE International Conference on Software Testing, Verification and Validation (ICST)},
year={2023},
}
````

## License

The software we developed is distributed under the Apache 2.0 license. See the [LICENSE](./LICENSE) file.

## Contacts

Please refer to the [FAQ page](https://github.com/skhatiri/UAV-Testing-Competition/wiki/Home) in the Wiki.

You may also refer to (and contribute to) the [Discussions Page](https://github.com/skhatiri/UAV-Testing-Competition/discussions), where you may find user-submitted questions and corresponding answers.

You can also contact us directly using email:

- Ramazan Erdem Uysal, University of Bern, [e-mail]
- Ali Javadi, University of Bern, [e-mail],
- Prakash Aryan, University of Bern, [e-mail]
- Loubet--Bonino Grégory, University of Bern, [e-mail]
- Aren Babikian, University of Toronto, [e-mail]
- Dmytro Humeniuk, Polytechnique Montréal, [e-mail],
- Sajad Mazraehkhatiri, University of Bern, [e-mail]
- Sebastiano Panichella, AI4I - The Italian Institute of Artificial Intelligence for Industry, [e-mail]

# 无人机测试竞赛数据集

搭载机载摄像头与各类传感器的无人机（Unmanned Aerial Vehicles, UAVs）已证实可在真实环境中实现自主飞行，进而在作物监测、安防监控、医疗物资配送与食品配送等诸多应用场景中引发了广泛关注。

多年来，面向无人机开发者的软硬件开源项目不断涌现，为其提供了更多支持，例如PX4与Ardupilot提供的自动驾驶支持。然而，尽管为确保这类复杂自动化系统在真实环境中安全运行，对其开展系统性测试是必要之举，但目前该领域的相关投入仍相对有限。

由国际软件测试、验证与确认会议（International Conference on Software Testing, Verification and Validation, ICST）与基于搜索与模糊测试研讨会（Search-Based and Fuzz Testing, SBFT）联合主办的无人机测试竞赛，旨在推动软件测试社区关注无人机这一快速兴起的关键领域。本次联合招募活动将通过优选便捷就近的会场，帮助有意向的作者或参与者缩减差旅开支。

## 文件

| 文件名称 | 描述 |
|------|-------------|
| `UAV.db` | SQLite数据库 — 存储全部飞行数据 |
| [`UAV_notebook.ipynb`](https://huggingface.co/datasets/it4lia/UAV_dataset/blob/main/UAV_notebook.ipynb) | 探索性笔记 — 包含可视化、指标计算、机器学习导出工具以及新增任务的相关工具 |
| [`Dataset_gen.ipynb`](https://huggingface.co/datasets/it4lia/UAV_dataset/blob/main/dataset_gen.ipynb) | Python处理流程 — 扫描飞行文件夹并将数据写入数据库 |
| `requirements.txt` | 用于复现环境配置的固定版本依赖库列表 |

运行笔记前，请将所有文件置于同一目录下。

---

## 数据库包含哪些内容？

当前数据库收录了基于PX4仿真的飞行数据，每一次飞行包含两类数据：

**动态数据** — 飞行过程中记录的传感器时序数据，以ULog主题形式存储：
- `vehicle_local_position` — 北东下（North East Down, NED）坐标系下的位置：x、y、z轴坐标（单位：米）与速度（单位：米/秒）
- `vehicle_attitude` — 以四元数表示的姿态（w, x, y, z）；无量纲
- `sensor_combined` — 原始惯性测量单元（IMU）测量值：加速度计（单位：米/秒²）、陀螺仪（单位：弧度/秒）
- `vehicle_status` — 飞行模式与解锁状态

**静态数据** — 飞行前设置的仿真条件：
- 风参数：平均风速（单位：米/秒）、风向（单位向量）、阵风与方差（单位：米/秒）
- 障碍物位置（单位：米）与尺寸——高度、长度、宽度（单位：米），每次飞行最多可包含N个障碍物
- PX4飞行控制器参数：导航接收半径（单位：米）、起飞高度（单位：米）等

### 数据库模式

missions
└── flights 每次仿真飞行对应一行记录
├── flight_context 静态条件（风参数、障碍物、PX4参数）
└── topics ULog主题记录
├── topic_fields 字段名称与数据类型
└── topic_data 时序数值（长格式）

`topic_data`采用**长格式**存储——每一行对应一个`(topic_id, row_index, field_name, value)`元组。笔记中的`get_topic()`辅助工具可自动将其转换为宽格式DataFrame。

---

## 快速入门

### 依赖要求

请使用提供的`requirements.txt`安装依赖库，以确保版本兼容性：

bash
pip install -r requirements.txt

### 打开笔记

bash
jupyter notebook UAV_notebook.ipynb

该笔记可直接连接至`UAV.db`，无需额外配置。

### 直接查询数据库

以下示例代码可直接查询数据库：

python
import sqlite3
import pandas as pd

con = sqlite3.connect("UAV.db")

# All flights with duration
flights = pd.read_sql(
"SELECT iter_number, duration_s FROM flights ORDER BY iter_number", con
)

# Position time-series for flight iteration #2 (long → wide)
pos_raw = pd.read_sql("""
SELECT td.row_index, td.field_name, td.value
FROM topic_data td
JOIN topics t ON t.id = td.topic_id
JOIN flights f ON f.id = t.flight_id
WHERE f.iter_number = 2
AND t.name = 'vehicle_local_position'
ORDER BY td.row_index
""", con)

pos = pos_raw.pivot(index="row_index", columns="field_name", values="value")

# Simulation conditions for every flight (wide format)
context = pd.read_sql("""
SELECT f.iter_number, c.key, c.value
FROM flights f
JOIN flight_context c ON c.flight_id = f.id
""", con)

context_wide = context.pivot_table(
index="iter_number", columns="key", values="value"
).reset_index()

---

## 机器学习数据集导出

可通过调用`build_ml_dataset()`函数（或运行笔记第7章节）导出可供训练的扁平化Parquet文件。文件中每一行对应一个时间步，同一飞行任务的所有行均会重复其静态特征。

| 特征组 | 示例列名 | 说明 |
|-------|-----------------|------|
| 时间 | `timestamp` | 微秒；已重采样至统一时间网格 |
| 位置 | `vehicle_local_position__x/y/z` | 北东下（NED）坐标系（单位：米），使用`-z`获取地面高度 |
| 姿态 | `vehicle_attitude__q[0..3]` | 四元数，标量优先（w, x, y, z）；无量纲 |
| 风参数 | `wind_velocity_mean`, `wind_dir_x/y/z` | 单次飞行静态参数；风速单位：米/秒，风向为单位向量 |
| 障碍物 | `obs0_x/y/z/h/l/w`, `obs1_...` | 单次飞行静态参数；位置与尺寸单位：米 |
| PX4参数 | `px4_NAV_ACC_RAD`, `px4_MIS_TAKEOFF_ALT` | 单次飞行静态参数；距离单位：米 |
| 飞行ID | `iter_number`, `iter_name` | 可用于按飞行任务分组或拆分数据集 |

---

## 笔记内容

笔记中包含数据科学研究所需的全部实用内容，例如统计分析、数据库查询方法以及数据库结构说明，同时还提供了数据库构建的相关代码。

---

## 新增飞行数据

笔记第8章节详细介绍了完整的导入流程，简要步骤如下：
1. 将飞行数据整理至根目录下（每个迭代任务对应一个子文件夹，其中包含一个`.ulg`文件，以及可选的`.yaml`配置文件）
2. 在笔记中设置`NEW_ROOT_DIR`参数
3. 运行预览单元格，查看即将导入的数据
4. 运行处理流程单元格，将数据写入`UAV.db`

您也可以直接通过Python调用处理流程：

python
from Dataset_gen import run_pipeline

run_pipeline(
root_dir = "./my_flights",
db_path = "UAV.db",
ml_topics = ["vehicle_local_position", "vehicle_attitude"],
resample_us = 100_000, # 10 Hz
downsample_factor = 10,
skip_existing = True,
)

---

## 注意事项

- **NED坐标系**：`z`轴指向地面，使用`-z`可获取地面以上高度（单位：米）
- **四元数约定**：`q[0]`为标量部分（w），`q[1..3]`为向量部分（x, y, z）
- `topic_data`以长格式存储；可使用`pivot()`或`get_topic()`辅助工具进行转换

---

## 完整数据集

完整数据集可通过以下链接获取：https://zenodo.org/records/18727376

---

## 参考文献

若您在研究中使用本数据集，请引用以下文献：

- **Sajad Khatiri**, Sebastiano Panichella, and Paolo Tonella, "Simulation-based Testing of Unmanned Aerial Vehicles with Aerialist," *In 2024 International Conference on Software Engineering (ICSE)*. [Link](https://dl.acm.org/doi/10.1145/3639478.3640031).

{code-block} bibtex
@inproceedings{icse2024Aerialist,
title={Simulation-based Testing of Unmanned Aerial Vehicles with Aerialist},
author={Khatiri, Sajad and Panichella, Sebastiano and Tonella, Paolo},
booktitle={International Conference on Software Engineering (ICSE)},
year={2024},
}

- **SBFT工具竞赛报告**
{code-block} bibtex
@inproceedings{SBFT-UAV2026,
author = {Ramazan Erdem Uysal and Ali Javadi and Prakash Aryan and Aren Babikian and Dmytro Humeniuk and Sajad Mazraehkhatiri and Sebastiano Panichella},
title = {{SBFT} Tool Competition 2026 – UAV Testing Track},
booktitle = {International Workshop on Search-Based and Fuzz Testing,
SBFT@ICSE 2026},
year = {2026}
}

- **ICST工具竞赛报告**
{code-block} bibtex
@inproceedings{ICST-UAV2026,
author = {Ramazan Erdem Uysal and Ali Javadi and Prakash Aryan and Aren Babikian and Dmytro Humeniuk and Sajad Mazraehkhatiri and Sebastiano Panichella},
title = {{ICST} Tool Competition 2026 – UAV Testing Track},
booktitle = {International Conference on Software Testing, Verification and Validation (ICST)},
year = {2026}
}

- **Sajad Khatiri**, Sebastiano Panichella, and Paolo Tonella, "Simulation-based Test Case Generation for Unmanned Aerial Vehicles in the Neighborhood of Real Flights," *In 2023 IEEE 16th International Conference on Software Testing, Verification and Validation (ICST)*. [Link](https://ieeexplore.ieee.org/document/10132225).

{code-block} bibtex
@inproceedings{khatiri2023simulation,
title={Simulation-based test case generation for unmanned aerial vehicles in the neighborhood of real flights},
author={Khatiri, Sajad and Panichella, Sebastiano and Tonella, Paolo},
booktitle={2023 16th IEEE International Conference on Software Testing, Verification and Validation (ICST)},
year={2023},
}

---

## 许可证

本项目开发的软件采用Apache 2.0许可证分发，详情请参见[LICENSE](./LICENSE)文件。

---

## 联系方式

请参阅项目Wiki中的[常见问题页面](https://github.com/skhatiri/UAV-Testing-Competition/wiki/Home)。您也可以访问[讨论页面](https://github.com/skhatiri/UAV-Testing-Competition/discussions)查看用户提交的问题与解答，或参与讨论贡献内容。

您也可通过以下邮箱直接联系我们：
- Ramazan Erdem Uysal, University of Bern, [e-mail]
- Ali Javadi, University of Bern, [e-mail]
- Prakash Aryan, University of Bern, [e-mail]
- Loubet--Bonino Grégory, University of Bern, [e-mail]
- Aren Babikian, University of Toronto, [e-mail]
- Dmytro Humeniuk, Polytechnique Montréal, [e-mail]
- Sajad Mazraehkhatiri, University of Bern, [e-mail]
- Sebastiano Panichella, AI4I - The Italian Institute of Artificial Intelligence for Industry, [e-mail]