wolfhece.async_image_loader
===========================

.. py:module:: wolfhece.async_image_loader

.. autoapi-nested-parse::

   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
---------------

.. py:class:: ImageLoadPriority(*args, **kwds)

   Bases: :py:obj:`enum.Enum`

   .. autoapi-inheritance-diagram:: wolfhece.async_image_loader.ImageLoadPriority
      :parts: 1
      :private-bases:


   Priority levels for image loading


   .. py:attribute:: LOW
      :value: 3



   .. py:attribute:: NORMAL
      :value: 2



   .. py:attribute:: HIGH
      :value: 1



.. py:class:: ImageLoadRequest

   Represents a request to load an image asynchronously


   .. py:attribute:: id
      :type:  str


   .. py:attribute:: loader_func
      :type:  Callable


   .. py:attribute:: callback
      :type:  Callable[[Optional[PIL.Image.Image]], None]


   .. py:attribute:: priority
      :type:  ImageLoadPriority


   .. py:attribute:: bounds
      :type:  tuple[float, float, float, float]
      :value: None



.. py:class:: AsyncImageLoader(max_workers: int = 4, loop: Optional[asyncio.AbstractEventLoop] = 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.


   .. py:attribute:: max_workers
      :value: 4



   .. py:attribute:: loop


   .. py:attribute:: _queue
      :type:  asyncio.PriorityQueue


   .. py:attribute:: _active_loads
      :type:  dict[str, asyncio.Task]


   .. py:attribute:: _pending_requests
      :type:  dict[str, ImageLoadRequest]


   .. py:attribute:: _running
      :value: False



   .. py:attribute:: _worker_task
      :type:  Optional[asyncio.Task]
      :value: None



   .. py:attribute:: _executor


   .. py:method:: start()

      Start the image loader background worker



   .. py:method:: stop()

      Stop the image loader and cleanup



   .. py:method:: schedule_load(request_id: str, loader_func: Callable, callback: Callable[[Optional[PIL.Image.Image]], None], priority: ImageLoadPriority = ImageLoadPriority.NORMAL, bounds: tuple[float, float, float, float] = None) -> None

      Schedule an image to be loaded asynchronously

      :param request_id: Unique identifier for this request (used for deduplication)
      :param loader_func: Callable that returns the image (PIL Image or None)
      :param callback: Callable to invoke when image is ready: callback(image)
      :param priority: ImageLoadPriority level
      :param bounds: Optional spatial bounds (xmin, xmax, ymin, ymax) for tracking



   .. py:method:: _worker_loop()
      :async:


      Main worker loop that processes the image queue



   .. py:method:: _load_image(request: ImageLoadRequest) -> None
      :async:


      Load an image asynchronously using executor

      :param request: ImageLoadRequest to process



   .. py:method:: 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.

      :param texture_id: The texture identifier (e.g., self.idx from wolf_texture)
      :param keep_request_id: The request ID to keep (typically the most recent one)
      :return: Number of requests cancelled



   .. py:method:: get_pending_count() -> int

      Get the number of pending image load requests



.. py:data:: _global_loader
   :type:  Optional[AsyncImageLoader]
   :value: None


.. py:function:: get_global_loader(max_workers: int = 4) -> AsyncImageLoader

   Get or create the global image loader instance

   :param max_workers: Number of worker threads (only used on first call)
   :return: Global AsyncImageLoader instance


.. py:function:: stop_global_loader()

   Stop the global image loader