wolfhece.cached_images

Module Contents

wolfhece.cached_images.NTILES = 5

class wolfhece.cached_images.TilesInfo

bounds: tuple[float, float, float, float]

tile_size: float

nbx: int

nby: int

width: int

height: int

class wolfhece.cached_images.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.

epsg

max_resolution

_magnetic_grid_size = 500.0

_cache

_executor

_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

Parameters:

• service – The web service from which to fetch the image (e.g., WebService.Walonmap)

• category – The category of the image to fetch (e.g., ‘Orthophotos’)

• subcategory – The subcategory of the image to fetch (e.g., ‘Last’)

• xmin – Minimum X coordinate of the spatial extent for which to fetch the image

• xmax – Maximum X coordinate of the spatial extent for which to fetch the image

• ymin – Minimum Y coordinate of the spatial extent for which to fetch the image

• ymax – Maximum Y coordinate of the spatial extent for which to fetch the image

• width – Width of the image to fetch in pixels

• height – Height of the image to fetch in pixels

Returns:

The fetched image as a PIL Image object, or None if there was an error

_align_to_magnetic_grid(value: float) → float

Align a coordinate value to the nearest grid line based on the specified grid size.

Parameters:

value – The coordinate value to align

Returns:

The aligned coordinate value

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

Parameters:

• xmin – Minimum X coordinate

• xmax – Maximum X coordinate

• ymin – Minimum Y coordinate

• ymax – Maximum Y coordinate

Returns:

Tuple of (aligned_xmin, aligned_xmax, aligned_ymin, aligned_ymax)

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

Parameters:

• xmin – Minimum X coordinate

• xmax – Maximum X coordinate

• ymin – Minimum Y coordinate

• ymax – Maximum Y coordinate

Returns:

The optimal tile size in coordinate units

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

Parameters:

• xmin – Minimum X coordinate

• xmax – Maximum X coordinate

• ymin – Minimum Y coordinate

• ymax – Maximum Y coordinate

• scale_x – Scale factor for X dimension (default: 1.0)

• scale_y – Scale factor for Y dimension (default: 1.0)

Returns:

TilesInfo object containing tile information and bounds

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

Parameters:

• service – The web service to check

• category – The image category

• subcategory – The image subcategory

• xmin – Minimum X coordinate

• xmax – Maximum X coordinate

• ymin – Minimum Y coordinate

• ymax – Maximum Y coordinate

• scale_x – Scale factor for X dimension (default: 1.0)

• scale_y – Scale factor for Y dimension (default: 1.0)

Returns:

True if all requested tiles are in cache, False otherwise

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

Parameters:

• service – The web service from which to fetch the image

• category – The image category

• subcategory – The image subcategory

• xmin – Minimum X coordinate

• xmax – Maximum X coordinate

• ymin – Minimum Y coordinate

• ymax – Maximum Y coordinate

• width – Width of image in pixels (default: 500)

• height – Height of image in pixels (default: 500)

Returns:

A Future object that resolves to the fetched and cached image

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.

Parameters:

• service – The web service from which to retrieve the image (e.g., WebService.Walonmap)

• category – The category of the image to retrieve (e.g., ‘Orthophotos’)

• subcategory – The subcategory of the image to retrieve (e.g., ‘Last’)

• xmin – Minimum X coordinate of the spatial extent for which to retrieve the image

• xmax – Maximum X coordinate of the spatial extent for which to retrieve the image

• ymin – Minimum Y coordinate of the spatial extent for which to retrieve the image

• ymax – Maximum Y coordinate of the spatial extent for which to retrieve the image

• async_fetch – Whether to fetch images asynchronously (default is True)

Returns:

A dictionary mapping spatial extents (xmin, xmax, ymin, ymax) to the corresponding images as PIL Image objects

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.

Parameters:

• service – The web service from which to retrieve the image (e.g., WebService.Walonmap)

• category – The category of the image to retrieve (e.g., ‘Orthophotos’)

• subcategory – The subcategory of the image to retrieve (e.g., ‘Last’)

• xmin – Minimum X coordinate of the spatial extent for which to retrieve the image

• xmax – Maximum X coordinate of the spatial extent for which to retrieve the image

• ymin – Minimum Y coordinate of the spatial extent for which to retrieve the image

• ymax – Maximum Y coordinate of the spatial extent for which to retrieve the image

• async_fetch – Whether to fetch images asynchronously (default is True)

• direct_fetch – Whether to fetch images directly from the web service (default is False)

Returns:

The retrieved image as a PIL Image object

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.

Parameters:

• service – The web service from which to retrieve the image

• category – The category of the image to retrieve

• subcategory – The subcategory of the image to retrieve

• xmin – Minimum X coordinate of the spatial extent

• xmax – Maximum X coordinate of the spatial extent

• ymin – Minimum Y coordinate of the spatial extent

• ymax – Maximum Y coordinate of the spatial extent

• scale_x – Scale factor for X dimension (default: 1.0)

• scale_y – Scale factor for Y dimension (default: 1.0)

• direct_fetch – Whether to fetch the entire extent as one image

Returns:

The retrieved image as a PIL Image object, or None if there was an error

clear_cache()

Clear the entire cache of images from disk