π 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) ordiscrete
. If a palette is specified,linear
uses a piecewise linear interpolation, anddiscrete
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) ordiscrete
. If a palette is specified,linear
uses a piecewise linear interpolation, anddiscrete
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) ordiscrete
. If a palette is specified,linear
uses a piecewise linear interpolation, anddiscrete
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) ordiscrete
. If a palette is specified,linear
uses a piecewise linear interpolation, anddiscrete
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) ordiscrete
. If a palette is specified,linear
uses a piecewise linear interpolation, anddiscrete
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#