vue-ts-example/public/html-page/planispherewidget.js.md

PlanisphereWidget 类文档

概述

PlanisphereWidget 是一个基于 JavaScript 的类，用于在网页中创建和展示星座图、矢量图和眼图等可视化内容。该类依赖于 Konva.js 库，通过 canvas 绘制图形，提供了一种灵活的方式来呈现复杂的波形数据和坐标系图形。它适用于需要动态展示信号处理结果或科学数据的场景。

Konva.js 是一个强大的 2D 绘图库，PlanisphereWidget 利用其舞台（Stage）和层（Layer）机制来管理绘图元素，确保图形的高效渲染和交互性。

构造函数

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 实例并绘制星座图：

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