RuView v2 Rust 工作区全景：WiFi-DensePose 无线人体感知的模块化 Crate 架构与实战指南

导读

本文以仓库 v2/crates/README.md 为主线，系统讲解 RuView 仓库中基于 Rust 的 WiFi-DensePose 无线感知工作区：它把 Wi-Fi 信道状态信息（CSI）转化为实时人体姿态、生命体征与灾后幸存者定位，全程无摄像头、无穿戴设备。读完本文，你将掌握该工作区的 14+ Crate 分层架构、六种 SOTA 信号处理算法、RuVector 图算法集成、vitals/MAT 的完整调用链，以及从构建、测试到 feature flags 的全套实战用法。

---

一、工作区定位：从 Python v1 到 Rust v2 的演进

WiFi-DensePose 是一个模块化 Rust 工作区，目标是用 CSI（Channel State Information，信道状态信息）实现穿墙人体姿态估计、生命体征监测与灾后救援。它的核心理念写在 README 开头：

See through walls with WiFi. No cameras. No wearables. Just radio waves.

整个系统建立在 RuVector 图算法与 WiFi-DensePose 研究平台之上。Rust v2 版本相对 Python v1 在实时性上做了彻底重写，README 记录了如下性能对比（数据为 README 文档声明，可配合 cargo bench 复现）：

操作	Python v1	Rust v2	加速比
CSI 预处理	~5 ms	5.19 us	~1000x
相位净化	~3 ms	3.84 us	~780x
特征提取	~8 ms	9.03 us	~890x
运动检测	~1 ms	186 ns	~5400x
全流水线	~15 ms	18.47 us	~810x
生命体征	N/A	86 us（11,665 fps）	--

需要说明的是，README 描述的是最初设计的 14 个 Crate 工作区；当前仓库 v2/Cargo.toml 中的成员规模已大幅扩展（homecore、ruview-*、nvsim 等数十个 Crate），且 wifi-densepose-api / -db / -config 三个早期预留 Crate 已在 #578 中移除——其功能分别由 wifi-densepose-sensing-server（REST/WS）、各 Crate 自带配置与 CLI 参数承担，系统为实时架构、不依赖持久化数据库。阅读旧版表格时需结合这一演进背景。

---

二、Crate 全景：按职责分层的模块设计

README 按职责把工作区划分为六个层级，本文保留其完整表格并标注当前仓库中的源码位置。

2.1 Core Foundation 核心基础层

Crate	说明	源码位置
wifi-densepose-core	类型、trait 与工具（CsiFrame、PoseEstimate、SignalProcessor）	v2/crates/wifi-densepose-core/
wifi-densepose-config	配置管理（env、TOML、YAML）	已随 #578 移除，功能并入各 Crate 配置与 CLI
wifi-densepose-db	数据库持久化（PostgreSQL、SQLite、Redis）	已移除；系统为实时架构

2.2 Signal Processing & Sensing 信号处理与感知层

Crate	说明	RuVector 集成
wifi-densepose-signal	SOTA CSI 信号处理（SpotFi、FarSense、Widar 3.0 等 6 种算法）	ruvector-mincut、ruvector-attn-mincut、ruvector-attention、ruvector-solver
wifi-densepose-vitals	生命体征提取：呼吸（6-30 BPM）、心率（40-120 BPM）	--
wifi-densepose-wifiscan	多 BSSID Wi-Fi 扫描，面向 Windows 增强感知	--

2.3 Neural Network & Training 神经网络与训练层

Crate	说明	RuVector 集成
wifi-densepose-nn	多后端推理（ONNX、PyTorch、Candle），DensePose 头输出 24 个身体部位	--
wifi-densepose-train	训练流水线，MM-Fi 数据集，114→56 子载波插值	全部 5 个 RuVector Crate

2.4 Disaster Response 灾后救援层

Crate	说明	RuVector 集成
wifi-densepose-mat	大规模伤亡评估工具——幸存者检测、分诊、多 AP 定位	ruvector-solver、ruvector-temporal-tensor

2.5 Hardware & Deployment 硬件与部署层

Crate	说明
wifi-densepose-hardware	ESP32、Intel 5300、Atheros CSI 传感器接口（纯 Rust，无 FFI）
wifi-densepose-wasm	浏览器灾后仪表盘的 WebAssembly 绑定
wifi-densepose-sensing-server	Axum 服务器：ESP32 UDP 摄入、WebSocket 广播、感知 UI

2.6 Applications 应用层

Crate	说明
wifi-densepose-api	REST + WebSocket API 层（README 设计；现由 sensing-server 承担）
wifi-densepose-cli	MAT 灾后扫描命令行工具

---

三、分层架构与调用链

README 给出了清晰的依赖关系图，原文如下，它揭示了"core 为基础、signal/nn/hardware 三足鼎立、train/mat 汇聚、api/wasm/cli/server 对外输出"的整体形态：

                          wifi-densepose-core
                         (types, traits, errors)
                                  |
              +-------------------+-------------------+
              |                   |                   |
    wifi-densepose-signal   wifi-densepose-nn   wifi-densepose-hardware
    (CSI processing)        (inference)         (ESP32, Intel 5300)
    + ruvector-mincut       + ONNX Runtime          |
    + ruvector-attn-mincut  + PyTorch (tch)   wifi-densepose-vitals
    + ruvector-attention    + Candle          (breathing, heart rate)
    + ruvector-solver            |
              |                  |             wifi-densepose-wifiscan
              +--------+---------+            (BSSID scanning)
                       |
          +------------+------------+
          |                         |
  wifi-densepose-train    wifi-densepose-mat
  (training pipeline)     (disaster response)
  + ALL 5 ruvector        + ruvector-solver
                          + ruvector-temporal-tensor
                                |
              +-----------------+-----------------+
              |                 |                 |
    wifi-densepose-api  wifi-densepose-wasm  wifi-densepose-cli
    (REST/WS)           (browser WASM)       (CLI tool)
              |
    wifi-densepose-sensing-server
    (Axum + WebSocket)

从源码看，这一架构在 wifi-densepose-core 中由三个核心 trait 落实（见 traits.rs）：

• SignalProcessor：把原始 CSI 帧处理为神经网络可用的信号（缓冲、噪声滤波、相位解卷绕、幅度归一化、特征提取）；
• NeuralInference：对处理后的信号执行姿态推理，输出 PoseEstimate（含 infer / infer_batch / warmup / stats）；
• DataStore：CSI 数据与姿态估计的持久化与查询（PostgreSQL/SQLite/Redis 三种后端可选）。

三个 trait 均提供 async feature 下的异步版本（AsyncSignalProcessor 等），并遵循"单一职责、可测试、错误统一使用 CoreError/SignalError/InferenceError/StorageError 领域错误"的设计原则。

---

四、RuVector 图算法集成

RuVector 是工作区的"数学引擎"，README 列出其在 crates.io 上的 5 个 Crate 及各自用途：

RuVector Crate	使用方	用途
ruvector-mincut	signal, train	动态最小割：子载波选择与人员匹配
ruvector-attn-mincut	signal, train	注意力加权最小割：天线门控与频谱图
ruvector-temporal-tensor	train, mat	分级时间压缩（4-10x 内存缩减）
ruvector-solver	signal, train, mat	稀疏 Neumann 求解器：插值与三角化
ruvector-attention	signal, train	缩放点积注意力：空间特征与 BVP

README 记录各 RuVector Crate 版本为 v2.0.4；当前仓库 v2/Cargo.toml 的 [workspace.dependencies] 中实际锁定版本已更新为 ruvector-core 2.3.0、ruvector-mincut 2.0.6、ruvector-attn-mincut 2.0.4、ruvector-temporal-tensor 2.0.6、ruvector-solver 2.0.6、ruvector-attention 2.1.0，并新增 ruvector-gnn 2.2.0。阅读或引用时以当前 Cargo.toml 为准。

---

五、信号处理引擎：六种 SOTA 算法

wifi-densepose-signal 是感知链路的起点，README 明确列出了六种复刻自顶会论文的算法及其对应源码模块：

算法	论文来源	年份	模块
共轭相乘（Conjugate Multiplication）	SpotFi（SIGCOMM）	2015	csi_ratio.rs
Hampel 滤波	WiGest	2015	hampel.rs
Fresnel 区域模型	FarSense（MobiCom）	2019	fresnel.rs
CSI 频谱图	标准 STFT	2018+	spectrogram.rs
子载波选择	WiDance（MobiCom）	2017	subcarrier_selection.rs
身体速度轮廓（BVP）	Widar 3.0（MobiSys）	2019	bvp.rs

5.1 数据模型：CsiData

CSI 数据的核心载体是 csi_processor.rs 中的 CsiData 结构体：

• amplitude / phase：Array2<f64>，维度为（天线数 × 子载波数）；
• frequency / bandwidth：中心频率与带宽（Hz）；
• num_subcarriers / num_antenants：子载波数与天线数；
• snr：信噪比（dB）；
• metadata：CsiMetadata，标记噪声滤波、加窗、归一化是否已应用，并支持 serde(flatten) 自定义扩展字段。

配合 CsiDataBuilder 链式构造，CsiProcessor 完成预处理、噪声去除、加窗与归一化；PhaseSanitizer 负责相位解卷绕、离群点剔除与平滑；FeatureExtractor 产出幅度、相位、相关性、多普勒与 PSD 特征；MotionDetector 输出带置信度的人体存在检测。

5.2 处理器配置示例（源码级）

当前 API 采用 builder 模式（见 signal/lib.rs 的文档示例）：

use wifi_densepose_signal::{
    CsiProcessor, CsiProcessorConfig,
    PhaseSanitizer, PhaseSanitizerConfig,
    MotionDetector,
};

// 配置 CSI 处理器
let config = CsiProcessorConfig::builder()
    .sampling_rate(1000.0)   // 采样率 Hz
    .window_size(256)        // FFT 窗口
    .overlap(0.5)            // 窗口重叠率
    .noise_threshold(-30.0)  // 噪声门限 dB
    .build();

let processor = CsiProcessor::new(config);

5.3 信号层的能力延伸

除六大论文算法外，signal Crate 还扩展了 hardware_norm（跨硬件归一化，HardwareNormalizer 将不同设备 CSI 转为 CanonicalCsiFrame 标准形态）以及 ruvsense 子模块（CIR 信道冲激响应估计、空房间基线校准 BaselineCalibration 等），后者对应 ADR-134 与 ADR-135。

---

六、核心基础层源码解读：常量、配置与契约

wifi-densepose-core 是 no_std 兼容、#![forbid(unsafe_code)] 的纯安全 Rust 库（lib.rs），它定义了全系统的关键常量与配置默认值：

常量/类型	值/说明
MAX_KEYPOINTS	17（COCO 格式关键点上限）
MAX_SUBCARRIERS	256（Wi-Fi CSI 子载波上限）
DEFAULT_CONFIDENCE_THRESHOLD	0.5（关键点可见性置信度阈值）
SignalProcessorConfig::default()	buffer_size=64、sample_rate_hz=1000.0、apply_noise_filter=true、filter_cutoff_hz=50.0、normalize_amplitude=true、unwrap_phase=true、窗函数 Hann
InferenceConfig::default()	device=Cpu、max_batch_size=8、num_threads=4、confidence_threshold=0.5、nms_threshold=0.45、use_fp16=false
InferenceDevice	Cpu / Cuda{device_id} / TensorRt{device_id} / CoreMl / WebGpu

值得一提的还有 traits.rs 中的 CanonicalFrame trait：它定义了确定性、跨架构的帧序列化契约（固定字段序 + little-endian + IEEE-754 原始字节），witness_hash() 对 to_canonical_bytes() 计算 BLAKE3-256，作为与 ADR-028 证明链兼容的见证哈希——这正是系统"可证明、可审计"特性的根基，也解释了为什么 homecore-recorder 等回放组件能够做到字节级一致。

feature flags：std（默认）、serde（序列化）、async（异步 trait）。

---

七、生命体征监测：vitals 四阶段流水线

wifi-densepose-vitals（对应 ADR-021）从 CSI 幅度/相位中提取心率与呼吸率，其流水线在 lib.rs 中明确分为四阶段：

1. 预处理（CsiVitalPreprocessor）：EMA 预测滤波抑制静态分量，产出逐子载波残差；
2. 呼吸提取（BreathingExtractor）：0.1–0.5 Hz 带通 + 过零分析得到呼吸率；
3. 心率提取（HeartRateExtractor）：0.8–2.0 Hz 带通 + 自相关峰值检测 + 子载波间相位相干性加权；
4. 异常检测（VitalAnomalyDetector）：Welford 运行统计的 Z-score 分析，产生临床告警（呼吸暂停、心动过速、心动过缓）。

结果存入 VitalSignStore（可配置保留时长），并可通过 groundtruth.rs（ADR-293）导入参考设备 CSV 进行会话级时间对齐与证据分级评估（MAE/RMSE/bias、Bland-Altman 界限、容差内百分比）。

7.1 实战代码（当前 API，来自源码文档示例）

use wifi_densepose_vitals::{
    CsiVitalPreprocessor, BreathingExtractor, HeartRateExtractor,
    VitalAnomalyDetector, VitalSignStore, CsiFrame,
    VitalReading, VitalEstimate,
};

let mut preprocessor = CsiVitalPreprocessor::new(56, 0.05); // 56 子载波, EMA alpha=0.05
let mut breathing = BreathingExtractor::new(56, 100.0, 30.0); // 子载波数, 100Hz 采样率, 30s 窗口
let mut heartrate = HeartRateExtractor::new(56, 100.0, 15.0);
let mut anomaly = VitalAnomalyDetector::default_config();
let mut store = VitalSignStore::new(3600); // 保留 1 小时

let frame = CsiFrame {
    amplitudes: vec![1.0; 56],
    phases: vec![0.0; 56],
    n_subcarriers: 56,
    sample_index: 0,
    sample_rate_hz: 100.0,
};

if let Some(residuals) = preprocessor.process(&frame) {
    let weights = vec![1.0 / 56.0; 56];
    let rr = breathing.extract(&residuals, &weights);
    let hr = heartrate.extract(&residuals, &frame.phases);

    let reading = VitalReading {
        respiratory_rate: rr.unwrap_or_else(VitalEstimate::unavailable),
        heart_rate: hr.unwrap_or_else(VitalEstimate::unavailable),
        subcarrier_count: frame.n_subcarriers,
        signal_quality: 0.9,
        timestamp_secs: 0.0,
    };

    let alerts = anomaly.check(&reading);
    store.push(reading);
}

注：README 早期示例中的 BreathingExtractor::new(100.0) / HeartRateExtractor::new(100.0) 为旧版单参数 API；当前源码签名已改为 (n_subcarriers, sample_rate_hz, window_secs)，以 preprocessor.rs 与 breathing.rs 为准。EMA 的 alpha 被 clamp 在 (0.001, 0.999)，0.05 为 ESP32 生命体征场景的推荐默认值（CsiVitalPreprocessor::esp32_default()）。

---

八、硬件接入与 Wi-Fi 扫描

8.1 硬件接口：纯 Rust 无 FFI

wifi-densepose-hardware 以纯 Rust 实现各传感器协议，无 FFI 依赖。以 ESP32 为例，当前源码（esp32_parser.rs）提供 parse_frame 与 parse_stream 两个入口：

use wifi_densepose_hardware::esp32_parser::Esp32CsiParser;

let raw_bytes: &[u8] = /* ESP32 经 UDP 发来的原始包 */;
let (frame, consumed) = Esp32CsiParser::parse_frame(raw_bytes)?;
println!("RSSI: {} dBm, {} subcarriers", frame.metadata.rssi, frame.subcarriers.len());

parse_frame 返回 (CsiFrame, usize) 元组——第二个值是本次消费的字节数，便于在流式场景中配合 parse_stream 持续解析。

8.2 支持的硬件清单（README 原文）

硬件	Crate Feature	CSI 子载波数	成本
ESP32-S3 网状（3-6 节点）	hardware/esp32	52-56	~$54
Intel 5300 网卡	hardware/intel5300	30	~$50
Atheros AR9580	hardware/linux-wifi	56	~$100
任意 Wi-Fi（Windows/Linux）	wifiscan	仅 RSSI	$0

wifi-densepose-wifiscan 面向 Windows 增强感知（ADR-022），提供多 BSSID 异步扫描（wlanapi feature），其中 PredictiveGate/CoarseBreathingExtractor 等管件与 vitals 流水线同源复用。

---

九、灾后救援：MAT 大规模伤亡评估工具

wifi-densepose-mat 把感知能力落地到地震、楼塌、雪崩、水灾、矿难等救援场景，能力清单（mat/lib.rs）：

• 生命体征检测：呼吸模式、心跳签名、运动特征；
• 幸存者定位：穿废墟的 3D 位置估计（Coordinates3D + LocationUncertainty）；
• 分诊分类：兼容 START 协议的分诊（TriageCalculator / TriageStatus）；
• 实时告警：基于优先级的告警生成与派发。

其架构遵循领域驱动设计（DDD），划分为 Detection / Localization / Alerting 三个有界上下文，由 Integration Layer 统一编排。领域模型覆盖 Survivor、ScanZone、DisasterEvent、VitalSignsReading，并内置事件溯源（EventStore / InMemoryEventStore）。

9.1 MAT 实战代码（当前 API）

use wifi_densepose_mat::{
    DisasterResponse, DisasterConfig, DisasterType,
    ScanZone, ZoneBounds,
};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    // 初始化灾后响应系统
    let config = DisasterConfig::builder()
        .disaster_type(DisasterType::Earthquake)
        .sensitivity(0.8)
        .build();

    let mut response = DisasterResponse::new(config);

    // 定义扫描区域
    let zone = ScanZone::new(
        "Building A - North Wing",
        ZoneBounds::rectangle(0.0, 0.0, 50.0, 30.0),
    );
    response.add_zone(zone)?;

    // 开始扫描
    response.start_scanning().await?;
    Ok(())
}

README 早期示例还给出了基于结构体字面量的构造方式（DisasterConfig { disaster_type: DisasterType::Earthquake, max_scan_zones: 16, ..Default::default() } 配合 add_scan_zone / start_continuous_scan），当前 builder API 为源码推荐用法。MAT 通过 ruvector-solver 完成多 AP 三角化定位，通过 ruvector-temporal-tensor 做时间维压缩。

---

十、构建、测试与 feature flags 全览

10.1 构建与测试命令

# 克隆仓库
git clone https://gitcode.com/GitHub_Trending/wi/RuView
cd RuView/v2

# 检查整个工作区（不引入 GPU 依赖）
cargo check --workspace --no-default-features

# 运行全部测试
cargo test --workspace --no-default-features

# 发布构建
cargo build --release --workspace

# 信号处理基准
cargo bench -p wifi-densepose-signal

# 训练基准
cargo bench -p wifi-densepose-train --no-default-features

# 检测（MAT）基准
cargo bench -p wifi-densepose-mat

README 徽章声明测试规模 542+；当前工作区以 edition = "2021"、workspace 版本 0.3.1、Rust 1.85+ 构建，[profile.release] 启用 lto=true、codegen-units=1、panic="abort"、strip=true 以追求极致体积与性能。

10.2 训练命令

# 检查训练 crate（无需 GPU）
cargo check -p wifi-densepose-train --no-default-features

# GPU 训练（需要 tch/libtorch）
cargo run -p wifi-densepose-train --features tch-backend --bin train -- \
    --config training.toml --dataset /path/to/mmfi

# 验证确定性训练证明
cargo run -p wifi-densepose-train --features tch-backend --bin verify-training

训练侧基于 MM-Fi 公开数据集，做 114→56 子载波插值（ADR-015），并集成全部 5 个 RuVector Crate（ADR-016）。推理侧 wifi-densepose-nn 支持 ONNX Runtime（默认）、PyTorch（tch）与 Candle（纯 Rust）三后端，DensePose 头输出 24 个身体部位。

10.3 Feature Flags 完整表格（README 原文）

Crate	Feature	说明
wifi-densepose-nn	onnx（默认）	ONNX Runtime 后端
wifi-densepose-nn	tch-backend	PyTorch（libtorch）后端
wifi-densepose-nn	candle-backend	Candle（纯 Rust）后端
wifi-densepose-nn	cuda	CUDA GPU 加速
wifi-densepose-train	tch-backend	启用 GPU 训练模块
wifi-densepose-mat	ruvector（默认）	RuVector 图算法
wifi-densepose-mat	api（默认）	REST + WebSocket API
wifi-densepose-mat	distributed	多节点协同
wifi-densepose-mat	drone	无人机挂载扫描
wifi-densepose-hardware	esp32	ESP32 协议支持
wifi-densepose-hardware	intel5300	Intel 5300 CSI Tool
wifi-densepose-hardware	linux-wifi	Linux 商用 Wi-Fi
wifi-densepose-wifiscan	wlanapi	Windows WLAN API 异步扫描
wifi-densepose-core	serde	序列化支持
wifi-densepose-core	async	异步 trait 支持

此外，工作区还单独排除两个 wasm32/no_std 目标 crate（wifi-densepose-wasm-edge、homecore-plugin-example），需要单独构建：

cargo build -p wifi-densepose-wasm-edge --target wasm32-unknown-unknown --release
cargo build --target wasm32-unknown-unknown --release -p homecore-plugin-example

---

十一、对外服务与部署形态

感知链路的对外出口由 wifi-densepose-sensing-server（Axum）承担：通过 UDP 摄入 ESP32 的 CSI 数据流，处理后在 WebSocket 上广播，并驱动感知 UI。README 架构图中的 wifi-densepose-api（REST/WS）与 wifi-densepose-wasm（浏览器 WASM 灾后仪表盘）、wifi-densepose-cli（MAT 命令行工具）共同构成三层出口；其中 wifi-densepose-api 在当前仓库中已由 sensing-server 的 Axum 层取代（v2/Cargo.toml #578 注释）。

---

十二、架构决策记录（ADR）与后续研读入口

README 列出的关键设计决策均可在本仓库 docs/adr/ 中直接研读（路径已转换为仓库根目录相对路径）：

ADR	标题	状态
ADR-014	SOTA 信号处理	已接受
ADR-015	MM-Fi + Wi-Pose 训练数据集	已接受
ADR-016	RuVector 训练流水线	已接受（完成）
ADR-017	RuVector 信号 + MAT 集成	已接受
ADR-021	生命体征检测流水线	已接受
ADR-022	Windows Wi-Fi 增强感知	已接受
ADR-024	对比式 CSI 嵌入模型	已接受

若想深入阅读源码，推荐按以下顺序展开：先读 core/lib.rs 与 traits.rs 建立类型心智模型，再依次进入 signal、vitals、mat，最后对照 Cargo.toml 理解整个工作区的依赖拓扑。

---

结语

RuView v2 的 WiFi-DensePose Rust 工作区用一套高度模块化、纯 Rust 安全代码（core 层 forbid(unsafe_code)）实现了"Wi-Fi 即传感器"的完整链路：core 定义契约、signal 消化物理层、nn/train 负责学习、vitals 与 mat 面向生命体征与灾后救援两大垂直场景、hardware/wasm/server/cli 打通从 ESP32 到浏览器的部署闭环。无论是研究 CSI 信号处理、复现 SOTA 算法，还是构建实时穿墙感知应用，这份 README 加上仓库源码都是一份可执行、可验证、可扩展的工程范本。所有 Crate 以 MIT OR Apache-2.0 双许可发布，相关许可文本见仓库根目录 LICENSE。