Python Client#

Core classes and helpers for launching a tile server and integrating with Jupyter mapping libraries.

TileClient#

Bases: TilerInterface, TileServerMixin

Tile client interface for generating and serving tiles.

Parameters:

source (pathlib.Path, str, Reader, DatasetReaderBase) – The source dataset to use for the tile client.
port (int) – The port on your host machine to use for the tile server. This defaults to getting an available port.
debug (bool) – Run the tile server in debug mode.
host (str) – The host address to bind the tile server to.
client_port (int) – The port on your client browser to use for fetching tiles. This is useful when running in Docker and performing port forwarding.
client_host (str) – The host on which your client browser can access the server.
client_prefix (str) – The URL prefix used for proxied access to the tile server.
cors_all (bool) – If True, enable CORS for all origins on the tile server.

localtileserver.get_or_create_tile_client(source: Path | str | TileClient | DatasetReaderBase, port: int | str = 'default', debug: bool = False)#

Get an existing TileClient or create a new one from a source.

Parameters:

source (pathlib.Path, str, TileClient, or rasterio.io.DatasetReaderBase) – The raster source. If already a TileClient, it is used directly. Otherwise, a new TileClient is created.
port (int or str, optional) – The port on your host machine to use for the tile server. Defaults to "default" which selects an available port.
debug (bool, optional) – Run the tile server in debug mode. Defaults to False.

Returns:

source (TileClient) – The tile client instance.
_internally_created (bool) – True if a new TileClient was created internally, False if the provided source was already a TileClient.

Notes

There should eventually be a check to see if a TileClient instance exists for the given filename. For now, it is not a big deal because the default is for all TileClients to share a single server.

class localtileserver.client.TilerInterface(source: Path | str | DatasetReaderBase)#

Base TileClient methods and configuration.

This class interfaces directly with rasterio and rio-tiler.

Parameters:: source (pathlib.Path, str, Reader, DatasetReaderBase) – The source dataset to use for the tile client.

property band_names#

Return the names of each band in the dataset.

Returns:: Band name strings extracted from the dataset metadata.
Return type:: list of str

bounds(projection: str = 'EPSG:4326', return_polygon: bool = False, return_wkt: bool = False)#

Get the bounds of the dataset.

Parameters:

projection (str, optional) – The spatial reference system as a Proj4 or EPSG string for the returned coordinates. Defaults to "EPSG:4326".
return_polygon (bool, optional) – If True, return a shapely.geometry.Polygon instead of a tuple. Requires shapely.
return_wkt (bool, optional) – If True, return a Well Known Text (WKT) string of the bounding polygon. Requires shapely.

Returns:

tuple of float – A tuple of (bottom, top, left, right) when neither return_polygon nor return_wkt is True.
shapely.geometry.Polygon – When return_polygon is True.
str – WKT string when return_wkt is True.

center(projection: str = 'EPSG:4326', return_point: bool = False, return_wkt: bool = False)#

Get center in the form of (y <lat>, x <lon>).

Parameters:

projection (str) – The srs or projection as a Proj4 string of the returned coordinates.
return_point (bool, optional) – If true, returns a shapely.Point object.
return_wkt (bool, optional) – If true, returns a Well Known Text (WKT) string of center coordinates.

Returns:

tuple of float – A tuple of (y, x) (latitude, longitude) when neither return_point nor return_wkt is True.
shapely.geometry.Point – When return_point is True.
str – WKT string when return_wkt is True.

property dataset#

Return the underlying rasterio dataset.

Returns:: The opened rasterio dataset.
Return type:: rasterio.io.DatasetReaderBase

property default_zoom#

Return the default zoom level for the dataset.

This is set to min_zoom.

Returns:: The default zoom level.
Return type:: int

Extract data masked to a GeoJSON feature.

Parameters:

geojson (dict) – A GeoJSON Feature or Geometry dictionary. If a bare Geometry is provided, it is automatically wrapped in a Feature.
indexes (list of int, optional) – The band(s) of the source raster to use (default if None is to show RGB if available). Band indexing starts at 1.
colormap (str, optional) – The name of the matplotlib colormap to use when plotting a single band. Default is greyscale.
vmin (float or list of float, optional) – The minimum value to use when colormapping a single band.
vmax (float or list of float, optional) – The maximum value to use when colormapping a single band.
nodata (int or float, optional) – The value from the band to use to interpret as not valid data.
output_path (pathlib.Path, optional) – If provided, write the image to this file path.
encoding (str, optional) – The image encoding 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 (e.g., "EPSG:3857").
expression (str, optional) – Band math expression (e.g., "(b4-b1)/(b4+b1)"). Mutually exclusive with indexes.
stretch (str, optional) – Image stretch mode. One of "none", "minmax", "linear", "equalize", "sqrt", or "log". When set, overrides vmin/vmax.

Returns:

The masked image as binary data in the specified encoding.

Return type:

bytes

property filename#

Return the file path or URI of the source dataset.

Returns:: The file path or URI string.
Return type:: str

property info#

Return dataset info from the rio-tiler reader.

Returns:: Dataset information including CRS, bounds, and band details.
Return type:: rio_tiler.models.Info

property max_zoom#

Return the maximum zoom level for the dataset.

Returns:: The maximum zoom level.
Return type:: int

property metadata#

Return metadata for the source dataset.

Returns:: A dictionary of dataset metadata including band descriptions, data types, and statistics.
Return type:: dict

property min_zoom#

Return the minimum zoom level for the dataset.

Returns:: The minimum zoom level.
Return type:: int

Extract a spatial subset by bounding box.

Parameters:

bbox (tuple of float) – Bounding box as (left, bottom, right, top).
indexes (list of int, optional) – The band(s) of the source raster to use (default if None is to show RGB if available). Band indexing starts at 1.
colormap (str, optional) – The name of the matplotlib colormap to use when plotting a single band. Default is greyscale.
vmin (float or list of float, optional) – The minimum value to use when colormapping a single band.
vmax (float or list of float, optional) – The maximum value to use when colormapping a single band.
nodata (int or float, optional) – The value from the band to use to interpret as not valid data.
output_path (pathlib.Path, optional) – If provided, write the image to this file path.
encoding (str, optional) – The image encoding 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 (e.g., "EPSG:3857").
bounds_crs (str, optional) – CRS of the bbox coordinates. Defaults to the dataset’s native CRS.
expression (str, optional) – Band math expression (e.g., "(b4-b1)/(b4+b1)"). Mutually exclusive with indexes.
stretch (str, optional) – Image stretch mode. One of "none", "minmax", "linear", "equalize", "sqrt", or "log". When set, overrides vmin/vmax.

Returns:

The cropped image as binary data in the specified encoding.

Return type:

bytes

point(lon: float, lat: float, **kwargs)#

Query pixel values at a geographic coordinate.

Parameters:

lon (float) – Longitude of the query point.
lat (float) – Latitude of the query point.
**kwargs – Additional keyword arguments passed to the underlying get_point function.

Returns:

Per-band pixel values at the queried location.

Return type:

dict

property reader#

Return the rio-tiler Reader for the source dataset.

Returns:: The rio-tiler Reader instance.
Return type:: Reader

statistics(indexes: list[int] | None = None, expression: str | None = None)#

Get per-band statistics (min, max, mean, std, histogram).

Parameters:

indexes (list of int, optional) – Band indexes to compute statistics for.
expression (str, optional) – Band math expression to compute statistics on.

Returns:

Per-band statistics keyed by band name.

Return type:

dict

Generate a thumbnail preview of the dataset.

Parameters:

indexes (list of int, optional) – The band(s) of the source raster to use (default if None is to show RGB if available). Band indexing starts at 1. This can also be a list of integers to set which 3 bands to use for RGB.
colormap (str, optional) – The name of the matplotlib colormap to use when plotting a single band. Default is greyscale.
vmin (float or list of float, optional) – The minimum value to use when colormapping a single band.
vmax (float or list of float, optional) – The maximum value to use when colormapping a single band.
nodata (int or float, optional) – The value from the band to use to interpret as not valid data.
output_path (pathlib.Path, optional) – If provided, write the thumbnail image to this file path.
encoding (str, optional) – The image encoding format (e.g., "PNG", "JPEG"). Defaults to "PNG".
max_size (int, optional) – Maximum size of the thumbnail in pixels. Defaults to 512.
crs (str, optional) – Target CRS for the thumbnail projection (e.g., "EPSG:3857"). When set, the preview is reprojected to this CRS.
expression (str, optional) – Band math expression (e.g., "(b4-b1)/(b4+b1)"). Mutually exclusive with indexes.
stretch (str, optional) – Image stretch mode. One of "none", "minmax", "linear", "equalize", "sqrt", or "log". When set, overrides vmin/vmax.

Returns:

The thumbnail image as binary data in the specified encoding.

Return type:

bytes

Generate a tile from the source raster.

Parameters:

z (int) – The zoom level of the tile.
x (int) – The x coordinate of the tile.
y (int) – The y coordinate of the tile.
indexes (list of int, optional) – The band(s) of the source raster to use (default if None is to show RGB if available). Band indexing starts at 1. This can also be a list of integers to set which 3 bands to use for RGB.
colormap (str, optional) – The name of the matplotlib colormap to use when plotting a single band. Default is greyscale.
vmin (float or list of float, optional) – The minimum value to use when colormapping a single band.
vmax (float or list of float, optional) – The maximum value to use when colormapping a single band.
nodata (int or float, optional) – The value from the band to use to interpret as not valid data.
output_path (pathlib.Path, optional) – If provided, write the tile image to this file path.
encoding (str, optional) – The image encoding format (e.g., "PNG", "JPEG"). Defaults to "PNG".
expression (str, optional) – Band math expression (e.g., "(b4-b1)/(b4+b1)" for NDVI). Mutually exclusive with indexes.
stretch (str, optional) – Image stretch mode. One of "none", "minmax", "linear", "equalize", "sqrt", or "log". When set, overrides vmin/vmax.

Returns:

The tile image as binary data in the specified encoding.

Return type:

bytes

class localtileserver.client.TileServerMixin(port: int | str = 'default', debug: bool = False, host: str = '127.0.0.1', client_port: int | None = None, client_host: str | None = None, client_prefix: str | None = None, cors_all: bool = False)#

Serve tiles from a local raster file in a background thread.

Parameters:

port (int) – The port on your host machine to use for the tile server. This defaults to getting an available port.
debug (bool) – Run the tile server in debug mode.
host (str) – The host address to bind the tile server to.
client_port (int) – The port on your client browser to use for fetching tiles. This is useful when running in Docker and performing port forwarding.
client_host (str) – The host on which your client browser can access the server.
client_prefix (str) – The URL prefix used for proxied access to the tile server.
cors_all (bool) – If True, enable CORS for all origins on the tile server.

as_leaflet_layer()#

Create an ipyleaflet TileLayer for this dataset.

Returns:: A tile layer that can be added to an ipyleaflet.Map.
Return type:: ipyleaflet.TileLayer

property client_base_url#

Return the base URL used by the client browser to access tiles.

The URL is constructed from client_host, client_port, and client_prefix. Falls back to a relative path "/" when neither host nor port is configured.

Returns:: The client-facing base URL.
Return type:: str

property client_host#

Return the host used by the client browser to access tiles.

Returns:: The client-side host address, or None if not explicitly set.
Return type:: str or None

property client_port#

Return the port used by the client browser to access tiles.

Returns:: The client-side port number, or None if not explicitly set.
Return type:: int or None

property client_prefix#

Return the URL prefix used by the client for proxied access.

Returns:: The client URL prefix with {port} replaced by the actual server port, or None if not set.
Return type:: str or None

create_url(path: str, client: bool = False)#

Build a full URL for the given API path.

Parameters:

path (str) – The relative API path (e.g., "api/metadata").
client (bool, optional) – If True, build the URL using the client-facing host and port instead of the server-side values. Defaults to False.

Returns:

The fully-qualified URL with query parameters.

Return type:

str

enable_colab()#

Configure this client for use on Google Colab.

Sets client_host to "localhost" and client_port to the server port so that tiles are accessible within Colab.

get_leaflet_map(add_bounds: bool = False, **kwargs)#

Get an ipyleaflet Map centered and zoomed to the dataset bounds.

Parameters:

add_bounds (bool, optional) – If True, add a WKT boundary layer to the map. Requires shapely. Defaults to False.
**kwargs – Additional keyword arguments passed to ipyleaflet.Map.

Returns:

A map widget centered on the dataset with the default zoom level.

Return type:

ipyleaflet.Map

Get slippy maps tile URL (e.g., /zoom/x/y.png).

Parameters:

indexes (list of int, optional) – The band(s) of the source raster to use (default if None is to show RGB if available). Band indexing starts at 1. This can also be a list of integers to set which 3 bands to use for RGB.
colormap (str or Colormap or list of str, optional) – The name of the matplotlib colormap, a Colormap instance, or a list of color strings to use when plotting a single band. Default is greyscale.
vmin (float or list of float, optional) – The minimum value to use when colormapping a single band.
vmax (float or list of float, optional) – The maximum value to use when colormapping a single band.
nodata (int or float, optional) – The value from the band to use to interpret as not valid data.
client (bool, optional) – If True, build the URL using the client-facing host and port. Defaults to False.
expression (str, optional) – Band math expression (e.g., "(b4-b1)/(b4+b1)"). Mutually exclusive with indexes.
stretch (str, optional) – Image stretch mode. One of "none", "minmax", "linear", "equalize", "sqrt", or "log". When set, overrides vmin/vmax.

Returns:

The tile URL template with {z}/{x}/{y} placeholders.

Return type:

str

property server#

Return the background server instance.

Returns:: The managed server thread.
Return type:: server_thread.ServerThread

property server_base_url#

Return the base URL for the tile server.

Returns:: The full server base URL (e.g., "http://127.0.0.1:8080").
Return type:: str

property server_host#

Return the host the tile server is bound to.

Returns:: The server host address.
Return type:: str

property server_port#

Return the port the tile server is listening on.

Returns:: The server port number.
Return type:: int

shutdown(force: bool = False)#

Shut down the background tile server.

Parameters:: force (bool, optional) – If True, forcefully terminate the server. Defaults to False.

STACClient#

A client for serving tiles directly from a STAC item URL, without requiring a local file.

class localtileserver.STACClient(url: str, assets: list[str] | None = None, expression: str | None = None, port: int | str = 'default', debug: bool = False, host: str = '127.0.0.1', client_port: int | None = None, client_host: str | None = None, client_prefix: str | None = None, cors_all: bool = False)#

Bases: TileServerMixin

Tile client for STAC (SpatioTemporal Asset Catalog) items.

This is a separate class from TileClient rather than a unified client because the two are backed by fundamentally different rio-tiler reader types with incompatible APIs:

TileClient wraps rio_tiler.io.Reader and addresses data by band index (indexes=[1, 2, 3]). The full rendering pipeline (colormap, vmin/vmax, stretch, nodata) is available.
STACClient wraps rio_tiler.io.STACReader and addresses data by asset name (assets=["B04", "B03", "B02"]). The STAC tile endpoints currently pass rendering through to rio-tiler defaults without colormap/stretch support.

All of TilerInterface’s methods call handler functions (e.g. get_tile, get_preview) that expect a Reader. The STAC handler functions (get_stac_tile, get_stac_preview) accept different arguments, so the two cannot share an implementation today.

Future improvement: A unified TileClient could accept either source type and dispatch to the correct handler, exposing both indexes and assets parameters where appropriate. This would also be the place to wire colormap/stretch/vmin/vmax support into the STAC rendering path (currently unsupported at the endpoint level).

Parameters:

url (str) – URL to a STAC item JSON document.
assets (list of str, optional) – Default asset names to use for tiles and thumbnails.
expression (str, optional) – Default band math expression for cross-asset computations.
port (int or str, optional) – Port for the tile server. Defaults to an available port.
debug (bool, optional) – Run the tile server in debug mode.
host (str, optional) – Host address to bind the tile server to.
client_port (int, optional) – Port used by the client browser.
client_host (str, optional) – Host used by the client browser.
client_prefix (str, optional) – URL prefix for proxied access.
cors_all (bool, optional) – If True, enable CORS for all origins.

bounds()#

Get the geographic bounds of the STAC item.

Returns:: A tuple of (south, north, west, east) in EPSG:4326.
Return type:: tuple of float

center()#

Get the center of the STAC item in (lat, lon) form.

Returns:: A tuple of (latitude, longitude).
Return type:: tuple of float

property default_zoom#

Return the default zoom level for the STAC item.

Returns:: The minimum zoom level.
Return type:: int

property filename#

Return the STAC item URL.

Returns:: The STAC item URL.
Return type:: str

get_tile_url(assets: list[str] | None = None, expression: str | None = None, client: bool = False, **kwargs)#

Get slippy maps tile URL for the STAC item.

Parameters:

assets (list of str, optional) – Asset names to include. Falls back to the default assets.
expression (str, optional) – Band math expression. Falls back to the default expression.
client (bool, optional) – If True, build the URL using the client-facing host/port.
**kwargs – Accepted for compatibility with widget helpers; ignored.

Returns:

The tile URL template with {z}/{x}/{y} placeholders.

Return type:

str

stac_info(assets: list[str] | None = None)#

Get STAC item metadata.

Parameters:: assets (list of str, optional) – Asset names to query. Falls back to the default assets.
Returns:: Dictionary mapping asset names to their metadata.
Return type:: dict

statistics(assets: list[str] | None = None, **kwargs)#

Get per-asset/band statistics.

Parameters:

assets (list of str, optional) – Asset names to compute statistics for. Falls back to the default assets.
**kwargs – Additional keyword arguments passed to the underlying statistics function.

Returns:

Per-asset/band statistics.

Return type:

dict

thumbnail(assets: list[str] | None = None, expression: str | None = None, encoding: str = 'PNG', max_size: int = 512, output_path: Path | None = None)#

Generate a thumbnail preview of the STAC item.

Parameters:

assets (list of str, optional) – Asset names to read. Falls back to the default assets.
expression (str, optional) – Band math expression. Falls back to the default expression.
encoding (str, optional) – Output image format. Defaults to "PNG".
max_size (int, optional) – Maximum dimension of the thumbnail. Defaults to 512.
output_path (pathlib.Path, optional) – If provided, write the image to this file path.

Returns:

The thumbnail image as binary data.

Return type:

bytes

tile(z: int, x: int, y: int, assets: list[str] | None = None, expression: str | None = None, encoding: str = 'PNG')#

Generate a tile from the STAC item.

Parameters:

z (int) – Tile zoom level.
x (int) – Tile column index.
y (int) – Tile row index.
assets (list of str, optional) – Asset names to read. Falls back to the default assets.
expression (str, optional) – Band math expression. Falls back to the default expression.
encoding (str, optional) – Output image format. Defaults to "PNG".

Returns:

The tile image as binary data.

Return type:

bytes

Jupyter Widget Helpers#

Generate an ipyleaflet TileLayer for the given TileClient.

Parameters:

source (pathlib.Path or str or TileClient or rasterio.io.DatasetReaderBase) – The source of the tile layer. This can be a path on disk or an already open TileClient.
port (int or str, optional) – The port on your host machine to use for the tile server (if creating a tileserver). This is ignored if a TileClient is given. This defaults to getting an available port.
debug (bool, optional) – Run the tile server in debug mode (if creating a tileserver). This is ignored if a TileClient is given.
indexes (list of int, optional) – The band of the source raster to use (default if None is to show RGB if available). Band indexing starts at 1. This can also be a list of integers to set which 3 bands to use for RGB.
colormap (str or matplotlib.colors.Colormap or list of str, optional) – The name of the matplotlib colormap to use when plotting a single band. Default is greyscale.
vmin (float or list of float, optional) – The minimum value to use when colormapping a single band.
vmax (float or list of float, optional) – The maximum value to use when colormapping a single band.
nodata (int or float, optional) – The value from the band to use to interpret as not valid data.
attribution (str, optional) – Attribution for the source raster. This defaults to a message about it being a local file.
stretch (str, optional) – Image stretch mode. One of "none", "minmax", "linear", "equalize", "sqrt", or "log". When set, overrides vmin/vmax.
expression (str, optional) – Band math expression (e.g., "(b4-b1)/(b4+b1)" for NDVI). Mutually exclusive with indexes.
**kwargs – All additional keyword arguments are passed to ipyleaflet.TileLayer.

Returns:

The tile layer that can be added to an ipyleaflet.Map.

Return type:

ipyleaflet.TileLayer

Generate a folium TileLayer for the given TileClient.

Parameters:

source (pathlib.Path or str or TileClient or rasterio.io.DatasetReaderBase) – The source of the tile layer. This can be a path on disk or an already open TileClient.
port (int or str, optional) – The port on your host machine to use for the tile server (if creating a tileserver). This is ignored if a TileClient is given. This defaults to getting an available port.
debug (bool, optional) – Run the tile server in debug mode (if creating a tileserver). This is ignored if a TileClient is given.
indexes (list of int, optional) – The band of the source raster to use (default if None is to show RGB if available). Band indexing starts at 1. This can also be a list of integers to set which 3 bands to use for RGB.
colormap (str, optional) – The name of the matplotlib colormap to use when plotting a single band. Default is greyscale.
vmin (float or list of float, optional) – The minimum value to use when colormapping a single band.
vmax (float or list of float, optional) – The maximum value to use when colormapping a single band.
nodata (int or float, optional) – The value from the band to use to interpret as not valid data.
attr (str, optional) – Folium requires the custom tile source have an attribution. This defaults to a message about it being a local file.
stretch (str, optional) – Image stretch mode. One of "none", "minmax", "linear", "equalize", "sqrt", or "log". When set, overrides vmin/vmax.
expression (str, optional) – Band math expression (e.g., "(b4-b1)/(b4+b1)" for NDVI). Mutually exclusive with indexes.
**kwargs – All additional keyword arguments are passed to folium.TileLayer.

Returns:

The tile layer that can be added to a folium.Map.

Return type:

folium.TileLayer

class localtileserver.LocalTileServerLayerMixin#: Mixin class for tile layers using localtileserver.