waterfallwidget.js.暂存.md

public/html-page/waterfallwidget.js.暂存.md

@@ -0,0 +1,192 @@
+# 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` 的完整文档，希望对您的使用和开发有所帮助。