PySide6.QtGui.QImageReader

class QImageReader

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

概要

方法

静态函数

注意

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

详细描述

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

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

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

注意

QImageReader 假设对分配的文件或设备拥有独占控制权。在 QImageReader 对象的生命周期内，任何尝试修改分配的文件或设备的行为都将产生未定义的结果。

格式

调用 supportedImageFormats() 获取 QImageReader 可以读取的格式列表。QImageReader 支持所有内置的图像格式，以及任何支持读取的图像格式插件。调用 supportedMimeTypes() 获取支持的 MIME 类型列表，例如可以传递给 QFileDialog::setMimeTypeFilters()。

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

高分辨率版本的图像

如果设备像素和设备独立像素之间存在缩放关系，可以提供高分辨率的图像版本。

高分辨率版本在基本名称上标有后缀@2x。读取的图像将设置其设备像素比为2。

这可以通过设置环境变量 QT_HIGHDPI_DISABLE_2X_IMAGE_LOADING 来禁用。

另请参阅

QImageWriter QImageIOHandler QImageIOPlugin QColorSpace devicePixelRatio() 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__()

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

__init__(device[, format=QByteArray()])
Parameters:

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

__init__(fileName[, format=QByteArray()])
Parameters:

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

另请参阅

setFileName()

static allocationLimit()
Return type:

整数

返回当前分配限制，单位为兆字节。

另请参阅

setAllocationLimit()

autoDetectImageFormat()
Return type:

布尔

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

autoTransform()
Return type:

布尔

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

backgroundColor()
Return type:

QColor

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

canRead()
Return type:

布尔

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

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

注意

对于识别潜在的非图像文件或数据，通常使用QMimeDatabase查找比此函数更好。

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

clipRect()
Return type:

QRect

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

另请参阅

setClipRect()

currentImageNumber()
Return type:

整数

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

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

currentImageRect()
Return type:

QRect

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

decideFormatFromContent()
Return type:

布尔

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

device()
Return type:

QIODevice

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

另请参阅

setDevice()

error()
Return type:

ImageReaderError

返回上次发生的错误类型。

errorString()
Return type:

字符串

返回最近发生的错误的人类可读描述。

另请参阅

error()

fileName()
Return type:

字符串

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

另请参阅

setFileName() setDevice()

format()
Return type:

QByteArray

警告

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

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

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

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

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

imageCount()
Return type:

整数

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

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

imageFormat()
Return type:

格式

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

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

static imageFormat(device)
Parameters:

设备 – QIODevice

Return type:

QByteArray

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

static imageFormat(fileName)
Parameters:

fileName – str

Return type:

QByteArray

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

static imageFormatsForMimeType(mimeType)
Parameters:

mimeType – QByteArray

Return type:

.list of QByteArray

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

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

jumpToImage(imageNumber)
Parameters:

imageNumber – 整数

Return type:

布尔

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

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

jumpToNextImage()
Return type:

布尔

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

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

loopCount()
Return type:

整数

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

nextImageDelay()
Return type:

整数

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

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

quality()
Return type:

整数

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

另请参阅

setQuality()

read()
Return type:

QImage

从设备读取图像。成功时，返回读取的图像；否则，返回一个空的QImage。然后，您可以调用error()来查找发生的错误类型，或调用errorString()以获取错误的人类可读描述。

对于支持动画的图像格式，重复调用read()将返回下一帧。当所有帧都被读取后，将返回一个空图像。

scaledClipRect()
Return type:

QRect

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

另请参阅

setScaledClipRect()

scaledSize()
Return type:

QSize

返回图像的缩放大小。

另请参阅

setScaledSize()

static setAllocationLimit(mbLimit)
Parameters:

mbLimit – int

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

此限制帮助应用程序避免因加载损坏的图像文件而导致意外的大内存使用。通常不需要更改它。默认限制对于所有常用图像尺寸来说足够大。

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

注意

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

另请参阅

allocationLimit()

setAutoDetectImageFormat(enabled)
Parameters:

enabled – 布尔值

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

QImageReader 使用一种广泛的方法来检测图像格式；首先，如果你将一个文件名传递给 QImageReader，如果给定的文件名没有指向一个存在的文件，它会尝试通过将支持的默认扩展名逐个附加到给定的文件名来检测文件扩展名。然后，它使用以下方法来检测图像格式：

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

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

  • 如果没有找到合适的插件或内置处理程序，则通过检查数据流的内容来测试每个插件。

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

  • 最后，如果上述所有方法都失败，QImageReader在尝试读取图像时将报告失败。

通过禁用图像格式自动检测，QImageReader 将仅根据格式字符串查询插件和内置处理程序（即不测试文件扩展名）。

另请参阅

autoDetectImageFormat() canRead() capabilities()

setAutoTransform(enabled)
Parameters:

enabled – 布尔值

确定如果enabled为true，则read()返回的图像应自动应用转换元数据。

setBackgroundColor(color)
Parameters:

颜色 – QColor

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

另请参阅

backgroundColor() read()

setClipRect(rect)
Parameters:

rect – QRect

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

setDecideFormatFromContent(ignored)
Parameters:

忽略 – bool

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

设置此标志意味着所有图像插件都会被加载。每个插件将读取图像数据的前几个字节，并决定插件是否兼容。

这也禁用了自动检测图像格式。

setDevice(device)
Parameters:

设备 – QIODevice

将QImageReader的设备设置为device。如果已经设置了设备，旧设备将从QImageReader中移除，否则保持不变。

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

另请参阅

device() setFileName()

setFileName(fileName)
Parameters:

fileName – str

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

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

setFormat(format)
Parameters:

format – QByteArray

警告

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

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

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

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

另请参阅

format()

setQuality(quality)
Parameters:

质量 – int

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

一些图像格式，特别是有损格式，需要在a) 生成图像的视觉质量和b) 解码执行时间之间进行权衡。此函数为支持此功能的图像格式设置权衡的级别。

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

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

另请参阅

quality() setScaledSize()

setScaledClipRect(rect)
Parameters:

rect – QRect

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

setScaledSize(size)
Parameters:

大小 – QSize

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

如果在size中只设置了一个维度，另一个维度将从图像的natural size计算得出，以保持宽高比。

size()
Return type:

QSize

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

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

subType()
Return type:

QByteArray

返回图像的子类型。

static supportedImageFormats()
Return type:

.list of QByteArray

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

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

格式

MIME类型

描述

BMP

image/bmp

Windows 位图

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 位图

XPM

image/x-xpixmap

X11 位图

SVG

image/svg+xml

可缩放矢量图形

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

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

另请参阅

setFormat() supportedImageFormats() QImageIOPlugin

static supportedMimeTypes()
Return type:

.list of QByteArray

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

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

supportedSubTypes()
Return type:

.list of QByteArray

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

supportsAnimation()
Return type:

布尔

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

另请参阅

supportedFormats()

supportsOption(option)
Parameters:

选项 – ImageOption

Return type:

布尔

警告

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

key – str

Return type:

字符串

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

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

另请参阅

textKeys() setText()

textKeys()
Return type:

字符串列表

返回此图像的文本键。您可以将这些键与text()一起使用，以列出某个键的图像文本。

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

另请参阅

text() setText() textKeys()

transformation()
Return type:

Transformation的组合

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