Skip to content

RasterLayer

lonboard.RasterLayer

Bases: BaseLayer, Generic[T]

The RasterLayer renders raster imagery.

This layer expects input such as Cloud-Optimized GeoTIFFs (COGs) that can be efficiently accessed by internal tiles.

debounce_time class-attribute instance-attribute 

debounce_time = Int(0)

Queue tile requests until no new tiles have been added for at least debounceTime milliseconds.

If debounceTime == 0, tile requests are issued as quickly as the maxRequests concurrent request limit allows.

If debounceTime > 0, tile requests are queued until a period of at least debounceTime milliseconds has passed without any new tiles being added to the queue. May reduce bandwidth usage and total loading time during interactive view transitions.

  • Default: 0

extent class-attribute instance-attribute 

extent = List(Float(), allow_none=True, default_value=None, minlen=4, maxlen=4)

The bounding box of the layer's data, in the form of [minX, minY, maxX, maxY].

If provided, the layer will only load and render the tiles that are needed to fill this box.

  • Default: null

max_cache_size class-attribute instance-attribute 

max_cache_size = Int(allow_none=True, default_value=None)

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.

  • Default: null

max_zoom class-attribute instance-attribute 

max_zoom = Int(allow_none=True, default_value=None)

The max zoom level of the layer's data.

When overzoomed (i.e. zoom > maxZoom), tiles from this level will be displayed.

  • Default: null

min_zoom class-attribute instance-attribute 

min_zoom = Int(0)

The min zoom level of the layer's data.

When underzoomed (i.e. zoom < minZoom), the layer will not display any tiles unless extent is defined, to avoid issuing too many tile requests.

  • Default: 0

zoom_offset class-attribute instance-attribute 

zoom_offset = Int(0)

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

  • Default: 0

__init__ 

__init__(
    *,
    _tile_matrix_set: TileMatrixSet | None,
    _crs: CRS,
    _fetch_tile: FetchTile[T],
    _render_tile: RenderTile[T],
    _bounds: Bbox | None = None,
    _center: tuple[float, float] | None = None,
    **kwargs: Unpack[RasterLayerKwargs]
) -> None

from_geotiff staticmethod 

from_geotiff(
    geotiff: GeoTIFF,
    /,
    *,
    render_tile: RenderTile[Tile],
    **kwargs: Unpack[RasterLayerKwargs],
) -> RasterLayer[Tile]

Create a RasterLayer from a GeoTIFF instance from Async-GeoTIFF.

This supports visualizing virtually any GeoTIFF instance, no matter whether it's a local file or stored on a remote store like S3.

This works best with Cloud-Optimized GeoTIFFs (COGs) since they are designed for efficient access by internal tiles. But it will work with any tiled GeoTIFF.

Parameters:

  • geotiff (GeoTIFF) –

    A GeoTIFF instance from [Async-GeoTIFF]. Refer to the [Async-GeoTIFF] documentation for how to create a GeoTIFF from various input sources.

Other Parameters:

  • render_tile (RenderTile[Tile]) –

    A callback to transform a Tile into a PNG-formatted image. The callback must return an EncodedImage instance.

    Keep in mind that an async_geotiff.RasterArray stores pixel data in "band-major" order, meaning that the shape is (bands, height, width). You'll usually need to transpose the array to (height, width, bands) before converting to PNG. You can use the async_geotiff.utils.reshape_as_image utility function to do this.

    Also keep in mind that the tile data is not necessarily in visual RGBA format, so you may need to do some processing in render_tile to convert it to RGBA. For example, you might need to apply a color map to a single-band raster, or handle alpha compositing if the GeoTIFF has an alpha channel.

  • kwargs (Unpack[RasterLayerKwargs]) –

    parameters passed on to __init__

Returns:

from_pmtiles staticmethod 

from_pmtiles(
    reader: PMTilesReader, **kwargs: Unpack[RasterLayerKwargs]
) -> RasterLayer[Buffer | None]

Create a RasterLayer from a PMTiles archive.

Example:

Using obstore.store.HTTPStore to read a PMTiles file over HTTP:

from async_pmtiles import PMTilesReader
from lonboard import Map, RasterLayer
from obstore.store import HTTPStore

store = HTTPStore("https://air.mtn.tw")
reader = await PMTilesReader.open("flowers.pmtiles", store=store)
layer = RasterLayer.from_pmtiles(reader)
m = Map(layer)

Parameters:

  • reader (PMTilesReader) –

    A PMTilesReader instance from async-pmtiles. Refer to the async-pmtiles documentation for how to create a PMTilesReader from various input sources.

Other Parameters:

  • kwargs (Unpack[RasterLayerKwargs]) –

    parameters passed on to __init__

Raises:

  • ValueError –

    if the PMTiles tile type is not a supported raster format (i.e. PNG, JPEG, WEBP, or AVIF).

Returns:

  • RasterLayer[Buffer | None] –

    A new RasterLayer instance.