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},
}
```

---