πŸ“– API#

Python Client#

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

A helper to safely get a TileClient from a path on disk.

Note

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

class localtileserver.client.BaseTileClientInterface(filename: Path | str, default_projection: str | None = 'EPSG:3857')#

Base TileClient methods and configuration.

This class does not perform any RESTful operations but will interface directly with large-image to produce results.

Parameters:

path (pathlib.Path, str) – The path on disk to use as the source raster for the tiles.

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

Get bounds in form of (ymin, ymax, xmin, xmax).

Parameters:
  • projection (str) – The EPSG projection of the returned coordinates. Can also be a Proj4 projection.

  • return_polygon (bool, optional) – If true, return a shapely.Polygon object of the bounding polygon of the raster.

  • return_wkt (bool, optional) – If true, return Well Known Text (WKT) string of the bounding polygon of the raster.

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.

create_url(path: str, **kwargs)#
property default_projection#
property default_zoom#
extract_roi(left: float, right: float, bottom: float, top: float, units: str = 'EPSG:4326', encoding: str = 'TILED', output_path: Path | None = None, return_bytes: bool = False, return_path: bool = False)#

Extract ROI in world coordinates.

extract_roi_pixel(left: int, right: int, bottom: int, top: int, encoding: str = 'TILED', output_path: Path | None = None, return_bytes: bool = False, return_path: bool = False)#

Extract ROI in pixel coordinates.

extract_roi_shape(shape, units: str = 'EPSG:4326', encoding: str = 'TILED', output_path: Path | None = None, return_bytes: bool = False, return_path: bool = False)#

Extract ROI in world coordinates using a Shapely Polygon.

Parameters:

shape – Anything shape-like (GeoJSON dict, WKT string, Shapely.Polygon) or anything with a bounds property that returns the bounding coordinates of the shape as: left, bottom, right, top.

property filename#
get_tile(z: int, x: int, y: int, *args, **kwargs)#

Get single tile binary.

get_tile_url(projection: str | None = '', band: int | List[int] = None, palette: str | List[str] = None, vmin: float | int | List[float | int] = None, vmax: float | int | List[float | int] = None, nodata: float | int | List[float | int] = None, scheme: str | List[str] = None, n_colors: int = 255, grid: bool = False, style: dict = None, cmap: str | List[str] = None)#

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

Parameters:
  • projection (str) – The Proj projection to use for the tile layer. Default is EPSG:3857.

  • band (int) – The band of the source raster to use (default in None 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.

  • palette (str) – The name of the color palette from palettable or colormap from matplotlib to use when plotting a single band. Default is greyscale. If viewing a single band, a list of hex colors can be passed for a user-defined color palette.

  • vmin (float) – The minimum value to use when colormapping the palette when plotting a single band.

  • vmax (float) – The maximized value to use when colormapping the palette when plotting a single band.

  • nodata (float) – The value from the band to use to interpret as not valid data.

  • scheme (str) – This is either linear (the default) or discrete. If a palette is specified, linear uses a piecewise linear interpolation, and discrete uses exact colors from the palette with the range of the data mapped into the specified number of colors (e.g., a palette with two colors will split exactly halfway between the min and max values).

  • n_colors (int) – The number (positive integer) of colors to discretize the matplotlib color palettes when used.

  • grid (bool) – Show the outline of each tile. This is useful when debugging your tile viewer.

  • style (dict, optional) – large-image JSON style. See https://girder.github.io/large_image/tilesource_options.html#style If given, this will override all other styling parameters.

  • cmap (str) – Alias for palette if not specified.

get_tile_url_params(projection: str | None = '', band: int | List[int] | None = None, palette: str | List[str] | None = None, vmin: float | int | List[float | int] | None = None, vmax: float | int | List[float | int] | None = None, nodata: float | int | List[float | int] | None = None, scheme: str | List[str] | None = None, n_colors: int = 255, grid: bool = False, style: dict | None = None, cmap: str | List[str] | None = None)#

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

Parameters:
  • projection (str) – The Proj projection to use for the tile layer. Default is EPSG:3857.

  • band (int) – The band of the source raster to use (default in None 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.

  • palette (str) – The name of the color palette from palettable or colormap from matplotlib to use when plotting a single band. Default is greyscale. If viewing a single band, a list of hex colors can be passed for a user-defined color palette.

  • vmin (float) – The minimum value to use when colormapping the palette when plotting a single band.

  • vmax (float) – The maximized value to use when colormapping the palette when plotting a single band.

  • nodata (float) – The value from the band to use to interpret as not valid data.

  • scheme (str) – This is either linear (the default) or discrete. If a palette is specified, linear uses a piecewise linear interpolation, and discrete uses exact colors from the palette with the range of the data mapped into the specified number of colors (e.g., a palette with two colors will split exactly halfway between the min and max values).

  • n_colors (int) – The number (positive integer) of colors to discretize the matplotlib color palettes when used.

  • grid (bool) – Show the outline of each tile. This is useful when debugging your tile viewer.

  • style (dict, optional) – large-image JSON style. See https://girder.github.io/large_image/tilesource_options.html#style If given, this will override all other styling parameters.

  • cmap (str) – Alias for palette if not specified.

histogram(bins: int = 256, density: bool = False)#

Get a histoogram for each band.

property is_geospatial#
property max_zoom#
metadata(projection: str | None = '')#
metadata_safe(projection: str | None = '')#
pixel(y: float, x: float, units: str = 'pixels', projection: str | None = None)#

Get pixel values for each band at the given coordinates (y <lat>, x <lon>).

Parameters:
  • y (float) – The Y coordinate (from top of image if pixels units or latitude if using EPSG)

  • x (float) – The X coordinate (from left of image if pixels units or longitude if using EPSG)

  • units (str) – The units of the coordinates (pixels or EPSG:4326).

  • projection (str, optional) – The projection in which to open the image.

property rasterio#

Open dataset with rasterio.

property server_base_url#
property server_host#
property server_port#
thumbnail(band: int | List[int] | None = None, palette: str | List[str] | None = None, vmin: float | int | List[float | int] | None = None, vmax: float | int | List[float | int] | None = None, nodata: float | int | List[float | int] | None = None, scheme: str | List[str] | None = None, n_colors: int = 255, output_path: Path | None = None, style: dict | None = None, cmap: str | List[str] | None = None, encoding: str = 'PNG')#
class localtileserver.TileClient(filename: Path | str | DatasetReaderBase | RasterioFileTileSource, default_projection: str | None = 'EPSG:3857', 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)#
class localtileserver.RemoteTileClient(filename: Path | str, default_projection: str | None = 'EPSG:3857', host: str | None = None)#

Connect to a remote localtileserver instance at a given host URL.

Parameters:
  • path (pathlib.Path, str) – The path on disk to use as the source raster for the tiles.

  • host (str) – The base URL of your remote localtileserver instance.

property server_base_url#
property server_host#

Jupyter Widget Helpers#

localtileserver.get_leaflet_tile_layer(source: Path | str | TileClient | DatasetReaderBase, port: int | str = 'default', debug: bool = False, projection: str | None = '', band: int | List[int] | None = None, palette: str | List[str] | None = None, vmin: float | int | List[float | int] | None = None, vmax: float | int | List[float | int] | None = None, nodata: float | int | List[float | int] | None = None, scheme: str | List[str] | None = None, n_colors: int = 255, attribution: str | None = None, style: dict | None = None, cmap: str | List[str] | None = None, default_projection: str | None = 'EPSG:3857', **kwargs)#

Generate an ipyleaflet TileLayer for the given TileClient.

Parameters:
  • source (Union[pathlib.Path, str, TileClient, rasterio.io.DatasetReaderBase]) – The source of the tile layer. This can be a path on disk or an already open TileClient

  • port (int) – The port on your host machine to use for the tile server (if creating a tileserver. This is ignored if a file path is given). This defaults to getting an available port.

  • debug (bool) – Run the tile server in debug mode (if creating a tileserver. This is ignored if a file path is given).

  • projection (str) – The Proj projection to use for the tile layer. Default is EPSG:3857.

  • band (int) – The band of the source raster to use (default in None 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.

  • palette (str) – The name of the color palette from palettable to use when plotting a single band. Default is greyscale.

  • vmin (float) – The minimum value to use when colormapping the palette when plotting a single band.

  • vmax (float) – The maximized value to use when colormapping the palette when plotting a single band.

  • nodata (float) – The value from the band to use to interpret as not valid data.

  • scheme (str) – This is either linear (the default) or discrete. If a palette is specified, linear uses a piecewise linear interpolation, and discrete uses exact colors from the palette with the range of the data mapped into the specified number of colors (e.g., a palette with two colors will split exactly halfway between the min and max values).

  • n_colors (int) – The number (positive integer) of colors to discretize the matplotlib color palettes when used.

  • attribution (str) – Attribution for the source raster. This defaults to a message about it being a local file.

  • style (dict, optional) – large-image JSON style. See https://girder.github.io/large_image/tilesource_options.html#style If given, this will override all other styling parameters.

  • cmap (str) – Alias for palette if not specified.

  • **kwargs – All additional keyword arguments are passed to ipyleaflet.TileLayer.

Return type:

ipyleaflet.TileLayer

localtileserver.get_leaflet_roi_controls(client: TileClient, button_position: str = 'topright', output_directory: Path = '.', debug: bool = False)#

Generate an ipyleaflet DrawControl and WidgetControl to add to your map for ROI extraction.

Parameters:
  • button_position (str) – The button position of the WidgetControl.

  • output_directory (pathlib.Path) – The directory to save the ROIs. Defaults to working directory.

  • debug (bool) – Return a widgets.Output to debug the ROI extraction callback.

Return type:

tuple(ipyleaflet.DrawControl, ipyleaflet.WidgetControl)

localtileserver.get_folium_tile_layer(source: Path | str | TileClient | DatasetReaderBase, port: int | str = 'default', debug: bool = False, projection: str | None = '', band: int | List[int] | None = None, palette: str | List[str] | None = None, vmin: float | int | List[float | int] | None = None, vmax: float | int | List[float | int] | None = None, nodata: float | int | List[float | int] | None = None, scheme: str | List[str] | None = None, n_colors: int = 255, attr: str | None = None, style: dict | None = None, cmap: str | List[str] | None = None, default_projection: str | None = 'EPSG:3857', **kwargs)#

Generate a folium TileLayer for the given TileClient.

Parameters:
  • source (Union[pathlib.Path, str, TileClient, rasterio.io.DatasetReaderBase]) – The source of the tile layer. This can be a path on disk or an already open TileClient

  • port (int) – The port on your host machine to use for the tile server (if creating a tileserver. This is ignored if a file path is given). This defaults to getting an available port.

  • debug (bool) – Run the tile server in debug mode (if creating a tileserver. This is ignored if a file path is given).

  • projection (str) – The Proj projection to use for the tile layer. Default is EPSG:3857.

  • band (int) – The band of the source raster to use (default in None 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.

  • palette (str) – The name of the color palette from palettable to use when plotting a single band. Default is greyscale.

  • vmin (float) – The minimum value to use when colormapping the palette when plotting a single band.

  • vmax (float) – The maximized value to use when colormapping the palette when plotting a single band.

  • nodata (float) – The value from the band to use to interpret as not valid data.

  • scheme (str) – This is either linear (the default) or discrete. If a palette is specified, linear uses a piecewise linear interpolation, and discrete uses exact colors from the palette with the range of the data mapped into the specified number of colors (e.g., a palette with two colors will split exactly halfway between the min and max values).

  • n_colors (int) – The number (positive integer) of colors to discretize the matplotlib color palettes when used.

  • attr (str) – Folium requires the custom tile source have an attribution. This defaults to a message about it being a local file.

  • style (dict, optional) – large-image JSON style. See https://girder.github.io/large_image/tilesource_options.html#style If given, this will override all other styling parameters.

  • cmap (str) – Alias for palette if not specified.

  • **kwargs – All additional keyword arguments are passed to folium.TileLayer.

Return type:

folium.TileLayer

Other Helpers#

localtileserver.helpers.save_new_raster(src, data, out_path: str | None = None)#

Save new raster from a numpy array using the metadata of another raster.

Note

Requires rasterio

Parameters:
  • src (str, DatasetReader, BaseTileClientInterface) – The source rasterio data whose spatial reference will be copied

  • data (np.ndarray) – The bands of data to save to the new raster

  • out_path (Optional[str]) – The path for which to write the new raster. If None, this will use a temporary file

localtileserver.make_vsi(url: str, **options)#
localtileserver.validate.validate_cog(path: str | RasterioFileTileSource | BaseTileClientInterface, strict: bool = True, warn: bool = True)#
localtileserver.helpers.polygon_to_geojson(polygon) str#

Dump shapely.Polygon to GeoJSON.