QImageReader¶
The
QImageReader
class provides a format independent interface for reading images from files or other devices. More…
Synopsis¶
Functions¶
def
autoDetectImageFormat
()def
autoTransform
()def
backgroundColor
()def
canRead
()def
clipRect
()def
currentImageNumber
()def
currentImageRect
()def
decideFormatFromContent
()def
device
()def
error
()def
errorString
()def
fileName
()def
format
()def
gamma
()def
imageCount
()def
imageFormat
()def
jumpToImage
(imageNumber)def
jumpToNextImage
()def
loopCount
()def
nextImageDelay
()def
quality
()def
read
()def
scaledClipRect
()def
scaledSize
()def
setAutoDetectImageFormat
(enabled)def
setAutoTransform
(enabled)def
setBackgroundColor
(color)def
setClipRect
(rect)def
setDecideFormatFromContent
(ignored)def
setDevice
(device)def
setFileName
(fileName)def
setFormat
(format)def
setGamma
(gamma)def
setQuality
(quality)def
setScaledClipRect
(rect)def
setScaledSize
(size)def
size
()def
subType
()def
supportedSubTypes
()def
supportsAnimation
()def
supportsOption
(option)def
text
(key)def
textKeys
()def
transformation
()
Static functions¶
def
imageFormat
(device)def
imageFormat
(fileName)def
imageFormatsForMimeType
(mimeType)def
supportedImageFormats
()def
supportedMimeTypes
()
Detailed Description¶
The most common way to read images is through
QImage
andQPixmap
‘s constructors, or by callingload()
andload()
.QImageReader
is a specialized class which gives you more control when reading images. For example, you can read an image into a specific size by callingsetScaledSize()
, and you can select a clip rect, effectively loading only parts of an image, by callingsetClipRect()
. Depending on the underlying support in the image format, this can save memory and speed up loading of images.To read an image, you start by constructing a
QImageReader
object. Pass either a file name or a device pointer, and the image format toQImageReader
‘s constructor. You can then set several options, such as the clip rect (by callingsetClipRect()
) and scaled size (by callingsetScaledSize()
).canRead()
returns the image if theQImageReader
can read the image (i.e., the image format is supported and the device is open for reading). Callread()
to read the image.If any error occurs when reading the image,
read()
will return a nullQImage
. You can then callerror()
to find the type of error that occurred, orerrorString()
to get a human readable description of what went wrong.Note
QImageReader
assumes exclusive control over the file or device that is assigned. Any attempts to modify the assigned file or device during the lifetime of theQImageReader
object will yield undefined results.
Formats¶
Call
supportedImageFormats()
for a list of formats thatQImageReader
can read.QImageReader
supports all built-in image formats, in addition to any image format plugins that support reading. CallsupportedMimeTypes()
to obtain a list of supported MIME types, which for example can be passed tosetMimeTypeFilters()
.
QImageReader
autodetects the image format by default, by looking at the provided (optional) format string, the file name suffix, and the data stream contents. You can enable or disable this feature, by callingsetAutoDetectImageFormat()
.
High Resolution Versions of Images¶
It is possible to provide high resolution versions of images should a scaling between device pixels and device independent pixels be in effect.
The high resolution version is marked by the suffix
@2x
on the base name. The image read will have its device pixel ratio set to a value of 2.This can be disabled by setting the environment variable
QT_HIGHDPI_DISABLE_2X_IMAGE_LOADING
.See also
QImageWriter
QImageIOHandler
QImageIOPlugin
QMimeDatabase
QColorSpace
devicePixelRatio()
devicePixelRatio()
QIcon
drawPixmap()
drawImage()
AA_UseHighDpiPixmaps
- class PySide2.QtGui.QImageReader¶
PySide2.QtGui.QImageReader(device[, format=QByteArray()])
PySide2.QtGui.QImageReader(fileName[, format=QByteArray()])
- param format:
- param device:
- param fileName:
str
Constructs an empty
QImageReader
object. Before reading an image, callsetDevice()
orsetFileName()
.
- PySide2.QtGui.QImageReader.ImageReaderError¶
This enum describes the different types of errors that can occur when reading images with
QImageReader
.Constant
Description
QImageReader.FileNotFoundError
QImageReader
was used with a file name, but not file was found with that name. This can also happen if the file name contained no extension, and the file with the correct extension is not supported by Qt.QImageReader.DeviceError
QImageReader
encountered a device error when reading the image. You can consult your particular device for more details on what went wrong.QImageReader.UnsupportedFormatError
Qt does not support the requested image format.
QImageReader.InvalidDataError
The image data was invalid, and
QImageReader
was unable to read an image from it. The can happen if the image file is damaged.QImageReader.UnknownError
An unknown error occurred. If you get this value after calling
read()
, it is most likely caused by a bug inQImageReader
.
- PySide2.QtGui.QImageReader.autoDetectImageFormat()¶
- Return type:
bool
Returns
true
if image format autodetection is enabled on this image reader; otherwise returnsfalse
. By default, autodetection is enabled.See also
- PySide2.QtGui.QImageReader.autoTransform()¶
- Return type:
bool
Returns
true
if the image handler will apply transformation metadata onread()
.See also
- PySide2.QtGui.QImageReader.backgroundColor()¶
- Return type:
Returns the background color that’s used when reading an image. If the image format does not support setting the background color an invalid color is returned.
See also
- PySide2.QtGui.QImageReader.canRead()¶
- Return type:
bool
Returns
true
if an image can be read for the device (i.e., the image format is supported, and the device seems to contain valid data); otherwise returnsfalse
.is a lightweight function that only does a quick test to see if the image data is valid.
read()
may still return false after returnstrue
, if the image data is corrupt.Note
A
QMimeDatabase
lookup is normally a better approach than this function for identifying potentially non-image files or data.For images that support animation, returns
false
when all frames have been read.See also
read()
supportedImageFormats()
QMimeDatabase
- PySide2.QtGui.QImageReader.clipRect()¶
- Return type:
Returns the clip rect (also known as the ROI, or Region Of Interest) of the image. If no clip rect has been set, an invalid
QRect
is returned.See also
- PySide2.QtGui.QImageReader.currentImageNumber()¶
- Return type:
int
For image formats that support animation, this function returns the sequence number of the current frame. If the image format doesn’t support animation, 0 is returned.
This function returns -1 if an error occurred.
- PySide2.QtGui.QImageReader.currentImageRect()¶
- Return type:
For image formats that support animation, this function returns the rect for the current frame. Otherwise, a null rect is returned.
See also
- PySide2.QtGui.QImageReader.decideFormatFromContent()¶
- Return type:
bool
Returns whether the image reader should decide which plugin to use only based on the contents of the datastream rather than on the file extension.
See also
- PySide2.QtGui.QImageReader.device()¶
- Return type:
Returns the device currently assigned to
QImageReader
, orNone
if no device has been assigned.See also
- PySide2.QtGui.QImageReader.error()¶
- Return type:
Returns the type of error that occurred last.
See also
ImageReaderError
errorString()
- PySide2.QtGui.QImageReader.errorString()¶
- Return type:
str
Returns a human readable description of the last error that occurred.
See also
- PySide2.QtGui.QImageReader.fileName()¶
- Return type:
str
If the currently assigned device is a
QFile
, or ifsetFileName()
has been called, this function returns the name of the fileQImageReader
reads from. Otherwise (i.e., if no device has been assigned or the device is not aQFile
), an emptyQString
is returned.See also
- PySide2.QtGui.QImageReader.format()¶
- Return type:
Returns the format
QImageReader
uses for reading images.You can call this function after assigning a device to the reader to determine the format of the device. For example:
reader = QImageReader("image.png") # reader.format() == "png"
If the reader cannot read any image from the device (e.g., there is no image there, or the image has already been read), or if the format is unsupported, this function returns an empty QByteArray().
See also
- PySide2.QtGui.QImageReader.gamma()¶
- Return type:
float
Note
This function is deprecated.
Use
colorSpace()
andgamma()
instead.Returns the gamma level of the decoded image. If
setGamma()
has been called and gamma correction is supported it will return the gamma set. If gamma level is not supported by the image format,0.0
is returned.See also
- PySide2.QtGui.QImageReader.imageCount()¶
- Return type:
int
For image formats that support animation, this function returns the total number of images in the animation. If the format does not support animation, 0 is returned.
This function returns -1 if an error occurred.
See also
- PySide2.QtGui.QImageReader.imageFormat()¶
- Return type:
Returns the format of the image, without actually reading the image contents. The format describes the image format
read()
returns, not the format of the actual image.If the image format does not support this feature, this function returns an invalid format.
See also
ImageOption
option()
supportsOption()
- static PySide2.QtGui.QImageReader.imageFormat(device)
- Parameters:
device –
PySide2.QtCore.QIODevice
- Return type:
If supported, this function returns the image format of the device
device
. Otherwise, an empty string is returned.See also
- static PySide2.QtGui.QImageReader.imageFormat(fileName)
- Parameters:
fileName – str
- Return type:
- static PySide2.QtGui.QImageReader.imageFormatsForMimeType(mimeType)¶
- Parameters:
mimeType –
PySide2.QtCore.QByteArray
- Return type:
Returns the list of image formats corresponding to
mimeType
.Note that the
QGuiApplication
instance must be created before this function is called.
- PySide2.QtGui.QImageReader.jumpToImage(imageNumber)¶
- Parameters:
imageNumber – int
- Return type:
bool
For image formats that support animation, this function skips to the image whose sequence number is
imageNumber
, returning true if successful or false if the corresponding image cannot be found.The next call to
read()
will attempt to read this image.See also
- PySide2.QtGui.QImageReader.jumpToNextImage()¶
- Return type:
bool
For image formats that support animation, this function steps over the current image, returning true if successful or false if there is no following image in the animation.
The default implementation calls
read()
, then discards the resulting image, but the image handler may have a more efficient way of implementing this operation.See also
- PySide2.QtGui.QImageReader.loopCount()¶
- Return type:
int
For image formats that support animation, this function returns the number of times the animation should loop. If this function returns -1, it can either mean the animation should loop forever, or that an error occurred. If an error occurred,
canRead()
will return false.See also
- PySide2.QtGui.QImageReader.nextImageDelay()¶
- Return type:
int
For image formats that support animation, this function returns the number of milliseconds to wait until displaying the next frame in the animation. If the image format doesn’t support animation, 0 is returned.
This function returns -1 if an error occurred.
See also
- PySide2.QtGui.QImageReader.quality()¶
- Return type:
int
Returns the quality setting of the image format.
See also
- PySide2.QtGui.QImageReader.read()¶
- Return type:
Reads an image from the device. On success, the image that was read is returned; otherwise, a null
QImage
is returned. You can then callerror()
to find the type of error that occurred, orerrorString()
to get a human readable description of the error.For image formats that support animation, calling repeatedly will return the next frame. When all frames have been read, a null image will be returned.
- PySide2.QtGui.QImageReader.scaledClipRect()¶
- Return type:
Returns the scaled clip rect of the image.
See also
- PySide2.QtGui.QImageReader.scaledSize()¶
- Return type:
Returns the scaled size of the image.
See also
- PySide2.QtGui.QImageReader.setAutoDetectImageFormat(enabled)¶
- Parameters:
enabled – bool
If
enabled
is true, image format autodetection is enabled; otherwise, it is disabled. By default, autodetection is enabled.QImageReader
uses an extensive approach to detecting the image format; firstly, if you pass a file name toQImageReader
, it will attempt to detect the file extension if the given file name does not point to an existing file, by appending supported default extensions to the given file name, one at a time. It then uses the following approach to detect the image format:Image plugins are queried first, based on either the optional format string, or the file name suffix (if the source device is a file). No content detection is done at this stage.
QImageReader
will choose the first plugin that supports reading for this format.If no plugin supports the image format, Qt’s built-in handlers are checked based on either the optional format string, or the file name suffix.
If no capable plugins or built-in handlers are found, each plugin is tested by inspecting the content of the data stream.
If no plugins could detect the image format based on data contents, each built-in image handler is tested by inspecting the contents.
Finally, if all above approaches fail,
QImageReader
will report failure when trying to read the image.
By disabling image format autodetection,
QImageReader
will only query the plugins and built-in handlers based on the format string (i.e., no file name extensions are tested).See also
autoDetectImageFormat()
canRead()
capabilities()
- PySide2.QtGui.QImageReader.setAutoTransform(enabled)¶
- Parameters:
enabled – bool
Determines that images returned by
read()
should have transformation metadata automatically applied ifenabled
istrue
.See also
- PySide2.QtGui.QImageReader.setBackgroundColor(color)¶
- Parameters:
color –
PySide2.QtGui.QColor
Sets the background color to
color
. Image formats that support this operation are expected to initialize the background tocolor
before reading an image.See also
- PySide2.QtGui.QImageReader.setClipRect(rect)¶
- Parameters:
rect –
PySide2.QtCore.QRect
Sets the image clip rect (also known as the ROI, or Region Of Interest) to
rect
. The coordinates ofrect
are relative to the untransformed image size, as returned bysize()
.See also
- PySide2.QtGui.QImageReader.setDecideFormatFromContent(ignored)¶
- Parameters:
ignored – bool
If
ignored
is set to true, then the image reader will ignore specified formats or file extensions and decide which plugin to use only based on the contents in the datastream.Setting this flag means that all image plugins gets loaded. Each plugin will read the first bytes in the image data and decide if the plugin is compatible or not.
This also disables auto detecting the image format.
See also
- PySide2.QtGui.QImageReader.setDevice(device)¶
- Parameters:
device –
PySide2.QtCore.QIODevice
Sets
QImageReader
‘s device todevice
. If a device has already been set, the old device is removed fromQImageReader
and is otherwise left unchanged.If the device is not already open,
QImageReader
will attempt to open the device inReadOnly
mode by calling open(). Note that this does not work for certain devices, such asQProcess
,QTcpSocket
andQUdpSocket
, where more logic is required to open the device.See also
- PySide2.QtGui.QImageReader.setFileName(fileName)¶
- Parameters:
fileName – str
Sets the file name of
QImageReader
tofileName
. Internally,QImageReader
will create aQFile
object and open it inReadOnly
mode, and use this when reading images.If
fileName
does not include a file extension (e.g., .png or .bmp),QImageReader
will cycle through all supported extensions until it finds a matching file.See also
- PySide2.QtGui.QImageReader.setFormat(format)¶
- Parameters:
format –
PySide2.QtCore.QByteArray
Sets the format
QImageReader
will use when reading images, toformat
.format
is a case insensitive text string. Example:reader = QImageReader() reader.setFormat("png") # same as reader.setFormat("PNG")
You can call
supportedImageFormats()
for the full list of formatsQImageReader
supports.See also
- PySide2.QtGui.QImageReader.setGamma(gamma)¶
- Parameters:
gamma – float
Note
This function is deprecated.
Use
QColorSpace
conversion on theQImage
instead.This is an image format specific function that forces images with gamma information to be gamma corrected to
gamma
. For image formats that do not support gamma correction, this value is ignored.To gamma correct to a standard PC color-space, set gamma to
1/2.2
.See also
- PySide2.QtGui.QImageReader.setQuality(quality)¶
- Parameters:
quality – int
Sets the quality setting of the image format to
quality
.Some image formats, in particular lossy ones, entail a tradeoff between a) visual quality of the resulting image, and b) decoding execution time. This function sets the level of that tradeoff for image formats that support it.
In case of scaled image reading, the quality setting may also influence the tradeoff level between visual quality and execution speed of the scaling algorithm.
The value range of
quality
depends on the image format. For example, the “jpeg” format supports a quality range from 0 (low visual quality) to 100 (high visual quality).See also
- PySide2.QtGui.QImageReader.setScaledClipRect(rect)¶
- Parameters:
rect –
PySide2.QtCore.QRect
Sets the scaled clip rect to
rect
. The scaled clip rect is the clip rect (also known as ROI, or Region Of Interest) that is applied after the image has been scaled.See also
- PySide2.QtGui.QImageReader.setScaledSize(size)¶
- Parameters:
size –
PySide2.QtCore.QSize
Sets the scaled size of the image to
size
. The scaling is performed after the initial clip rect, but before the scaled clip rect is applied. The algorithm used for scaling depends on the image format. By default (i.e., if the image format does not support scaling),QImageReader
will use QImage::scale() with Qt::SmoothScaling.See also
- PySide2.QtGui.QImageReader.size()¶
- Return type:
Returns the size of the image, without actually reading the image contents.
If the image format does not support this feature, this function returns an invalid size. Qt’s built-in image handlers all support this feature, but custom image format plugins are not required to do so.
See also
ImageOption
option()
supportsOption()
- PySide2.QtGui.QImageReader.subType()¶
- Return type:
Returns the subtype of the image.
- static PySide2.QtGui.QImageReader.supportedImageFormats()¶
- Return type:
Returns the list of image formats supported by
QImageReader
.By default, Qt can read the following formats:
Format
MIME type
Description
BMP
image/bmp
Windows Bitmap
GIF
image/gif
Graphic Interchange Format (optional)
JPG
image/jpeg
Joint Photographic Experts Group
PNG
image/png
Portable Network Graphics
PBM
image/x-portable-bitmap
Portable Bitmap
PGM
image/x-portable-graymap
Portable Graymap
PPM
image/x-portable-pixmap
Portable Pixmap
XBM
image/x-xbitmap
X11 Bitmap
XPM
image/x-xpixmap
X11 Pixmap
SVG
image/svg+xml
Scalable Vector Graphics
Reading and writing SVG files is supported through the Qt SVG module. The Qt Image Formats module provides support for additional image formats.
Note that the
QApplication
instance must be created before this function is called.See also
setFormat()
supportedImageFormats()
QImageIOPlugin
- static PySide2.QtGui.QImageReader.supportedMimeTypes()¶
- Return type:
Returns the list of MIME types supported by
QImageReader
.Note that the
QApplication
instance must be created before this function is called.
- PySide2.QtGui.QImageReader.supportedSubTypes()¶
- Return type:
Returns the list of subtypes supported by an image.
- PySide2.QtGui.QImageReader.supportsAnimation()¶
- Return type:
bool
Returns
true
if the image format supports animation; otherwise, false is returned.See also
- PySide2.QtGui.QImageReader.supportsOption(option)¶
- Parameters:
option –
ImageOption
- Return type:
bool
Returns
true
if the reader supportsoption
; otherwise returns false.Different image formats support different options. Call this function to determine whether a certain option is supported by the current format. For example, the PNG format allows you to embed text into the image’s metadata (see
text()
), and the BMP format allows you to determine the image’s size without loading the whole image into memory (seesize()
).reader = QImageReader(":/image.png") if reader.supportsOption(QImageIOHandler.Size): print "Size:", str(reader.size())
See also
- PySide2.QtGui.QImageReader.text(key)¶
- Parameters:
key – str
- Return type:
str
Returns the image text associated with
key
.Support for this option is implemented through
Description
.See also
- PySide2.QtGui.QImageReader.textKeys()¶
- Return type:
list of strings
Returns the text keys for this image. You can use these keys with
text()
to list the image text for a certain key.Support for this option is implemented through
Description
.See also
- PySide2.QtGui.QImageReader.transformation()¶
- Return type:
Returns the transformation metadata of the image, including image orientation. If the format does not support transformation metadata,
TransformationNone
is returned.See also
© 2022 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.