PySide6.QtGui.QPixmap¶

class QPixmap¶

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

继承者： QBitmap

概要¶

方法¶

def __init__()
def cacheKey()
def convertFromImage()
def copy()
def createHeuristicMask()
def createMaskFromColor()
def deviceIndependentSize()
def fill()
def hasAlpha()
def hasAlphaChannel()
def isNull()
def isQBitmap()
def load()
def loadFromData()
def mask()
def rect()
def save()
def scaled()
def scaledToHeight()
def scaledToWidth()
def scroll()
def setDevicePixelRatio()
def setMask()
def size()
def swap()
def toImage()
def transformed()

注意

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

详细描述¶

Qt 提供了四个类来处理图像数据：QImage、QPixmap、QBitmap 和 QPicture。QImage 是为 I/O 和直接像素访问和操作而设计和优化的，而 QPixmap 是为在屏幕上显示图像而设计和优化的。QBitmap 只是一个继承自 QPixmap 的便利类，确保深度为 1。如果 QPixmap 对象真的是位图，isQBitmap() 函数返回 true，否则返回 false。最后，QPicture 类是一个记录和重放 QPainter 命令的绘图设备。

一个QPixmap可以很容易地使用QLabel或QAbstractButton的子类（如QPushButton和QToolButton）在屏幕上显示。QLabel有一个pixmap属性，而QAbstractButton有一个icon属性。

QPixmap 对象可以通过值传递，因为 QPixmap 类使用了隐式数据共享。更多信息，请参阅隐式数据共享文档。QPixmap 对象也可以被流式传输。

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

有一些函数可以在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 位图

读取/写入

格式	描述	Qt的支持
BMP	Windows 位图	读取/写入
GIF	图形交换格式（可选）	读取
JPG	联合图像专家组	读取/写入
JPEG	联合图像专家组	读/写
PNG	便携式网络图形	读取/写入
PBM	便携式位图	读取
PGM	便携式灰度图	读取
PPM	便携式像素图	读取/写入
XBM	X11位图	读取/写入
XPM	X11 位图	读取/写入

Pixmap 信息¶

QPixmap 提供了一系列函数，可用于获取有关位图的各种信息：

可用函数

几何

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

Alpha 组件

如果 pixmap 的格式尊重 alpha 通道，则 hasAlphaChannel() 返回 true，否则返回 false。hasAlpha()、setMask() 和 mask() 函数是遗留的，不应使用。它们可能非常慢。

createHeuristicMask() 函数创建并返回此 pixmap 的 1-bpp 启发式掩码（即 QBitmap）。它通过从其中一个角落选择一种颜色，然后从所有边缘开始去除该颜色的像素来工作。createMaskFromColor() 函数根据给定颜色创建并返回 pixmap 的掩码（即 QBitmap）。

低级信息

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

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

	可用函数
几何	`size()`、`width()` 和 `height()` 函数提供有关像素图大小的信息。`rect()` 函数返回图像的包围矩形。
Alpha 组件	如果 pixmap 的格式尊重 alpha 通道，则 hasAlphaChannel() 返回 `true`，否则返回 `false`。hasAlpha()、`setMask()` 和 `mask()` 函数是遗留的，不应使用。它们可能非常慢。 `createHeuristicMask()` 函数创建并返回此 pixmap 的 1-bpp 启发式掩码（即 `QBitmap`）。它通过从其中一个角落选择一种颜色，然后从所有边缘开始去除该颜色的像素来工作。`createMaskFromColor()` 函数根据给定颜色创建并返回 pixmap 的掩码（即 `QBitmap`）。
低级信息	`depth()` 函数返回像素图的深度。defaultDepth() 函数返回默认深度，即应用程序在给定屏幕上使用的深度。 `cacheKey()` 函数返回一个唯一标识 `QPixmap` 对象内容的数字。

Pixmap 转换¶

一个QPixmap对象可以使用toImage()函数转换为QImage。同样地，一个QImage可以使用fromImage()转换为QPixmap。如果这个操作太昂贵，你可以使用fromImage()代替。

要将QPixmap转换为HICON或从HICON转换回来，你可以分别使用toHICON()和fromHICON()函数（在将QPixmap转换为QImage之后，如上所述）。

Pixmap 变换¶

QPixmap 支持多种函数来创建一个新的位图，该位图是原始位图的转换版本：

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

transformed() 函数返回一个经过给定变换矩阵和变换模式变换后的 pixmap 副本：在内部，变换矩阵会被调整以补偿不需要的平移，即 transformed() 返回包含原始 pixmap 所有变换点的最小 pixmap。静态函数 trueMatrix() 返回用于变换 pixmap 的实际矩阵。

另请参阅

QBitmap QImage QImageReader QImageWriter

__init__()¶

构造一个空的像素图。

另请参阅

isNull()

__init__(image)

Parameters:: 图像 – QImage

__init__(pixmap)

Parameters:: pixmap – QPixmap

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

另请参阅

copy()

__init__(size)

Parameters:: 大小 – QSize

这是一个重载函数。

构造一个给定size的像素图。

警告

这将创建一个带有未初始化数据的QPixmap。在使用QPainter绘制之前，调用fill()以用适当的颜色填充像素图。

__init__(xpm)

Parameters:: xpm – char[]

__init__(w, h)

Parameters:

w – 整数
h – 整数

使用给定的width和height构造一个pixmap。如果width或height中的任何一个为零，则构造一个空的pixmap。

警告

这将创建一个带有未初始化数据的QPixmap。在使用QPainter绘制之前，调用fill()以用适当的颜色填充像素图。

另请参阅

isNull()

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

Parameters:

fileName – str
format – str
flags – ImageConversionFlag 的组合

从具有给定fileName的文件中构造一个pixmap。如果文件不存在或格式未知，pixmap将变为空pixmap。

加载器尝试使用指定的format读取像素图。如果未指定format（这是默认情况），加载器会探测文件的头部以猜测文件格式。

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

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

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

另请参阅

读取和写入图像文件

cacheKey()¶

Return type:: 整数

返回一个标识此QPixmap的数字。不同的QPixmap对象只有在引用相同内容时才能具有相同的缓存键。

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

convertFromImage(img[, flags=Qt.AutoColor])¶

Parameters:

img – QImage
flags – ImageConversionFlag 的组合

Return type:

布尔

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

另请参阅

fromImage()

copy([rect=QRect()])¶

Parameters:: rect – QRect
Return type:: QPixmap

返回由给定的rectangle指定的pixmap子集的深拷贝。有关深拷贝的更多信息，请参阅隐式数据共享文档。

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

另请参阅

operator=() QPixmap() Pixmap 变换

copy(x, y, width, height)

Parameters:

x – 整数
y – 整数
width – int
height – int

Return type:

QPixmap

这是一个重载函数。

返回由矩形QRect(x, y, width, height)指定的像素图子集的深拷贝。

createHeuristicMask([clipTight=true])¶

Parameters:: clipTight – 布尔值
Return type:: QBitmap

警告

本节包含从C++自动翻译到Python的代码片段，可能包含错误。

创建并返回此位图的启发式掩码。

该函数的工作原理是从一个角落选择一种颜色，然后从所有边缘开始，逐渐去除该颜色的像素。如果clipTight为true（默认值），则掩码刚好足够覆盖像素；否则，掩码会比数据像素大。

面具可能不完美，但应该是合理的，所以你可以做以下事情：

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

这个函数运行缓慢，因为它涉及到与QImage之间的转换，以及非平凡的计算。

另请参阅

createMaskFromColor()

createMaskFromColor(maskColor[, mode=Qt.MaskInColor])¶

Parameters:

maskColor – QColor
mode – MaskMode

Return type:

QBitmap

根据给定的maskColor创建并返回此像素图的掩码。如果mode是Qt::MaskInColor，所有与maskColor匹配的像素将是透明的。如果mode是Qt::MaskOutColor，所有与maskColor匹配的像素将是不透明的。

这个函数很慢，因为它涉及到与QImage之间的转换。

另请参阅

createHeuristicMask() createMaskFromColor()

static defaultDepth()¶

Return type:: 整数

deviceIndependentSize()¶

Return type:: QSizeF

返回与设备无关的像素中pixmap的大小。

在用户界面尺寸计算中使用像素图大小时，应使用此值。

返回值等同于 pixmap. size() / pixmap. devicePixelRatio() .

fill([fillColor=Qt.white])¶

Parameters:: fillColor – QColor

用给定的color填充像素图。

当在 pixmap 上进行绘制时，此函数的效果是未定义的。

另请参阅

Pixmap Transformations

static fromImage(image[, flags=Qt.AutoColor])¶

Parameters:

image – QImage
flags – ImageConversionFlag 的组合

Return type:

QPixmap

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

在单色和8位图像的情况下，图像首先被转换为32位像素图，然后用颜色表中的颜色填充。如果这个操作过于昂贵，你可以使用fromImage()来代替。

另请参阅

fromImageReader() toImage() Pixmap 转换

static fromImageInPlace(image[, flags=Qt.AutoColor])¶

Parameters:

image – QImage
flags – ImageConversionFlag 的组合

Return type:

QPixmap

static fromImageReader(imageReader[, flags=Qt.AutoColor])¶

Parameters:

imageReader – QImageReader
flags – ImageConversionFlag 的组合

Return type:

QPixmap

从直接从imageReader读取的图像创建一个QPixmap。flags参数是Qt::ImageConversionFlags的按位或运算。为flags传递0将设置所有默认选项。

在某些系统中，直接读取图像到QPixmap可能比读取QImage再将其转换为QPixmap使用更少的内存。

另请参阅

fromImage() toImage() Pixmap 转换

hasAlpha()¶

Return type:: 布尔

hasAlphaChannel()¶

Return type:: 布尔

isNull()¶

Return type:: 布尔

如果这是一个空的pixmap，则返回true；否则返回false。

空位图具有零宽度、零高度且没有内容。您不能在空位图中绘制。

isQBitmap()¶

Return type:: 布尔

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

load(fileName[, format=None[, flags=Qt.AutoColor]])¶

Parameters:

fileName – str
format – str
flags – ImageConversionFlag 的组合

Return type:

布尔

从具有给定fileName的文件中加载一个像素图。如果像素图成功加载，则返回true；否则使像素图无效并返回false。

加载器尝试使用指定的format读取像素图。如果未指定format（这是默认情况），加载器会探测文件的头部以猜测文件格式。

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

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

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

另请参阅

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

loadFromData(data[, format=None[, flags=Qt.AutoColor]])¶

Parameters:

data – QByteArray
format – str
flags – ImageConversionFlag 的组合

Return type:

布尔

这是一个重载函数。

从二进制data中加载一个像素图，使用指定的format和转换flags。

loadFromData(buf[, format=None[, flags=Qt.AutoColor]])

Parameters:

buf – str
format – str
flags – ImageConversionFlag 的组合

Return type:

布尔

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

加载器尝试使用指定的format读取像素图。如果未指定format（这是默认情况），加载器会探测文件的头部以猜测文件格式。

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

另请参阅

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

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

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

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

mask()¶

Return type:: QBitmap

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

警告

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

另请参阅

setMask() Pixmap 信息

rect()¶

Return type:: QRect

返回pixmap的包围矩形。

另请参阅

Pixmap 信息

save(device[, format=None[, quality=-1]])¶

Parameters:

设备 – QIODevice
format – str
quality – int

Return type:

布尔

警告

本节包含从C++自动翻译到Python的代码片段，可能包含错误。

这是一个重载函数。

此函数使用指定的图像文件format和quality因子将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]])

Parameters:

fileName – str
format – str
quality – int

Return type:

布尔

使用指定的图像文件format和quality因子将pixmap保存到给定的fileName文件中。如果成功，返回true；否则返回false。

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

如果 format 是 None，将从 fileName 的后缀中选择一个图像格式。

另请参阅

读取和写入图像文件

scaled(s[, aspectMode=Qt.IgnoreAspectRatio[, mode=Qt.FastTransformation]])¶

Parameters:

s – QSize
aspectMode – AspectRatioMode
mode – TransformationMode

Return type:

QPixmap

将像素图缩放到给定的size，使用由aspectRatioMode和transformMode指定的宽高比和变换模式。

如果 aspectRatioMode 是 Qt::IgnoreAspectRatio，则 pixmap 会被缩放到 size。

如果 aspectRatioMode 是 Qt::KeepAspectRatio，则 pixmap 会被缩放到尽可能大的矩形内，保持宽高比。

如果 aspectRatioMode 是 Qt::KeepAspectRatioByExpanding，则 pixmap 会被缩放到尽可能小的矩形，该矩形位于 size 之外，同时保持宽高比。

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

在某些情况下，将pixmap绘制到设置了比例的painter上比缩放pixmap更有利。例如，当painter基于OpenGL或比例因子快速变化时就是这种情况。

另请参阅

isNull() Pixmap 变换

scaled(w, h[, aspectMode=Qt.IgnoreAspectRatio[, mode=Qt.FastTransformation]])

Parameters:

w – 整数
h – 整数
aspectMode – AspectRatioMode
mode – TransformationMode

Return type:

QPixmap

这是一个重载函数。

返回一个根据给定的aspectRatioMode和transformMode缩放到具有指定width和height的矩形的pixmap副本。

如果width或height中的任何一个为零或负数，此函数将返回一个空的pixmap。

scaledToHeight(h[, mode=Qt.FastTransformation])¶

Parameters:

h – 整数
mode – TransformationMode

Return type:

QPixmap

返回图像的缩放副本。返回的图像使用指定的变换mode缩放到给定的height。pixmap的宽度会自动计算，以保持pixmap的宽高比。

如果 height 为 0 或负数，则返回一个空的 pixmap。

另请参阅

isNull() Pixmap Transformations

scaledToWidth(w[, mode=Qt.FastTransformation])¶

Parameters:

w – 整数
mode – TransformationMode

Return type:

QPixmap

返回图像的缩放副本。返回的图像使用指定的变换mode缩放到给定的width。pixmap的高度会自动计算，以保持pixmap的宽高比。

如果 width 为 0 或负数，则返回一个空的 pixmap。

另请参阅

isNull() Pixmap 变换

scroll(dx, dy, rect[, exposed=None])¶

Parameters:

dx – 整数
dy – 整数
rect – QRect
暴露 – QRegion

警告

本节包含从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])

Parameters:

dx – 整数
dy – 整数
x – 整数
y – 整数
width – int
height – int
暴露的 – QRegion

这个便捷函数等同于调用 scroll (dx, dy, QRect(x, y, width, height), exposed)。

另请参阅

scroll()

setDevicePixelRatio(scaleFactor)¶

Parameters:: scaleFactor – 浮点数

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

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

在像素图上打开的QPainters将被缩放。例如，在一个200x200的图像上以2.0的比例进行绘制，将导致有效的（设备无关的）绘制边界为100x100。

在Qt中，基于像素图大小计算布局几何的代码路径将考虑比例：QSize layoutSize = pixmap. size() / pixmap. devicePixelRatio() 这样做的最终效果是，像素图以高DPI像素图显示，而不是一个大像素图（参见Drawing High Resolution Versions of Pixmaps and Images）。

另请参阅

devicePixelRatio() deviceIndependentSize()

setMask(mask)¶

Parameters:: mask – QBitmap

设置一个遮罩位图。

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

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

警告

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

另请参阅

mask() Pixmap 变换 QBitmap

size()¶

Return type:: QSize

返回pixmap的大小。

另请参阅

width() height() Pixmap 信息

swap(other)¶

Parameters:: 其他 – QPixmap

将此 pixmap 与 other 交换。此操作非常快速且永远不会失败。

toImage()¶

Return type:: QImage

将像素图转换为QImage。如果转换失败，则返回空图像。

如果位图的深度为1位，返回的图像也将是1位深度。具有更多位的图像将以接近底层系统的格式返回。通常，对于具有alpha通道的位图，这将返回Format_ARGB32_Premultiplied，而对于没有alpha通道的位图，将返回Format_RGB32或Format_RGB16。

请注意，目前单色图像上的alpha遮罩被忽略。

另请参阅

fromImage() Image 格式

transformed(arg__1[, mode=Qt.FastTransformation])¶

Parameters:

arg__1 – QTransform
mode – TransformationMode

Return type:

QPixmap

static trueMatrix(m, w, h)¶

Parameters:

m – QTransform
w – 整数
h – 整数

Return type:

QTransform

返回用于转换具有给定width、height和matrix的像素图的实际矩阵。

当使用transformed()函数变换像素图时，内部会调整变换矩阵以补偿不需要的平移，即transformed()返回包含原始像素图所有变换点的最小像素图。此函数返回修改后的矩阵，该矩阵将点从原始像素图正确映射到新的像素图。

另请参阅

Pixmap Transformations