images

The module defines ImageCache, a utility class used to store image and color data and all other utility methods needed to create, load and store thumbnail images.

Use the high-level get_thumbnail() to get an item’s thumbnail. This relies on the ImageCache to retrieve data and will return an existing thumbnail image or a suitable placeholder image. See get_placeholder_path().

Note

The thumbnail files are stored in the bookmark item cache folder (see common.bookmark_cache_dir).

Under the hood, get_thumbnail() uses ImageCache.get_pixmap() and ImageCache.get_image().

We’re using OpenImageIO to generate thumbnails. To load an image using OpenImageIO as a QtGui.QImage see oiio_get_qimage().

To load gui resources, use ImageCache.rsc_pixmap().

Classes:

ImageCache

Utility class for storing, and accessing image data.

Functions:

create_thumbnail_from_image(server, job, ...)	Creates a thumbnail from a given image file and saves it as the source file's thumbnail image.
get_cached_thumbnail_path(server, job, root, ...)	Returns the path to a cached thumbnail file.
get_oiio_extensions()	Returns a list of extensions accepted by OpenImageIO.
get_oiio_namefilters()	Gets all accepted formats from the oiio build as a namefilter list.
get_placeholder_path(file_path, fallback)	Returns an image path used to represent an item.
get_thumbnail(server, job, root, source[, ...])	Get the thumbnail of a list item.
init_image_cache()	Initialises the OpenImageIO and our own internal image cache.
init_pixel_ratio()	Initialises the pixel ratio value.
init_resources()	Initialises the GUI image resources.
oiio_get_buf(source[, hash, force, subimage])	Checks and loads a source image with OpenImageIO's format reader.
oiio_get_qimage(source[, buf, force])	Load the pixel data using OpenImageIO and return it as a RGBA8888 / RGB888 QImage.
wait_for_lock(source[, timeout])	Waits for a maximum amount of time when a lock file is present.

Data:

QT_IMAGE_FORMATS

The list of image formats QT is configured to read.

class bookmarks.images.ImageCache

Bases: QObject

Utility class for storing, and accessing image data.

You shouldn’t have to use the value() and setValue() methods. Instead, use the get_image() and get_pixmap() - they’re high-level functions, that will automatically cache and convert resources.

The stored data is associated with a type and hash (see get_hash()) and size. This means a single source image can have multiple QPixmap and QImage cache entries as various sizes are requested and cached.

common.image_cache[cache_type][hash][size] = pixmap

To remove a resource from the cache use the flush() method.

Methods:

contains(_hash, cache_type)	Checks if the given hash exists in the database.
flush(source)	Flushes all values associated with a given source from the image cache.
get_color(source[, hash, force])	Gets a cached QColor associated with the given source.
get_image(source, size[, hash, force, oiio])	Loads, resizes source as a QImage and stores it for later use.
get_pixmap(source, size[, hash, force, oiio])	Loads, resizes source as a QPixmap and stores it for later use.
make_color(source[, hash])	Calculate the average color of a source image.
resize_image(image, size)	Returns a scaled copy of the image that fits in size.
rsc_pixmap(name, color, size[, opacity, ...])	Loads an image resource and returns it as a resized (and recolored) QPixmap.
setValue(hash, value, cache_type[, size])	Sets a value in the ImageCache using hash and the cache_type.
value(hash, cache_type[, size])	Get a value from the ImageCache.

classmethod contains(_hash, cache_type)

Checks if the given hash exists in the database.

classmethod flush(source)

Flushes all values associated with a given source from the image cache.

Parameters:

source (str) – A file path.

classmethod get_color(source, hash=None, force=False)

Gets a cached QColor associated with the given source.

Parameters:

• source (str) – A file path.

• force (bool) – Force value recache.

• hash (str) – Hash value override.

classmethod get_image(source, size, hash=None, force=False, oiio=False)

Loads, resizes source as a QImage and stores it for later use.

When size is ‘-1’ the full image will be loaded without resizing.

The resource will be stored as QImage instance at common.image_cache[ImageType][hash]. The hash value is generated by default using source’s value but this can be overwritten by explicitly setting hash.

Parameters:

• source (str) – Path to an OpenImageIO compliant image file.

• size (int) – The size of the requested image.

• hash (str) – Use this hash key instead source to store the data.

• force (bool) – Force reloads the image from source.

• oiio (bool) – Use OpenImageIO to load the image data.

Returns:

The loaded and resized QImage, or None if loading fails.

Return type:

QImage

classmethod get_pixmap(source, size, hash=None, force=False, oiio=False)

Loads, resizes source as a QPixmap and stores it for later use.

When size is ‘-1’ the full image will be loaded without resizing.

The resource will be stored as a QPixmap instance and saved to common.image_cache[PixmapType][hash]. The hash value is generated using source but this can be overwritten by explicitly setting hash.

Note

It is not possible to call this method outside the main gui thread. Use get_image() instead. This method is backed by get_image() anyway.

Parameters:

• source (str) – Path to an image file.

• size (int) – The size of the requested image.

• hash (str) – Use this hash key instead of a source’s hash value to store the data.

• force (bool) – Force reloads the pixmap.

• oiio (bool) – Use OpenImageIO to load the image, instead of Qt.

Returns:

The loaded and resized QPixmap, or None.

Return type:

QPixmap

classmethod make_color(source, hash=None)

Calculate the average color of a source image.

Parameters:

• source (str) – Path to an image file.

• hash (str, optional) – Has value to use instead of source image’s hash.

Returns:

The average color of the source image.

Return type:

QtGui.QImage

static resize_image(image, size)

Returns a scaled copy of the image that fits in size.

Parameters:

• image (QImage) – The image to rescale.

• size (int) – The size of the square to fit.

Returns:

The resized copy of the original image.

Return type:

QImage

classmethod rsc_pixmap(name, color, size, opacity=1.0, resource=common.GuiResource, get_path=False, oiio=False)

Loads an image resource and returns it as a resized (and recolored) QPixmap.

Parameters:

• name (str) – Name of the resource without the extension.

• color (QColor or None) – The color of the icon.

• size (int or None) – The size of pixmap.

• opacity (float) – Sets the opacity of the returned pixmap.

• resource (str) – Optional resource type. Default: common.GuiResource.

• get_path (bool) – Returns a path when True.

Returns:

A QPixmap of the requested resource, or a str path if get_path is True. None if the resource could not be found.

classmethod setValue(hash, value, cache_type, size=None)

Sets a value in the ImageCache using hash and the cache_type.

If force is True, we will flush the sizes stored in the cache before setting the new value. This only applies to Image- and PixmapTypes.

classmethod value(hash, cache_type, size=None)

Get a value from the ImageCache.

Parameters:

hash (str) – A hash value generated by common.get_hash

bookmarks.images.create_thumbnail_from_image(server, job, root, source, image, proxy=False)

Creates a thumbnail from a given image file and saves it as the source file’s thumbnail image.

The server, job, root, source arguments refer to a file we want to create a new thumbnail for. The image argument should be a path to an image file that will be converted using bookmarks_oiio.make_thumbnail() to a thumbnail image and saved to our image cache and disk to represent source.

Parameters:

• server (str) – server path segment.

• job (str) – job path segment.

• root (str) – root path segment.

• source (str) – The full file path.

• image (str) – Path to an image file to use as a thumbnail for source.

• proxy (bool, optional) – Specify if the source is an image sequence and if the proxy path should be used to save the thumbnail instead.

bookmarks.images.get_cached_thumbnail_path(server, job, root, source, proxy=False)

Returns the path to a cached thumbnail file.

When proxy is set to True or the source file is a sequence, we will use the sequence’s first item as our thumbnail source.

Parameters:

• server (str) – server path segment.

• job (str) – job path segment.

• root (str) – root path segment.

• source (str) – The full file path.

Returns:

The resolved thumbnail path.

Return type:

str

bookmarks.images.get_oiio_extensions()

Returns a list of extensions accepted by OpenImageIO.

bookmarks.images.get_oiio_namefilters()

Gets all accepted formats from the oiio build as a namefilter list. Use the return value on the QFileDialog.setNameFilters() method.

bookmarks.images.get_placeholder_path(file_path, fallback)

Returns an image path used to represent an item.

In absence of a custom user, or generated thumbnail, we’ll try and find one based on the file’s format extension.

Parameters:

• file_path (str) – Path to a file or folder.

• fallback (str) – An image to use if no suitable placeholder is found.

Returns:

Path to the placeholder image.

Return type:

str

bookmarks.images.get_thumbnail(server, job, root, source, size=common.thumbnail_size, fallback_thumb='placeholder', get_path=False)

Get the thumbnail of a list item.

When an item is missing a bespoke cached thumbnail file, we will try to load a fallback image instead. For files, this will be an image associated with the file-format, or for asset and bookmark items, we will look in bookmark’s, then the job’s root folder to see if we can find a thumbnail.png file. When all lookup fails we’ll return the provided fallback_thumb.

See also get_cached_thumbnail_path() for a lower level method used to find a cached image file.

Parameters:

• server (str) – server path segment.

• job (str) – job path segment.

• root (str) – root path segment.

• source (str) – Full file path of source item.

• size (int) – The size of the thumbnail image in pixels.

• fallback_thumb (str) – A fallback thumbnail image.

• get_path (bool) – Returns a path instead of a QPixmap if set to True.

Returns:

(QPixmap, QColor), or (None, None). str: Path to the thumbnail file when get_path=True.

Return type:

tuple

bookmarks.images.init_image_cache()

Initialises the OpenImageIO and our own internal image cache.

bookmarks.images.init_pixel_ratio()

Initialises the pixel ratio value.

bookmarks.images.init_resources()

Initialises the GUI image resources.

bookmarks.images.oiio_get_buf(source, hash=None, force=False, subimage=0)

Checks and loads a source image with OpenImageIO’s format reader.

Parameters:

• source (str) – Path to an OpenImageIO compatible image file.

• hash (str) – Specify the hash manually, otherwise will be generated.

• force (bool) – When true, forces the buffer to be re-cached.

Returns:

An ImageBuf instance or None if the image cannot be read.

Return type:

ImageBuf

bookmarks.images.oiio_get_qimage(source, buf=None, force=True)

Load the pixel data using OpenImageIO and return it as a RGBA8888 / RGB888 QImage.

Parameters:

• source (str) – Path to an OpenImageIO readable image.

• buf (OpenImageIO.ImageBuf) – When buf is valid ImageBuf instance it will be used as the source instead of source. Defaults to None.

Returns:

An QImage instance or None if the image/source is invalid.

Return type:

QImage

bookmarks.images.wait_for_lock(source, timeout=1.0)

Waits for a maximum amount of time when a lock file is present.

Parameters:

• source (str) – A file path.

• timeout (float) – The maximum amount of time to wait in seconds.

bookmarks.images.QT_IMAGE_FORMATS = {'bmp', 'pbm', 'pgm', 'png', 'ppm', 'xbm', 'xpm'}

The list of image formats QT is configured to read.