JessicaSanson/wird_gest_wifi_gesture_monostatic_intel

--- license: cc-by-4.0 language: - en pretty_name: monostatic full-duplex Wi-Fi gesture sensing --- # WIRD-GEST Dataset Gesture recognition dataset collected via **monostatic full-duplex Wi-Fi sensing** on commercial off-the-shelf (COTS) laptops — no external sensors, no dedicated transmitter, no hardware modification of any kind. Accompanying paper: **"WIRD-GEST: Gesture Recognition in the Real World Using Active Range-Doppler Wi-Fi Sensing on COTS Hardware"** (Sanson et al., 2025). --- ## Key Innovation: Monostatic Sensing Most Wi-Fi sensing datasets use a **bistatic** setup: a separate transmitter (e.g., a router) and a receiver capture CSI between two devices. This requires coordinating two pieces of hardware and a line-of-sight path between them. This dataset uses a **monostatic** setup instead. A single unmodified laptop simultaneously transmits and receives by sharing its Local Oscillator and baseband processing — the device's own self-interference becomes the sensing signal. CSI is read directly from the built-in NIC. No second device, no external transmitter, no hardware modification of any kind is required. --- ## Hardware & Capture Parameters | Parameter | Value | |---|---| | Hardware | Lenovo ThinkPad (Wi-Fi 6E) | | Bandwidth | 160 MHz | | Frame rate | ~40 Hz | | Channel | 79 (Fc ≈ 6.3 GHz) | | Subcarriers | 512 (data subcarriers only, pilots removed) | | LTF frames | 2 (csi1, csi2) — 1 RX antenna | --- ## Dataset Overview | Property | Value | |---|---| | Participants | 5 (users 1–5) | | Gesture classes | 5 | | Session folders | 55 (50 lab + 5 café) | | Total raw frames | 191,442 | | Complete gesture instances | 722 | | Collection environments | Lab (primary) + café/public space (cross-location subset) | | Disk size | ~12 GB | Sessions are pre-split into **train** (25 folders, 5 users × 5 gestures) and **val** (25 lab + 5 café = 30 folders) sets. The **café subset** (user 1 only) provides an out-of-environment evaluation split for cross-location generalisation. --- ## Gesture Classes | Class key | Description | |---|---| | `hand_forward_back` | Forward / backward wave | | `hand_up_down` | Up / down wave | | `hand_pulse` | Pulse (push forward and back) | | `hand_clock` | Clockwise circular motion | | `hand_side` | Side-to-side wave | --- ## Folder Structure ``` gesture_wifi_monostatic_dataset/ ├── dataset_metadata.json # aggregate statistics for the full dataset ├── lenovo_user1_clock_train/ │ ├── csi.csv │ ├── metadata.yaml │ └── range_doppler_data_32/ │ └── range_doppler_frames_1.pkl ├── lenovo_user1_clock_val/ │ └── ... ├── lenovo_user{1-5}_{clock,front,pulse,side,up}_{train,val}/ │ └── ... # one folder per user × gesture × split (50 total) └── cafe/ └── lenovo_user1_public_space_{clock,front,pulse,side,up}_val/ └── ... # cross-location evaluation subset (5 folders) ``` **Naming convention:** `lenovo_user<ID>_<gesture>_<split>` Each session folder contains: - `csi.csv` — calibrated CSI measurements with per-frame gesture labels - `metadata.yaml` — session-level metadata (participant, gesture, date, frame statistics) - `range_doppler_data_32/range_doppler_frames_1.pkl` — pre-processed range-Doppler frames --- ## Data Files ### `csi.csv` — Raw CSI Each row is one measurement frame (~25 ms interval at 40 Hz). #### Calibration State The CSI samples are frequency-domain measurements that have already been pre-processed: - **Pilot subcarriers removed** — only the 512 data subcarriers are retained. - **Phase and delay calibrated** — carrier frequency offset and timing offset compensation has been applied. - **Two LTF frames averaged per measurement frame** — `csi1` and `csi2` columns hold the two averaged LTF measurements. The data is ready for direct 2D DFT processing to produce range-Doppler maps. No additional calibration or pilot removal is required. #### CSV Columns | Column | Description | |---|---| | `event_timeStamp` | Device event timestamp (integer, ms) | | `unix_timestamp` | Unix time in seconds (float) | | `channel` | Wi-Fi channel number | | `bandwidth_MHz` | Capture bandwidth in MHz | | `measurement_time_repetition_ms` | Target frame interval in ms | | `frequency_carrier_MHz` | Carrier frequency in MHz | | `subcarrier_number` | Number of data subcarriers (512) | | `csi1-{i}-real` | LTF 1, subcarrier i, real part (i = 0..511) | | `csi1-{i}-imag` | LTF 1, subcarrier i, imaginary part (i = 0..511) | | `csi2-{i}-real` | LTF 2, subcarrier i, real part (i = 0..511) | | `csi2-{i}-imag` | LTF 2, subcarrier i, imaginary part (i = 0..511) | | `label` | Gesture label: `front`, `up`, `pulse`, `clock`, or `side` | | `start_end` | Gesture boundary marker: `start`, `end`, or `none` | **`start_end` semantics:** Each gesture instance is bracketed by a `start` marker at the first frame of the motion and an `end` marker at the last frame. Frames outside any gesture instance are marked `none`. This allows precise extraction of complete gesture instances from the continuous recording. --- ### `range_doppler_data_32/range_doppler_frames_1.pkl` — Pre-processed Radar Frames A Python pickle file containing a **list of frame dictionaries**, one entry per measurement frame (~40 Hz), in temporal order. #### Per-frame dictionary keys | Key | Type | Description | |---|---|---| | `range_doppler_snr` | 2D numpy array | Range-Doppler heatmap, SNR values in dB | | `timestamp` | int | Unix timestamp — matches `unix_timestamp` in `csi.csv` | #### Processing pipeline applied 1. The two LTF measurements (`csi1`, `csi2`) from `csi.csv` are averaged per frame. 2. A 2D DFT is applied across the subcarrier (range) and time (Doppler) axes. 3. Range and Doppler axes are interpolated to the cell sizes listed below. 4. SNR is computed in dB and clipped to [5, 40] dB, then normalised to [0, 1]. 5. The heatmap is resized to 64 × 64 and stored as `range_doppler_snr`. #### Range-Doppler map properties | Property | Value | |---|---| | Image size | 64 × 64 (range bins × Doppler bins) | | Range axis | 0 to 0.63 m | | Velocity axis | ±0.45 m/s | | Range cell size | 0.93 cm | | Doppler cell size | 0.015 m/s | | Range resolution (physical) | 0.93 cm (from 160 MHz bandwidth) | | Doppler resolution (physical) | 0.03 m/s (from 40 Hz frame rate) | | Unambiguous velocity | ±0.4 m/s | --- ### `metadata.yaml` — Session Metadata A small YAML file present in every session folder summarising that session's recording. | Field | Description | |---|---| | `dataset.user` | Participant identifier (e.g. `user1`) | | `dataset.gesture` | Gesture type for this session (e.g. `clock`) | | `dataset.data_function` | Split: `training` or `validation` | | `dataset.PC` | Recording machine identifier | | `dataset.date` | Recording date (DD_MM_YYYY) | | `csi.number_of_gestures` | Number of complete gesture instances in the session | | `csi.frames_min` | Minimum frame count across gesture instances | | `csi.frames_median` | Median frame count across gesture instances | | `csi.frames_max` | Maximum frame count across gesture instances | | `summary.number_of_gestures` | Total gesture instances (same as `csi.number_of_gestures`) | --- ### `dataset_metadata.json` — Aggregate Statistics A top-level JSON file with aggregate counts across all sessions. | Field | Description | |---|---| | `dataset_summary.total_samples` | Total raw frames across all sessions (191,442) | | `dataset_summary.gesture_samples` | Frames labelled as a gesture (77,538) | | `dataset_summary.none_samples` | Frames labelled as background / none (113,904) | | `dataset_summary.train_samples` | Total frames in train sessions (125,898) | | `dataset_summary.val_samples` | Total frames in val sessions (65,544) | | `complete_gesture_breakdown` | Complete gesture instance counts per class | | `folder_details` | Per-session sample and gesture counts | **Complete gesture instances per class:** | Gesture | Instances | |---|---| | clock | 142 | | front | 146 | | pulse | 145 | | side | 145 | | up | 144 | | **Total** | **722** | --- ## Citation ```bibtex @article{sanson2025wirdgest, title = {WIRD-GEST: Gesture Recognition in the Real World Using Active Range-Doppler Wi-Fi Sensing on COTS Hardware}, author = {Sanson, Jessica Barthold and Shah, Rahul C. and Zhu, Yazhou and Rosales, Rafael and Frascolla, Valerio}, year = {2025}, note = {Under review}, } ``` ---license: cc-by-4.0 language: - en pretty_name: 单静态全双工Wi-Fi手势感知（monostatic full-duplex Wi-Fi gesture sensing） # WIRD-GEST 数据集 本数据集为通过**单静态全双工Wi-Fi感知（monostatic full-duplex Wi-Fi sensing）**在商用现货（Commercial Off-The-Shelf, COTS）笔记本电脑上采集的手势识别数据集——无需外部传感器、专用发射机或任何形式的硬件修改。 配套论文：**《WIRD-GEST：基于COTS硬件的主动距离多普勒Wi-Fi感知实现现实场景手势识别》**（Sanson等人，2025）。 --- ## 核心创新：单静态感知 绝大多数Wi-Fi感知数据集采用**双静态（bistatic）**架构：使用独立的发射机（如路由器）与接收机在两台设备间采集信道状态信息（Channel State Information, CSI），该方案需要协调两套硬件且设备间需存在视距传输路径。 本数据集转而采用**单静态（monostatic）**架构：单台未修改的笔记本电脑通过共享本地振荡器与基带处理模块同时实现发射与接收，设备自身的自干扰即作为感知信号。数据直接从内置网络接口控制器（Network Interface Controller, NIC）读取CSI，无需额外设备、外部发射机或任何硬件修改。 --- ## 硬件与采集参数 | 参数 | 取值 | |---|---| | 硬件 | 联想ThinkPad（Wi-Fi 6E） | | 带宽 | 160 MHz | | 帧率 | ~40 Hz | | 信道 | 79（中心载波频率Fc ≈ 6.3 GHz） | | 子载波数 | 512（仅保留数据子载波，已移除导频） | | LTF帧 | 2（csi1、csi2）——1个接收天线 | --- ## 数据集概览 | 属性 | 取值 | |---|---| | 参与者 | 5名（用户1–5） | | 手势类别 | 5类 | | 会话文件夹数 | 55个（50个实验室场景 + 5个咖啡馆场景） | | 总原始帧数 | 191,442 | | 完整手势实例数 | 722 | | 采集环境 | 实验室（主要场景） + 咖啡馆/公共空间（跨位置子集） | | 磁盘占用 | ~12 GB | 会话已预先划分为**训练集**（25个文件夹，5名用户 × 5类手势）与**验证集**（25个实验室场景 + 5个咖啡馆场景 = 30个文件夹）。其中**咖啡馆子集**（仅包含用户1的数据）为跨位置泛化任务提供了域外评估划分。 --- ## 手势类别 | 类别键 | 描述 | |---|---| | `hand_forward_back` | 前后挥手 | | `hand_up_down` | 上下挥手 | | `hand_pulse` | 脉冲手势（向前推送后收回） | | `hand_clock` | 顺时针圆周运动 | | `hand_side` | 左右挥手 | --- ## 文件夹结构 gesture_wifi_monostatic_dataset/ ├── dataset_metadata.json # 全数据集聚合统计信息 ├── lenovo_user1_clock_train/ │ ├── csi.csv │ ├── metadata.yaml │ └── range_doppler_data_32/ │ └── range_doppler_frames_1.pkl ├── lenovo_user1_clock_val/ │ └── ... ├── lenovo_user{1-5}_{clock,front,pulse,side,up}_{train,val}/ │ └── ... # 每个用户×手势×划分对应一个文件夹（共50个） └── cafe/ └── lenovo_user1_public_space_{clock,front,pulse,side,up}_val/ └── ... # 跨位置评估子集（共5个文件夹） **命名规范：** `lenovo_user<ID>_<gesture>_<split>` 每个会话文件夹包含以下文件： - `csi.csv` —— 已校准的信道状态信息测量值，附带每帧手势标签 - `metadata.yaml` —— 会话级元数据（包含参与者、手势类型、录制日期、帧统计信息） - `range_doppler_data_32/range_doppler_frames_1.pkl` —— 预处理后的距离多普勒帧数据 --- ## 数据文件 ### `csi.csv` —— 原始信道状态信息 每一行对应一个测量帧（40Hz帧率下约25ms的采集间隔）。 #### 校准状态 CSI样本为频域测量值，已完成预处理： - **已移除导频子载波**：仅保留512个数据子载波。 - **已完成相位与延迟校准**：已补偿载波频率偏移与定时偏移。 - **每测量帧对两个LTF帧取平均**：`csi1`与`csi2`列存储两个取平均后的LTF测量结果。 该数据可直接用于二维离散傅里叶变换（Discrete Fourier Transform, DFT）以生成距离多普勒图，无需额外校准或导频移除操作。 #### CSV列说明 | 列名 | 描述 | |---|---| | `event_timeStamp` | 设备事件时间戳（整数，单位：毫秒） | | `unix_timestamp` | Unix时间（浮点数，单位：秒） | | `channel` | Wi-Fi信道编号 | | `bandwidth_MHz` | 采集带宽（单位：MHz） | | `measurement_time_repetition_ms` | 目标帧间隔（单位：毫秒） | | `frequency_carrier_MHz` | 载波频率（单位：MHz） | | `subcarrier_number` | 数据子载波数量（512） | | `csi1-{i}-real` | LTF1中第i个子载波的实部（i = 0..511） | | `csi1-{i}-imag` | LTF1中第i个子载波的虚部（i = 0..511） | | `csi2-{i}-real` | LTF2中第i个子载波的实部（i = 0..511） | | `csi2-{i}-imag` | LTF2中第i个子载波的虚部（i = 0..511） | | `label` | 手势标签：`front`、`up`、`pulse`、`clock`或`side` | | `start_end` | 手势边界标记：`start`（运动起始帧）、`end`（运动结束帧）或`none`（无手势帧） | **`start_end`语义说明：** 每个手势实例由运动第一帧的`start`标记与最后一帧的`end`标记包围，无手势的帧标记为`none`。该设计支持从连续录制中精确提取完整的手势实例。 --- ### `range_doppler_data_32/range_doppler_frames_1.pkl` —— 预处理后的雷达帧 Python pickle格式文件，包含按时间顺序排列的帧字典列表，每个条目对应一个测量帧（40Hz帧率）。 #### 单帧字典键说明 | 键名 | 数据类型 | 描述 | |---|---|---| | `range_doppler_snr` | 二维numpy数组 | 距离多普勒热图，信噪比（Signal-to-Noise Ratio, SNR）值以dB为单位 | | `timestamp` | 整数 | Unix时间戳，与`csi.csv`中的`unix_timestamp`字段一致 | #### 应用的处理流程 1. 对每个帧的`csi.csv`中的两个LTF测量值`csi1`与`csi2`取平均。 2. 对子载波（距离维度）与时间（多普勒维度）轴应用二维DFT。 3. 将距离与多普勒轴插值至指定的单元尺寸。 4. 计算信噪比并转换为dB格式，裁剪至[5, 40] dB区间，随后归一化至[0, 1]范围。 5. 将热图调整为64 × 64的尺寸并存储为`range_doppler_snr`。 #### 距离多普勒图属性 | 属性 | 取值 | |---|---| | 图像尺寸 | 64 × 64（距离箱 × 多普勒箱） | | 距离轴范围 | 0 至 0.63 m | | 速度轴范围 | ±0.45 m/s | | 距离单元尺寸 | 0.93 cm | | 多普勒单元尺寸 | 0.015 m/s | | 物理距离分辨率 | 0.93 cm（由160 MHz带宽决定） | | 物理多普勒分辨率 | 0.03 m/s（由40 Hz帧率决定） | | 无模糊速度范围 | ±0.4 m/s | --- ### `metadata.yaml` —— 会话元数据 每个会话文件夹中均包含一个小型YAML文件，用于总结该会话的录制信息。 | 字段 | 描述 | |---|---| | `dataset.user` | 参与者标识符（例如`user1`） | | `dataset.gesture` | 当前会话的手势类型（例如`clock`） | | `dataset.data_function` | 数据集划分：`training`（训练集）或`validation`（验证集） | | `dataset.PC` | 录制设备标识符 | | `dataset.date` | 录制日期（格式：DD_MM_YYYY） | | `csi.number_of_gestures` | 当前会话中完整手势实例的数量 | | `csi.frames_min` | 单个手势实例的最小帧数 | | `csi.frames_median` | 单个手势实例的帧数中位数 | | `csi.frames_max` | 单个手势实例的最大帧数 | | `summary.number_of_gestures` | 总手势实例数（与`csi.number_of_gestures`取值一致） | --- ### `dataset_metadata.json` —— 聚合统计信息 顶层JSON文件，包含所有会话的聚合统计数据。 | 字段 | 描述 | |---|---| | `dataset_summary.total_samples` | 所有会话的总原始帧数（191,442） | | `dataset_summary.gesture_samples` | 标记为手势的总帧数（77,538） | | `dataset_summary.none_samples` | 标记为背景/无手势的总帧数（113,904） | | `dataset_summary.train_samples` | 训练集会话的总帧数（125,898） | | `dataset_summary.val_samples` | 验证集会话的总帧数（65,544） | | `complete_gesture_breakdown` | 每类手势的完整实例计数 | | `folder_details` | 单个会话的样本与手势计数详情 | **每类手势的完整实例数：** | 手势类型 | 实例数量 | |---|---| | clock | 142 | | front | 146 | | pulse | 145 | | side | 145 | | up | 144 | | **总计** | **722** | --- ## 引用格式 bibtex @article{sanson2025wirdgest, title = {WIRD-GEST: Gesture Recognition in the Real World Using Active Range-Doppler Wi-Fi Sensing on COTS Hardware}, author = {Sanson, Jessica Barthold and Shah, Rahul C. and Zhu, Yazhou and Rosales, Rafael and Frascolla, Valerio}, year = {2025}, note = {Under review}, }