Skip to content

BitmapTileLayer

lonboard.BitmapTileLayer

Bases: BaseLayer

The BitmapTileLayer renders image tiles (e.g. PNG, JPEG, or WebP) in the web mercator tiling system. Only the tiles visible in the current viewport are loaded and rendered.

Example:

from lonboard import Map, BitmapTileLayer

# We set `max_requests < 0` because `tile.openstreetmap.org` supports HTTP/2.
layer = BitmapTileLayer(
    data="https://tile.openstreetmap.org/{z}/{x}/{y}.png",
    tile_size=256,
    max_requests=-1,
    min_zoom=0,
    max_zoom=19,
)
m = Map(layer)

auto_highlight class-attribute instance-attribute 

auto_highlight = tag(sync=True)

When true, the current object pointed to by the mouse pointer (when hovered over) is highlighted with highlightColor.

Requires pickable to be True.

  • Type: bool
  • Default: False

data class-attribute instance-attribute 

data = tag(sync=True)

Either a URL template or an array of URL templates from which the tile data should be loaded.

If the value is a string: a URL template. Substrings {x} {y} and {z}, if present, will be replaced with a tile's actual index when it is requested.

If the value is an array: multiple URL templates. Each endpoint must return the same content for the same tile index. This can be used to work around domain sharding, allowing browsers to download more resources simultaneously. Requests made are balanced among the endpoints, based on the tile index.

desaturate class-attribute instance-attribute 

desaturate = tag(sync=True)

The desaturation of the bitmap. Between [0, 1].

  • Type: float, optional
  • Default: 0

extensions class-attribute instance-attribute 

extensions = tag(sync=True, **widget_serialization)

A list of layer extension objects to add additional features to a layer.

extent class-attribute instance-attribute 

extent = tag(sync=True)

The bounding box of the layer's data, in the form of [min_x, min_y, max_x, max_y]. If provided, the layer will only load and render the tiles that are needed to fill this box.

  • Type: List[float], optional
  • Default: None

highlight_color class-attribute instance-attribute 

highlight_color = VariableLengthTuple(
    Int(), default_value=None, minlen=3, maxlen=4
)

RGBA color to blend with the highlighted object (the hovered over object if auto_highlight=true). When the value is a 3 component (RGB) array, a default alpha of 255 is applied.

  • Type: List or Tuple of integers
  • Default: [0, 0, 128, 128]

max_cache_size class-attribute instance-attribute 

max_cache_size = tag(sync=True)

The maximum number of tiles that can be cached. The tile cache keeps loaded tiles in memory even if they are no longer visible. It reduces the need to re-download the same data over and over again when the user pan/zooms around the map, providing a smoother experience.

If not supplied, the max_cache_size is calculated as 5 times the number of tiles in the current viewport.

  • Type: int, optional
  • Default: None

max_requests class-attribute instance-attribute 

max_requests = tag(sync=True)

The maximum number of concurrent data fetches.

If <= 0, no throttling will occur, and get_tile_data may be called an unlimited number of times concurrently regardless of how long that tile is or was visible.

If > 0, a maximum of max_requests instances of get_tile_data will be called concurrently. Requests may never be called if the tile wasn't visible long enough to be scheduled and started. Requests may also be aborted (through the signal passed to get_tile_data) if there are more than max_requests ongoing requests and some of those are for tiles that are no longer visible.

If get_tile_data makes fetch requests against an HTTP 1 web server, then max_requests should correlate to the browser's maximum number of concurrent fetch requests. For Chrome, the max is 6 per domain. If you use the data prop and specify multiple domains, you can increase this limit. For example, with Chrome and 3 domains specified, you can set max_requests=18.

If the web server supports HTTP/2 (Open Chrome dev tools and look for "h2" in the Protocol column), then you can make an unlimited number of concurrent requests (and can set max_requests=-1). Note that this will request data for every tile, no matter how long the tile was visible, and may increase server load.

max_zoom class-attribute instance-attribute 

max_zoom = tag(sync=True)

The max zoom level of the layer's data. When overzoomed (i.e. zoom > max_zoom), tiles from this level will be displayed.

  • Type: int, optional
  • Default: None

min_zoom class-attribute instance-attribute 

min_zoom = tag(sync=True)

The min zoom level of the layer's data. When underzoomed (i.e. zoom < min_zoom), the layer will not display any tiles unless extent is defined, to avoid issuing too many tile requests.

  • Type: int, optional
  • Default: None

opacity class-attribute instance-attribute 

opacity = tag(sync=True)

The opacity of the layer.

  • Type: float. Must range between 0 and 1.
  • Default: 1

pickable class-attribute instance-attribute 

pickable = tag(sync=True)

Whether the layer responds to mouse pointer picking events.

This must be set to True for tooltips and other interactive elements to be available. This can also be used to only allow picking on specific layers within a map instance.

Note that picking has some performance overhead in rendering. To get the absolute best rendering performance with large data (at the cost of removing interactivity), set this to False.

  • Type: bool
  • Default: True

refinement_strategy class-attribute instance-attribute 

refinement_strategy = tag(sync=True)

How the tile layer refines the visibility of tiles.

When zooming in and out, if the layer only shows tiles from the current zoom level, then the user may observe undesirable flashing while new data is loading. By setting refinement_strategy the layer can attempt to maintain visual continuity by displaying cached data from a different zoom level before data is available.

This prop accepts one of the following:

  • "best-available": If a tile in the current viewport is waiting for its data to load, use cached content from the closest zoom level to fill the empty space. This approach minimizes the visual flashing due to missing content.
  • "no-overlap": Avoid showing overlapping tiles when backfilling with cached content. This is usually favorable when tiles do not have opaque backgrounds.

  • "never": Do not display any tile that is not selected.

  • Type: str, optional

  • Default: "best-available"

selected_index class-attribute instance-attribute 

selected_index = tag(sync=True)

The positional index of the most-recently clicked on row of data.

You can use this to access the full row of data from a GeoDataFrame

gdf.iloc[layer.selected_index]

Setting a value here from Python will do nothing. This attribute only exists to be updated from JavaScript on a map click. Note that pickable must be True (the default) on this layer for the JavaScript onClick handler to work; if pickable is set to False, selected_index will never update.

Note that you can use observe to call a function whenever a new value is received from JavaScript. Refer here for an example.

tile_size class-attribute instance-attribute 

tile_size = tag(sync=True)

The pixel dimension of the tiles, usually a power of 2.

Tile size represents the target pixel width and height of each tile when rendered. Smaller tile sizes display the content at higher resolution, while the layer needs to load more tiles to fill the same viewport.

  • Type: int, optional
  • Default: 512

tint_color class-attribute instance-attribute 

tint_color = VariableLengthTuple(
    Float(), default_value=None, allow_none=True, minlen=3, maxlen=4
)

The color to tint the bitmap by, in [r, g, b].

  • Type: List[float], optional
  • Default: [255, 255, 255]

transparent_color class-attribute instance-attribute 

transparent_color = VariableLengthTuple(
    Float(), default_value=None, allow_none=True, minlen=3, maxlen=4
)

The color to use for transparent pixels, in [r, g, b, a].

  • Type: List[float], optional
  • Default: [0, 0, 0, 0]

visible class-attribute instance-attribute 

visible = tag(sync=True)

Whether the layer is visible.

Under most circumstances, using the visible attribute to control the visibility of layers is recommended over removing/adding the layer from the Map.layers list.

In particular, toggling the visible attribute will persist the layer on the JavaScript side, while removing/adding the layer from the Map.layers list will re-download and re-render from scratch.

  • Type: bool
  • Default: True

zoom_offset class-attribute instance-attribute 

zoom_offset = tag(sync=True)

This offset changes the zoom level at which the tiles are fetched. Needs to be an integer.

  • Type: int, optional
  • Default: 0