`gws.lib.grid`¶

Map grids: tile pyramid math.

A grid is a gws.MapGrid: a CRS, a frame extent, a base resolution and a tile size. The origin is the north-west corner of the frame. Level z has the resolution baseResolution / 2**z, so levels nest exactly (quad tree) and the ladder has no bottom: any resolution can be served by downsampling from the coarsest level whose resolution does not exceed it.

Defaults: projected CRS use the web mercator square as frame and one tile at level 0; geographic CRS use (-180, -90, 180, 90) and two tiles (2x1) at level 0. Without an explicit base resolution, one tile at level 0 spans the frame height, so that the default resolutions are 156543.03392804097 / 2**z metres and 0.703125 / 2**z degrees for a 256px tile. Custom frames, base resolutions and tile sizes (tile source grids) are possible; a non-square custom frame needs an explicit base resolution. The frame is an indexing frame and does not have to be inside the area of use of the CRS.

A custom grid can be snapped to the default grid of its CRS (withSnap): the base resolution becomes a ladder value, the nearest one if given, otherwise the coarsest whose tile spans the extent, and the extent is expanded outward to tile boundaries at that level. A snapped grid is a window on the default grid: its tile (x, y, z) is the default grid’s (x + ox * 2**z, y + oy * 2**z, z + k) for the integer offset (ox, oy) of the window at level k.

Tiles are (x, y, z), ranges (min_x, min_y, max_x, max_y, z).

Tile matrix sets (gws.TileMatrixSet, as in WMTS) describe foreign pyramids: each matrix has its own origin, size and resolution, and the resolutions need not form a ladder. matrix_set_for_grid expresses a grid as a matrix set, the matrix_* functions are the matrix counterparts of the grid functions.

Example:

mg = gws.lib.grid.for_crs(gws.lib.crs.get(3857))
z = gws.lib.grid.level_for_resolution(mg, 10.0)
tr = gws.lib.grid.range_for_extent(mg, (1000000, 6000000, 1010000, 6010000), z)
for mt in gws.lib.grid.enum_tiles(tr):
    extent = gws.lib.grid.extent_for_tile(mg, mt)

A custom grid from a Config-like set of options:

mg = gws.lib.grid.new(gws.lib.grid.Options(
    crs=gws.lib.crs.get(25832),
    extent=(280000, 5200000, 920000, 6100000),
    tileSize=512,
))

Source code: gws.lib.grid

Package Contents¶

class gws.lib.grid.Config(*args, **kwargs)¶

Bases: gws.Config

Tile grid. (changed in 8.5)

baseResolution: float | None¶: Resolution at level 0. (added in 8.5)

crs: gws.CrsName | None¶: Grid CRS.

extent: gws.Extent | None¶: Grid frame extent, with the origin at its north-west corner.

tileSize: int | None¶: Tile size in pixels.

withSnap: bool = True¶: Snap the extent and the base resolution to the default grid of the CRS. (added in 8.5)

gws.lib.grid.DEFAULT_TILE_SIZE = 256¶: Default tile size in pixels.

gws.lib.grid.enum_tiles(tr: gws.MapTileRange) → Iterator[gws.MapTile]¶

Enumerate the tiles of a range, row by row.

Parameters:: tr – Tile range.
Yields:: Tiles (x, y, z).

gws.lib.grid.extent_for_range(mg: gws.MapGrid, tr: gws.MapTileRange) → gws.Extent¶

Return the extent of a tile range.

Parameters:

mg – A grid.
tr – Tile range.

Returns:

Extent in the grid CRS.

gws.lib.grid.extent_for_tile(mg: gws.MapGrid, tile: gws.MapTile) → gws.Extent¶

Return the extent of a tile.

Parameters:

mg – A grid.
tile – Tile.

Returns:

Extent in the grid CRS.

gws.lib.grid.for_crs(crs: gws.Crs) → gws.MapGrid¶

Create the default grid for a CRS.

Parameters:: crs – Grid CRS.
Returns:: A grid with the default frame, base resolution and tile size.

gws.lib.grid.in_range(mt: gws.MapTile, tr: gws.MapTileRange) → bool¶

Check if a tile lies within a range.

Parameters:

mt – Tile.
tr – Tile range.

Returns:

True if the tile is at the level of the range and inside it.

gws.lib.grid.intersect_ranges(a: gws.MapTileRange, b: gws.MapTileRange) → gws.MapTileRange | None¶

Return the intersection of two tile ranges of the same level.

Parameters:

a – First tile range.
b – Second tile range.

Returns:

The intersection, or None if the ranges do not intersect.

Raises:

ValueError – If the ranges are at different levels.

gws.lib.grid.level_for_resolution(mg: gws.MapGrid, resolution: float) → int¶

Return the coarsest level whose resolution does not exceed the given one.

A level whose resolution is within RESOLUTION_TOLERANCE of the given one also matches.

Parameters:

mg – A grid.
resolution – Resolution in CRS units per pixel.

Returns:

Level number.

Raises:

ValueError – If the resolution is not positive or no level up to 99 matches.

gws.lib.grid.matrix_extent_for_range(tm: gws.TileMatrix, tr: gws.MapTileRange) → gws.Extent¶

Return the extent of a range of matrix tiles.

Parameters:

tm – Tile matrix.
tr – Tile range; z is ignored.

Returns:

Extent in the matrix CRS.

gws.lib.grid.matrix_for_resolution(tms: gws.TileMatrixSet, resolution: float) → gws.TileMatrix¶

Return the coarsest matrix that does not need upscaling.

A matrix whose resolution is within RESOLUTION_TOLERANCE of the given one also matches.

Parameters:

tms – Tile matrix set.
resolution – Wanted resolution in CRS units per pixel.

Returns:

The matching matrix, or the finest one if all are coarser.

gws.lib.grid.matrix_range_for_extent(tm: gws.TileMatrix, extent: gws.Extent) → gws.MapTileRange | None¶

Return the range of matrix tiles covering an extent.

The range is clipped to the matrix.

Parameters:

tm – Tile matrix.
extent – Extent in the matrix CRS.

Returns:

A tile range with z set to 0, or None if the extent does not intersect the matrix.

gws.lib.grid.matrix_set_for_grid(mg: gws.MapGrid, max_level: int, identifier: str = '') → gws.TileMatrixSet¶

Express the levels 0..max_level of a grid as a tile matrix set.

Matrix identifiers are the level numbers as strings. scale is not set.

Parameters:

mg – A grid.
max_level – Finest level to include.
identifier – Identifier of the matrix set.

Returns:

A tile matrix set.

gws.lib.grid.new(opts: Options) → gws.MapGrid¶

Create a grid.

Missing options are filled with the defaults for the CRS. If a custom extent or base resolution is given and snapping is not disabled, the grid is snapped to the default grid of the CRS.

Parameters:: opts – Grid options.
Returns:: A new grid.

class gws.lib.grid.Options(*args, **kwargs)¶

Bases: gws.Data

Options for creating a grid with new.

baseResolution: float | None¶: Resolution at level 0. By default, one tile spans the frame height.

crs: gws.Crs¶: Grid CRS.

extent: gws.Extent | None¶: Frame extent. The default depends on the CRS.

tileSize: int | None¶: Tile size in pixels, DEFAULT_TILE_SIZE by default.

withSnap: bool | None¶: Snap a custom extent or base resolution to the default grid of the CRS, True by default.

class gws.lib.grid.Props(*args, **kwargs)¶

Bases: gws.Props

Object properties.

extent: gws.Extent¶

origin: str¶

resolutions: list[float]¶

tileSize: int¶

gws.lib.grid.props_for_resolutions(mg: gws.MapGrid, resolutions: list[float]) → Props¶

Create client props for a grid.

Parameters:

mg – A grid.
resolutions – Resolutions the client uses. The finest one determines the finest level.

Returns:

Grid props with the resolutions of levels 0 up to the finest level needed.

gws.lib.grid.range_for_extent(mg: gws.MapGrid, extent: gws.Extent, z: int) → gws.MapTileRange | None¶

Return the range of tiles covering an extent at a level.

The range is clipped to the grid frame.

Parameters:

mg – A grid.
extent – Extent in the grid CRS.
z – Level.

Returns:

A tile range, or None if the extent does not intersect the frame.

gws.lib.grid.resolution_for_level(mg: gws.MapGrid, z: int) → float¶

Return the resolution of a level.

Parameters:

mg – A grid.
z – Level.

Returns:

baseResolution / 2**z.

gws.lib.grid.RESOLUTION_TOLERANCE = 0.01¶

Relative tolerance for a resolution to count as a level’s resolution.

Requests are often rounded (bboxes with a few decimals), so a resolution slightly above a level’s must still map to that level rather than to the next finer one.

gws.lib.grid.tile_count_for_level(mg: gws.MapGrid, z: int) → tuple[int, int]¶

Return the number of tiles a level has across the frame.

Parameters:

mg – A grid.
z – Level.

Returns:

Number of columns and rows, at least 1 each.

`gws.lib.grid`¶

Package Contents¶

Table of Contents

Previous topic

Next topic

gws.lib.grid¶

Package Contents¶

`gws.lib.grid`¶