Skip to main content

Locally serve geospatial raster tiles in the Slippy Map standard.

Project description

🌐 Local Tile Server for Geospatial Rasters

codecov PyPI

Need to visualize a rather large (gigabytes) raster you have locally? This is for you.

A Flask application for serving tiles from large raster files in the Slippy Maps standard (i.e., /zoom/x/y.png)

tile-diagram

🌟 Highlights

  • Create a local tile server for large geospatial images
  • View local raster files with ipyleaflet or folium
  • Extract regions of interest (ROIs) interactively
  • Use the example datasets to generate Digital Elevation Models
  • Visualize rasters with the included CesiumJS web viewer

ℹ️ Overview

Under the hood, this uses large_image to launch a tile server in a background thread which will serve raster imagery to a tile viewer (see ipyleaflet and folium examples below). This tile server can efficiently deliver varying levels of detail of your raster imagery to your viewer; it helps to have pre-tiled, Cloud Optimized GeoTIFFs (COG), but no wories if not as large_image will tile and cache for you when opening the raster.

There is an included, standalone web viewer leveraging CesiumJS and GeoJS. You can use the web viewer to select and extract regions of interest from rasters.

Disclaimer: I put this together over a weekend and I'm definitely going to change a few things moving forward to make it more stable/robust. This means that things will most likely break between minor releases (I use the major.minor.patch versioning scheme).

⬇️ Installation

Install from PyPI: https://pypi-hypernode.com/project/localtileserver/

pip install localtileserver

📝 A Brief Note on Installing GDAL

GDAL can be a pain in the 🍑 to install, and you may want to handle GDAL before installing localtileserver.

If on linux, I highly recommend using the large_image_wheels from Kitware.

pip install --find-links=https://girder.github.io/large_image_wheels --no-cache GDAL

Otherwise, I recommend using conda:

conda install -c conda-forge GDAL

💭 Feedback

Please share your thoughts and questions on the Discussions board. If you would like to report any bugs or make feature requests, please open an issue.

If filing a bug report, please share a scooby Report:

import localtileserver
print(localtileserver.Report())

🚀 Usage

🍃 ipyleaflet Tile Layers

The TileClient class is a nifty tool to launch a tile server as a background thread to serve image tiles from any raster file on your local file system. Additionally, it can be used in conjunction with the get_leaflet_tile_layer utility to create an ipyleaflet.TileLayer for interactive visualization in a Jupyter notebook. Here is an example:

from localtileserver import get_leaflet_tile_layer, TileClient
from ipyleaflet import Map

# First, create a tile server from local raster file
tile_client = TileClient('~/Desktop/TC_NG_SFBay_US_Geo.tif')

# Create ipyleaflet tile layer from that server
t = get_leaflet_tile_layer(tile_client)

# Create ipyleaflet map, add tile layer, and display
m = Map(center=tile_client.center())
m.add_layer(t)
m

ipyleaflet

🥓 Two Rasters at Once

from localtileserver import get_leaflet_tile_layer
from ipyleaflet import Map, ScaleControl, FullScreenControl, SplitMapControl

# Create 2 tile layers from 2 separate raster files
l = get_leaflet_tile_layer('~/Desktop/TC_NG_SFBay_US_Geo.tif',
                           band=1, palette='matplotlib.Viridis_20', vmin=50, vmax=200)
r = get_leaflet_tile_layer('~/Desktop/small.tif',
                           band=2, palette='matplotlib.Plasma_6', vmin=0, vmax=150)

# Make the ipyleaflet map
m = Map(center=(37.7249511580583, -122.27230466902257), zoom=9)
control = SplitMapControl(left_layer=l, right_layer=r)
m.add_control(control)
m.add_control(ScaleControl(position='bottomleft'))
m.add_control(FullScreenControl())
m

ipyleaflet-double

🎯 Using ipyleaflet for ROI Extraction

I have included the get_leaflet_roi_controls utility to create some leaflet UI controls for extracting regions of interest from a tile client. You can use it as follows and then draw a polygon and click the "Extract ROI" button.

The outputs are save in your working directory by default (next to the Jupyter notebook).

from localtileserver import get_leaflet_tile_layer, get_leaflet_roi_controls
from localtileserver import TileClient
from ipyleaflet import Map

# First, create a tile server from local raster file
tile_client = TileClient('~/Desktop/TC_NG_SFBay_US_Geo.tif')

# Create ipyleaflet tile layer from that server
t = get_leaflet_tile_layer(tile_client)

# Create ipyleaflet controls to extract an ROI
draw_control, roi_control = get_leaflet_roi_controls(tile_client)

# Create ipyleaflet map, add layers, add controls, and display
m = Map(center=(37.7249511580583, -122.27230466902257), zoom=9)
m.add_layer(t)
m.add_control(draw_control)
m.add_control(roi_control)
m

ipyleaflet-draw-roi

🌳 folium Tile Layers

Similarly to the support provided for ipyleaflet, I have included a utility to generate a folium.TileLayer with get_folium_tile_layer. Here is an example with almost the exact same code as the ipyleaflet example, just note that Map is imported from folium and we use add_child instead of add_layer:

from localtileserver import get_folium_tile_layer
from localtileserver import TileClient
from folium import Map

# First, create a tile server from local raster file
tile_client = TileClient('~/Desktop/TC_NG_SFBay_US_Geo.tif')

# Create folium tile layer from that server
t = get_folium_tile_layer(tile_client)

m = Map(location=tile_client.center())
m.add_child(t)
m

folium

🗺️ Example Datasets

A few example datasets are included with localtileserver. A particularly useful one has global elevation data which you can use to create high resolution Digital Elevation Models (DEMs) of a local region.

from localtileserver import get_leaflet_tile_layer, get_leaflet_roi_controls, examples
from ipyleaflet import Map

# Load example tile layer from publicly available DEM source
tile_client = examples.get_elevation()

# Create ipyleaflet tile layer from that server
t = get_leaflet_tile_layer(tile_client,
                           band=1, vmin=-500, vmax=5000,
                           palette='matplotlib.Plasma_6',
                           opacity=0.75)

# Create ipyleaflet controls to extract an ROI
draw_control, roi_control = get_leaflet_roi_controls(tile_client)

m = Map(zoom=2)
m.add_layer(t)
m.add_control(draw_control)
m.add_control(roi_control)
m

elevation

Then you can follow the same routine as described above to extract an ROI.

I zoomed in over Golden, Colorado and drew a polygon of the extent of the DEM I would like to create:

golden

And perform the extraction:

roi_path = '...'  # Look in your working directory

r = get_leaflet_tile_layer(roi_path, band=1,
                           palette='matplotlib.Plasma_6', opacity=0.75)

m2 = Map(
        center=(39.763427033262175, -105.20614908076823),
        zoom=12,
       )
m2.add_layer(r)
m2

golden-dem

Here is another example with the Virtual Earth satellite imagery

from localtileserver import get_leaflet_tile_layer, examples
from ipyleaflet import Map

# Load example tile layer from publicly available imagery
tile_client = examples.get_virtual_earth()

# Create ipyleaflet tile layer from that server
t = get_leaflet_tile_layer(tile_client, opacity=1)

m = Map(center=(39.751343612695145, -105.22181306125279), zoom=18)
m.add_layer(t)
m

kafadar

🖥️ Local Web Application

Launch the tileserver from the commandline to use the included web application where you can view the raster and extract regions of interest.

python -m localtileserver path/to/raster.tif

cesium-viewer

You can use the web viewer to extract regions of interest:

webviewer-roi

You can also launch the web viewer with any of the available example datasets:

python -m localtileserver dem

Available choices are:

  • dem or elevation: global elevation dataset
  • blue_marble: Blue Marble satellite imagery
  • virtual_earth: Microsoft's satellite/aerial imagery
  • arcgis: ArcGIS World Street Map
  • bahamas: Sample raster over the Bahamas

Usage Notes

  • get_leaflet_tile_layer accepts either an existing TileClient or a path from which to create a TileClient under the hood.
  • The color palette choices come from palettable.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

localtileserver-0.3.3.tar.gz (864.1 kB view details)

Uploaded Source

Built Distribution

localtileserver-0.3.3-py3-none-any.whl (869.4 kB view details)

Uploaded Python 3

File details

Details for the file localtileserver-0.3.3.tar.gz.

File metadata

  • Download URL: localtileserver-0.3.3.tar.gz
  • Upload date:
  • Size: 864.1 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.6.0 importlib_metadata/4.8.2 pkginfo/1.8.1 requests/2.26.0 requests-toolbelt/0.9.1 tqdm/4.62.3 CPython/3.8.12

File hashes

Hashes for localtileserver-0.3.3.tar.gz
Algorithm Hash digest
SHA256 af3c2392bec7ab6df45fe4e0036f54eb2eca02f55eb07b7cc341ab23f092146c
MD5 f3abaa7e122f7ea4dbb4ce4bab23e167
BLAKE2b-256 5936f4beecc2e75beaa7bf60d6037d2454fbd951f9792230bf46076583f1fbe5

See more details on using hashes here.

Provenance

File details

Details for the file localtileserver-0.3.3-py3-none-any.whl.

File metadata

  • Download URL: localtileserver-0.3.3-py3-none-any.whl
  • Upload date:
  • Size: 869.4 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.6.0 importlib_metadata/4.8.2 pkginfo/1.8.1 requests/2.26.0 requests-toolbelt/0.9.1 tqdm/4.62.3 CPython/3.8.12

File hashes

Hashes for localtileserver-0.3.3-py3-none-any.whl
Algorithm Hash digest
SHA256 f0980e17f84b8f1f09082bd9b52465a9c346826e20d6b9ee16116b4fceb4bf99
MD5 d4e2407dbc49790befdb9908f7a9842a
BLAKE2b-256 dddf9e50a6b3af7861ae02e7256d962ad38b172df1344c6732d7b3be500ebc65

See more details on using hashes here.

Provenance

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page