wolfhece.async_image_loader

Author: HECE - University of Liege, Pierre Archambeau Date: 2024

Copyright (c) 2024 University of Liege. All rights reserved.

This script and its content are protected by copyright law. Unauthorized copying or distribution of this file, via any medium, is strictly prohibited.

Module Contents

class wolfhece.async_image_loader.ImageLoadPriority(*args, **kwds)

Bases: enum.Enum

Priority levels for image loading

LOW = 3

NORMAL = 2

HIGH = 1

class wolfhece.async_image_loader.ImageLoadRequest

Represents a request to load an image asynchronously

id: str

loader_func: Callable

callback: Callable[[PIL.Image.Image | None], None]

priority: ImageLoadPriority

bounds: tuple[float, float, float, float] = None

class wolfhece.async_image_loader.AsyncImageLoader(max_workers: int = 4, loop: asyncio.AbstractEventLoop | None = None)

Manages asynchronous loading of images with a priority queue.

Allows scheduling images to be loaded in the background without blocking the UI. Uses asyncio with ThreadPoolExecutor for blocking I/O operations.

max_workers = 4

loop

_queue: asyncio.PriorityQueue

_active_loads: dict[str, asyncio.Task]

_pending_requests: dict[str, ImageLoadRequest]

_running = False

_worker_task: asyncio.Task | None = None

_executor

start()

Start the image loader background worker

stop()

Stop the image loader and cleanup

schedule_load(request_id: str, loader_func: Callable, callback: Callable[[PIL.Image.Image | None], None], priority: ImageLoadPriority = ImageLoadPriority.NORMAL, bounds: tuple[float, float, float, float] = None) → None

Schedule an image to be loaded asynchronously

Parameters:

• request_id – Unique identifier for this request (used for deduplication)

• loader_func – Callable that returns the image (PIL Image or None)

• callback – Callable to invoke when image is ready: callback(image)

• priority – ImageLoadPriority level

• bounds – Optional spatial bounds (xmin, xmax, ymin, ymax) for tracking

async _worker_loop()

Main worker loop that processes the image queue

async _load_image(request: ImageLoadRequest) → None

Load an image asynchronously using executor

Parameters:

request – ImageLoadRequest to process

cancel_obsolete_for_texture(texture_id: str, keep_request_id: str) → int

Cancel all pending/active loads for a texture except the specified request

Useful when panning/zooming: old requests for the same texture become obsolete and can be cleared from the queue to improve responsiveness.

Parameters:

• texture_id – The texture identifier (e.g., self.idx from wolf_texture)

• keep_request_id – The request ID to keep (typically the most recent one)

Returns:

Number of requests cancelled

get_pending_count() → int

Get the number of pending image load requests

wolfhece.async_image_loader._global_loader: AsyncImageLoader | None = None

wolfhece.async_image_loader.get_global_loader(max_workers: int = 4) → AsyncImageLoader

Get or create the global image loader instance

Parameters:

max_workers – Number of worker threads (only used on first call)

Returns:

Global AsyncImageLoader instance

wolfhece.async_image_loader.stop_global_loader()

Stop the global image loader