📖 API#

Python Client#

localtileserver.get_or_create_tile_client(source: Path | str | TileClient | None | FileTileSource, 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.BaseTileClient(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 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 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')#

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)#

enable_colab()#: Configure this client for use on Google Colab.

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: 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#

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)

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, BaseTileClient) – 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 | FileTileSource | BaseTileClient, check_tiled: bool = True, full_check: bool = False, strict: bool = True, warn: bool = True)#

localtileserver.helpers.polygon_to_geojson(polygon) → str#: Dump shapely.Polygon to GeoJSON.