libxtos-signal

时间戳、DFT 功率、滤波状态和 SSVEP/P300 特征。

本页目录

输入与单位

调用方提供并拥有输入、输出、结果和滤波器结构。FFT、SSVEP、P300 不修改输入；滤波支持 input==output 的精确原地处理，不要使用部分重叠数组。每通道独立维护状态，先 init 再连续 process，最后在完整窗口上提取特征。库不管理设备、调度或单位。

时间戳为 uint64 纳秒，采样率为 Hz，幅值为 double；功率随幅值单位平方变化，P300 peak_amplitude 保持输入单位。调用方必须拒绝 NaN/Inf 和不合理长度。notch、bandpass、ssvep 的公开实现没有 isfinite 检查；未报错不等于数值有效。除时间戳三态返回外，int 接口成功为 0，失败为 -1/errno；失败后不要使用部分结果。链接需要 -lm。

时间戳

int xtos_signal_validate_timestamps(const uint64_t *timestamps_ns,
    size_t count, uint32_t sample_rate_hz, uint64_t tolerance_ns,
    struct xtos_signal_validation *result);

int xtos_signal_correct_timestamps(uint64_t start_timestamp_ns,
    uint32_t sample_rate_hz, uint64_t *timestamps_ns, size_t count);

两个接口要求数组非 NULL、count>0、sample_rate_hz>0；校验还要求 result 非 NULL，否则 -1/EINVAL。

期望间隔为 llround(1000000000.0 / sample_rate_hz)。

校验只对严格递增相邻时间计算 interval_anomalies；间隔误差大于 tolerance_ns 才计数。

重复或倒退计入 timestamp_anomalies。

返回	含义	结果
0	无异常。	expected_interval_ns 和正向间隔 min/max；count=1 时均为 0。
1	完成但发现异常，不是 errno 失败。	读取两个异常计数；无正向间隔时 min=UINT64_MAX、max=0。
-1	参数无效，errno=EINVAL。	不要读取未成功初始化的 result。

correct_timestamps 写入 start + i×rounded_interval，不逐点对精确分数时间取整；非整纳秒周期会积累舍入误差，也不检查 uint64 乘加溢出。调用方保证范围安全，长期准确时间轴自行维护有理数时钟。保留原始时间戳和异常记录，修正只用于重采样、回放或缺失标签。

DFT 功率

int xtos_signal_fft_power(const double *input, size_t n,
                          double *power, size_t power_count);

/* Caller allocates n input values and at least n/2 + 1 output values. */

n 必须是非零 2 的幂；input、power 非 NULL，power_count≥n/2+1，否则 -1/EINVAL。radix-2 FFT 返回 bin 0 到 n/2（含 Nyquist）的一侧结果；多余输出保持原样。power[k]=Re(X[k])²+Im(X[k])²，X 未归一化；不除以 n 或 n²、不加窗、不去均值、不将内部正频率 bin 乘 2。因此它不是按 Hz 归一化的 PSD。频率为 k×fs/n，分辨率为 fs/n。

函数内部为输入复制分配两个 n 长度 double 数组；失败为 -1/ENOMEM，返回前释放。power 仍由调用方拥有；预分配 power 不能消除内部堆分配，不应把它放进严格无分配采集路径。n 同时影响内存、FFT 时间、频率分辨率和更新延迟。

滤波器

接口	参数	行为
notch_init	filter 非 NULL；fs>0、0<f0<fs/2、Q>0 的范围比较；无显式 finite 检查。	二阶 IIR 陷波，Q 控制带宽；init 清零历史。
bandpass_init	filter 非 NULL；0<low<high<fs/2；Nyquist 不合法；无显式 finite 检查。	二阶高通接二阶低通，Q=1/√2，各级合计四阶基线。
process	filter/input/output 非 NULL；数组至少 count 个；count=0 允许。	成功 0，错误 -1/EINVAL；支持精确原地，不分配。

Nyquist=fs/2。fs=250 Hz 时 50 Hz 陷波、5–40 Hz 带通合法，125 Hz 截止不合法；50/60 Hz 由实际电源环境选择，不自动检测。采样率变化后重算系数。滤波器是有状态因果 IIR，不是零相位；启动和重新 init 有瞬态，频率相关相位延迟会影响 ERP。连续块保留状态，每通道独立，不要每窗清零或并发共享。

SSVEP

int xtos_signal_ssvep_feature(const double *input, size_t n,
    uint32_t sample_rate_hz, double target_frequency_hz,
    size_t harmonic_count, size_t neighbor_bins,
    struct xtos_ssvep_feature *result);

要求 input/result 非 NULL、n 为非零 2 的幂、fs>0、0<target<fs/2、harmonic_count>0、neighbor_bins>0。实现只做普通范围比较，没有 isfinite；调用方先拒绝 target_frequency_hz 的 NaN/Inf。target_bin=llround(target×n/fs) 必须非零且≤n/2；每个 target_bin×h 也须≤n/2，否则 -1/EINVAL。基频合法不表示谐波都不越界。

signal_power 是目标谐波 bin 功率和；noise_power 是两侧有效邻居的平均功率，跳过 DC 和所有目标 bin，重叠邻域可能重复计数。

snr=signal_power/noise_power，snr_db=10×log10(snr)。

无有效邻居或噪声≤0 为 -1/EDOM，分配失败为 ENOMEM。

它不做 CCA、刺激识别、伪迹剔除或个体校准；这是研究特征，不是诊断或安全控制信号。

P300

int xtos_signal_p300_feature(const double *input, size_t n,
    uint32_t sample_rate_hz, size_t baseline_samples,
    uint32_t window_start_ms, uint32_t window_end_ms,
    double detection_z_threshold, struct xtos_p300_feature *result);

int xtos_signal_p300_quality_gate(const struct xtos_p300_feature *trials,
    size_t trial_count, size_t min_valid_trials,
    double min_detection_rate, double min_mean_z_score,
    double max_latency_stddev_ms, struct xtos_p300_quality *result);

input[0..baseline_samples) 是刺激前基线，刺激起点为 baseline_samples。

要求 fs>0、2≤baseline_samples<n、start_ms<end_ms、有限且大于 0 的 z 阈值。

毫秒转样本为 (ms×fs+500)/1000；分析区间为 [baseline+start_offset, baseline+end_offset)，结束点不含，舍入后必须非空且在 n 内。

n 不要求 2 的幂。

基线均值和总体标准差用于中心化与 z 分数；窗口取最大正向中心化幅值，等值保留最早索引。

peak_latency_ms 相对刺激起点；window_energy 是中心化样本平方和；detected 仅表示 peak_z_score≥阈值。

无效参数或被检查的基线/窗口非有限值为 EINVAL；基线标准差为零或非有限为 EDOM。

quality_gate 要求 trial_count>0、min_valid_trials>0、有限 detection_rate∈[0,1]、有限 mean_z、有限且非负 latency_stddev 上限以及非 NULL trials/result。

它检查 trial 字段一致性，统计有效 trial 的检出率、平均 z 和潜伏期总体标准差。

任何 rejected trial、有效数不足、阈值不达标或全部无效都使 passed=0；统计完成仍返回 0。

验证与源码

公开 tests/test_signal.c 覆盖固定时间序列、单位冲激、整数 bin 正弦、滤波稳定区间和合成 P300 epoch。应用还应测试单位转换、缺失样本、NaN/Inf、短输出、Nyquist 边界、跨块状态和刺激起点。阈值取决于幅度、预处理和窗口，不能直接用于人体实验。

源码：sdk/libxtos-signal/include/xtos/signal.h 定义结果字段，sdk/libxtos-signal/src/signal.c 定义舍入、归一化、滤波系数和质量门。记录原始输入、采样率、窗口和版本，才能解释和重放结果。