Skip to main content

A tile-on-demand tile server built with PIL and Tornado

Project description

projectile

PyPI - Python Version PyPI - Wheel PyPI - Downloads Tests

A tile-on-demand tile server built with PIL and Tornado.

Motivation

We want to store a high-resolution image in memory on the server as a numpy array. Then when a client requests a particular tile, we can make the PNG of the requested tile by slicing the numpy array and using PIL to write the resulting PNG back to the client through a StringIO stream.

This is primarily intended for building interactive visualizations in research settings where we might want to skip the time- and/or disk-intensive tile generation step required by typical tile servers.

Demo

Install projectile

$ pip install projectile

Serve a test image from the USC-SIPI Image Database:

$ projectile sanfran

Manually request a particular tile by navigating to http://localhost:8000/2/1/2.png.

Try zooming and panning in the demo client by navigating to http://localhost:8000/.

Serve one of your own images (any format readable by PIL) with

$ projectile some_image.tiff

or, if you have data in a numpy .npy file,

$ projectile some_image.npy

Load an image in grayscale mode and apply a colormap:

$ projectile --mode L --cmap viridis pentagon

Stress testing

To test the performance limits of on-demand tiling, download this high resolution map of Great Britain (8,150 × 13,086 pixels, file size: 102.74 MB) from Wikimedia Commons.

Grayscale performance test:

$ projectile britain.jpg -m L

Reducing tile resolution when running in color:

$ projectile britain.jpg --tile_size 128

Dependencies

  • numpy>=1.13.3
  • Pillow>=4.3.0
  • tornado>=4.5.2
  • matplotlib>=2.1.0

API

URL scheme

The server will serve grayscale and RGB images in their original colors at

/<z>/<x>/<y>/<s>.png

where <z> is the zoom level, <x> and <y> specify the coordinates of the tile at that zoom level (0/0 is the top left tile), and <s> specifies the image tile resolution in pixels (must be a power of 2).

The server will serve colormapped versions of a grayscale image at

/<z>/<x>/<y>/<s>/<cmap>/<vmin>/<vmax>.png

where <cmap> is the name of a matplotlib colormap, and <vmin> and <vmax> specify the range of image pixel values linearly interpolate against the colormap (pixel values outside this range will be clipped).

Using a custom client

If you like the projectile backend but just want to use a simple custom client contained in a single HTML file custom_client.html, you can run

$ projectile array.npy --client custom_client.html

to make projectile serve your client instead of the included demo client.

Using projectile in your existing Tornado web application

The core functionality is exposed in the TileHandler class defined in server.py, which you can use in your own Tornado web applications:

from tornado import web
from projectile.server import TileHandler

...

app = web.Application([
    (r'/([0-9]+)/([0-9]+)/([0-9]+)/([0-9]+).png', TileHandler,
     dict(array=array)),
    ...
])

...

Launching projectile from your own Python code

You can also launch a server from your own Python code with the run() function defined in server.py:

from projectile.server import run

run(array)

Credits

The demo client is lifted from http://bl.ocks.org/mbostock/5914438, with the addition of a small filtering check to prevent the client from requesting tiles which lie beyond the image boundaries.

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

projectile-0.0.6.tar.gz (26.1 kB view details)

Uploaded Source

Built Distribution

projectile-0.0.6-py2.py3-none-any.whl (9.2 kB view details)

Uploaded Python 2Python 3

File details

Details for the file projectile-0.0.6.tar.gz.

File metadata

  • Download URL: projectile-0.0.6.tar.gz
  • Upload date:
  • Size: 26.1 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.1.1 pkginfo/1.5.0.1 requests/2.22.0 setuptools/41.2.0 requests-toolbelt/0.9.1 tqdm/4.42.1 CPython/3.8.1

File hashes

Hashes for projectile-0.0.6.tar.gz
Algorithm Hash digest
SHA256 c3b02ec78dec050b4b1e90ed88f06f3e7c5e422780dda9652602a7787f7ef12e
MD5 c46e1d640ac7024b2697cef68f932257
BLAKE2b-256 b6a75b44db5905657b7b37179e9fe99e9dca035dab2726da73e4dcfe59a306e9

See more details on using hashes here.

File details

Details for the file projectile-0.0.6-py2.py3-none-any.whl.

File metadata

  • Download URL: projectile-0.0.6-py2.py3-none-any.whl
  • Upload date:
  • Size: 9.2 kB
  • Tags: Python 2, Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.1.1 pkginfo/1.5.0.1 requests/2.22.0 setuptools/41.2.0 requests-toolbelt/0.9.1 tqdm/4.42.1 CPython/3.8.1

File hashes

Hashes for projectile-0.0.6-py2.py3-none-any.whl
Algorithm Hash digest
SHA256 5ca4d4f5adf00a60067897664c0df8ccf84f87ade248280c51d64bf13c8604e6
MD5 a0502937c2a52d1ca93834c17e328a07
BLAKE2b-256 3cff965a46ef8085c6c050995ad64d0d7dd5e1469beeb2be478265e993501653

See more details on using hashes here.

Supported by

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