@rfkit/spectrum-analyzer/README.md

A high-performance spectrum analyzer library for RF signal processing, supporting real-time spectrum analysis, waterfall display, and multi-segment frequency scanning

# @rfkit/spectrum-analyzer

高性能 RF 频谱分析库，支持实时频谱分析、瀑布图显示和多段频率扫描。

提供 **JS 版本** 和 **WASM 高性能版本** 两种选择。

## 安装

```bash
pnpm add @rfkit/spectrum-analyzer
```

正式版本默认走 `Release PR -> 合并 -> GitHub Actions 自动发布 npm`。仓库里的 `publish:npm` / `build:npm` 只保留为调试或应急入口，不作为日常正式发版流程。

## 使用

### JS 版本（默认）

```typescript
import {
  ExtraDataMode,
  SpectrumAnalyzer,
  LevelStreamAnalyzer,
  type SpectrumConfig,
  type SpectrumOutputData,
} from '@rfkit/spectrum-analyzer';

const analyzer = new SpectrumAnalyzer({
  maxPoints: 2048,
  outputPoints: 1024,
  enableStatistics: true,
  onSpectrumUpdate: (data) => {
    console.log(data.realData);
  },
});

// 处理频谱数据
analyzer.process({ data: Float32Array, timestamp: Date.now() });
```

### 分段额外数据

`setExtraData` 默认保持完整数组设置语义。传入第三个参数后，每条额外数据会独立维护全长缓冲区，并按 `segmentOffset + offset` 局部写入；未写入的位置保留为 `NaN`。

```typescript
analyzer.setExtraData(
  {
    traceA: traceAChunk,
    traceB: traceBChunk,
  },
  ExtraDataMode.MERGE,
  { segmentOffset: 1, offset: 200 },
);
```

### WASM 高性能版本

`SpectrumAnalyzer` 和 `LevelStreamAnalyzer` 的 WASM API 与 JS 版本一致；`WaterfallAnalyzer` 和 `SeriesManager` 为纯 JS 实现，同样可从 `/wasm` 入口导入（重导出）。

```typescript
import {
  initWasm,
  SpectrumAnalyzer,
  LevelStreamAnalyzer,
  WaterfallAnalyzer,
  SeriesManager,
} from '@rfkit/spectrum-analyzer/wasm';

// 应用启动时初始化（仅需一次）
await initWasm();

// 之后使用方式与 JS 版本完全一致
const analyzer = new SpectrumAnalyzer({
  maxPoints: 2048,
  outputPoints: 1024,
  enableStatistics: true,
  onSpectrumUpdate: (data) => {
    console.log(data.realData);
  },
});

analyzer.process({ data: Float32Array, timestamp: Date.now() });
```

## 核心组件

### SpectrumAnalyzer

频谱分析器，支持：
- 实时数据处理与重采样
- 最大值/最小值/平均值统计
- 瀑布图数据管理
- 天线因子补偿
- 模板超限检测
- 多段频率扫描

### WaterfallAnalyzer

独立瀑布图数据分析器，支持完整矩阵更新、增量帧，以及 X/Y 二维裁剪与降采样。采样范围使用原始矩阵索引的半开区间 `[start, end)`：

```typescript
import { WaterfallAnalyzer } from '@rfkit/spectrum-analyzer';

const analyzer = new WaterfallAnalyzer({
  onWaterfallUpdate: ({ data }) => {
    console.log(data);
  },
});

analyzer.setData(waterfallFrames);
analyzer.updateSamplingRange({
  x: [100, 900],
  y: [20, 120],
  outputWidth: 400,
  outputHeight: 100,
});
```

`setData()` 要求数据为非空等宽矩阵，传入空数组表示清空；`appendFrame()` 用于实时增量场景，应配置 `maxFrames` 避免缓存无限增长。采样范围会夹紧到矩阵边界，夹紧后为空的范围会报错。

`WaterfallAnalyzer` 为纯 JS 实现，可从默认入口或 `/wasm` 入口导入。

### LevelStreamAnalyzer

电平流分析器，支持：
- 电平概率分布统计
- 时间/点数缓存模式

## License

MIT