Skip to content

PythonQt.Qt.QImage

QImage

PythonQtInstanceWrapper object

Native bases: PythonQtInstanceWrapper

Supplemental documentation: Qt 5 reference:

Detailed Description

Qt provides four classes for handling image data: QImage, QPixmap, QBitmap and QPicture. QImage is designed and optimized for I/O, and for direct pixel access and manipulation, while QPixmap is designed and optimized for showing images on screen. QBitmap is only a convenience class that inherits QPixmap, ensuring a depth of 1. Finally, the QPicture class is a paint device that records and replays QPainter commands.

Because QImage is a QPaintDevice subclass, QPainter can be used to draw directly onto images. When using QPainter on a QImage, the painting can be performed in another thread than the current GUI thread.

The QImage class supports several image formats described by the Format enum. These include monochrome, 8-bit, 32-bit and alpha-blended images which are available in all versions of Qt 4.x.

QImage provides a collection of functions that can be used to obtain a variety of information about the image. There are also several functions that enables transformation of the image.

QImage objects can be passed around by value since the QImage class uses implicit data sharing. QImage objects can also be streamed and compared.

Note: If you would like to load QImage objects in a static build of Qt, refer to the Plugin HowTo.

Warning: Painting on a QImage with the format QImage::Format_Indexed8 is not supported.

Reading and Writing Image Files

QImage provides several ways of loading an image file: The file can be loaded when constructing the QImage object, or by using the load() or loadFromData() functions later on. QImage also provides the static fromData() function, constructing a QImage from the given data. When loading an image, the file name can either refer to an actual file on disk or to one of the application's embedded resources. See The Qt Resource System overview for details on how to embed images and other resource files in the application's executable.

Simply call the save() function to save a QImage object.

The complete list of supported file formats are available through the QImageReader::supportedImageFormats() and QImageWriter::supportedImageFormats() functions. New file formats can be added as plugins. By default, Qt supports the following formats:

Format Description Qt's support
BMP Windows Bitmap Read/write
GIF Graphic Interchange Format (optional) Read
JPG Joint Photographic Experts Group Read/write
JPEG Joint Photographic Experts Group Read/write
PNG Portable Network Graphics Read/write
PBM Portable Bitmap Read
PGM Portable Graymap Read
PPM Portable Pixmap Read/write
XBM X11 Bitmap Read/write
XPM X11 Pixmap Read/write

Image Information

QImage provides a collection of functions that can be used to obtain a variety of information about the image:

Available Functions
Geometry The size(), width(), height(), dotsPerMeterX(), and dotsPerMeterY() functions provide information about the image size and aspect ratio. The rect() function returns the image's enclosing rectangle. The valid() function tells if a given pair of coordinates is within this rectangle. The offset() function returns the number of pixels by which the image is intended to be offset by when positioned relative to other images, which also can be manipulated using the setOffset() function.
Colors The color of a pixel can be retrieved by passing its coordinates to the pixel() function. The pixel() function returns the color as a QRgb value indepedent of the image's format. In case of monochrome and 8-bit images, the colorCount() and colorTable() functions provide information about the color components used to store the image data: The colorTable() function returns the image's entire color table. To obtain a single entry, use the pixelIndex() function to retrieve the pixel index for a given pair of coordinates, then use the color() function to retrieve the color. Note that if you create an 8-bit image manually, you have to set a valid color table on the image as well. The hasAlphaChannel() function tells if the image's format respects the alpha channel, or not. The allGray() and isGrayscale() functions tell whether an image's colors are all shades of gray. See also the Pixel Manipulation and Image Transformations sections.
Text The text() function returns the image text associated with the given text key. An image's text keys can be retrieved using the textKeys() function. Use the setText() function to alter an image's text.
Low-level information The depth() function returns the depth of the image. The supported depths are 1 (monochrome), 8, 16, 24 and 32 bits. The bitPlaneCount() function tells how many of those bits that are used. For more information see the Image Formats section. The format(), bytesPerLine(), and sizeInBytes() functions provide low-level information about the data stored in the image. The cacheKey() function returns a number that uniquely identifies the contents of this QImage object.

Pixel Manipulation

The functions used to manipulate an image's pixels depend on the image format. The reason is that monochrome and 8-bit images are index-based and use a color lookup table, while 32-bit images store ARGB values directly. For more information on image formats, see the Image Formats section.

In case of a 32-bit image, the setPixel() function can be used to alter the color of the pixel at the given coordinates to any other color specified as an ARGB quadruplet. To make a suitable QRgb value, use the qRgb() (adding a default alpha component to the given RGB values, i.e. creating an opaque color) or qRgba() function. For example:

32-bit
QImage image(3, 3, QImage::Format_RGB32); QRgb value; value = qRgb(189, 149, 39); // 0xffbd9527 image.setPixel(1, 1, value); value = qRgb(122, 163, 39); // 0xff7aa327 image.setPixel(0, 1, value); image.setPixel(1, 0, value); value = qRgb(237, 187, 51); // 0xffedba31 image.setPixel(2, 1, value);

In case of a 8-bit and monchrome images, the pixel value is only an index from the image's color table. So the setPixel() function can only be used to alter the color of the pixel at the given coordinates to a predefined color from the image's color table, i.e. it can only change the pixel's index value. To alter or add a color to an image's color table, use the setColor() function.

An entry in the color table is an ARGB quadruplet encoded as an QRgb value. Use the qRgb() and qRgba() functions to make a suitable QRgb value for use with the setColor() function. For example:

8-bit
QImage image(3, 3, QImage::Format_Indexed8); QRgb value; value = qRgb(122, 163, 39); // 0xff7aa327 image.setColor(0, value); value = qRgb(237, 187, 51); // 0xffedba31 image.setColor(1, value); value = qRgb(189, 149, 39); // 0xffbd9527 image.setColor(2, value); image.setPixel(0, 1, 0); image.setPixel(1, 0, 0); image.setPixel(1, 1, 2); image.setPixel(2, 1, 1);

For images with more than 8-bit per color-channel. The methods setPixelColor() and pixelColor() can be used to set and get with QColor values.

QImage also provide the scanLine() function which returns a pointer to the pixel data at the scanline with the given index, and the bits() function which returns a pointer to the first pixel data (this is equivalent to scanLine(0)).

Image Formats

Each pixel stored in a QImage is represented by an integer. The size of the integer varies depending on the format. QImage supports several image formats described by the Format enum.

Monochrome images are stored using 1-bit indexes into a color table with at most two colors. There are two different types of monochrome images: big endian (MSB first) or little endian (LSB first) bit order.

8-bit images are stored using 8-bit indexes into a color table, i.e. they have a single byte per pixel. The color table is a QVector\<QRgb>, and the QRgb typedef is equivalent to an unsigned int containing an ARGB quadruplet on the format 0xAARRGGBB.

32-bit images have no color table; instead, each pixel contains an QRgb value. There are three different types of 32-bit images storing RGB (i.e. 0xffRRGGBB), ARGB and premultiplied ARGB values respectively. In the premultiplied format the red, green, and blue channels are multiplied by the alpha component divided by 255.

An image's format can be retrieved using the format() function. Use the convertToFormat() functions to convert an image into another format. The allGray() and isGrayscale() functions tell whether a color image can safely be converted to a grayscale image.

Image Transformations

QImage supports a number of functions for creating a new image that is a transformed version of the original: The createAlphaMask() function builds and returns a 1-bpp mask from the alpha buffer in this image, and the createHeuristicMask() function creates and returns a 1-bpp heuristic mask for this image. The latter function works by selecting a color from one of the corners, then chipping away pixels of that color starting at all the edges.

The mirrored() function returns a mirror of the image in the desired direction, the scaled() returns a copy of the image scaled to a rectangle of the desired measures, and the rgbSwapped() function constructs a BGR image from a RGB image.

The scaledToWidth() and scaledToHeight() functions return scaled copies of the image.

The transformed() function returns a copy of the image that is transformed with the given transformation matrix and transformation mode: Internally, the transformation matrix is adjusted to compensate for unwanted translation, i.e. transformed() returns the smallest image containing all transformed points of the original image. The static trueMatrix() function returns the actual matrix used for transforming the image.

There are also functions for changing attributes of an image in-place:

Function Description
setDotsPerMeterX() Defines the aspect ratio by setting the number of pixels that fit horizontally in a physical meter.
setDotsPerMeterY() Defines the aspect ratio by setting the number of pixels that fit vertically in a physical meter.
fill() Fills the entire image with the given pixel value.
invertPixels() Inverts all pixel values in the image using the given InvertMode value.
setColorTable() Sets the color table used to translate color indexes. Only monochrome and 8-bit formats.
setColorCount() Resizes the color table. Only monochrome and 8-bit formats.

Source: https://doc.qt.io/archives/qt-5.15/qimage.html

Complete member index

Every captured member retains its own identity. Identical captured declaration text is linked once; this does not establish native inheritance or interchangeable objects.

Member Kind Signature Summary
Format attribute type Convert a number or string to an integer, or return 0 if no arguments are given. (shared captured text)
Format_A2BGR30_Premultiplied attribute Any (shared captured text)
Format_A2RGB30_Premultiplied attribute Any (shared captured text)
Format_ARGB32 attribute Any (shared captured text)
Format_ARGB32_Premultiplied attribute Any (shared captured text)
Format_ARGB4444_Premultiplied attribute Any (shared captured text)
Format_ARGB6666_Premultiplied attribute Any (shared captured text)
Format_ARGB8555_Premultiplied attribute Any (shared captured text)
Format_ARGB8565_Premultiplied attribute Any (shared captured text)
Format_Alpha8 attribute Any (shared captured text)
Format_BGR30 attribute Any (shared captured text)
Format_Grayscale8 attribute Any (shared captured text)
Format_Indexed8 attribute Any (shared captured text)
Format_Invalid attribute Any (shared captured text)
Format_Mono attribute Any (shared captured text)
Format_MonoLSB attribute Any (shared captured text)
Format_RGB16 attribute Any (shared captured text)
Format_RGB30 attribute Any (shared captured text)
Format_RGB32 attribute Any (shared captured text)
Format_RGB444 attribute Any (shared captured text)
Format_RGB555 attribute Any (shared captured text)
Format_RGB666 attribute Any (shared captured text)
Format_RGB888 attribute Any (shared captured text)
Format_RGBA8888 attribute Any (shared captured text)
Format_RGBA8888_Premultiplied attribute Any (shared captured text)
Format_RGBX8888 attribute Any (shared captured text)
InvertMode attribute type Convert a number or string to an integer, or return 0 if no arguments are given. (shared captured text)
InvertRgb attribute Any (shared captured text)
InvertRgba attribute Any (shared captured text)
NImageFormats attribute Any (shared captured text)
PaintDeviceMetric attribute type Convert a number or string to an integer, or return 0 if no arguments are given. (shared captured text)
PdmDepth attribute Any (shared captured text)
PdmDevicePixelRatio attribute Any (shared captured text)
PdmDevicePixelRatioScaled attribute Any (shared captured text)
PdmDpiX attribute Any (shared captured text)
PdmDpiY attribute Any (shared captured text)
PdmHeight attribute Any (shared captured text)
PdmHeightMM attribute Any (shared captured text)
PdmNumColors attribute Any (shared captured text)
PdmPhysicalDpiX attribute Any (shared captured text)
PdmPhysicalDpiY attribute Any (shared captured text)
PdmWidth attribute Any (shared captured text)
PdmWidthMM attribute Any (shared captured text)
__init__ function (self, *args: Any, **kwargs: Any) -> None Native constructor; consult class documentation for supported overloads. (shared captured text)
allGray function (self) -> bool X.allGray() -> bool (shared captured text)
alphaChannel function (self) -> Any X.alphaChannel() -> PythonQt.QtGui.QImage (shared captured text)
bitPlaneCount function (self) -> int X.bitPlaneCount() -> int (shared captured text)
bits function (self) -> str Returns a pointer to the first pixel data. (shared captured text)
byteCount function (self) -> int X.byteCount() -> int (shared captured text)
bytesPerLine function (self) -> int X.bytesPerLine() -> int (shared captured text)
cacheKey function (self) -> int X.cacheKey() -> int (shared captured text)
className function (self, *args: Any, **kwargs: Any) -> Any Return the classname of the object (shared captured text)
color function (self, i: int) -> int X.color(i) -> int (shared captured text)
colorCount function (self) -> int X.colorCount() -> int (shared captured text)
colorTable function (self) -> tuple X.colorTable() -> tuple (shared captured text)
constBits function (self) -> str Returns a pointer to the first pixel data. (shared captured text)
constScanLine function (self, line: Any) -> str Returns a pointer to the pixel data at the scanline with index i. (shared captured text)
convertToFormat function (self, f: Any, colorTable: Any, arg2: flags) -> Any X.convertToFormat(f, colorTable, flags) -> PythonQt.QtGui.QImage (shared captured text)
convertToFormat_helper function (self, format: Any, arg1: flags) -> Any X.convertToFormat_helper(format, flags) -> PythonQt.QtGui.QImage (shared captured text)
convertToFormat_inplace function (self, format: Any, arg1: flags) -> bool X.convertToFormat_inplace(format, flags) -> bool (shared captured text)
copy function (self, x: Any, y: Any, w: Any, h: Any) -> Any X.copy(x, y, w, h) -> PythonQt.QtGui.QImage (shared captured text)
createAlphaMask function (self, arg0: flags) -> Any X.createAlphaMask(flags) -> PythonQt.QtGui.QImage (shared captured text)
createHeuristicMask function (self, clipTight: bool) -> Any X.createHeuristicMask(clipTight) -> PythonQt.QtGui.QImage (shared captured text)
createMaskFromColor function (self, color: int, mode: Any) -> Any X.createMaskFromColor(color, mode) -> PythonQt.QtGui.QImage (shared captured text)
delete function (self, *args: Any, **kwargs: Any) -> Any Deletes the C++ object (at your own risk, my friend!) (shared captured text)
depth function (self) -> int X.depth() -> int (shared captured text)
devType function (self) -> int X.devType() -> int (shared captured text)
devicePixelRatio function (self) -> float X.devicePixelRatio() -> float (shared captured text)
devicePixelRatioF function (self) -> float X.devicePixelRatioF() -> float (shared captured text)
devicePixelRatioFScale function (self) -> float X.devicePixelRatioFScale() -> float (shared captured text)
dotsPerMeterX function (self) -> int X.dotsPerMeterX() -> int (shared captured text)
dotsPerMeterY function (self) -> int X.dotsPerMeterY() -> int (shared captured text)
fill function (self, color: Any) -> None Fills the entire image with the given pixelValue. (shared captured text)
format function (self) -> Any Returns the format of the image. (shared captured text)
fromData function (self, data: Any, format: Any) -> Any X.fromData(data, format) -> PythonQt.QtGui.QImage (shared captured text)
hasAlphaChannel function (self) -> bool X.hasAlphaChannel() -> bool (shared captured text)
height function (self) -> int X.height() -> int (shared captured text)
heightMM function (self) -> int X.heightMM() -> int (shared captured text)
help function (self, *args: Any, **kwargs: Any) -> Any Shows the help of available methods for this class (shared captured text)
inherits function (self, *args: Any, **kwargs: Any) -> Any Returns if the class inherits or is of given type name (shared captured text)
initPainter function (self, painter: Any) -> Any (shared captured text)
invertPixels function (self, arg__1: Any) -> None Inverts all pixel values in the image. (shared captured text)
isGrayscale function (self) -> bool X.isGrayscale() -> bool (shared captured text)
isNull function (self) -> bool X.isNull() -> bool (shared captured text)
load function (self, device: Any, format: Any) -> bool X.load(device, format) -> bool (shared captured text)
loadFromData function (self, data: Any, aformat: Any) -> bool X.loadFromData(data, aformat) -> bool (shared captured text)
logicalDpiX function (self) -> int X.logicalDpiX() -> int (shared captured text)
logicalDpiY function (self) -> int X.logicalDpiY() -> int (shared captured text)
metric function (self, metric: Any) -> int X.metric(metric) -> int (shared captured text)
mirrored function (self, horizontally: bool, vertically: bool) -> Any X.mirrored(horizontally, vertically) -> PythonQt.QtGui.QImage (shared captured text)
mirrored_helper function (self, horizontal: bool, vertical: bool) -> Any X.mirrored_helper(horizontal, vertical) -> PythonQt.QtGui.QImage (shared captured text)
mirrored_inplace function (self, horizontal: bool, vertical: bool) -> None X.mirrored_inplace(horizontal, vertical) (shared captured text)
offset function (self) -> Any X.offset() -> PythonQt.QtCore.QPoint (shared captured text)
paintEngine function (self) -> Any X.paintEngine() -> PythonQt.QtGui.QPaintEngine (shared captured text)
paintingActive function (self) -> bool X.paintingActive() -> bool (shared captured text)
physicalDpiX function (self) -> int X.physicalDpiX() -> int (shared captured text)
physicalDpiY function (self) -> int X.physicalDpiY() -> int (shared captured text)
pixel function (self, x: Any, y: Any) -> int X.pixel(x, y) -> int (shared captured text)
pixelColor function (self, x: Any, y: Any) -> Any X.pixelColor(x, y) -> PythonQt.QtGui.QColor (shared captured text)
pixelFormat function (self) -> Any X.pixelFormat() -> PythonQt.QtGui.QPixelFormat (shared captured text)
pixelIndex function (self, x: Any, y: Any) -> int X.pixelIndex(x, y) -> int (shared captured text)
readFrom function (self, arg__1: Any) -> Any (shared captured text)
rect function (self) -> Any X.rect() -> PythonQt.QtCore.QRect (shared captured text)
redirected function (self, offset: Any) -> Any X.redirected(offset) -> PythonQt.QtGui.QPaintDevice (shared captured text)
rgbSwapped function (self) -> Any X.rgbSwapped() -> PythonQt.QtGui.QImage (shared captured text)
rgbSwapped_helper function (self) -> Any X.rgbSwapped_helper() -> PythonQt.QtGui.QImage (shared captured text)
rgbSwapped_inplace function (self) -> None (shared captured text)
save function (self, device: Any, format: Any, quality: int) -> bool X.save(device, format, quality) -> bool (shared captured text)
scaled function (self, w: Any, h: Any, aspectMode: Any, mode: Any) -> Any X.scaled(w, h, aspectMode, mode) -> PythonQt.QtGui.QImage (shared captured text)
scaledToHeight function (self, h: int, mode: Any) -> Any X.scaledToHeight(h, mode) -> PythonQt.QtGui.QImage (shared captured text)
scaledToWidth function (self, w: int, mode: Any) -> Any X.scaledToWidth(w, mode) -> PythonQt.QtGui.QImage (shared captured text)
scanLine function (self, line: Any) -> str Returns a pointer to the pixel data at the scanline with index i. (shared captured text)
setAlphaChannel function (self, alphaChannel: Any) -> None Sets the alpha channel of this image to the given alphaChannel. (shared captured text)
setColor function (self, i: int, c: int) -> None X.setColor(i, c) (shared captured text)
setColorCount function (self, arg__1: int) -> None Resizes the color table to contain colorCount entries. (shared captured text)
setDevicePixelRatio function (self, scaleFactor: float) -> None Sets the device pixel ratio for the image. (shared captured text)
setDotsPerMeterX function (self, arg__1: int) -> None Sets the number of pixels that fit horizontally in a physical meter, to x. (shared captured text)
setDotsPerMeterY function (self, arg__1: int) -> None Sets the number of pixels that fit vertically in a physical meter, to y. (shared captured text)
setOffset function (self, arg__1: Any) -> None Sets the number of pixels by which the image is intended to be offset by when positioning relative to other images, to offset. (shared captured text)
setPixel function (self, x: Any, y: Any, index_or_rgb: int) -> None X.setPixel(x, y, index_or_rgb) (shared captured text)
setPixelColor function (self, x: Any, y: Any, c: Any) -> None X.setPixelColor(x, y, c) (shared captured text)
setText function (self, key: str, value: str) -> None X.setText(key, value) (shared captured text)
sharedPainter function (self) -> Any X.sharedPainter() -> PythonQt.QtGui.QPainter (shared captured text)
size function (self) -> Any X.size() -> PythonQt.QtCore.QSize (shared captured text)
smoothScaled function (self, w: int, h: int) -> Any X.smoothScaled(w, h) -> PythonQt.QtGui.QImage (shared captured text)
swap function (self, other: Any) -> None Swaps image other with this image. (shared captured text)
text function (self, key: str) -> str X.text(key) -> str (shared captured text)
textKeys function (self) -> tuple X.textKeys() -> tuple (shared captured text)
toImageFormat function (self, format: Any) -> Any Converts format into a [QImage::Format](https://doc.qt.io/archives/qt-5.15/qimage.html#Format-enum) (shared captured text)
toPixelFormat function (self, format: Any) -> Any X.toPixelFormat(format) -> PythonQt.QtGui.QPixelFormat (shared captured text)
transformed function (self, matrix: Any, mode: Any) -> Any X.transformed(matrix, mode) -> PythonQt.QtGui.QImage (shared captured text)
trueMatrix function (self, arg__1: Any, w: int, h: int) -> Any X.trueMatrix(arg__1, w, h) -> PythonQt.QtGui.QMatrix (shared captured text)
valid function (self, x: Any, y: Any) -> bool X.valid(x, y) -> bool (shared captured text)
width function (self) -> int X.width() -> int (shared captured text)
widthMM function (self) -> int X.widthMM() -> int (shared captured text)
writeTo function (self, arg__1: Any) -> Any (shared captured text)