198 lines
9.5 KiB
Markdown
198 lines
9.5 KiB
Markdown
# PlanisphereWidget 类文档
|
||
|
||
## 概述
|
||
`PlanisphereWidget` 是一个基于 JavaScript 的类，用于在网页中创建和展示星座图、矢量图和眼图等可视化内容。该类依赖于 Konva.js 库，通过 canvas 绘制图形，提供了一种灵活的方式来呈现复杂的波形数据和坐标系图形。它适用于需要动态展示信号处理结果或科学数据的场景。
|
||
|
||
Konva.js 是一个强大的 2D 绘图库，`PlanisphereWidget` 利用其舞台（Stage）和层（Layer）机制来管理绘图元素，确保图形的高效渲染和交互性。
|
||
|
||
## 构造函数
|
||
```javascript
|
||
constructor(id, options)
|
||
```
|
||
|
||
- **参数**：
|
||
- `id` (String): 指定容器的 ID，`PlanisphereWidget` 将在这个容器内创建 Konva 舞台并绘制图形。
|
||
- `options` (Object): 可选的配置对象，用于自定义绘图样式和布局。
|
||
- `bg_color` (String): 背景颜色，默认值为 '#27293D'。
|
||
- `fore_color` (String): 前景颜色，默认值为 '#CCCCCC'。
|
||
- `coor_color` (String): 坐标系颜色，默认值为 '#1B1B24'。
|
||
- `border_color` (String): 边框颜色，默认值为 '#CCCCCC'。
|
||
- `wave_color` (String): 波形颜色，默认值为 '#1D8CF8'。
|
||
- `margin_left` (Number): 左边距，默认值为 0。
|
||
- `margin_top` (Number): 上边距，默认值为 0。
|
||
|
||
- **功能**：初始化 `PlanisphereWidget` 实例，设置容器、颜色配置和 Konva 舞台。构造函数会创建两个 Konva 层（`layer_coor` 用于坐标系，`layer_wave` 用于波形图），并调用 `init()` 和 `initResize()` 方法进行进一步的初始化。
|
||
|
||
## 属性
|
||
- `container`: 绘图所在的 DOM 元素，通过构造函数中的 `id` 参数获取。
|
||
- `stage`: Konva 舞台对象，用于管理绘图层和渲染。
|
||
- `layer_coor`: Konva 层对象，用于绘制坐标系，不启用命中检测（`hitGraphEnabled(false)`）。
|
||
- `layer_wave`: Konva 层对象，用于绘制波形图，不启用命中检测。
|
||
- `bg_color`: 背景颜色，用于填充绘图区域。
|
||
- `fore_color`: 前景颜色，目前与 `bg_color` 绑定，实际用途待定。
|
||
- `coor_color`: 坐标系颜色，目前未直接使用。
|
||
- `border_color`: 边框和坐标线颜色。
|
||
- `wave_color`: 波形和指针颜色。
|
||
- `margin_left`: 左边距，定义绘图区域的左边界。
|
||
- `margin_top`: 上边距，定义绘图区域的上边界。
|
||
- `area_x`: 绘图区域的 X 坐标，等于 `margin_left`。
|
||
- `area_y`: 绘图区域的 Y 坐标，等于 `margin_top`。
|
||
- `area_width`: 绘图区域的宽度，等于舞台宽度减去 `margin_left`。
|
||
- `area_height`: 绘图区域的高度，等于舞台高度减去 `margin_top`。
|
||
- `canvas`: 用于离屏绘制的临时 canvas 元素。
|
||
- `ctx_canvas`: 临时 canvas 的 2D 上下文，用于绘制波形数据。
|
||
- `pointer`: Konva 圆形对象，用于表示波形中的指针。
|
||
- `viewmodel`: 当前视图模式，0 表示星座图，1 和 2 表示眼图的不同模式。
|
||
- `dAlpha`: 布尔值，是否启用余晖效果。
|
||
- `d1`, `d2`, `d3`, `d4`: 用于存储历史数据以实现余晖效果。
|
||
|
||
## 方法
|
||
|
||
### `init()`
|
||
- **功能**：初始化舞台和绘图区域。如果容器高度为 0，则不执行初始化。设置舞台的宽度和高度，计算绘图区域的尺寸，并调用 `drawCoor()` 绘制坐标系。初始化离屏 canvas 和指针对象。
|
||
- **参数**：无
|
||
- **返回值**：无
|
||
|
||
### `drawCoor()`
|
||
- **功能**：绘制坐标系，包括边框、网格线和圆形参考线。坐标系包括水平和垂直的虚线网格、对角线以及两个同心圆，中心位于绘图区域的中心。
|
||
- **参数**：无
|
||
- **返回值**：无
|
||
|
||
### `setViewMode(vm)`
|
||
- **功能**：设置视图模式，决定绘制星座图还是眼图。如果 `vm` 为 3，则启用余晖效果并将模式设为 0（星座图）。调用 `clear()` 方法清除当前绘图内容。
|
||
- **参数**：
|
||
- `vm` (Number): 视图模式，0 表示星座图，1 和 2 表示眼图，3 表示带余晖效果的星座图。
|
||
- **返回值**：无
|
||
|
||
### `feed(d, di, dq)`
|
||
- **功能**：处理星座图数据。如果当前视图模式为 0（星座图），则调用 `drawWave_vector(d)` 绘制矢量图。
|
||
- **参数**：
|
||
- `d` (Array): 星座图数据。
|
||
- `di` (Array): 眼图 I 通道数据，未使用。
|
||
- `dq` (Array): 眼图 Q 通道数据，未使用。
|
||
- **返回值**：无
|
||
|
||
### `feedVector(d)`
|
||
- **功能**：处理矢量图数据。如果当前视图模式为 0，则调用 `drawWave_vector(d)` 绘制矢量图。
|
||
- **参数**：
|
||
- `d` (Array): 矢量图数据，二维数组，每个元素包含 x 和 y 坐标。
|
||
- **返回值**：无
|
||
|
||
### `feedIQ(di, dq)`
|
||
- **功能**：处理眼图数据。如果视图模式为 1，则绘制 `di` 数据；如果为 2，则绘制 `dq` 数据。调用 `drawIQ()` 方法进行实际绘制。
|
||
- **参数**：
|
||
- `di` (Array): 眼图 I 通道数据。
|
||
- `dq` (Array): 眼图 Q 通道数据。
|
||
- **返回值**：无
|
||
|
||
### `drawIQ(IQBuff)`
|
||
- **功能**：绘制眼图数据。清除当前绘图内容，然后遍历 `IQBuff` 数组，调用 `drawWave_eye()` 绘制每个数据段。
|
||
- **参数**：
|
||
- `IQBuff` (Array): 眼图数据数组，每个元素是一段波形数据。
|
||
- **返回值**：无
|
||
|
||
### `clear()`
|
||
- **功能**：清除当前绘图内容，重置图像数据，并调用 `drawWave_planis([])` 和 `drawWave_vector([])` 清空星座图和矢量图。
|
||
- **参数**：无
|
||
- **返回值**：无
|
||
|
||
### `drawWave_eye(d)`
|
||
- **功能**：绘制眼图波形。使用 Konva 层的上下文绘制折线图，横轴为数据索引，纵轴为数据值，缩放至绘图区域的一半高度。
|
||
- **参数**：
|
||
- `d` (Array): 波形数据数组，每个元素是一个数值。
|
||
- **返回值**：无
|
||
|
||
### `drawWave_planis(d)`
|
||
- **功能**：绘制星座图。清除当前绘图内容，创建图像数据对象。如果启用余晖效果（`dAlpha` 为 true），则使用历史数据（`d1` 到 `d4`）绘制不同透明度的点，实现余晖效果。最后绘制当前数据 `d`。
|
||
- **参数**：
|
||
- `d` (Array): 星座图数据，二维数组，每个元素包含 x 和 y 坐标。
|
||
- **返回值**：无
|
||
|
||
### `drawWave_vector(d)`
|
||
- **功能**：绘制矢量图。清除当前绘图内容，使用 Konva 层的上下文绘制折线图，连接数据点，最多处理前 100 个点以提高性能。
|
||
- **参数**：
|
||
- `d` (Array): 矢量图数据，二维数组，每个元素包含 x 和 y 坐标。
|
||
- **返回值**：无
|
||
|
||
### `drawWave_plainsD(rwidth, rHeight, width, imgData, dlen, d, a)`
|
||
- **功能**：辅助方法，用于绘制星座图中的点，支持透明度设置。计算每个数据点的坐标位置，并设置图像数据中的颜色和透明度。
|
||
- **参数**：
|
||
- `rwidth` (Number): 绘图区域宽度的一半。
|
||
- `rHeight` (Number): 绘图区域高度的一半。
|
||
- `width` (Number): 图像数据的宽度。
|
||
- `imgData` (ImageData): 图像数据对象。
|
||
- `dlen` (Number): 图像数据的长度。
|
||
- `d` (Array): 星座图数据，二维数组。
|
||
- `a` (Number): 透明度值，范围 0-255。
|
||
- **返回值**：无
|
||
|
||
### `getDrawWHByPixelRatio(xory)`
|
||
- **功能**：根据设备像素比计算绘图尺寸，用于处理高分辨率显示器上的绘图精度问题。
|
||
- **参数**：
|
||
- `xory` (Number): 输入的宽度或高度值。
|
||
- **返回值**：Number - 调整后的尺寸值。
|
||
|
||
### `setWaveColor(imgData, p, dlen, rowlen, a = 255)`
|
||
- **功能**：设置图像数据中指定位置的颜色和透明度，用于绘制星座图中的点。如果透明度不是 255，则使用绿色，否则使用蓝色。
|
||
- **参数**：
|
||
- `imgData` (ImageData): 图像数据对象。
|
||
- `p` (Number): 像素位置索引。
|
||
- `dlen` (Number): 图像数据长度。
|
||
- `rowlen` (Number): 每行的字节数。
|
||
- `a` (Number): 透明度值，默认 255。
|
||
- **返回值**：无
|
||
|
||
### `destroy()`
|
||
- **功能**：销毁实例，清除图像数据并销毁 Konva 舞台。
|
||
- **参数**：无
|
||
- **返回值**：无
|
||
|
||
### `dispose()`
|
||
- **功能**：释放资源，调用 `destroy()` 方法。
|
||
- **参数**：无
|
||
- **返回值**：无
|
||
|
||
### `initResize()`
|
||
- **功能**：初始化窗口大小调整事件监听。使用 jQuery 的 `resize` 事件监听容器大小变化，延迟 100 毫秒后调用 `init()` 方法重新初始化绘图区域。
|
||
- **参数**：无
|
||
- **返回值**：无
|
||
|
||
## 使用示例
|
||
以下是一个简单的代码示例，展示如何创建 `PlanisphereWidget` 实例并绘制星座图：
|
||
|
||
```javascript
|
||
// HTML 中需要有一个容器元素
|
||
<div id="planisphereContainer" style="width: 500px; height: 500px;"></div>
|
||
|
||
// JavaScript 代码
|
||
const widget = new PlanisphereWidget('planisphereContainer', {
|
||
bg_color: '#27293D',
|
||
wave_color: '#1D8CF8',
|
||
border_color: '#CCCCCC',
|
||
margin_left: 10,
|
||
margin_top: 10
|
||
});
|
||
|
||
// 设置视图模式为星座图
|
||
widget.setViewMode(0);
|
||
|
||
// 提供星座图数据，格式为二维数组 [[x1, y1], [x2, y2], ...]
|
||
const data = [
|
||
[0.5, 0.5],
|
||
[-0.5, 0.5],
|
||
[-0.5, -0.5],
|
||
[0.5, -0.5]
|
||
];
|
||
widget.feed(data);
|
||
|
||
// 启用余晖效果
|
||
widget.setViewMode(3);
|
||
widget.feed(data);
|
||
```
|
||
|
||
## 注意事项
|
||
- 确保容器元素（通过 `id` 指定）在 DOM 中存在，并且具有明确的宽度和高度，否则初始化可能会失败。
|
||
- 数据格式必须符合方法的要求，例如 `feed()` 和 `feedVector()` 需要二维数组，`feedIQ()` 需要一维数组。
|
||
- 余晖效果会保存历史数据，可能会增加内存使用量，长时间使用后建议调用 `clear()` 清除历史数据。
|
||
- 绘图性能可能受数据量影响，`drawWave_vector()` 方法限制了最多绘制 100 个点以保证性能。
|
||
- 该类依赖于 Konva.js 和 jQuery 库，确保在页面中引入这些库。 |