OpenAXES Example Robot Dataset

**This is an example dataset recorded using version 1.0 of the [open-source-hardware OpenAXES IMU](https://github.com/OpenAXES-IMU/OpenAXES). Please see the github repository for more information on the hardware and firmware. Please find [the most up-to-date version of this document in the repository](https://github.com/OpenAXES-IMU/OpenAXES/blob/main/dataset/README.md)** This dataset was recorded using four OpenAXES IMUs mounted on the segments of a robot arm (UR5 by Universal Robots). The robot arm was programmed to perform a calibration movement, then trace a 2D circle or triangle in the air with its tool center point (TCP), and return to its starting position, at four different speeds from 100 mm/s to 250 mm/s. This results in a total of 8 different scenarios (2 shapes times 4 speeds). The ground truth joint angle and TCP position values were obtained from the robot controller. The calibration movement at the beginning of the measurement allows for calculating the exact orientation of the sensors on the robot arm. The IMUs were configured to send the raw data from the three gyroscope axes and the six accelerometer axes to a PC via BLE with 16 bit resolution per axis and 100 Hz sample rate. Since no data packets were lost during this process, this dataset allows comparing and tuning different sensor fusion algorithms on the recorded raw data while using the ground truth robot data as a reference. In order to visualize the results, the quaternion sequences from the IMUs were applied to the individual segments of a 3D model of the robot arm. The end of this kinematic chain represents the TCP of the virtual model, which should ideally move along the same trajectory as the ground truth, barring the accuracy of the IMUs. Since the raw sensor data of these measurements is available, the calibration coefficients can also be applied ex-post. Since there are are 6 joints but only 4 IMUS, some redundancy must be exploited. The redundancy comes from the fact that each IMU has 3 rotational degrees of fredom, but each joint has only one: * The data for `q0` and `q1` are both derived from the orientation of the "humerus" IMU. * `q2` is the difference† between the orientation of the "humerus" and "radius" IMUs. * `q3` is the difference between the orientation of the "radius" and "carpus" IMUs. * `q4` is the difference between the orientation of the "carpus" and "digitus" IMUs. * The joint `q5` does not influence the position of the TCP, only its orientation, so it is ignored in the evaluation. * † *Of course, difference here means not the subtraction of the quaternions but the rotational difference, which is the `R1 * inv(R0)` for two quaternions (or rotations) `R0` and `R1`. The actual code works a bit differently, but this describes the general principle.* ## Data * Data recorded from the IMUs is in the directory `measure_raw-2022-09-15/`, one folder per scenario. In those folders, there is one CSV file per IMU. * Data recorded from the robot arm is in the directory `measure_raw-2022-09-15/robot/`, one CSV and MAT file per scenario. * Some photos and videos of the recording process can be found in `Media`. Videos are stored in [git lfs](https://git-lfs.com/). ## Evaluation The file `openaxes-example-robot-dataset.ipynb` is provided to play around with the data in the dataset and demonstrate how the files are read and interpreted. To use the notebook, set up a Python 3 virtual environment and therein install the necessary packets with `pip install -r resuirements.txt`. In order to view the graphs contained in the ipynb file, you will most likely have to trust the notebook beforehand, using the following command: ```bash jupyter trust openaxes-example-robot-dataset.ipynb ``` **Beware:** This notebook is not a comprehensive evaluation and any results and plots shown in the file are not necessarily scientifically sound evidence of anything. The notebook will store intermediate files in the `measure_raw-2022-09-15` directory, like the quaternion files calculated by the different filters, or the files containing the reconstructed TCP positions. All intermediate files should be ignored by the file `measure_raw-2022-09-15/.gitignore`. The generated intermediate files are also provided in the file `measure_raw-2022-09-15.tar.bz2`, in case you want to inspect the generated files without running the the notebook. ## Tools A number of tools are used in the evaluation notebook. Below is a short overview, but not a complete specification. If you need to understand the input and output formats for each tool, please read the code. * The file `calculate-quaternions.py` is used in the evaluation notebook to compute different attitude estimation filters like Madgwick or VQF on the raw accelerometer and gyroscrope measurements at 100 Hz. * The directory `madgwick-filter` contains a small C program that applies the original Madgwick filter to a CSV file containing raw measurements and prints the results. It is used by `calculate-quaternions.py`. * The file `calculate-robot-quaternions.py` calculates a CSV file of quaternions equivalent to the IMU quaternions from a CSV file containing the joint angles of the robot. * The program `dsense_vis` mentioned in the notebook is used to calculate the 3D model of the robot arm from quaternions and determine the mounting orientations of the IMUs on the robot arm. This program will be released at a future date. In the meantime, the output files of `dsense_vis` are provided in the file `measure_raw-2022-09-15.tar.bz2`, which contains the complete content of the `measure_raw-2022-09-15` directory after executing the whole notebook. Just unpack this archive and merge its contents with the `measure_raw-2022-09-15` directory. This allows you to explore the reconstructed TCP files for the filters implemented at the time of publication.**本数据集为使用开源硬件OpenAXES惯性测量单元（Inertial Measurement Unit, IMU）1.0版本录制的示例数据集。有关该硬件与固件的更多信息，请参阅其GitHub仓库。本文档的最新版本可在仓库中查看：https://github.com/OpenAXES-IMU/OpenAXES/blob/main/dataset/README.md** 本数据集使用4台安装在优傲机器人（Universal Robots）UR5型机械臂各连杆段上的OpenAXES惯性测量单元录制。该机械臂被编程执行校准运动，随后以工具中心点（Tool Center Point, TCP）为末端，在空中绘制二维圆形或三角形轨迹，并返回初始位置，运动速度分为100 mm/s至250 mm/s共4档，最终形成8种不同测试场景（2种轨迹形状 × 4种运动速度）。 关节角与TCP位置的真值（ground truth）数据取自机械臂控制器。测量起始处的校准运动可用于计算各传感器在机械臂上的精确安装姿态。IMU被配置为通过蓝牙低功耗（Bluetooth Low Energy, BLE）向PC传输三轴陀螺仪与六轴加速度计的原始数据，每轴分辨率为16位，采样率为100 Hz。 本次录制过程无数据包丢失，因此本数据集可基于记录的原始数据，结合机器人真值数据作为参考，用于对比与调优不同的传感器融合算法。为可视化结果，将IMU输出的四元数（quaternion）序列应用于机械臂三维模型的各连杆段，该运动学链的末端对应虚拟模型的TCP，在IMU精度允许的理想情况下，其运动轨迹应与真值轨迹一致。 由于本次测量的原始传感器数据可获取，校准系数也可在事后应用。本机械臂共包含6个关节，但仅搭载了4台IMU，因此需利用系统的冗余性。该冗余性源于：每台IMU具备3个旋转自由度，但每个关节仅具备1个旋转自由度： * `q0`与`q1`的数据均取自"humerus"IMU的姿态。 * `q2`为"humerus"与"radius"IMU姿态的旋转差值。 * `q3`为"radius"与"carpus"IMU姿态的旋转差值。 * `q4`为"carpus"与"digitus"IMU姿态的旋转差值。 * 关节`q5`仅影响TCP的姿态，不改变其位置，因此在评估中可忽略该关节。 * 注：此处的"差值"并非指四元数的减法，而是指旋转差值，即对于两个四元数（或旋转矩阵）`R0`与`R1`，其旋转差值为`R1 * inv(R0)`。实际代码实现略有差异，但该描述阐明了核心原理。 ## 数据集文件 * IMU录制数据存储于`measure_raw-2022-09-15/`目录下，每个测试场景对应一个子文件夹，每个子文件夹内包含各IMU对应的CSV文件。 * 机械臂录制数据存储于`measure_raw-2022-09-15/robot/`目录下，每个测试场景对应一个CSV文件与一个MAT文件。 * 录制过程的部分照片与视频可在`Media`目录中查看，视频采用Git大文件存储（Git Large File Storage, Git LFS）托管。 ## 评估与使用说明 本数据集附带`openaxes-example-robot-dataset.ipynb`交互式脚本，用于演示数据集的读取、解析与数据探索。使用该脚本前，请先搭建Python 3虚拟环境，并通过`pip install -r requirements.txt`安装所需依赖包。若需查看脚本内的图表，通常需先执行以下命令信任该Jupyter Notebook： bash jupyter trust openaxes-example-robot-dataset.ipynb **注意：** 本脚本并非完整的评估工具，文件中展示的任何结果与图表均不构成针对任何对象的科学严谨验证依据。脚本运行时会在`measure_raw-2022-09-15`目录下生成中间文件，例如不同滤波器计算得到的四元数文件，或重构TCP位置的文件。`measure_raw-2022-09-15/.gitignore`文件已配置忽略所有中间文件。为方便用户无需运行脚本即可查看生成的中间文件，我们将其打包为`measure_raw-2022-09-15.tar.bz2`一并提供。 ## 配套工具 评估脚本中使用了多款配套工具，以下为简要概述而非完整规范说明，若需了解各工具的输入输出格式，请查阅对应代码。 * `calculate-quaternions.py`：用于在评估脚本中，基于100 Hz采样的原始加速度计与陀螺仪数据，计算包括Madgwick滤波器、VQF滤波器在内的多种姿态估计算法结果。 * `madgwick-filter`目录：包含一个小型C程序，可将原始测量数据的CSV文件输入原生Madgwick滤波器并输出计算结果，供`calculate-quaternions.py`调用。 * `calculate-robot-quaternions.py`：基于包含机械臂关节角的CSV文件，计算与IMU四元数等效的机械臂姿态四元数CSV文件。 * 脚本中提及的`dsense_vis`工具：用于基于四元数计算机械臂三维模型，并确定各IMU在机械臂上的安装姿态。该工具将于后续正式发布。在此期间，`measure_raw-2022-09-15.tar.bz2`文件中已包含完整运行该脚本后生成的`measure_raw-2022-09-15`目录内容，用户只需解压该归档文件并将其内容合并至本地`measure_raw-2022-09-15`目录，即可查看发布时已实现的各滤波器对应的重构TCP文件。