192 lines
6.5 KiB
Markdown
192 lines
6.5 KiB
Markdown
# WaterfallWidget.js 文档
|
||
|
||
本文档为 `waterfallwidget.js` 文件提供详细说明，涵盖了 `waterfallwidget` 类的功能、用法和配置选项。该类用于创建频谱图和瀑布图可视化工具，广泛应用于信号处理和频谱分析领域。
|
||
|
||
## 概述
|
||
|
||
`waterfallwidget` 是一个功能强大的 JavaScript 类，用于在网页中绘制频谱图和瀑布图。它支持实时数据更新、频率缩放、用户交互、信号标注等多种功能，适用于无线电信号分析、频谱监控等场景。该类基于 Konva.js 库实现绘图功能，并提供了丰富的配置选项和事件处理机制。
|
||
|
||
## 初始化
|
||
|
||
要使用 `waterfallwidget`，需要通过构造函数创建一个实例，并传入容器 ID 和配置选项。以下是构造函数的定义：
|
||
|
||
```javascript
|
||
function waterfallwidget(id, options)
|
||
```
|
||
|
||
- **id**：字符串，指定容器的 DOM ID，用于渲染瀑布图。
|
||
- **options**：对象，包含各种配置选项，用于自定义瀑布图的行为和外观。
|
||
|
||
### 配置选项
|
||
|
||
以下是常用的配置选项及其默认值：
|
||
|
||
- **min_db**：最小分贝值，默认为 -200。
|
||
- **max_db**：最大分贝值，默认为 0。
|
||
- **min_freq**：最小频率值，默认为 0。
|
||
- **max_freq**：最大频率值，默认为 40000。
|
||
- **showSpectrogramAvg**：是否显示频谱平均值，默认为 false。
|
||
- **showSpectrogramMin**：是否显示频谱最小值，默认为 false。
|
||
- **showSpectrogramMax**：是否显示频谱最大值，默认为 false。
|
||
- **showPeakMarker**：是否显示峰值标记，默认为 false。
|
||
- **allowRunMode**：运行模式，0 表示侦察模式，1 表示实时模式，默认为 0。
|
||
- **disableZoom**：是否禁用缩放功能，默认为 false。
|
||
- **wfFreqPointLable**：是否启用频点标注，默认为 false。
|
||
- **bg_color**：背景颜色，默认为 '#37384B'。
|
||
- **fore_color**：前景颜色，默认为 '#CCCCFF'。
|
||
- **wave_color**：波形颜色，默认为 '#4BF3A7'。
|
||
|
||
更多配置选项请参见代码中的构造函数部分。
|
||
|
||
### 初始化示例
|
||
|
||
```javascript
|
||
var widget = new waterfallwidget('container', {
|
||
min_db: -150,
|
||
max_db: 0,
|
||
min_freq: 50000000,
|
||
max_freq: 100000000,
|
||
showPeakMarker: true,
|
||
allowRunMode: 1
|
||
});
|
||
widget.init();
|
||
```
|
||
|
||
## 主要方法
|
||
|
||
`waterfallwidget` 类提供了大量方法，用于数据处理、绘图和用户交互。以下是一些关键方法：
|
||
|
||
### addData(d, time)
|
||
|
||
添加新数据并更新瀑布图和频谱图。
|
||
|
||
- **d**：数组，包含信号强度数据。
|
||
- **time**：字符串，可选，数据的时间戳。
|
||
|
||
### drawWaterFall(bins)
|
||
|
||
绘制瀑布图的一行数据。
|
||
|
||
- **bins**：数组，包含信号强度数据。
|
||
|
||
### setFreqZoom(start, end)
|
||
|
||
设置频率缩放范围。
|
||
|
||
- **start**：数字，起始频率。
|
||
- **end**：数字，结束频率。
|
||
|
||
### changeDBRange(min_db, max_db, force)
|
||
|
||
更改分贝范围。
|
||
|
||
- **min_db**：数字，最小分贝值。
|
||
- **max_db**：数字，最大分贝值。
|
||
- **force**：布尔值，是否强制更新，默认为 false。
|
||
|
||
### drawAllSpectrogram(bins)
|
||
|
||
绘制完整的频谱图，包括峰值标记、最大/最小保持等。
|
||
|
||
- **bins**：数组，包含信号强度数据。
|
||
|
||
### setAdjCenter(freq, fireEvent)
|
||
|
||
设置调整中心频率。
|
||
|
||
- **freq**：数字，中心频率。
|
||
- **fireEvent**：布尔值，是否触发事件，默认为 false。
|
||
|
||
更多方法请参见代码中的详细实现。
|
||
|
||
## 属性
|
||
|
||
`waterfallwidget` 类包含大量属性，用于控制瀑布图的状态和外观。以下是一些重要属性：
|
||
|
||
- **min_db**：最小分贝值。
|
||
- **max_db**：最大分贝值。
|
||
- **freq_start**：当前显示的起始频率。
|
||
- **freq_end**：当前显示的结束频率。
|
||
- **showSpectrogramAvg**：是否显示频谱平均值。
|
||
- **showPeakMarker**：是否显示峰值标记。
|
||
- **adj_start**：调整起始频率。
|
||
- **adj_end**：调整结束频率。
|
||
- **bg_color**：背景颜色。
|
||
- **wave_color**：波形颜色。
|
||
|
||
## 事件处理
|
||
|
||
`waterfallwidget` 支持多种事件，允许开发者响应用户交互和状态变化。以下是一些常用事件：
|
||
|
||
- **zoom-change**：频率缩放变化时触发。
|
||
- **pointer-change**：指针位置变化时触发。
|
||
- **adj-change**：调整范围变化时触发。
|
||
- **label-change**：标签选择变化时触发。
|
||
- **context-click**：右键菜单点击时触发。
|
||
|
||
### 事件绑定示例
|
||
|
||
```javascript
|
||
widget.on('zoom-change', function(event) {
|
||
console.log('Zoom changed to:', event.start, event.end);
|
||
});
|
||
```
|
||
|
||
## 用户交互
|
||
|
||
`waterfallwidget` 支持丰富的用户交互功能，包括：
|
||
|
||
- **频率缩放**：通过鼠标滚轮或拖动选择区域进行缩放。
|
||
- **调整范围**：在实时模式下，可以拖动调整频率范围。
|
||
- **峰值标记**：显示信号峰值并标注频率和强度。
|
||
- **右键菜单**：提供上下文菜单，支持多种操作如侦察、数据采集等。
|
||
- **频点标注**：允许用户添加和编辑频率点标注。
|
||
|
||
## 绘图逻辑
|
||
|
||
`waterfallwidget` 将绘图区域分为频谱图和瀑布图两部分：
|
||
|
||
- **频谱图**：显示当前信号的强度分布，支持平均值、最大值、最小值等多种显示模式。
|
||
- **瀑布图**：随时间滚动显示历史信号数据，使用颜色映射表示信号强度。
|
||
|
||
绘图使用 Konva.js 库实现，通过多层 canvas 叠加实现复杂的视觉效果。
|
||
|
||
## 使用示例
|
||
|
||
以下是一个完整的示例，展示如何初始化和使用 `waterfallwidget`：
|
||
|
||
```javascript
|
||
// 创建瀑布图实例
|
||
var widget = new waterfallwidget('waterfall-container', {
|
||
min_db: -150,
|
||
max_db: 0,
|
||
min_freq: 50000000,
|
||
max_freq: 100000000,
|
||
showPeakMarker: true,
|
||
showSpectrogramMax: true,
|
||
allowRunMode: 0
|
||
});
|
||
|
||
// 初始化
|
||
widget.init();
|
||
|
||
// 添加数据
|
||
setInterval(function() {
|
||
var data = Array.from({length: 2000}, () => Math.random() * (-50 + 150) - 150);
|
||
widget.addData(data, new Date().toLocaleTimeString());
|
||
}, 1000);
|
||
|
||
// 监听缩放事件
|
||
widget.on('zoom-change', function(event) {
|
||
console.log('Frequency range:', event.start, 'to', event.end);
|
||
});
|
||
```
|
||
|
||
## 注意事项
|
||
|
||
- **性能考虑**：对于大数据量和高频率更新，建议优化数据处理逻辑，避免频繁重绘。
|
||
- **浏览器兼容性**：依赖 Konva.js 库，确保在支持 HTML5 Canvas 的现代浏览器中使用。
|
||
- **配置选项**：初始化时需仔细配置频率和分贝范围，以适应具体的信号分析需求。
|
||
- **事件处理**：事件监听器应妥善管理，避免内存泄漏。
|
||
|
||
以上是 `waterfallwidget.js` 的完整文档，希望对您的使用和开发有所帮助。 |