Handler Functions#

Core tile generation, statistics, and image manipulation functions for raster files, STAC catalogs, xarray DataArrays, and virtual mosaics.

Tile Handlers#

localtileserver.tiler.handler.get_reader(path: Path | str) → Reader#

Open a raster file and return a rio-tiler Reader.

Parameters:: path (pathlib.Path or str) – Path or URL to the raster file.
Returns:: A rio-tiler Reader instance for the given path.
Return type:: Reader

Generate a rendered map tile for the given ZXY index.

Parameters:

tile_source (Reader) – An open rio-tiler Reader for the raster dataset.
z (int) – Zoom level of the tile.
x (int) – Column index of the tile.
y (int) – Row index of the tile.
indexes (list of int, optional) – Band indexes to render. Auto-detected when not provided.
colormap (str, optional) – Name of a colormap to apply when rendering a single band.
vmin (float or list of float, optional) – Minimum value(s) for rescaling band data.
vmax (float or list of float, optional) – Maximum value(s) for rescaling band data.
nodata (int or float, optional) – Override nodata value for the dataset.
img_format (str, optional) – Output image format (e.g., "PNG", "JPEG"). Defaults to "PNG".
expression (str, optional) – Band math expression (e.g., "b1/b2"). When provided, indexes is ignored.
stretch (str, optional) – Stretch mode to apply before rendering. One of "none", "minmax", "linear", "equalize", "sqrt", or "log".

Returns:

Encoded image bytes with an associated MIME type.

Return type:

ImageBytes

Generate a downsampled preview image of the entire raster.

Parameters:

tile_source (Reader) – An open rio-tiler Reader for the raster dataset.
indexes (list of int, optional) – Band indexes to render. Auto-detected when not provided.
colormap (str, optional) – Name of a colormap to apply when rendering a single band.
vmin (float or list of float, optional) – Minimum value(s) for rescaling band data.
vmax (float or list of float, optional) – Maximum value(s) for rescaling band data.
nodata (int or float, optional) – Override nodata value for the dataset.
img_format (str, optional) – Output image format (e.g., "PNG", "JPEG"). Defaults to "PNG".
max_size (int, optional) – Maximum dimension of the output image in pixels. Defaults to 512.
crs (str, optional) – Target CRS for the preview. When provided, the image is reprojected via Reader.part.
expression (str, optional) – Band math expression (e.g., "b1/b2"). When provided, indexes is ignored.
stretch (str, optional) – Stretch mode to apply before rendering. One of "none", "minmax", "linear", "equalize", "sqrt", or "log".

Returns:

Encoded image bytes with an associated MIME type.

Return type:

ImageBytes

localtileserver.tiler.handler.get_statistics(tile_source: Reader, indexes: list[int] | None = None, expression: str | None = None, **kwargs)#

Get per-band statistics for the raster dataset.

Parameters:

tile_source (Reader) – An open rio-tiler Reader for the raster dataset.
indexes (list of int, optional) – Band indexes to compute statistics for. When None, all bands are included.
expression (str, optional) – Band math expression (e.g., "b1/b2"). When provided, indexes is ignored.
**kwargs – Additional keyword arguments passed to Reader.statistics.

Returns:

A dictionary keyed by band name (e.g., "b1", "b2") whose values are dictionaries of statistics including min, max, mean, std, and histogram.

Return type:

dict

localtileserver.tiler.handler.get_meta_data(tile_source: Reader)#

Retrieve metadata for a raster dataset.

Parameters:: tile_source (Reader) – An open rio-tiler Reader for the raster dataset.
Returns:: A dictionary containing dataset metadata including band info, CRS, transform, data type, and geographic bounds.
Return type:: dict

localtileserver.tiler.handler.get_source_bounds(tile_source: Reader, projection: str = 'EPSG:4326', decimal_places: int = 6)#

Get the geographic bounds of the raster reprojected to a target CRS.

Parameters:

tile_source (Reader) – An open rio-tiler Reader for the raster dataset.
projection (str, optional) – Target CRS string for the output bounds. Defaults to "EPSG:4326".
decimal_places (int, optional) – Number of decimal places to round the output coordinates. Defaults to 6.

Returns:

A dictionary with keys "left", "bottom", "right", and "top" representing the bounding box in the target CRS.

Return type:

dict

localtileserver.tiler.handler.get_point(tile_source: Reader, lon: float, lat: float, **kwargs)#

Query pixel values at a geographic point.

Parameters:

tile_source (Reader) – An open rio-tiler Reader for the raster dataset.
lon (float) – Longitude of the query point (EPSG:4326).
lat (float) – Latitude of the query point (EPSG:4326).
**kwargs – Additional keyword arguments passed to Reader.point.

Returns:

A rio-tiler PointData object containing the band values at the requested location.

Return type:

PointData

Extract a spatial subset (bounding box crop) from the raster.

Parameters:

tile_source (Reader) – An open rio-tiler Reader for the raster dataset.
bbox (tuple of float) – Bounding box as (left, bottom, right, top).
indexes (list of int, optional) – Band indexes to render. Auto-detected when not provided.
colormap (str, optional) – Name of a colormap to apply when rendering a single band.
vmin (float or list of float, optional) – Minimum value(s) for rescaling band data.
vmax (float or list of float, optional) – Maximum value(s) for rescaling band data.
nodata (int or float, optional) – Override nodata value for the dataset.
img_format (str, optional) – Output image format (e.g., "PNG", "JPEG"). Defaults to "PNG".
max_size (int, optional) – Maximum dimension of the output image in pixels. Defaults to 1024.
dst_crs (str, optional) – Target CRS for the output image.
bounds_crs (str, optional) – CRS of the bbox coordinates. Defaults to the dataset’s native CRS.
expression (str, optional) – Band math expression (e.g., "b1/b2"). When provided, indexes is ignored.
stretch (str, optional) – Stretch mode to apply before rendering.

Returns:

Encoded image bytes with an associated MIME type.

Return type:

ImageBytes

Extract data masked to a GeoJSON feature.

Parameters:

tile_source (Reader) – An open rio-tiler Reader for the raster dataset.
geojson (dict) – A GeoJSON Feature or Geometry dictionary.
indexes (list of int, optional) – Band indexes to render. Auto-detected when not provided.
colormap (str, optional) – Name of a colormap to apply when rendering a single band.
vmin (float or list of float, optional) – Minimum value(s) for rescaling band data.
vmax (float or list of float, optional) – Maximum value(s) for rescaling band data.
nodata (int or float, optional) – Override nodata value for the dataset.
img_format (str, optional) – Output image format (e.g., "PNG", "JPEG"). Defaults to "PNG".
max_size (int, optional) – Maximum dimension of the output image in pixels. Defaults to 1024.
dst_crs (str, optional) – Target CRS for the output image.
expression (str, optional) – Band math expression (e.g., "b1/b2"). When provided, indexes is ignored.
stretch (str, optional) – Stretch mode to apply before rendering.

Returns:

Encoded image bytes with an associated MIME type.

Return type:

ImageBytes

STAC Handlers#

Functions for working with STAC (SpatioTemporal Asset Catalog) items.

localtileserver.tiler.stac.get_stac_reader(url: str, **kwargs) → STACReader#

Create a STACReader for a STAC item URL.

Parameters:

url (str) – URL to a STAC item JSON document.
**kwargs (dict, optional) – Additional keyword arguments passed to rio_tiler.io.STACReader.

Returns:

An open STACReader instance for the given STAC item.

Return type:

STACReader

localtileserver.tiler.stac.get_stac_info(reader: STACReader, assets: list[str] | None = None)#

Get STAC item info (available assets, metadata).

Parameters:

reader (STACReader) – An open STACReader instance.
assets (list of str or None, optional) – Asset names to query. If None, info for all assets is returned.

Returns:

Dictionary mapping asset names to their metadata dictionaries.

Return type:

dict

localtileserver.tiler.stac.get_stac_statistics(reader: STACReader, assets: list[str] | None = None, **kwargs)#

Get per-asset/band statistics.

Parameters:

reader (STACReader) – An open STACReader instance.
assets (list of str or None, optional) – Asset names to compute statistics for. If None, statistics for all assets are returned.
**kwargs (dict, optional) – Additional keyword arguments passed to STACReader.statistics.

Returns:

Dictionary mapping asset/band keys to their statistics dictionaries.

Return type:

dict

localtileserver.tiler.stac.get_stac_tile(reader: STACReader, z: int, x: int, y: int, assets: list[str] | None = None, expression: str | None = None, img_format: str = 'PNG', **kwargs)#

Get a tile from a STAC item.

Parameters:

reader (STACReader) – An open STACReader instance.
z (int) – Tile zoom level.
x (int) – Tile column index.
y (int) – Tile row index.
assets (list of str or None, optional) – Asset names to read. If None, the reader default is used.
expression (str or None, optional) – Band math expression (e.g., "B04/B03").
img_format (str, optional) – Output image format. Default is "PNG".
**kwargs (dict, optional) – Additional keyword arguments passed to STACReader.tile.

Returns:

Rendered tile image bytes with MIME type metadata.

Return type:

ImageBytes

localtileserver.tiler.stac.get_stac_preview(reader: STACReader, assets: list[str] | None = None, expression: str | None = None, img_format: str = 'PNG', max_size: int = 512, **kwargs)#

Get a thumbnail/preview from a STAC item.

Parameters:

reader (STACReader) – An open STACReader instance.
assets (list of str or None, optional) – Asset names to read. If None, the reader default is used.
expression (str or None, optional) – Band math expression (e.g., "B04/B03").
img_format (str, optional) – Output image format. Default is "PNG".
max_size (int, optional) – Maximum dimension (width or height) of the preview image in pixels. Default is 512.
**kwargs (dict, optional) – Additional keyword arguments passed to STACReader.preview.

Returns:

Rendered preview image bytes with MIME type metadata.

Return type:

ImageBytes

Xarray Handlers#

Functions for serving tiles from xarray DataArrays. Requires the xarray optional dependency group (pip install localtileserver[xarray]).

localtileserver.tiler.xarray_handler.get_xarray_reader(data_array) → XarrayReader#

Create an XarrayReader from an xarray DataArray.

Parameters:: data_array (xarray.DataArray) – A DataArray with spatial dimensions and CRS metadata (typically set via rioxarray’s .rio.write_crs()).
Returns:: An open XarrayReader instance backed by the given DataArray.
Return type:: XarrayReader

localtileserver.tiler.xarray_handler.get_xarray_info(reader: XarrayReader)#

Get metadata/info from an XarrayReader.

Parameters:: reader (XarrayReader) – An open XarrayReader instance.
Returns:: Dictionary of dataset metadata (bounds, data types, band information, etc.).
Return type:: dict

localtileserver.tiler.xarray_handler.get_xarray_statistics(reader: XarrayReader, indexes: list[int] | None = None, **kwargs)#

Get statistics from an XarrayReader.

Parameters:

reader (XarrayReader) – An open XarrayReader instance.
indexes (list of int or None, optional) – Band indexes to compute statistics for (1-based). If None, statistics for all bands are returned.
**kwargs (dict, optional) – Additional keyword arguments passed to XarrayReader.statistics.

Returns:

Dictionary mapping band keys to their statistics dictionaries.

Return type:

dict

localtileserver.tiler.xarray_handler.get_xarray_tile(reader: XarrayReader, z: int, x: int, y: int, img_format: str = 'PNG', indexes: list[int] | None = None, **kwargs)#

Get a tile from an XarrayReader.

Parameters:

reader (XarrayReader) – An open XarrayReader instance.
z (int) – Tile zoom level.
x (int) – Tile column index.
y (int) – Tile row index.
img_format (str, optional) – Output image format. Default is "PNG".
indexes (list of int or None, optional) – Band indexes to read (1-based). If None, all bands are included.
**kwargs (dict, optional) – Additional keyword arguments passed to XarrayReader.tile.

Returns:

Rendered tile image bytes with MIME type metadata.

Return type:

ImageBytes

localtileserver.tiler.xarray_handler.get_xarray_preview(reader: XarrayReader, img_format: str = 'PNG', max_size: int = 512, indexes: list[int] | None = None, **kwargs)#

Get a thumbnail/preview from an XarrayReader.

Parameters:

reader (XarrayReader) – An open XarrayReader instance.
img_format (str, optional) – Output image format. Default is "PNG".
max_size (int, optional) – Maximum dimension (width or height) of the preview image in pixels. Default is 512.
indexes (list of int or None, optional) – Band indexes to read (1-based). If None, all bands are included.
**kwargs (dict, optional) – Additional keyword arguments passed to XarrayReader.preview.

Returns:

Rendered preview image bytes with MIME type metadata.

Return type:

ImageBytes

Mosaic Handlers#

Functions for creating virtual mosaics from multiple raster files.

localtileserver.tiler.mosaic.get_mosaic_tile(assets: list[str], z: int, x: int, y: int, img_format: str = 'PNG', indexes: list[int] | None = None, pixel_selection=None, **kwargs)#

Get a mosaic tile from multiple raster assets.

Parameters:

assets (list of str) – List of file paths or URLs to raster datasets.
z (int) – Tile zoom level.
x (int) – Tile column index.
y (int) – Tile row index.
img_format (str, optional) – Output image format. Default is "PNG".
indexes (list of int or None, optional) – Band indexes to read (1-based). If None, all bands are included.
pixel_selection (MosaicMethodBase or None, optional) – Mosaic pixel selection method. Defaults to FirstMethod (first valid pixel wins).
**kwargs (dict, optional) – Additional keyword arguments passed to the underlying tile reader.

Returns:

Rendered mosaic tile image bytes with MIME type metadata.

Return type:

ImageBytes

localtileserver.tiler.mosaic.get_mosaic_preview(assets: list[str], img_format: str = 'PNG', max_size: int = 512, indexes: list[int] | None = None, pixel_selection=None, **kwargs)#

Get a mosaic preview from multiple raster assets.

Parameters:

assets (list of str) – List of file paths or URLs to raster datasets.
img_format (str, optional) – Output image format. Default is "PNG".
max_size (int, optional) – Maximum dimension (width or height) of the preview image in pixels. Default is 512.
indexes (list of int or None, optional) – Band indexes to read (1-based). If None, all bands are included.
pixel_selection (MosaicMethodBase or None, optional) – Mosaic pixel selection method. Defaults to FirstMethod (first valid pixel wins).
**kwargs (dict, optional) – Additional keyword arguments passed to the underlying preview reader.

Returns:

Rendered mosaic preview image bytes with MIME type metadata.

Return type:

ImageBytes