tpkutils 0.5.1

Goals

• easy access to tiles in a tile package

• export to mbtiles, for hosting on any of a variety of mbtiles servers, such as mbtileserver

Our workflow

• create beautiful maps in ArcGIS Desktop

• export to ArcGIS tile package

• convert to mbtiles format using this package

• host as an XYZ tile service using mbtileserver

Installation

For now, while this is under active development, install from master branch on GitHub using pip:

pip install git+https://github.com/consbio/tpkutils.git --upgrade

Once functionality stabilizes, it will be added to PyPi

Usage

from tpkutils import TPK

tpk = TPK('my_tiles.tpk')

# close when done
tpk.close()

with TPK('my_tiles.tpk') as tpk:

tpk.bounds  # tuple of (xmin, ymin, xmax, ymax) in geographic coordinates
tpk.zoom_levels  # list of zoom levels available in package [0,1,...]

for tile in tpk.read_tiles():
    with open('{0}_{1}_{2}.png'.format(tile.x, tile.y, tile.z), 'wb') as outfile:
        outfile.write(tile.data)

tpk.read_tiles(zoom=[4])

tpk.read_tiles(flip_y=True)

tpk.to_mbtiles('my_tiles.mbtiles')

tpk.to_mbtiles('fewer_tiles.mbtiles', zoom=[0,1,2,3,4])

tpk.to_disk('my_tiles')

tpk.to_disk('my_tiles', zoom=[0,1,2], scheme='xyz', drop_empty=True)

tpk.name = 'Some new name'
tpk.description = 'This is a much better description'
tpk.to_mbtiles(...)

tpk.version  # version of tileset, defaults to 1.0.0
tpk.attribution  # copyright / attribution statement.  Used by some
                 # clients for attribution info shown on map.

Command line interface

You can also use the command line to perform export operations:

$ tpk export mbtiles --help
Usage: tpk export mbtiles [OPTIONS] TPK_FILENAME MBTILES_FILENAME

  Export the tile package to mbtiles format

Options:
  -z, --zoom TEXT  Limit zoom levels to export: "0,1,2"
  --overwrite      Overwrite existing mbtiles file  [default: False]
  -v, --verbose    Verbose output
  --help           Show this message and exit.

$ tpk export disk --help
Usage: tpk export disk [OPTIONS] TPK_FILENAME PATH

  Export the tile package to disk: z/x/y.<ext> or pattern specified using
  --path-format option.

  Will use the 'arcgis' tile scheme by default.  If using with an XYZ tile
  server or client, use the 'xyz' tile scheme.

  Not recommended for higher zoom levels as this will produce large
  directory trees.

Options:
  -z, --zoom TEXT        Limit zoom levels to export: "0,1,2"
  --scheme [xyz|arcgis]  Tile numbering scheme: xyz or arcgis  [default:
                         arcgis]
  --drop-empty           Drop empty tiles from output
  --path-format TEXT     Format expression for output tile files, within
                         output path. Must contain parameters for z, x, y, and
                         ext (extension).  [default: {z}/{x}/{y}.{ext}]
  -p, --preview          Preview the exported tiles in a simple map.
  -v, --verbose          Verbose output
  --help                 Show this message and exit.

Note

All tile packages are assumed to follow the Web Mercator Tiling Scheme (Google/Bing/etc), and be in the Web Mercator coordinate reference system.

Developed and tested using image tile packages created using ArcGIS 10.3; however, these appear to use the 10.1 compact bundle format.

ArcGIS Server 10.3 introduced a new version of the compact bundle, which is not handled here yet. If you want this, please submit an issue with a small test file in 10.3 format.

Tile packages created using other versions may not work correctly (please log an issue with test data).

Versions from ArcGIS older than 10.1 are unlikely to be supported.

No support for Python 2 is planned.

Credits:

Tile package format is described here.

Inspired by: * tiler-arcgis-bundle * mbutil * node-mbtiles

SQL for creating mbtiles database derived from node-mbtiles

ArcGIS is a trademark of of ESRI and is used here to refer to specific technologies. No endorsement by ESRI is implied.

License:

See LICENSE.md