πŸ“– API#

Python Client#

localtileserver.get_or_create_tile_client(source: Union[pathlib.Path, str, localtileserver.client.TileClient, None, large_image.tilesource.base.FileTileSource], port: Union[int, str] = 'default', debug: bool = False, default_projection: Optional[str] = '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.BaseTileClient(filename: Union[pathlib.Path, str], default_projection: Optional[str] = 'EPSG:3857')#

Connect to a localtileserver instance.

Parameters

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

bounds(projection: str = 'EPSG:4326')#

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

center(projection: str = 'EPSG:4326')#

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

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: Optional[pathlib.Path] = None)#

Extract ROI in world coordinates.

extract_roi_pixel(left: int, right: int, bottom: int, top: int, encoding: str = 'TILED', output_path: Optional[pathlib.Path] = None)#

Extract ROI in pixel coordinates.

property filename#
get_tile_url(projection: Optional[str] = '', band: Union[int, List[int]] = None, palette: Union[str, List[str]] = None, vmin: Union[float, int, List[Union[float, int]]] = None, vmax: Union[float, int, List[Union[float, int]]] = None, nodata: Union[float, int, List[Union[float, int]]] = None, scheme: Union[str, List[str]] = None, n_colors: int = 255, grid: bool = False, style: dict = None, cmap: Union[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: Optional[str] = '', band: Optional[Union[int, List[int]]] = None, palette: Optional[Union[str, List[str]]] = None, vmin: Optional[Union[float, int, List[Union[float, int]]]] = None, vmax: Optional[Union[float, int, List[Union[float, int]]]] = None, nodata: Optional[Union[float, int, List[Union[float, int]]]] = None, scheme: Optional[Union[str, List[str]]] = None, n_colors: int = 255, grid: bool = False, style: Optional[dict] = None, cmap: Optional[Union[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.

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

Get a histoogram for each band.

property is_geospatial#
property max_zoom#
metadata(projection: Optional[str] = '')#
metadata_safe(projection: Optional[str] = '')#
pixel(y: float, x: float, units: str = 'pixels', projection: Optional[str] = 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 server_base_url#
property server_host#
property server_port#
thumbnail(band: Optional[Union[int, List[int]]] = None, palette: Optional[Union[str, List[str]]] = None, vmin: Optional[Union[float, int, List[Union[float, int]]]] = None, vmax: Optional[Union[float, int, List[Union[float, int]]]] = None, nodata: Optional[Union[float, int, List[Union[float, int]]]] = None, scheme: Optional[Union[str, List[str]]] = None, n_colors: int = 255, output_path: Optional[pathlib.Path] = None, style: Optional[dict] = None, cmap: Optional[Union[str, List[str]]] = None)#
class localtileserver.TileClient(filename: Union[pathlib.Path, str, None, large_image.tilesource.base.FileTileSource], default_projection: Optional[str] = 'EPSG:3857', port: Union[int, str] = 'default', debug: bool = False, host: str = '127.0.0.1', client_port: Optional[int] = None, client_host: Optional[str] = None, client_prefix: Optional[str] = None, cors_all: bool = False)#

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

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

  • 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.

  • 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.

property client_base_url#
property client_host#
property client_port#
property client_prefix#
create_url(path: str, client: bool = False)#
get_tile_url(projection: Optional[str] = '', band: Union[int, List[int]] = None, palette: Union[str, List[str]] = None, vmin: Union[float, int, List[Union[float, int]]] = None, vmax: Union[float, int, List[Union[float, int]]] = None, nodata: Union[float, int, List[Union[float, int]]] = None, scheme: Union[str, List[str]] = None, n_colors: int = 255, grid: bool = False, style: dict = None, cmap: Union[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.

property server#
property server_base_url#
property server_host#
property server_port#
shutdown(force: bool = False)#
class localtileserver.RemoteTileClient(filename: Union[pathlib.Path, str], default_projection: Optional[str] = 'EPSG:3857', host: Optional[str] = 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: Optional[Union[pathlib.Path, str, localtileserver.client.TileClient]], port: Union[int, str] = 'default', debug: bool = False, projection: Optional[str] = '', band: Optional[Union[int, List[int]]] = None, palette: Optional[Union[str, List[str]]] = None, vmin: Optional[Union[float, int, List[Union[float, int]]]] = None, vmax: Optional[Union[float, int, List[Union[float, int]]]] = None, nodata: Optional[Union[float, int, List[Union[float, int]]]] = None, scheme: Optional[Union[str, List[str]]] = None, n_colors: int = 255, attribution: Optional[str] = None, style: Optional[dict] = None, cmap: Optional[Union[str, List[str]]] = None, default_projection: Optional[str] = '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: localtileserver.client.TileClient, button_position: str = 'topright', output_directory: pathlib.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: Optional[Union[pathlib.Path, str, localtileserver.client.TileClient]], port: Union[int, str] = 'default', debug: bool = False, projection: Optional[str] = '', band: Optional[Union[int, List[int]]] = None, palette: Optional[Union[str, List[str]]] = None, vmin: Optional[Union[float, int, List[Union[float, int]]]] = None, vmax: Optional[Union[float, int, List[Union[float, int]]]] = None, nodata: Optional[Union[float, int, List[Union[float, int]]]] = None, scheme: Optional[Union[str, List[str]]] = None, n_colors: int = 255, attr: Optional[str] = None, style: Optional[dict] = None, cmap: Optional[Union[str, List[str]]] = None, default_projection: Optional[str] = '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_path, out_path, data)#

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

Requires rasterio

Parameters
  • src_path (str) – The source data whose spatial reference will be copied

  • out_path (str) – The path for which to write the new raster

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

localtileserver.make_vsi(url: str, **options)#
localtileserver.validate.validate_cog(path: Union[str, large_image.tilesource.base.FileTileSource, localtileserver.client.BaseTileClient], check_tiled: bool = True, full_check: bool = False, strict: bool = True, warn: bool = True)#

Exceptions#

class localtileserver.validate.ValidateCloudOptimizedGeoTIFFException#