class QPixmap#

QPixmap 类是一个离屏图像表示，可以用作绘图设备。更多…

Inheritance diagram of PySide6.QtGui.QPixmap

继承自： QBitmap

概要#

方法#

静态函数#

注意

这份文档可能包含自动从C++翻译成Python的代码片段。我们始终欢迎对片段翻译的贡献。如果您发现翻译存在问题，也可以通过在https:/bugreports.qt.io/projects/PYSIDE上创建一个工单来告诉我们。

详细描述#

Qt提供了四个处理图像数据的类：`QImage`，`QPixmap`，`QBitmap`和`QPicture`。`QImage`是为输入/输出设计并优化的，同时提供直接像素访问和操作；而`QPixmap`是为在屏幕上显示图像而设计和优化的。`QBitmap`仅是一个方便类，继承自`QPixmap`，确保深度为1。《isQBitmap()`函数如果`QPixmap`对象确实是一个位图则返回`true`，否则返回`false`。最后，`QPicture`类是一个绘制设备，用于记录和回放`QPainter`命令。

`QPixmap`可以通过使用`QLabel`或`QAbstractButton`的子类（如`QPushButton`和`QToolButton`）轻松显示在屏幕上。`QLabel`具有图片属性，而`QAbstractButton`则具有图标属性。

`QPixmap`对象可以通过值传递，因为`QPixmap`类使用隐式数据共享。更多详情请参阅隐式数据共享文档。《a class="reference internal" href="#PySide6.QtGui.QPixmap" title="PySide6.QtGui.QPixmap">QPixmap`对象还可以进行流处理。

请注意，位图中的像素数据是内部的，由底层窗口系统管理。因为 QPixmap 是一个 QPaintDevice 子类，所以可以使用 QPainter 类在像素上直接绘制。像素只能通过 QPainter 函数或通过将 QPixmap 转换为 QImage 来访问。但是，有一个 fill() 函数可用于用给定颜色初始化整个像素。

提供了在 QImage 和 QPixmap 之间转换的函数。通常，QImage 类用于加载图像文件，可选地对图像数据进行操作，然后将 QImage 对象转换为 QPixmap 以在屏幕上显示。或者，如果不需要进行操作，可以将图像文件直接加载到 QPixmap 中。

QPixmap 提供了一组函数，可以用来获取有关像素的多种信息。此外，还有一些函数可以用于对像素进行变换。

读取和编写图像文件#

QPixmap 提供了多种读取图像文件的方法：可以在构建 QPixmap 对象时加载文件，或稍后使用 load() 或 loadFromData() 函数进行加载。当加载图像时，文件名可以指向磁盘上的实际文件，也可以指向应用程序的嵌入式资源之一。有关如何在应用程序的可执行文件中嵌入图像和其他资源文件的详细信息，请参阅 Qt 资源系统概述。

通过调用save()函数来保存一个QPixmap对象。

支持的文件格式列表可以通过supportedImageFormats()和supportedImageFormats()函数获得。新的文件格式可以通过插件添加。默认情况下，Qt支持以下格式

格式

描述

Qt支持

BMP

Windows位图

读写

GIF

图形交换格式（可选）

只读

JPG

联合图像专家小组

读写

JPEG

联合图像专家小组

读写

PNG

可移植网络图形

读写

PBM

可移植位图

只读

PGM

可移植灰度图

只读

PPM

可移植像素映射

读写

XBM

X11位图

读写

XPM

X11像素映射

读写

像素映射信息#

QPixmap提供了一系列函数，可用于获取像素映射的各种信息

可用函数

几何形状

size()，width()和height()函数提供有关像素映射大小的信息。函数rect()返回图像的包含矩形。

透明通道组件

如果像素映射具有尊重透明通道的格式，则函数hasAlphaChannel()返回true，否则返回false。函数hasAlpha()，setMask()和mask()是遗留函数，不应使用。它们的执行速度可能会非常慢。

函数createHeuristicMask()为该像素映射创建并返回一个1位的启发式遮罩（即一个QBitmap）。它通过从一个角落选择一个颜色，然后从这个颜色的所有边缘开始移除像素来实现。函数createMaskFromColor()根据给定的颜色创建并返回一个遮罩（即一个QBitmap）。

底层信息

函数depth()返回像素映射的深度。函数defaultDepth()返回默认深度，即在给定屏幕上应用程序使用的深度。

函数 cacheKey() 返回一个唯一标识 QPixmap 对象内容的数字。

位图转换#

可以通过使用 toImage() 函数将 QPixmap 对象转换为 QImage。 类似地，可以使用 fromImage() 函数将 QImage 转换为 QPixmap。 如果这个操作过于昂贵，可以使用 fromImage() 代替。

要将在 HICON 之间进行转换的 QPixmap，可以使用 QtWinExtras 函数 QtWin::toHICON() 和 QtWin::fromHICON() 分别转换。

位图变换#

QPixmap 支持创建新的 QPixmap 对象以表示原始图像的变换版本的功能

scaled()、scaledToWidth() 和 scaledToHeight() 函数返回位图的缩放副本，而 copy() 函数创建一个 QPixmap，它是原始图像的纯复制。

transformed() 函数返回一个经过给定变换矩阵和变换方式的变换后的位图副本。内部，变换矩阵调整为补偿不可取的平移，即 transformed() 返回包含原始位图中所有变换点的新最小位图。静态函数 trueMatrix() 返回用于变换位图的实际矩阵。

__init__(image)#
参数：

image – QImage

__init__()

构造一个空的位图。

__init__(w, h)
参数：

  • w – int

  • h – int

根据指定的宽度和高度构造一个位图。如果宽度或高度为零，将构造一个空位图。

警告

这将创建一个未初始化数据的 QPixmap。在使用 QPainter 绘制之前，请调用 fill() 以填充位图到合适的颜色。

参阅相关内容

isNull()

__init__(xpm)
参数：

xpm – char[]

__init__(arg__1)
参数：

arg__1 – QSize

这是一个重载函数。

根据指定的幅面大小构造位图。

警告

这将创建一个未初始化数据的 QPixmap。在使用 QPainter 绘制之前，请调用 fill() 以填充位图到合适的颜色。

__init__(arg__1)
参数：

arg__1 – QPixmap

构造一个与给定位图相同的副本。

__init__(fileName[, format=None[, flags=Qt.AutoColor]])
参数：

从给定的 fileName 文件中构建 pixmap。如果文件不存在或格式未知，则 pixmap 为空 pixmap。

加载器尝试使用指定的 format 读取 pixmap。如果没有指定 format（默认情况），则加载器将探测文件头以猜测文件格式。

文件名可以指向磁盘上的实际文件，也可以指向应用程序的嵌入式资源之一。有关如何在应用程序的可执行文件中嵌入图像和其他资源文件的详细信息，请参阅“资源系统概述”。

如果需要修改图像以匹配较低的分辨率结果（例如，从 32 位转换为 8 位），请使用 flags 控制转换。

fileName、format 和 flags 参数被传递给 load()。这意味着 fileName 中的数据不是编译到二进制文件中的。如果 fileName 包含相对路径（例如，仅文件名），则相关文件必须在运行时工作目录中找到。

参阅相关内容

读取和写入图像文件

cacheKey()#
返回类型：

int

返回一个标识这个 QPixmap 的数字。不同的 QPixmap 对象只有当它们引用相同的内容时，才具有相同的缓存键。

当 pixmap 被修改时，cacheKey() 将会改变。

convertFromImage(img[, flags=Qt.AutoColor])#
参数：
返回类型：

bool

使用指定的 flags 控制转换，用给定的 image 替换此 pixmap 的数据。flags 参数是 Qt::ImageConversionFlags 的位或。将 0 传递给 flags 将设置所有默认选项。如果结果是此 pixmap 不是 null，则返回 true。

注意：该功能曾是 Qt 4.6 及之前版本中 Qt 3 的支持的一部分。在 4.7 中升级为官方 API 状态，以支持更新 pixmap 的图像而不需要创建新的 QPixmap，正如 fromImage() 所做的那样。

copy([rect=QRect()])#
参数：

rect – QRect

返回类型：

QPixmap

返回给定 rectangle 指定的位图子集的深度复制。有关深度复制的更多信息，请参阅隐式数据共享文档。

如果给定的 rectangle 是空的，则复制整个图像。

参阅相关内容

operator=() QPixmap() Pixmap Transformations

copy(x, y, width, height)
参数：

  • x – int

  • y – int

  • width – int

  • height – int

返回类型：

QPixmap

这是一个重载函数。

返回由矩形 QRect(x, y, width, height) 指定的位图子集的深度复制。

createHeuristicMask([clipTight=true])#
参数：

clipTight – bool

返回类型：

QBitmap

警告

本节包含从 C++ 自动转换为 Python 的代码片段，可能会存在错误。

为该位图创建并返回一个启发式遮罩。

该函数通过从一个角落中选择一种颜色，然后从所有边开始剔除该颜色的像素来实现。如果 clipTight 为 true（默认值），则遮罩正好足够覆盖像素；否则，遮罩大于数据像素。

遮罩可能不是完美的，但它应该是合理的，因此你可以进行以下操作

myPixmap = QPixmap()
myPixmap.setMask(myPixmap.createHeuristicMask())

此函数执行较慢，因为它涉及转换为/从 QImage ，以及非平凡的计算。

createMaskFromColor(maskColor[, mode=Qt.MaskInColor])#
参数：
返回类型：

QBitmap

根据给定的 maskColor 为该位图创建并返回一个遮罩。如果 mode 是 Qt::MaskInColor，则所有匹配 maskColor 的像素将是透明的。如果 mode 是 Qt::MaskOutColor，则所有匹配 maskColor 的像素将是不可见的。

此函数执行较慢，因为它涉及转换为/从 QImage 。

静态 defaultDepth()#
返回类型：

int

deviceIndependentSize()#
返回类型：

QSizeF

返回位图在设备独立像素中的大小。

此值应在使用位图大小时用于用户界面大小计算。

返回值等效于位图的 size() / 位图的 devicePixelRatio()。

fill([fillColor=Qt.white])#
参数：

fillColor – QColor

使用指定的颜色填充位图。

如果在绘制位图时调用此函数，则其效果是未定义的。

参阅相关内容

Pixmap 变换

静态 fromImage(image[, flags=Qt.AutoColor])#
参数：
返回类型：

QPixmap

使用指定的 flags 将给定的 image 转换为位图，以控制转换。 flags 参数是 Qt::ImageConversionFlags 的按位或。传递 0 到 flags 将设置所有默认选项。

对于单色和 8 位图像，图像会首先被转换为 32 位位图，然后再填充颜色表中的颜色。如果这个操作太昂贵，可以使用 fromImage() 代替。

静态 fromImageInPlace(image[, flags=Qt.AutoColor])#
参数：
返回类型：

QPixmap

静态 fromImageReader(imageReader[, flags=Qt.AutoColor])#
参数：
返回类型：

QPixmap

从 imageReader 直接读取的图像中创建一个 QPixmap。参数 flags 是 Qt::ImageConversionFlags 的按位或操作。如果为 flags 传递 0，则设置所有默认选项。

在某些系统上，将图像直接读取到 QPixmap 中可能比将其转换为 QPixmap 来说要少占用内存。

参阅相关内容

fromImage() toImage() Pixmap Conversion

hasAlpha()#
返回类型：

bool

hasAlphaChannel()#
返回类型：

bool

isNull()#
返回类型：

bool

如果这是空位图，则返回 true；否则返回 false。

空位图的宽度为零，高度为零，且没有内容。您无法在空位图中绘制。

isQBitmap()#
返回类型：

bool

如果这是 QBitmap，则返回 true；否则返回 false。

load(fileName[, format=None[, flags=Qt.AutoColor]])#
参数：
返回类型：

bool

从具有给定 fileName 的文件加载位图。如果成功加载位图，则返回 true；否则破坏位图并返回 false。

加载器尝试使用指定的 format 读取 pixmap。如果没有指定 format（默认情况），则加载器将探测文件头以猜测文件格式。

文件名可以是指硬盘中实际文件或应用程序嵌入的资源之一。请参阅资源系统概述中的信息，了解如何将位图和其他资源文件嵌入到应用程序的可执行文件中。

如果需要修改数据以适合较低分辨率的输出（例如，从 32 位转换为 8 位），请使用 flags 来控制转换。

请注意，当从主线程文件中加载时，QPixmap会自动添加到QPixmapCache中；使用的键是内部的，无法获取。

参阅相关内容

loadFromData() 读取和写入图像文件

loadFromData(data[, format=None[, flags=Qt.AutoColor]])#
参数：
返回类型：

bool

这是一个重载函数。

使用指定的format和转换flags从二进制data中加载位图。

loadFromData(buf[, format=None[, flags=Qt.AutoColor]])
参数：
返回类型：

bool

从给定的二进制data的前len个字节中加载位图。如果成功加载位图，则返回true；否则使位图无效并返回false。

加载器尝试使用指定的 format 读取 pixmap。如果没有指定 format（默认情况），则加载器将探测文件头以猜测文件格式。

如果需要修改数据以适合较低分辨率的输出（例如，从 32 位转换为 8 位），请使用 flags 来控制转换。

参阅相关内容

load() 读取和写入图像文件

此方法必须与QPixmap对象一起使用，而不是类

# Wrong
pixmap = QPixmap.loadFromData(...)

# Right
pixmap = QPixmap().loadFromData(...)
mask()#
返回类型：

QBitmap

从位图的alpha通道中提取位图掩码。

警告

这可能是一个昂贵的操作。位图掩码是动态从像素数据中提取的。

参阅相关内容

setMask() 位图信息

rect()#
返回类型：

QRect

返回位图的包围矩形。

参阅相关内容

位图信息

save(device[, format=None[, quality=-1]])#
参数：

  • device – QIODevice

  • format – str

  • quality – int

返回类型：

bool

警告

本节包含从 C++ 自动转换为 Python 的代码片段，可能会存在错误。

这是一个重载函数。

此函数使用指定的图像文件格式和画质因子将 QPixmap 写入给定的 device。这可以用于将位图直接保存到 QByteArray 中。

pixmap = QPixmap()
bytes = QByteArray()
buffer = QBuffer(bytes)
buffer.open(QIODevice.WriteOnly)
pixmap.save(buffer, "PNG") # writes pixmap into bytes in PNG format
save(fileName[, format=None[, quality=-1]])
参数：

  • fileName – str

  • format – str

  • quality – int

返回类型：

bool

使用指定的图像文件格式和画质因子将位图保存到具有给定 fileName 的文件中。如果成功返回 true；否则返回 false。

画质因子必须在 [0,100] 范围内或 -1。指定 0 获取小压缩文件，100 获取大未压缩文件，-1 使用默认设置。

如果 format 为 None，则从 fileName 的后缀中选择图像格式。

参阅相关内容

读取和写入图像文件

scaled(s[, aspectMode=Qt.IgnoreAspectRatio[, mode=Qt.FastTransformation]])#
参数：
返回类型：

QPixmap

使用 aspectRatioMode 和 transformMode 指定的宽高比和转换模式缩放位图到给定的 size。

../../_images/qimage-scaling1.png

  • 如果 aspectRatioMode 是 Qt::IgnoreAspectRatio，则位图缩放到 size。

  • 如果 aspectRatioMode 是 Qt::KeepAspectRatio，则位图缩放到尽可能大的矩形中，同时在 size 内保持宽高比。

  • 如果 aspectRatioMode 是 Qt::KeepAspectRatioByExpanding，则位图缩放到尽可能小的矩形中，同时在 size 外部保持宽高比。

如果给定的 size 为空，此函数返回一个空位图。

在某些情况下，将Pixmap绘制到设置了Scale的Painter中可能更有益，而不是对Pixmap进行缩放。当Painter基于OpenGL或缩放因子迅速变化时，就是这种情况。

参阅相关内容

isNull() Pixmap Transformations

scaled(w, h[, aspectMode=Qt.IgnoreAspectRatio[, mode=Qt.FastTransformation]])
参数：
返回类型：

QPixmap

这是一个重载函数。

返回一个根据指定的Aspect Ratio Mode和Transform Mode，按给定宽度和高度缩放后的Pixmap副本。

如果宽度和高度为零或负值，则该函数返回一个空Pixmap。

scaledToHeight(h[, mode=Qt.FastTransformation])#
参数：
返回类型：

QPixmap

返回图像的缩放副本。返回的图像根据指定的转换模式缩放至给定的高度。Pixmap的宽度自动计算，以便保持Pixmap的纵横比。

如果高度为0或负值，则返回一个空Pixmap。

参阅相关内容

isNull() Pixmap Transformations

scaledToWidth(w[, mode=Qt.FastTransformation])#
参数：
返回类型：

QPixmap

返回图像的缩放副本。返回的图像根据指定的转换模式缩放至给定的宽度。Pixmap的高度自动计算，以便保持Pixmap的纵横比。

如果宽度为0或负值，则返回一个空Pixmap。

参阅相关内容

isNull() Pixmap Transformations

scroll(dx, dy, rect[, exposed=None])#
参数：

警告

本节包含从 C++ 自动转换为 Python 的代码片段，可能会存在错误。

将此位图的区域rect沿（dx，dy）方向进行滚动。曝光区域保持不变。您可以可选地传递一个指向空的QRegion的指针，以获取由滚动操作带来的曝光区域。

pixmap = QPixmap("background.png")
exposed = QRegion()
pixmap.scroll(10, 10, pixmap.rect(), exposed)

在位图上有活动的画家时，无法进行滚动。

参阅相关内容

scroll()

scroll(dx, dy, x, y, width, height[, exposed=None])
参数：

  • dx – int

  • dy – int

  • x – int

  • y – int

  • width – int

  • height – int

  • exposed – QRegion

该便利函数等同于调用QPixmap::scroll(dx，dy，QRect(x，y，width，height)，exposed)。

参阅相关内容

scroll()

setDevicePixelRatio(scaleFactor)#
参数：

scaleFactor – float

设置位图的设备像素比。这是图像像素与设备无关像素之间的比率。

默认的scaleFactor为1.0。将其设置为其他值有两个效果

在位图上打开的QPainters将会缩放。例如，在200x200的图像上以2.0的比率绘制，将有效绘制边界为100x100。

基于位图大小计算布局几何的Qt代码路径将考虑比率：QSize布局大小 = pixmap.size / pixmap.devicePixelRatio。这会导致位图以高DPI位图的形式显示而不是大位图（参见绘制高分辨率版本的位图和图像）。

参阅相关内容

devicePixelRatio deviceIndependentSize

setMask(arg__1)#
参数：

arg__1 – QBitmap

设置掩码位图。

此函数将mask与位图的alpha通道合并。掩码中的像素值为1表示位图的像素保持不变；值为0表示像素透明。掩码必须与该位图具有相同的大小。

设置一个空面具将重置面具，将之前透明的像素设置为黑色。当位图正在绘制时，此函数的效果是未定义的。

警告

这可能是一个昂贵的操作。

参阅相关内容

mask() Pixmap Transformations QBitmap

size()#
返回类型：

QSize

返回位图的尺寸。

参阅相关内容

width() height() Pixmap Information

swap(other)#
参数：

other – QPixmap

将位图 other 与此位图交换。这个操作非常快且永远不会失败。

toImage()#
返回类型：

QImage

将位图转换为 QImage . 如果转换失败，则返回一个空图像。

如果位图的深度为1位，则返回的图像也将是1位。具有更多位的图像将返回一个与底层系统紧密相关的格式。通常，带有alpha的位图将是 Format_ARGB32_Premultiplied，而没有alpha的位图将是 Format_RGB32 或 Format_RGB16。

请注意，目前，单色图像上的alpha掩码会被忽略。

参阅相关内容

fromImage() Image Formats

transformed(arg__1[, mode=Qt.FastTransformation])#
参数：
返回类型：

QPixmap

static trueMatrix(m, w, h)#
参数：
返回类型：

QTransform

返回实际用于将给定 width、height 和 matrix 的位图进行变换的矩阵。

当使用 transformed() 函数进行位图变换时，变换矩阵会内部调整以补偿不希望的平移，即 transformed() 返回包含原始位图中所有变换点的最小位图。此函数返回修改后的矩阵，该矩阵能够正确地将原始位图中的点映射到新的位图中。

参阅相关内容

Pixmap 变换