Class: QgsImageCache¶
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()
.
Added in version 3.6.
Class Hierarchy¶
Base classes¶
A QObject derived base class for |
|
Methods
Returns the maximum size of the cache, in bytes. |
|
For image formats that support animation, this function returns the number of milliseconds to wait until displaying the next frame in the animation. |
|
Returns the original size (in pixels) of the image at the specified path. |
|
Returns the specified path rendered as an image. |
|
Prepares for optimized retrieval of frames for the animation at the given path. |
|
Returns the total frame count of the image at the specified path. |
Signals
Emitted when the cache has finished retrieving an image file from a remote url. |
- class qgis.core.QgsImageCache[source]¶
Bases:
QgsAbstractContentCacheBase
- __init__(parent: QObject | None = None)
Constructor for QgsImageCache, with the specified
parent
object.- Parameters:
parent (Optional[QObject] = None)
- maximumSize(self) int [source]¶
Returns the maximum size of the cache, in bytes.
Added in version 3.26.
- Return type:
int
- nextFrameDelay(self, path: str | None, currentFrame: int = 0, blocking: bool = False) int [source]¶
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: theblocking
parameter must NEVER beTrue
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.
Added in version 3.26.
- Parameters:
path (Optional[str])
currentFrame (int = 0)
blocking (bool = False)
- Return type:
int
- originalSize(self, path: str | None, blocking: bool = False) QSize [source]¶
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: theblocking
parameter must NEVER beTrue
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 (Optional[str])
blocking (bool = False)
- Return type:
QSize
- pathAsImage(self, path: str | None, size: QSize, keepAspectRatio: bool, opacity: float, blocking: bool = False, targetDpi: float = 96, frameNumber: int = -1)[source]¶
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 (Optional[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: theblocking
parameter must NEVER beTrue
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 validsize
is specified then the image will always be rendered at this size, regardless of thetargetDpi
.frameNumber (int = -1) -> (QImage) – (since QGIS 3.26) specifies a frame number for image formats which support animations. This should be set to -1 if not required.
- Returns:
rendered image
fitsInCache:
True
if the resultant raster was of a sufficiently small size to store in the cache
- prepareAnimation(self, path: str | None)[source]¶
Prepares for optimized retrieval of frames for the animation at the given
path
.Added in version 3.26.
- Parameters:
path (Optional[str])
- signal remoteImageFetched(url: str)[source]¶
Emitted when the cache has finished retrieving an image file from a remote
url
.- Parameters:
url (str)
- totalFrameCount(self, path: str | None, blocking: bool = False) int [source]¶
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: theblocking
parameter must NEVER beTrue
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
Added in version 3.26.
- Parameters:
path (Optional[str])
blocking (bool = False)
- Return type:
int