# 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 库，确保在页面中引入这些库。