gws.gis.zoom

Zoom levels of maps and layers.

A map has a list of resolutions (map units per pixel), its zoom levels. Layers use a subset of the map resolutions. This package computes these lists from the zoom configuration of maps and layers, from source layer scale hints, and converts between scales and resolutions.

Zoom levels can be configured in three ways:

  • as levels of the standard tile grid of the map CRS (gws.lib.grid.for_crs), bounded by minLevel / maxLevel or by minScale / maxScale. Without explicit bounds, the map gets levels 0 to DEFAULT_MAX_LEVEL.

  • as an explicit list of scales (scale denominators).

  • with the deprecated resolutions, initResolution, minResolution and maxResolution options, which still work and produce a configuration warning (warn_deprecated_options).

Levels are indices into the resolution list, 0 being the coarsest. Scale bounds snap to the nearest available resolution. For a layer, the levels are map-wide indices, and its resolutions are always taken from the map resolutions. The initial map resolution is given by initLevel or initScale, by default it is the middle of the list.

Scales and resolutions are converted with the OGC standard pixel size. For geographic CRS, resolutions are in degrees per pixel, converted with gws.lib.crs.METERS_PER_DEGREE. Scales must be between MIN_SCALE and MAX_SCALE, levels between 0 and MAX_LEVEL; otherwise a gws.ConfigurationError is raised.

Example:

map.zoom { minLevel 6 maxLevel 19 initScale 50000 }

map.layers+ {
    type "wms"
    provider.url "https://example.com/wms"
    zoom { maxScale 100000 }
}

Python usage example:

resolutions = gws.gis.zoom.resolutions_from_config(cfg, crs=gws.lib.crs.WEBMERCATOR)
init = gws.gis.zoom.init_resolution(cfg, resolutions, crs=gws.lib.crs.WEBMERCATOR)
scale = gws.gis.zoom.res_to_scale(init, gws.lib.crs.WEBMERCATOR)

Source code: gws.gis.zoom

Package Contents

class gws.gis.zoom.Config(*args, **kwargs)

Bases: gws.Config

Zoom levels of a map or layer, given as scales or levels.

initLevel: int | None

Zoom level to open the map at. (added in 8.5)

initResolution: float | None

Initial resolution. (deprecated in 8.5)

initScale: float | None

Scale to open the map at, snapped to the nearest zoom level.

maxLevel: int | None

Finest zoom level. (added in 8.5)

maxResolution: float | None

Max. resolution. (deprecated in 8.5)

maxScale: float | None

Largest scale denominator, snapped to the nearest zoom level.

minLevel: int | None

Coarsest zoom level. (added in 8.5)

minResolution: float | None

Min. resolution. (deprecated in 8.5)

minScale: float | None

Smallest scale denominator, snapped to the nearest zoom level.

resolutions: list[float] | None

Allowed resolutions. (deprecated in 8.5)

scales: list[float] | None

Scale denominators of the zoom levels.

gws.gis.zoom.DEFAULT_MAX_LEVEL = 20

Default finest level for grid-based resolutions.

gws.gis.zoom.init_resolution(cfg, resolutions: list, crs: gws.Crs = None) → float

Compute the initial resolution of a map.

initLevel (an index, 0 = coarsest) wins over initScale, which snaps to the nearest resolution; the default is the middle of the list.

Parameters:

  • cfg – A zoom config.

  • resolutions – Map resolutions.

  • crs – Map CRS, for scale conversions.

Returns:

One of the given resolutions.

Raises:

gws.ConfigurationError – If a value is out of bounds.

gws.gis.zoom.MAX_LEVEL = 30

Highest allowed zoom level.

gws.gis.zoom.MAX_SCALE = 500000000

Largest allowed scale denominator.

gws.gis.zoom.MIN_SCALE = 1

Smallest allowed scale denominator.

gws.gis.zoom.res_to_scale(res: float, crs: gws.Crs = None) → int

Convert a resolution to a scale denominator.

Parameters:

  • res – Resolution in map units per pixel.

  • crs – CRS. For a geographic CRS the resolution is in degrees per pixel, otherwise in meters per pixel.

Returns:

Scale denominator.

gws.gis.zoom.resolutions_for_layer(cfg, parent_resolutions: list[float], crs: gws.Crs = None) → list[float]

Compute layer resolutions from a zoom config.

The result is always a subset of the parent (map) resolutions: scales entries snap to the nearest parent resolution; deprecated resolutions entries must match parent resolutions; level and scale bounds select from the parent list (levels are map-wide indices).

Parameters:

  • cfg – A zoom config.

  • parent_resolutions – Parent (map) resolutions.

  • crs – Map CRS, for scale conversions.

Returns:

A list of resolutions, sorted ascending.

Raises:

gws.ConfigurationError – If a value is invalid or the bounds select no resolutions.

gws.gis.zoom.resolutions_from_config(cfg, crs: gws.Crs = None) → list[float]

Compute map resolutions from a zoom config.

An explicit scales (or deprecated resolutions) list is taken as is; otherwise the resolutions of the standard grid for the CRS are used. Level bounds are indices into the list (0 = coarsest); scale bounds snap to the nearest entry. For the grid default, the bounds drive generation, so a minScale beyond the default range extends the list.

Parameters:

  • cfg – A zoom config.

  • crs – CRS of the map, Web Mercator if not given.

Returns:

A list of resolutions, sorted ascending.

Raises:

gws.ConfigurationError – If a value is out of bounds or the result is empty.

gws.gis.zoom.resolutions_from_scale_range(smin: float, smax: float, parent_resolutions: list[float], crs: gws.Crs = None) → list[float]

Compute layer resolutions from a scale range.

The range bounds snap to the nearest parent resolutions and select the range between.

Parameters:

  • smin – Min. scale denominator.

  • smax – Max. scale denominator.

  • parent_resolutions – Parent (map) resolutions.

  • crs – Map CRS, for scale conversions.

Returns:

A list of resolutions, sorted ascending. Empty if the range lies outside the parent resolutions.

gws.gis.zoom.resolutions_from_source_layers(source_layers: list[gws.SourceLayer], parent_resolutions: list[float], crs: gws.Crs = None) → list[float]

Compute layer resolutions from source layer scale hints.

The union of the scale ranges of all source layers acts as scale bounds over the parent resolutions, see resolutions_from_scale_range. If any source layer has no scale range, the parent resolutions are returned.

Parameters:

  • source_layers – Source layers.

  • parent_resolutions – Parent (map) resolutions.

  • crs – Map CRS, for scale conversions.

Returns:

A list of resolutions, sorted ascending.

gws.gis.zoom.scale_to_res(scale: float, crs: gws.Crs = None) → float

Convert a scale denominator to a resolution.

Parameters:

  • scale – Scale denominator.

  • crs – CRS. For a geographic CRS the result is in degrees per pixel, otherwise in meters per pixel.

Returns:

Resolution in map units per pixel.

gws.gis.zoom.warn_deprecated_options(cfg, root: gws.Root)

Register a configuration warning for each deprecated zoom option in use.

Parameters:

  • cfg – A zoom config.

  • root – Configuration root.