Class: QgsImageCache¶

class qgis.core.QgsImageCache¶

Bases: QgsAbstractContentCacheBase

A cache for images derived from raster files.

QgsImageCache stores pre-rendered resampled versions of raster image files, allowing efficient reuse without incurring the cost of resampling on every render.

QgsImageCache is not usually directly created, but rather accessed through QgsApplication.imageCache().

New in version 3.6.

QgsImageCache(parent: QObject = None) Constructor for QgsImageCache, with the specified parent object.

Methods

checkReply

Runs additional checks on a network reply to ensure that the reply content is consistent with that required by the cache.

childEvent

connectNotify

customEvent

disconnectNotify

isSignalConnected

maximumSize

Returns the maximum size of the cache, in bytes.

nextFrameDelay

For image formats that support animation, this function returns the number of milliseconds to wait until displaying the next frame in the animation.

onRemoteContentFetched

Triggered after remote content (i.e.

originalSize

Returns the original size (in pixels) of the image at the specified path.

pathAsImage

Returns the specified path rendered as an image.

prepareAnimation

Prepares for optimized retrieval of frames for the animation at the given path.

receivers

sender

senderSignalIndex

timerEvent

totalFrameCount

Returns the total frame count of the image at the specified path.

Signals

remoteImageFetched

pyqtSignal(*types, name: str = ..., revision: int = ..., arguments: Sequence = ...) -> PYQT_SIGNAL

checkReply(self, reply: QNetworkReply, path: str) → bool¶: Runs additional checks on a network reply to ensure that the reply content is consistent with that required by the cache.

childEvent(self, QChildEvent)¶

connectNotify(self, QMetaMethod)¶

customEvent(self, QEvent)¶

disconnectNotify(self, QMetaMethod)¶

isSignalConnected(self, QMetaMethod) → bool¶

maximumSize(self) → int¶

Returns the maximum size of the cache, in bytes.

New in version 3.26.

Return type:: int

nextFrameDelay(self, path: str, currentFrame: int = 0, blocking: bool = False) → 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.

path may be a local file, remote (HTTP) url, or a base 64 encoded string (with a “base64:” prefix).

If path is a remote file, then -1 may be returned while the image is in the process of being fetched.

The blocking boolean forces to wait for loading before returning the frame delay. The content is loaded in the same thread to ensure provided the original size. WARNING: the blocking parameter must NEVER be True from GUI based applications (like the main QGIS application) or crashes will result. Only for use in external scripts or QGIS server.

If the image could not be read or is not an animated format then -1 is returned.

New in version 3.26.

Parameters:

path (str) –
currentFrame (int = 0) –
blocking (bool = False) –

Return type:

int

onRemoteContentFetched(self, url: str, success: bool)¶

Triggered after remote content (i.e. HTTP linked content at the given url) has been fetched.

The success argument will be True if the content was successfully fetched, or False if it was not fetched successfully.

originalSize(self, path: str, blocking: bool = False) → QSize¶

Returns the original size (in pixels) of the image at the specified path.

path may be a local file, remote (HTTP) url, or a base 64 encoded string (with a “base64:” prefix).

If path is a remote file, then an invalid size may be returned while the image is in the process of being fetched.

The blocking boolean forces to wait for loading before returning the original size. The content is loaded in the same thread to ensure provided the original size. WARNING: the blocking parameter must NEVER be True from GUI based applications (like the main QGIS application) or crashes will result. Only for use in external scripts or QGIS server.

If the image could not be read then an invalid QSize is returned.

Parameters:

path (str) –
blocking (bool = False) –

Return type:

QSize

pathAsImage(self, path: str, size: QSize, keepAspectRatio: bool, opacity: float, blocking: bool = False, targetDpi: float = 96, frameNumber: int = -1) → Tuple[QImage, bool]¶

Returns the specified path rendered as an image. If possible, a pre-existing cached version of the image will be used. If not, the image is fetched and resampled to the desired size, and then the result cached for subsequent lookups.

Parameters:

path (str) – may be a local file, remote (HTTP) url, or a base 64 encoded string (with a “base64:” prefix).
size (QSize) – dictates the target size of the image. An invalid size indicates the original raster image size (with no resampling). A size in which the width or height is set to zero will have the zeroed value automatically computed when keepAspectRatio is True.
keepAspectRatio (bool) – if True then the original raster aspect ratio will be maintained during any resampling operations.
opacity (float) – dictates the opacity of the image (between 0 and 1).
blocking (bool = False) – if True, forces to wait for loading before returning image. The content is loaded in the same thread to ensure provided the image. WARNING: the blocking parameter must NEVER be True from GUI based applications (like the main QGIS application) or crashes will result. Only for use in external scripts or QGIS server.
targetDpi (float = 96) – (since QGIS 3.22) can be used to specify an explicit DPI to render the image at. This is used for some image formats (e.g. PDF) to ensure that content is rendered at the desired DPI. This argument is only used when an invalid size argument is specified. If a valid size is specified then the image will always be rendered at this size, regardless of the targetDpi.
frameNumber (int = -1) – (since QGIS 3.26) specifies a frame number for image formats which support animations. This should be set to -1 if not required.

Return type:

Tuple[QImage, bool]

Returns:

rendered image
fitsInCache: will be set to True if the resultant raster was of a sufficiently small size to store in the cache

prepareAnimation(self, path: str)¶

Prepares for optimized retrieval of frames for the animation at the given path.

New in version 3.26.

Parameters:: path (str) –

receivers(self, PYQT_SIGNAL) → int¶

remoteImageFetched¶

pyqtSignal(*types, name: str = …, revision: int = …, arguments: Sequence = …) -> PYQT_SIGNAL

types is normally a sequence of individual types. Each type is either a type object or a string that is the name of a C++ type. Alternatively each type could itself be a sequence of types each describing a different overloaded signal. name is the optional C++ name of the signal. If it is not specified then the name of the class attribute that is bound to the signal is used. revision is the optional revision of the signal that is exported to QML. If it is not specified then 0 is used. arguments is the optional sequence of the names of the signal’s arguments.

Parameters:

name (str = ...) –
revision (int = ...) –
arguments (Sequence = ...) –

Return type:

PYQT_SIGNAL

sender(self) → QObject¶

senderSignalIndex(self) → int¶

timerEvent(self, QTimerEvent)¶

totalFrameCount(self, path: str, blocking: bool = False) → int¶

Returns the total frame count of the image at the specified path.

path may be a local file, remote (HTTP) url, or a base 64 encoded string (with a “base64:” prefix).

If path is a remote file, then -1 may be returned while the image is in the process of being fetched.

The blocking boolean forces to wait for loading before returning the frame count. The content is loaded in the same thread to ensure provided the original size. WARNING: the blocking parameter must NEVER be True from GUI based applications (like the main QGIS application) or crashes will result. Only for use in external scripts or QGIS server.

If the image could not be read or is not an animated format then -1 is returned

New in version 3.26.

Parameters:

path (str) –
blocking (bool = False) –

Return type:

int