mmWave Radar Human Activity Recognition System (RACA)

这是一个完整的毫米波雷达人体活动识别系统，涵盖了从硬件数据采集、信号预处理、特征生成到深度学习分类的全流程。系统核心算法基于 Range-Anchored Cross-Attention (RACA) 网络。

🌟 项目亮点

• 全流程支持: 提供 DCA1000 数据采集、MIMO 虚拟孔径重组、多维度热图生成及端到端训练。
• 自适应模型: 能够根据数据集大小自动选择最优的时序模型 (LSTM vs Transformer) 和训练超参数。
• 高精度: 在极小样本 (92个样本) 下实现了 94.7% 的验证集准确率。
• 多视图融合: 融合 Range-Doppler (RD), Range-Azimuth (RA), Range-Elevation (RE) 三种特征。

📁 目录结构

src/
├── collect_data.py          # [Step 1] 硬件数据采集 (雷达 + 摄像头同步)
├── process_data.py          # [Step 2] 原始 .bin 数据转 MIMO Cube (.npy)
├── mmWave_RA_RE.py          # [Step 3] 生成 RD/RA/RE 热图特征
├── DCA1000_control.py       # DCA1000 控制库
├── DL/                      # 深度学习模块
│   ├── train_raca.py        # [Step 4] 自适应训练脚本
│   ├── radar_dataset.py     # 数据集加载 (含归一化)
│   ├── RACA_v1.py           # 模型定义 (LSTM后端)
│   ├── RACA_v2.py           # 模型定义 (Transformer后端)
│   └── README.md            # 本文档
├── cfg/
│   └── Radar.cfg            # IWR6843ISK 雷达配置文件
├── Data_bin/                # 原始 ADC 二进制文件
├── Cube_data/               # 处理后的 4D 雷达立方体
├── Heatmap_Features/        # 最终输入模型的特征文件
└── checkpoints_adaptive/    # 训练模型与日志

🚀 工作流 (Pipeline)

Step 1: 数据采集 (Data Collection)

使用 IWR6843ISK 雷达和 DCA1000 采集卡，配合网络摄像头同步采集。

python src/collect_data.py

• 功能: 自动配置 FPGA 和雷达，同步录制 .bin 雷达数据和 .mp4 视频（用于真值标注）。
• 输出: Data_bin/*.bin

Step 2: 原始信号处理 (MIMO Processing)

将 DCA1000 的原始 ADC 数据解析并重组为虚拟天线阵列立方体。

python src/process_data.py

• 功能: 解析 .bin，处理 I/Q 格式，执行 MIMO 虚拟孔径重组 (Virtual Array Construction)。
• 输出: Cube_data/*_cube.npy (Shape: [Frames, VirtualRx, Loops, Samples])

Step 3: 特征生成 (Feature Generation)

生成用于深度学习的 Range-Doppler, Range-Azimuth, Range-Elevation 热图。

python src/mmWave_RA_RE.py

• 功能: 距离 FFT -> 杂波滤除 -> 角度 FFT -> 降采样。
• 输出: Heatmap_Features/*_merged.npy
  • 格式: [Frames, Range, Channels] (Channels = D+A+E bins)

Step 4: 模型训练 (Training)

使用 RACA 网络进行训练。脚本会根据数据量自动调整超参数。

# 自动模式 (推荐)
python src/DL/train_raca.py --data_dir <Feature_Path>

# 强制使用特定模型
python src/DL/train_raca.py --force_model v1  # LSTM (小样本)
python src/DL/train_raca.py --force_model v2  # Transformer (大样本)

🧠 算法核心: RACA

RACA (Range-Anchored Cross-Attention) 是一种专门针对 4D 雷达点云/热图设计的融合机制。

核心思想

由于雷达的 Range (距离) 维度是最可靠的特征，我们以 Range 特征为“锚点” (Query)，通过 Cross-Attention 机制动态聚合来自 Doppler (速度) 和 Angle (角度) 维度的上下文信息。

graph LR
    RD[Range-Doppler] -->|Query| RACA
    RA[Range-Azimuth] -->|Key/Value| RACA
    RE[Range-Elevation] -->|Key/Value| RACA
    RACA --> Fused[Fused Range Features]
    Fused --> Temporal[LSTM / Transformer]
    Temporal --> Class[Action Class]

性能基准 (Benchmark)

基于 92 个样本的小样本训练测试结果：

• 模型: RACA-LSTM
• Epochs: 50 (Convergence at Epoch 26)
• 最佳验证准确率: 94.74%

类别 (Class)	Precision	Recall	F1-Score
Walk	1.00	1.00	1.00
Sit	0.80	1.00	0.89
Stand	1.00	1.00	1.00
Fall	1.00	0.80	0.89

注意: 在该次测试中，唯一的错误是将一个 Fall 样本误判为 Sit。这是因为两者最终状态相似（低高度静止），未来可通过加权 Loss 改进。

⚙️ 关键配置参数

数据集参数

• 类别: walk, sit, stand, fall (文件名必须包含这些关键词)
• 输入形状: [Frames, 128, 192] (默认 Range=128)

自适应训练策略

train_raca.py 会根据样本数量 N 自动调整：

样本数 N	推荐模型	Batch Size	Learning Rate	策略说明
N < 100	LSTM	4	1e-4	强正则化，避免过拟合
100 < N < 300	Transformer	8	3e-4	增加模型容量
N > 300	Transformer	16	5e-4	全量大数据训练

🛠️ 常见问题 (FAQ)

Q1: 为什么我的验证集准确率很低?

• 检查数据量：如果少于 50 个样本，波动会很大。
• 检查文件名：脚本通过文件名包含关键词 (fall, walk 等) 来提取标签，确保命名正确。
• 检查数据平衡：确保每个类别的样本数大致相等。

Q2: 遇到 CUDA Out of Memory (OOM)?

• 在 train_raca.py 中手动减小 batch_size (例如设为 2)。
• 减小 embed_dim (例如设为 32)。

Q3: 如何连接 DCA1000?

• 确保 IP 地址设置为 192.168.33.30。
• 关闭防火墙。
• 检查 cfg/DCA1000EVM_CLI_setup.json 路径是否正确。