π 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) 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: 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) 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: 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) 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: 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) 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, 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.