Skip to content

TileLayer

TileLayer #

Bases: MapLayer

The map's main layer. Displays square raster images in a continuous grid, sourced from the provided url_template and fallback_url.

additional_options: Dict[str, str] = field(default_factory=dict) #

Static information that should replace placeholders in the url_template. Applying API keys, for example, is a good usecase of this parameter.

Example:

TileLayer(
    url_template="https://api.tiles.mapbox.com/v4/{id}/{z}/{x}/{y}{r}.png?access_token={accessToken}",
    additional_options={
        'accessToken': '<ACCESS_TOKEN_HERE>',
        'id': 'mapbox.streets',
    },
),

Defaults to {}.

display_mode: TileDisplay = field(default_factory=lambda: FadeInTileDisplay(start_opacity=0.0, reload_start_opacity=0.0)) #

Defines how tiles are displayed on the map.

Defaults to FadeInTileDisplay().

enable_retina_mode: bool = False #

Whether to enable retina mode. Retina mode improves the resolution of map tiles, particularly on high density displays.

Defaults to False.

enable_tms: bool = False #

Whether to inverse Y-axis numbering for tiles. Turn this on for TMS services.

Defaults to False.

error_image_src: Optional[str] = None #

The source of the tile image to show in place of the tile that failed to load.

See on_image_error property for details on the error.

evict_error_tile_strategy: Optional[TileLayerEvictErrorTileStrategy] = TileLayerEvictErrorTileStrategy.NONE #

If a tile was loaded with error, the tile provider will be asked to evict the image based on this strategy.

Defaults to TileLayerEvictErrorTileStrategy.NONE.

fallback_url: Optional[str] = None #

Fallback URL template, used if an error occurs when fetching tiles from the url_template.

Note that specifying this (non-none) will result in tiles not being cached in memory. This is to avoid issues where the url_template is flaky, to prevent different tilesets being displayed at the same time.

It is expected that this follows the same retina support behaviour as url_template.

keep_buffer: int = 2 #

When panning the map, keep this many rows and columns of tiles before unloading them.

Defaults to 2.

max_native_zoom: int = 19 #

Maximum zoom number supported by the tile source has available.

Tiles from above this zoom level will not be displayed, instead tiles at this zoom level will be displayed and scaled.

Most tile servers support up to zoom level 19, which is the default. Otherwise, this should be specified.

Defaults to 19.

max_zoom: ft.Number = float('inf') #

The maximum zoom level up to which this layer will be displayed (inclusive). The main usage for this property is to display a different TileLayer when zoomed far in.

Prefer max_native_zoom for setting the maximum zoom level supported by the tile source.

Typically set to infinity so that there are tiles always displayed.

Defaults to float("inf").

min_native_zoom: int = 0 #

Minimum zoom level supported by the tile source.

Tiles from below this zoom level will not be displayed, instead tiles at this zoom level will be displayed and scaled.

This should usually be 0 (as default), as most tile sources will support zoom levels onwards from this.

min_zoom: ft.Number = 0.0 #

The minimum zoom level at which this layer is displayed (inclusive). Typically set to 0.0 by default.

Defaults to 0.0.

on_image_error: ft.OptionalControlEventCallable = None #

Fires if an error occurs when fetching the tiles.

Event handler argument data property contains information about the error.

pan_buffer: int = 1 #

When loading tiles only visible tiles are loaded by default. This option increases the loaded tiles by the given number on both axis which can help prevent the user from seeing loading tiles whilst panning. Setting the pan buffer too high can impact performance, typically this is set to 0 or 1.

Defaults to 1.

subdomains: List[str] = field(default_factory=lambda: ['a', 'b', 'c']) #

List of subdomains used in the URL template.

For example, if subdomains is set to ["a", "b", "c"] and the url_template is "https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png", the resulting tile URLs will be:

Defaults to ["a", "b", "c"].

tile_bounds: Optional[MapLatitudeLongitudeBounds] = None #

Defines the bounds of the map. Only tiles that fall within these bounds will be loaded.

tile_size: int = 256 #

The size in pixels of each tile image.

Should be a positive power of 2.

Defaults to 256.

url_template: str #

The URL template is a string that contains placeholders, which, when filled in, create a URL/URI to a specific tile.

user_agent_package_name: str = 'unknown' #

The package name of the user agent.

Defaults to "unknown".

zoom_offset: ft.Number = 0.0 #

The zoom number used in tile URLs will be offset with this value.

Defaults to 0.0.

zoom_reverse: bool = False #

Whether the zoom number used in tile URLs will be reversed (max_zoom - zoom instead of zoom).

Defaults to False.