wolfhece.cached_images ====================== .. py:module:: wolfhece.cached_images Module Contents --------------- .. py:data:: NTILES :value: 5 .. py:class:: TilesInfo .. py:attribute:: bounds :type: tuple[float, float, float, float] .. py:attribute:: tile_size :type: float .. py:attribute:: nbx :type: int .. py:attribute:: nby :type: int .. py:attribute:: width :type: int .. py:attribute:: height :type: int .. py:class:: CachedImages(epsg: str, max_resolution: float, magnetic_grid: float = 500.0, max_workers: int = 4) Manage a cache of images obtained from web services, stored on disk using diskcache. The cache is organized by service, category, subcategory, and spatial extent (xmin, xmax, ymin, ymax). The get method retrieves images from the cache if they exist, or fetches them from the web service and adds them to the cache if they do not. The clear_cache method allows clearing the entire cache when needed. .. py:attribute:: epsg .. py:attribute:: max_resolution .. py:attribute:: _magnetic_grid_size :value: 500.0 .. py:attribute:: _cache .. py:attribute:: _executor .. py:method:: _fetch_one_image_and_cache(service: wolfhece.PyWMS.WebService, category: str, subcategory: str, xmin: float, xmax: float, ymin: float, ymax: float, width: int = 500, height: int = 500) -> PIL.Image.Image | None Fetch an image from the specified web service and add it to the cache :param service: The web service from which to fetch the image (e.g., WebService.Walonmap) :param category: The category of the image to fetch (e.g., 'Orthophotos') :param subcategory: The subcategory of the image to fetch (e.g., 'Last') :param xmin: Minimum X coordinate of the spatial extent for which to fetch the image :param xmax: Maximum X coordinate of the spatial extent for which to fetch the image :param ymin: Minimum Y coordinate of the spatial extent for which to fetch the image :param ymax: Maximum Y coordinate of the spatial extent for which to fetch the image :param width: Width of the image to fetch in pixels :param height: Height of the image to fetch in pixels :return: The fetched image as a PIL Image object, or None if there was an error .. py:method:: _align_to_magnetic_grid(value: float) -> float Align a coordinate value to the nearest grid line based on the specified grid size. :param value: The coordinate value to align :return: The aligned coordinate value .. py:method:: _get_bounds_to_magnetic_grid(xmin: float, xmax: float, ymin: float, ymax: float) -> tuple[float, float, float, float] Align the spatial bounds to the grid based on the specified grid size. :param xmin: Minimum X coordinate :param xmax: Maximum X coordinate :param ymin: Minimum Y coordinate :param ymax: Maximum Y coordinate :return: Tuple of (aligned_xmin, aligned_xmax, aligned_ymin, aligned_ymax) .. py:method:: _get_tile_size(xmin: float, xmax: float, ymin: float, ymax: float) -> int Determine the best tile size for caching based on the requested resolution and the maximum resolution of the cache. We accept NTILES tiles in each direction as a good balance between cache hit rate and number of requests. :param xmin: Minimum X coordinate :param xmax: Maximum X coordinate :param ymin: Minimum Y coordinate :param ymax: Maximum Y coordinate :return: The optimal tile size in coordinate units .. py:method:: _get_infos(xmin: float, xmax: float, ymin: float, ymax: float, scale_x: float = 1.0, scale_y: float = 1.0) -> TilesInfo Prepare the spatial bounds by aligning them to the magnetic grid and determining the appropriate tile size. :param xmin: Minimum X coordinate :param xmax: Maximum X coordinate :param ymin: Minimum Y coordinate :param ymax: Maximum Y coordinate :param scale_x: Scale factor for X dimension (default: 1.0) :param scale_y: Scale factor for Y dimension (default: 1.0) :return: TilesInfo object containing tile information and bounds .. py:method:: _check_if_all_is_in_cache(service: wolfhece.PyWMS.WebService, category: str, subcategory: str, xmin: float, xmax: float, ymin: float, ymax: float, scale_x: float = 1.0, scale_y: float = 1.0) -> bool Perform a rapid check to see if the requested image is likely to be in the cache based on the magnetic grid size and spatial extent. :param service: The web service to check :param category: The image category :param subcategory: The image subcategory :param xmin: Minimum X coordinate :param xmax: Maximum X coordinate :param ymin: Minimum Y coordinate :param ymax: Maximum Y coordinate :param scale_x: Scale factor for X dimension (default: 1.0) :param scale_y: Scale factor for Y dimension (default: 1.0) :return: True if all requested tiles are in cache, False otherwise .. py:method:: _async_add_and_cache(service: wolfhece.PyWMS.WebService, category: str, subcategory: str, xmin: float, xmax: float, ymin: float, ymax: float, width: int = 500, height: int = 500) -> concurrent.futures.Future Asynchronously submit a fetch task to the thread pool without blocking. Returns a Future object that can be waited on later. This allows multiple requests to be submitted in parallel before waiting for results. :param service: The web service from which to fetch the image :param category: The image category :param subcategory: The image subcategory :param xmin: Minimum X coordinate :param xmax: Maximum X coordinate :param ymin: Minimum Y coordinate :param ymax: Maximum Y coordinate :param width: Width of image in pixels (default: 500) :param height: Height of image in pixels (default: 500) :return: A Future object that resolves to the fetched and cached image .. py:method:: get_dict(service: wolfhece.PyWMS.WebService, category: str, subcategory: str, xmin: float, xmax: float, ymin: float, ymax: float, scale_x: float = 1.0, scale_y: float = 1.0, async_fetch: bool = True) -> dict[tuple[float, float, float, float], PIL.Image.Image] Retrieve an image from the cache if it exists, or fetch it from the web service and add it to the cache if it does not. :param service: The web service from which to retrieve the image (e.g., WebService.Walonmap) :param category: The category of the image to retrieve (e.g., 'Orthophotos') :param subcategory: The subcategory of the image to retrieve (e.g., 'Last') :param xmin: Minimum X coordinate of the spatial extent for which to retrieve the image :param xmax: Maximum X coordinate of the spatial extent for which to retrieve the image :param ymin: Minimum Y coordinate of the spatial extent for which to retrieve the image :param ymax: Maximum Y coordinate of the spatial extent for which to retrieve the image :param async_fetch: Whether to fetch images asynchronously (default is True) :return: A dictionary mapping spatial extents (xmin, xmax, ymin, ymax) to the corresponding images as PIL Image objects .. py:method:: get_image(service: wolfhece.PyWMS.WebService, category: str, subcategory: str, xmin: float, xmax: float, ymin: float, ymax: float, scale_x: float = 1.0, scale_y: float = 1.0, async_fetch: bool = True, direct_fetch: bool = False) -> PIL.Image.Image Retrieve an image from the cache if it exists, or fetch it from the web service and add it to the cache if it does not. :param service: The web service from which to retrieve the image (e.g., WebService.Walonmap) :param category: The category of the image to retrieve (e.g., 'Orthophotos') :param subcategory: The subcategory of the image to retrieve (e.g., 'Last') :param xmin: Minimum X coordinate of the spatial extent for which to retrieve the image :param xmax: Maximum X coordinate of the spatial extent for which to retrieve the image :param ymin: Minimum Y coordinate of the spatial extent for which to retrieve the image :param ymax: Maximum Y coordinate of the spatial extent for which to retrieve the image :param async_fetch: Whether to fetch images asynchronously (default is True) :param direct_fetch: Whether to fetch images directly from the web service (default is False) :return: The retrieved image as a PIL Image object .. py:method:: get_image_for_async(service: wolfhece.PyWMS.WebService, category: str, subcategory: str, xmin: float, xmax: float, ymin: float, ymax: float, scale_x: float = 1.0, scale_y: float = 1.0, direct_fetch: bool = False) -> PIL.Image.Image | None Synchronous wrapper for async loaders - returns image directly. This method is designed to be called from an asyncio executor for non-blocking operation. It combines tiles if needed and returns the final image suitable for OpenGL texture loading. :param service: The web service from which to retrieve the image :param category: The category of the image to retrieve :param subcategory: The subcategory of the image to retrieve :param xmin: Minimum X coordinate of the spatial extent :param xmax: Maximum X coordinate of the spatial extent :param ymin: Minimum Y coordinate of the spatial extent :param ymax: Maximum Y coordinate of the spatial extent :param scale_x: Scale factor for X dimension (default: 1.0) :param scale_y: Scale factor for Y dimension (default: 1.0) :param direct_fetch: Whether to fetch the entire extent as one image :return: The retrieved image as a PIL Image object, or None if there was an error .. py:method:: clear_cache() Clear the entire cache of images from disk