PyQtGraph库的基本使用

前言

最近接手一个PySide中画图的任务，用到了PyQtGraph库，发现该库的中文文档相对缺乏。于是稍微整理了一下。

PyQtGraph is a pure-python graphics and GUI library built on PyQt / PySide and numpy. It is intended for use in mathematics / scientific / engineering applications. Despite being written entirely in python, the library is very fast due to its heavy leverage of NumPy for number crunching and Qt’s GraphicsView framework for fast display.

PySide6的GraphicsView框架介绍

PySide6 的 QGraphicsView 框架是用于构建复杂的图形界面的一个强大工具。这个框架包括了 QGraphicsScene、QGraphicsView 和 QGraphicsItem 等核心组件。它们共同提供了丰富的功能，比如动画、拖拽操作、缩放和平移等。

坐标系统

PyQtGraph 中有几个不同的坐标系统，这些坐标系统对于理解和交互图形元素非常重要。以下是主要的坐标系统：

像素坐标 (Pixel Coordinates)：
    像素坐标是相对于屏幕或窗口的坐标系统。原点 (0, 0) 通常位于窗口的左上角。这对于直接操作窗口上的元素（如放置控件）非常有用。

视图坐标 (View Coordinates)：
    视图坐标是 ViewBox 内部使用的坐标系统。ViewBox 是一个可以缩放和平移的容器，它允许你在图形中平移和缩放。视图坐标的原点取决于视图的当前状态。例如，如果你向右平移视图，视图坐标的原点也会向右移动。

项目坐标 (Item Coordinates)：
    每个图形项（例如 PlotItem, ScatterPlotItem, ImageItem 等）都有自己的本地坐标系统。对于大多数图形项来说，原点 (0, 0) 通常位于项的左下角，y 轴向上增长。

场景坐标 (Scene Coordinates)：
    场景坐标是整个图形布局的全局坐标系统。图形布局包含一个或多个 ViewBox 和其他项。场景坐标的原点 (0, 0) 通常位于图形布局的左上角。当你在图形布局中拖动物品时，它们的位置就是相对于场景坐标的。

为了更好地理解这些坐标系统之间的关系，这里有一些关键的转换方法：

mapToScene()：将项目本地坐标转换为场景坐标。
mapFromScene()：将场景坐标转换为项目本地坐标。
mapToView()：将项目本地坐标转换为视图坐标。
mapFromView()：将视图坐标转换为项目本地坐标。

ViewBox 类似地提供了转换方法，例如 mapSceneToView() 和 mapViewToScene()，用于在场景坐标和视图坐标之间进行转换。

使用了 view.mapFromScene(pos) 来将场景坐标转换为视图坐标。这是因为我们需要知道在视图中的确切位置，以便正确地放置 TextItem。

了解这些坐标系统及其转换对于编写能够正确响应用户交互的图形应用程序是非常重要的。如果你需要在不同的坐标系统之间进行更复杂的转换，确保考虑到 ViewBox 的当前变换（如缩放和平移）。

核心组件

QGraphicsObject

QGraphicsObject 是 Qt 中的一个类，它是所有图形项的基础类。QGraphicsObject 是 QObject 的子类，同时也是一个抽象基类，它为 QGraphicsItem 添加了信号和槽的支持。这使得你可以创建自定义的图形项，这些图形项可以与其他 Qt 对象交互，发送信号以及接收来自其他对象的信号。
QGraphicsObject 的重要方法:

• boundingRect：返回一个 QRectF 对象，表示项的边界框。这是必须实现的，因为 QGraphicsScene 使用此方法来确定项是否与其它项重叠或被鼠标点击。
• paint：此方法负责实际绘制项。它接受一个 QPainter 对象作为参数，用于执行绘图操作。
• shape：可选实现，用于定义项的形状。默认情况下，形状是由 boundingRect 决定的。
• contains：判断一个点是否在图形项内。
• type：返回一个整数标识符，用来区分不同的图形项类型。

QGraphicsObject 是一个抽象基类，主要用于为 QGraphicsItem 提供信号和槽机制的支持。这意味着你可以创建自定义的图形项，并且这些项可以和其他的 Qt 对象进行信号和槽的连接。QGraphicsObject 本身并不知道如何绘制自己；你需要继承 QGraphicsObject 并重写 paint() 和 boundingRect() 方法来实现具体的图形项。

QGraphicsWidget

QGraphicsWidget是一个用于创建可绘制的自定义图形控件的基类。它继承自 QGraphicsObject，并且允许你创建可绘制的自定义图形小部件，这些小部件可以放置在 QGraphicsScene 中，并与其他图形元素一起参与布局和交互。

QGraphicsWidget 是一个特殊的 QGraphicsObject，它用于创建可绘制的用户界面组件，如按钮、标签等。QGraphicsWidget 实现了基本的小部件接口，类似于 QWidget，但它是在 QGraphicsScene 中绘制的。
特点：

小部件接口：QGraphicsWidget 实现了类似于 QWidget 的布局和样式系统。
自动绘制：不需要重写 paint() 方法，除非你想自定义其外观。
布局管理：支持使用 QGraphicsLayout 进行布局管理。
样式表支持：可以使用 Qt 样式表来设置外观。

使用场景：

QGraphicsObject：当你需要创建一个自定义的图形项，并且这个项不是传统意义上的 UI 小部件时，应该选择 QGraphicsObject。例如，你可能想创建一个代表地图上的点或者一个简单的几何图形。
QGraphicsWidget：当你需要在 QGraphicsScene 中创建一个具有复杂 UI 行为的项时，可以选择 QGraphicsWidget。例如，一个带有文本标签的按钮或者一个复杂的控件。

QGraphicsScene

QGraphicsScene 是一个容器，用于保存所有的图形项。它是图形项的集合，负责管理图形项的绘制、事件传递以及动画等。

QGraphicsView

QGraphicsView 是一个窗口小部件，它显示 QGraphicsScene 中的内容。你可以通过 QGraphicsView 控制视口的缩放、平移和旋转。

QGraphicsItem

QGraphicsItem 是 QGraphicsScene 中所有图形项的基类。每个图形项都可以有自己的形状、位置、变换以及事件处理机制。

自定义图形组件

import sys
from PySide6.QtWidgets import QApplication, QGraphicsScene, QGraphicsView
from PySide6.QtCore import QRectF, Qt
from PySide6.QtGui import QPainter, QBrush, QColor

class CustomGraphicsObject(QGraphicsObject):
    def __init__(self, parent=None):
        super().__init__(parent)
        self.setFlag(QGraphicsItem.ItemIsMovable)  # 允许移动
        self.setFlag(QGraphicsItem.ItemIsSelectable)  # 可选中

    def boundingRect(self):
        """ 返回项目的边界矩形 """
        return QRectF(0, 0, 100, 100)

    def paint(self, painter, option, widget=None):
        """ 绘制项目 """
        painter.setBrush(QBrush(Qt.red))
        painter.drawEllipse(self.boundingRect())

if __name__ == '__main__':
    app = QApplication(sys.argv)
    
    scene = QGraphicsScene()
    view = QGraphicsView(scene)
    view.show()

    item = CustomGraphicsObject()
    scene.addItem(item)
    item.setPos(100, 100)  # 设置初始位置
    
    sys.exit(app.exec())

示例

以下是一个简单的例子，演示如何使用 QGraphicsView 框架来创建一个基本的应用程序：

import sys
from PySide6.QtWidgets import QApplication, QGraphicsView, QGraphicsScene, QGraphicsRectItem
from PySide6.QtCore import QRectF

if __name__ == '__main__':
    # 创建一个应用程序实例
    app = QApplication(sys.argv)

    # 创建一个 QGraphicsScene 实例
    scene = QGraphicsScene()

    # 设置场景的范围
    scene.setSceneRect(-100, -100, 200, 200)

    # 创建一个矩形图形项
    rect = QGraphicsRectItem(-50, -50, 100, 100)  # x, y, width, height
    rect.setBrush(Qt.red)  # 设置填充色为红色

    # 将矩形添加到场景中
    scene.addItem(rect)

    # 创建一个 QGraphicsView 实例
    view = QGraphicsView(scene)

    # 显示视图
    view.show()

    # 执行应用程序的事件循环
    sys.exit(app.exec())

PyQtGraph 常用类和组件

Plot

Plot:（表现两个变量关系的）图表；<美>图表，地图；<美>底层平面图

GraphicsObject

GraphicsObject 类是 pyqtgraph 提供的一个基础类，它继承自PySide6中的QtWidgets.QGraphicsObject，并且增加了对 pyqtgraph 特定功能的支持。GraphicsObject 主要用来创建自定义的图形元素，这些元素可以被添加到 GraphicsLayout 或者 PlotItem 中，并且能够与 ViewBox 一起工作。

GraphicsObject 是 pyqtgraph 中用于创建自定义图形的重要组件。它提供了一个基础框架，你可以在此基础上扩展出各种复杂和美观的图形元素，并且能够方便地与 ViewBox 和其他 pyqtgraph 组件集成。

GraphicsObject 的主要用途:

自定义绘图：
    使用 GraphicsObject，你可以创建自己的绘图逻辑，覆盖 paint 方法来自定义绘图过程。
    你还可以覆盖 boundingRect 方法来指定图形的边界矩形，这对于优化图形的绘制非常重要。

响应图形事件：
    你可以重写 GraphicsObject 的事件处理方法，比如 mouseClickEvent、mouseDragEvent 等，这样就可以实现图形的交互功能。
    通过这种方式，你可以使你的图形对象响应用户的点击、拖拽等操作。

图形属性管理：
    GraphicsObject 允许你管理图形的属性，例如颜色、透明度等。
    你可以利用这些属性来改变图形的外观。

动画效果：
    GraphicsObject 支持动画，可以通过 prepareGeometryChange 和 update 方法来通知图形需要重新布局或绘制，从而实现平滑的动画效果。

下面是一个简单的例子，展示了如何使用 GraphicsObject 创建一个自定义图形对象，该对象将在点击时改变颜色。

import pyqtgraph as pg
from pyqtgraph.Qt import QtGui, QtCore

class CustomGraphicObject(pg.GraphicsObject):
    def __init__(self):
        pg.GraphicsObject.__init__(self)
        self.pen = pg.mkPen(255, 0, 0)
        self.brush = pg.mkBrush(255, 0, 0, 100)

    def paint(self, p, *args):
        p.setPen(self.pen)
        p.setBrush(self.brush)
        p.drawEllipse(-50, -50, 100, 100)  # 绘制一个椭圆

    def boundingRect(self):
        # 返回图形的边界矩形
        return QtCore.QRectF(-50, -50, 100, 100)

    def mouseClickEvent(self, ev):
        # 鼠标点击事件
        if self.brush.color().red() == 255:
            self.brush = pg.mkBrush(0, 0, 255, 100)
            self.pen = pg.mkPen(0, 0, 255)
        else:
            self.brush = pg.mkBrush(255, 0, 0, 100)
            self.pen = pg.mkPen(255, 0, 0)
        self.update()  # 更新图形

app = QtGui.QApplication([])
view = pg.GraphicsLayoutWidget()
view.setWindowTitle('Custom Graphic Object Example')
view.setBackground('w')

g = view.addPlot()
obj = CustomGraphicObject()
g.addItem(obj)

view.show()
app.exec_()

GraphicsWidget

继承自QtWidgets.QGraphicsWidget。

GraphicsLayout

GraphicsLayout 是一个非常有用的类，用于组织和排列多个图形元素（如 PlotItem、ImageItem、GraphicsObject 等）。GraphicsLayout 可以帮助你在图形界面中创建复杂的布局结构，如网格布局、嵌套布局等。此外，GraphicsLayout 还能自动管理各个图形元素的位置和大小，确保它们正确地显示在一起。
GraphicsLayout 的基本用法：

创建 GraphicsLayoutWidget：
GraphicsLayoutWidget 是 GraphicsLayout 的容器，通常用于创建包含多个图形项的窗口。

添加图形元素：
你可以向 GraphicsLayout 添加多个 PlotItem 或者其他的图形元素。
你可以控制这些元素的相对位置，如创建一个 2x2 的网格布局。

自定义布局：
你可以调整 GraphicsLayout 中元素的位置和大小，以及添加标签和其他控件。

下面是一个简单的例子，展示如何使用 GraphicsLayoutWidget 创建一个包含多个 PlotItem 的布局：

import pyqtgraph as pg
from pyqtgraph.Qt import QtWidgets

# 创建一个主窗口
app = QtWidgets.QApplication([])

# 创建一个 GraphicsLayoutWidget
win = pg.GraphicsLayoutWidget()
win.setWindowTitle('PyQtGraph Graphics Layout Example')

# 添加 PlotItem 到第一行
p1 = win.addPlot(title="Plot 1")
p1.plot([1, 2, 3, 4, 5], [2, 3, 6, 9, 10])

# 在同一行添加另一个 PlotItem
p2 = win.addPlot(title="Plot 2")
win.nextRow()  # 移动到下一行

# 在第二行添加 PlotItem
p3 = win.addPlot(title="Plot 3")
p3.plot([1, 2, 3, 4, 5], [2, 3, 6, 9, 10])

# 展示窗口
win.show()
win.resize(800, 600)

# 启动事件循环
app.exec_()

ViewBox

ViewBox 是一个非常重要的组件，它主要用于控制图形的缩放和平移，提供了一种灵活的方式来展示和操作数据。ViewBox 允许你创建自定义的图形界面，并且可以与其他 pyqtgraph 组件（如 PlotItem）结合使用。
ViewBox 的主要用途:

缩放和平移：
    ViewBox 可以让你控制图形的缩放和平移，这对于查看不同比例尺下的数据非常有用。
    你可以手动调整 ViewBox 的范围，也可以通过交互方式（例如使用鼠标滚轮缩放和平移）。

自定义坐标系：
    ViewBox 允许你创建自定义的坐标系，这对于需要特殊坐标轴的应用非常有用。
    你可以单独控制每个轴的行为，例如设置不同的缩放比例、逆序显示等。

多个视图：
    你可以创建多个 ViewBox，并将它们链接在一起，使得一个 ViewBox 的操作会影响到另一个 ViewBox 的显示。
    这对于实现同步缩放和平移非常有用。

图形的独立性：
    ViewBox 可以独立于 PlotItem 存在，这意味着你可以在同一个 GraphicsLayout 中拥有多个独立的视图。

自定义图形：
    你可以使用 ViewBox 来绘制自定义的图形，而不局限于 PlotItem 提供的基本图形类型。
    例如，你可以使用 ViewBox 来绘制路径、图形、图像等。

示例：

import pyqtgraph as pg
from pyqtgraph.Qt import QtCore, QtGui
import sys

class GraphicsView(pg.GraphicsLayoutWidget):
    def __init__(self, parent=None):
        super().__init__(parent)
        self.rect_item = None
        self.last_pos = None
        self.view = self.addViewBox(row=0, col=0, enableMenu=False)
        self.view.setAspectLocked(True)
        self.scene().sigMouseMoved.connect(self.mouse_moved)

    def mouse_moved(self, pos):
        # 将场景坐标转换为视图坐标
        view_pos = self.view.mapFromScene(pos)
        self.update_rect(view_pos)

    def update_rect(self, pos):
        if self.rect_item is not None:
            self.removeItem(self.rect_item)
            self.rect_item = None

        if self.last_pos is not None:
            rect = QtCore.QRectF(self.last_pos, pos).normalized()
            self.rect_item = pg.QtGui.QGraphicsRectItem(rect)
            self.rect_item.setPen(pg.mkPen('r', width=2))
            self.rect_item.setBrush(pg.mkBrush((255, 0, 0, 100)))
            self.view.addItem(self.rect_item)

        self.last_pos = pos

if __name__ == '__main__':
    app = QtGui.QApplication(sys.argv)
    view = GraphicsView()
    view.show()
    sys.exit(app.exec())

该示例演示如何在鼠标移动时绘制新的矩形框并同时擦除原来的矩形框。

在PySide6中绘制基本图形

在PySide6中使用QtGui.QPainter来绘制图形是一种常见的方法。QPainter是一个绘图设备，它可以用来绘制各种基本图形元素，如点、线、矩形、椭圆以及更复杂的形状。下面我将为你提供一个简单的例子，展示如何使用QPainter在一个QWidget上绘制一些基本图形。
在PySide中绘制基本图形

import sys
from PySide6.QtWidgets import QApplication, QWidget
from PySide6.QtGui import QPainter, QColor, QPen, QFont
from PySide6.QtCore import Qt

class DrawingWidget(QWidget):
    def __init__(self):
        super().__init__()
        self.init_ui()

    def init_ui(self):
        self.setGeometry(300, 300, 350, 300)
        self.setWindowTitle('Simple Drawing')

    def paintEvent(self, event):
        painter = QPainter()
        painter.begin(self)
        self.draw_shapes(painter)
        painter.end()

    def draw_shapes(self, painter):
        # 设置画笔颜色和宽度
        pen = QPen(Qt.blue, 2, Qt.SolidLine)
        painter.setPen(pen)

        # 绘制一个矩形
        painter.drawRect(20, 20, 100, 100)

        # 设置画笔颜色和宽度
        pen.setColor(Qt.red)
        painter.setPen(pen)

        # 绘制一个椭圆
        painter.drawEllipse(150, 20, 100, 100)

        # 设置字体
        font = QFont('Serif', 10)
        painter.setFont(font)

        # 设置画笔颜色
        pen.setColor(Qt.black)
        painter.setPen(pen)

        # 在指定位置写入文本
        painter.drawText(20, 150, "Hello, QPainter!")

if __name__ == '__main__':
    app = QApplication(sys.argv)

    drawing_widget = DrawingWidget()
    drawing_widget.show()

    sys.exit(app.exec())

import sys
from PySide6.QtWidgets import QApplication, QWidget
from PySide6.QtGui import QPainter, QPen, QBrush
from PySide6.QtCore import Qt

class DrawingWidget(QWidget):
    def __init__(self):
        super().__init__()
        self.setWindowTitle('Drawing Lines and Rectangles')
        self.setGeometry(100, 100, 400, 300)

    def paintEvent(self, event):
        painter = QPainter(self)
        painter.setRenderHint(QPainter.Antialiasing)

        # 绘制直线
        pen = QPen(Qt.red, 2, Qt.SolidLine)
        painter.setPen(pen)
        painter.drawLine(50, 50, 350, 50)

        # 绘制矩形
        pen = QPen(Qt.blue, 2, Qt.SolidLine)
        painter.setPen(pen)
        brush = QBrush(Qt.green, Qt.SolidPattern)
        painter.setBrush(brush)
        painter.drawRect(50, 100, 300, 100)

if __name__ == '__main__':
    app = QApplication(sys.argv)
    window = DrawingWidget()
    window.show()
    sys.exit(app.exec_())