class QImageReader#

QImageReader 类提供了一个通用的接口，用于从文件或其他设备读取图像。 更多信息…

概要#

方法#

静态函数#

注意

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

详细描述#

读取图像最常见的方式是通过调用QImage和QPixmap构造函数，或者通过调用QImage::load()和QPixmap::load()。QImageReader是一个专门类，它提供了在读取图像时更多的控制。例如，您可以通过调用setScaledSize()来将图像读取到指定大小，也可以通过调用setClipRect()来选择剪裁矩形，从而只加载图像的一部分。根据图像格式的底层支持，这可以节省内存并加快图像的加载速度。

读取图像时，您首先通过构造一个QImageReader对象开始。传递一个文件名或设备指针以及图像格式到QImageReader的构造函数。然后，您可以设置几个选项，例如剪辑矩形（通过调用setClipRect()）和缩放大小（通过调用setScaledSize()）。canRead()在QImageReader能够读取图像时返回图像（即，图像格式受到支持，并且设备已打开以供读取）。调用read()以读取图像。

如果在读取图像时发生任何错误，read()将返回一个空的QImage。然后，您可以调用error()以找到发生的错误类型，或者调用errorString()以获得发生错误的描述。

注意

QImageReader假定对分配的文件或设备有排他性控制。在QImageReader对象的生命周期中尝试修改分配的文件或设备将产生未定义的结果。

格式#

调用supportedImageFormats()以获取QImageReader能够读取的格式列表。《a class="reference internal" href="#PySide6.QtGui.QImageReader" title="PySide6.QtGui.QImageReader">QImageReader支持所有内置图像格式，以及任何支持读取的图像格式插件。调用supportedMimeTypes()以获取支持的MIME类型列表，例如，可以将它传递给QFileDialog::setMimeTypeFilters()。

QImageReader 默认通过查看所提供的（可选）格式字符串、文件名后缀以及数据流内容来自动检测图片格式。您可以通过调用 setAutoDetectImageFormat() 来启用或禁用此功能。

图片的高分辨率版本#

如果存在 设备像素 与 设备无关像素 之间的缩放，则可以提供图片的高分辨率版本。

高分辨率版本通过在基础名称后附加后缀 @2x 来标记。读取的图片其 设备像素比 将设置为 2。

可以通过设置环境变量 QT_HIGHDPI_DISABLE_2X_IMAGE_LOADING 来禁用此功能。

另请参阅

QImageWriter QImageIOHandler QImageIOPlugin QColorSpace devicePixelRatio() QIcon drawPixmap() drawImage()

class ImageReaderError#

该枚举描述了使用 QImageReader 读取图片时可能发生的不同类型的错误。

常量

描述

QImageReader.FileNotFoundError

QImageReader 使用了文件名，但没有找到该名称的文件。如果文件名中没有扩展名，并且在 Qt 不支持带有正确扩展名的文件，也可能发生这种情况。

QImageReader.DeviceError

QImageReader 在读取图片时遇到了设备错误。您可以咨询您的设备以获取更多有关错误详情。

QImageReader.UnsupportedFormatError

Qt 不支持请求的图片格式。

QImageReader.InvalidDataError

图片数据无效，且 QImageReader 无法从其读取图片。如果图片文件损坏，则可能会发生这种情况。

QImageReader.UnknownError

发生了未知错误。如果您在调用read()后得到此值，则很可能是由于QImageReader中的故障引起的。
__init__(device[, format=QByteArray()])#
参数:

使用设备device和图像格式format构建一个QImageReader对象。

__init__()

构建一个空的QImageReader对象。在读取图像之前，调用setDevice()或setFileName()。

__init__(fileName[, format=QByteArray()])
参数:

使用文件名fileName和图像格式format构建一个QImageReader对象。

另请参阅

setFileName()

静态allocationLimit()#
返回类型:

int

返回当前分配限制（以兆字节为单位）。

另请参阅

setAllocationLimit()

autoDetectImageFormat()#
返回类型:

bool

如果在此图像读取器上启用了图像格式自动检测，则返回true；否则返回false。默认情况下，自动检测已启用。

autoTransform()#
返回类型:

bool

如果图像处理程序将在read()上应用转换元数据，则返回true。

backgroundColor()#
返回类型:

QColor

返回在读取图像时使用的背景颜色。如果图像格式不支持设置背景颜色，将返回无效的颜色。

canRead()#
返回类型:

bool

如果设备可以读取图像（即，图像格式受支持，并且设备似乎包含有效数据），则返回true；否则返回false。

canRead()是一个轻量级函数，它只进行快速测试以检查图像数据是否有效。《read()`可能在canRead()返回true后仍返回false，如果图像数据已损坏。

注意

对于标识可能是非图像文件或数据的情况，通常此函数不如QMimeDatabase查找更有效。

对于支持动画的图像，当所有帧都已读取时，canRead()返回false。

clipRect()#
返回类型:

QRect

返回图像的裁剪矩形（也称为ROI或感兴趣区域）。如果没有设置裁剪矩形，则返回无效的QRect。

另请参阅

setClipRect()

currentImageNumber()#
返回类型:

int

对于支持动画的图像格式，此函数返回当前帧的序列号。如果图像格式不支持动画，则返回0。

如果发生错误，此函数返回-1。

currentImageRect()#
返回类型:

QRect

对支持动画的图像格式，此函数返回当前帧的矩形。否则，返回空矩形。

decideFormatFromContent()#
返回类型:

bool

返回图像读取器是否应仅根据数据流的内容而不是文件扩展名来决定使用哪个插件。

device()#
返回类型:

QIODevice

返回当前分配给 QImageReader 的设备，如果没有分配设备，则返回 None。

另请参阅

setDevice()

error()#
返回类型:

ImageReaderError

返回最近发生的错误的类型。

errorString()#
返回类型:

str

返回最后一次发生的错误的人读描述。

另请参阅

error()

fileName()#
返回类型:

str

如果当前分配的设备是 QFile，或者如果已调用 setFileName()，则此函数返回 QImageReader 读取的文件名。否则（即如果没有分配设备或者设备不是 QFile），返回空 QString。

另请参阅

setFileName() setDevice()

format()#
返回类型:

QByteArray

警告

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

返回用于读取图像的格式 QImageReader。

在将设备分配给读取器之后，您可以调用此函数来确定设备的格式。例如

reader = QImageReader("image.png")
# reader.format() == "png"

如果读取器无法从设备读取任何图像（例如，设备中没有图像，或者图像已被读取），或者格式不受支持，则此函数返回一个空的QByteArray()。

imageCount()#
返回类型:

int

对于支持动画的图像格式，此函数返回动画中图像的总数。如果不支持动画，返回0。

如果发生错误，此函数返回-1。

imageFormat()#
返回类型:

格式

返回图像的格式，而不实际读取图像内容。该格式描述了返回的图像格式 read()，而不是实际图像的格式。

如果图像格式不支持此功能，则此函数返回一个无效的格式。

静态 imageFormat(device)
参数:

device – QIODevice

返回类型:

QByteArray

如果支持，此函数返回设备 device 的图像格式。否则，返回空字符串。

静态 imageFormat(fileName)
参数:

fileName – 字符串

返回类型:

QByteArray

如果支持，此函数返回文件 fileName 的图像格式。否则，返回空字符串。

静态 imageFormatsForMimeType(mimeType)#
参数:

mimeType – QByteArray

返回类型:

的QByteArray列表

返回与mimeType对应的图像格式列表。

注意，在调用此函数之前必须创建QGuiApplication实例。

jumpToImage(imageNumber)#
参数:

imageNumber – int

返回类型:

bool

对于支持动画的图像格式，此函数跳到序列号为imageNumber的图像，如果成功返回true，如果找不到对应图像则返回false。

下一个调用read()将尝试读取此图像。

jumpToNextImage()#
返回类型:

bool

对于支持动画的图像格式，此函数跳过当前图像，如果成功返回true，如果没有后续图像则返回false。

默认实现调用read()，然后丢弃结果图像，但图像处理程序可能有更有效的方法来实现此操作。

loopCount()#
返回类型:

int

对于支持动画的图像格式，此函数返回动画应循环的次数。如果此函数返回-1，则意味着动画应无限循环，或者发生了错误。如果发生错误，canRead() 将返回false。

nextImageDelay()#
返回类型:

int

对于支持动画的图像格式，此函数返回在显示动画的下一帧之前应等待的毫秒数。如果图像格式不支持动画，则返回0。

如果发生错误，此函数返回-1。

quality()#
返回类型:

int

返回图像格式的质量设置。

另请参阅

setQuality()

read()#
返回类型:

QImage

从设备中读取图像。在成功的情况下，返回读取到的图像；否则，返回一个空 QImage。您可以通过调用 error() 来查找发生的错误类型，或者通过调用 errorString() 来获取错误的可读描述。

对于支持动画的图像格式，连续调用read()将返回下一帧。当读取完所有帧后，将返回空图像。

scaledClipRect()#
返回类型:

QRect

返回图像的缩放剪辑矩形。

另请参阅

setScaledClipRect()

scaledSize()#
返回类型:

QSize

返回图像的缩放大小。

另请参阅

setScaledSize()

静态 setAllocationLimit(mbLimit)#
参数:

mbLimit – int

将分配限制设置为 mbLimit 兆字节。任何需要超过此限制 QImage 内存分配的图像将被拒绝。如果 mbLimit 为 0，则将禁用分配大小检查。

此限制有助于应用程序避免意外使用大量内存来自动加载损坏的图像文件。通常不需要更改它。默认限制对于所有常用的图像大小来说已经足够大。

在运行时，此值可能被环境变量 QT_IMAGEIO_MAXALLOC 覆盖。

注意

内存需求是根据每像素至少 32 位计算的，因为 Qt 通常会在 GUI 中使用时将图像转换为该深度。这意味着当读取 1 bpp 和 8 bpp 图像时，有效分配限制显著小于 mbLimit。

另请参阅

allocationLimit()

setAutoDetectImageFormat(enabled)#
参数:

enabled – bool

如果 enabled 为 true，将启用图像格式自动检测；否则，将禁用。默认情况下，自动检测是启用的。

QImageReader 使用广泛的方法来检测图像格式；首先，如果您向 QImageReader 传递一个文件名，它将尝试检测文件扩展名，如果提供的文件名不指向一个现有的文件，它会通过一次将支持的默认扩展名附加到提供的文件名上来尝试检测。然后它会使用以下方法来检测图像格式

  • 首先查询图像插件，基于可选的格式字符串或文件名后缀（如果源设备是文件）。在此阶段不执行内容检测。如果该格式支持读取，则 QImageReader 会选择第一个支持该格式的插件。

  • 如果没有插件支持该图像格式，将根据可选的格式字符串或文件名后缀检查 Qt 的内置处理程序。

  • 如果没有找到具备能力的插件或内置处理程序，将通过检查数据流的内容测试每个插件。

  • 如果没有插件能够基于数据内容检测图像格式，将通过检查内容测试每个内置图像处理程序。

  • 最后，如果所有上述方法都失败，当尝试读取图像时，<code class="xref py py-class docutils literal notranslate">QImageReader</code> 将报告失败。

通过禁用图像格式自动检测，<code class="xref py py-class docutils literal notranslate">QImageReader</code> 将仅根据格式字符串查询插件和内置处理程序（即不会测试文件名扩展名）。

另请参阅

autoDetectImageFormat() canRead() capabilities()

setAutoTransform(enabled)#
参数:

enabled – bool

确定由 read() 返回的图像应在 enabled 为 true 时自动应用转换元数据。

setBackgroundColor(color)#
参数:

color – QColor

将背景颜色设置为 color。预期支持此操作的字节码格式在读取图像之前将背景初始化为 color。

另请参阅

backgroundColor() read()

setClipRect(rect)#
参数:

rect – QRect

将图像裁剪矩形（也称为区域（ROI）或感兴趣区域）设置为 rect。rect 的坐标是相对于由 size() 返回的非转换图像大小。

setDecideFormatFromContent(ignored)#
参数:

ignored – bool

如果将ignored设置为true，则图像读取器将忽略指定的格式或文件扩展名，并且仅根据数据流中的内容来决定使用哪个插件。

设置此标志表示将加载所有图像插件。每个插件将读取图像数据中的前几个字节，并决定该插件是否兼容。

这还会禁用自动检测图像格式。

setDevice(device)#
参数:

device – QIODevice

将QImageReader的设备设置为device。如果一个设备已经被设置，那么旧的设备将取消与QImageReader的关联，否则保持不变。

如果设备尚未打开，QImageReader将尝试通过调用open()以只读模式打开设备。请注意，这对于某些设备（如QProcess、QTcpSocket和QUdpSocket）不起作用，因为这些设备打开需要更多的逻辑。

另请参阅

device() setFileName()

setFileName(fileName)#
参数:

fileName – 字符串

将QImageReader的文件名设置为fileName。内部地，QImageReader将创建一个QFile对象并在只读模式下打开它，并在读取图像时使用该对象。

如果fileName不包含文件扩展名（例如，.png或.bmp），则QImageReader将遍历所有支持的扩展名，直到找到一个匹配的文件。

setFormat(format)#
参数:

format – QByteArray

警告

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

设置在读取图像时QImageReader将使用的格式为format。格式是一个不区分大小写的文本字符串。例如

reader = QImageReader()
reader.setFormat("png") # same as reader.setFormat("PNG")

您可以通过调用 supportedImageFormats() 获取 QImageReader 支持的所有格式的完整列表。

另请参阅

format()

setQuality(quality)#
参数:

quality – int

将图像格式的质量设置为 quality。

某些图像格式，特别是有损格式，需要在以下两个方面之间进行权衡：a) 最终图像的视觉效果，以及b) 解码执行时间。本函数将设置支持此功能的图像格式的权衡水平。

在缩放图像读取的情况下，质量设置也可能影响缩放算法的视觉效果和执行速度之间的权衡水平。

quality 的值范围取决于图像格式。例如，“jpeg”格式支持从 0（低视觉效果）到 100（高视觉效果）的质量范围。

另请参阅

quality() setScaledSize()

setScaledClipRect(rect)#
参数:

rect – QRect

将缩放剪裁矩形设置为 rect。缩放剪裁矩形是在图像缩放后应用的剪裁矩形（也称为ROI，即感兴趣区域）。

setScaledSize(size)#
参数:

size – QSize

将图像的缩放大小设置为 size。缩放是在初始剪裁矩形之后执行的，但在应用缩放剪裁矩形之前。所使用的缩放算法取决于图像格式。默认情况下（即，如果图像格式不支持缩放），QImageReader 将使用 Qt::SmoothScaling 的 QImage::scale()。

size()#
返回类型:

QSize

返回图像大小，而不实际读取图像内容。

如果图像格式不支持此功能，则该函数返回一个无效的大小。Qt的内置图像处理器都支持此功能，但自定义图像格式插件并不需要这样做。

subType()[链接]
返回类型:

QByteArray

返回图像的子类型。

静态supportedImageFormats()[链接]
返回类型:

的QByteArray列表

返回QImageReader支持的图像格式列表。

默认情况下，Qt可以读取以下格式

格式

MIME 类型

描述

BMP

image/bmp

Windows Bitmap

GIF

image/gif

图形交换格式（可选）

JPG

image/jpeg

联合摄影专家组

PNG

image/png

可移植网络图形

PBM

image/x-portable-bitmap

可移植位图

PGM

image/x-portable-graymap

可移植灰度图

PPM

image/x-portable-pixmap

可移植像素图

XBM

image/x-xbitmap

X11 Bitmap

XPM

image/x-xpixmap

X11 Pixmap

SVG

image/svg+xml

可缩放矢量图形

通过Qt SVG模块支持阅读和写入SVG文件。Qt图像格式模块提供了对其他图像格式的支持。

请注意，在调用此函数之前，必须创建QApplication实例。

另请参阅

setFormat() supportedImageFormats() QImageIOPlugin

静态supportedMimeTypes()[链接]
返回类型:

的QByteArray列表

返回QImageReader支持的MIME类型列表。

请注意，在调用此函数之前，必须创建QApplication实例。

supportedSubTypes()[链接]
返回类型:

的QByteArray列表

返回图像支持的子类型列表。

supportsAnimation()[链接]
返回类型:

bool

如果图像格式支持动画，则返回true；否则返回false。

另请参阅

supportedFormats

supportsOption(option)[链接]
参数:

选项 – ImageOption

返回类型:

bool

警告

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

如果读取器支持 option，则返回 true；否则返回 false。

不同的图像格式支持不同的选项。调用此函数以确定当前格式是否支持某个选项。例如，PNG 格式允许您将文本嵌入到图像的元数据中（见 text() ），而 BMP 格式允许您在将整个图像加载到内存中之前确定图像的大小（见 size() ）。

reader = QImageReader(":/image.png")
if reader.supportsOption(QImageIOHandler.Size):
    print("Size:", reader.size())

另请参阅

supportsOption()

text(key)#
参数:

key – str

返回类型:

str

返回与 key 关联的图像文本。

此选项的支持通过 Description 实现。

另请参阅

textKeys() setText()

textKeys()#
返回类型:

字符串列表

返回此图像的文本密钥。您可以使用这些密钥与 text() 结合，以列出与特定密钥关联的图像文本。

此选项的支持通过 Description 实现。

另请参阅

text() setText() textKeys()

transformation()#
返回类型:

Transformation 组合

返回图像的转换元数据，包括图像方向。如果格式不支持转换元数据，则返回 TransformationNone。