Skip to main content

ArcGIS Tile Package Utilities

Project description

ArcGIS Tile Package Utilities

A Python 3 library for reading tiles and exporting tools from ArcGIS Tile Packages which contain tile caches using the ArcGIS Compact Tile Cache

Python Tests

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

Installation

pip install tpkutils --upgrade

Usage

Python API

Open a tile package:

from tpkutils import TPK

tpk = TPK('my_tiles.tpk')

# close when done
tpk.close()

Or use with:

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

You can query basic information about the tile package:

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

Tile access

You can iterate over individual tiles - for instance, to save to disk. Tiles are returned as a namedtuple: Tile(z, x, y, data):

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)

You can also just read tiles for a given zoom level or levels:

tpk.read_tiles(zoom=[4])

By default, tiles are returned according to the ArcGIS tile scheme. To output tiles in xyz scheme, the y-value needs to be flipped:

tpk.read_tiles(flip_y=True)

Note: no direct interface to read a single tile or tiles specified by x or y is currently provided.

Export to mbtiles

You can export a tile package to a MapBox mbtiles v1.1 file:

tpk.to_mbtiles('my_tiles.mbtiles')

Or just export a subset of zoom levels:

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

Note:

  • tiles are output to mbtiles format in xyz tile scheme.
  • mixed format tiles are not supported for export to mbtiles.

Export to disk

You can export the tile package to disk. Files are written to '[z]/[x]/[y].[ext]' where [ext] is one png or jpg. Alternative file names can be provided using the --path-format option.

By default, tiles will be written in the 'arcgis' tile scheme. If using tiles in an XYZ tilevserver or client, use the 'xyz' tile scheme.

Output directory must be empty.

tpk.to_disk('my_tiles')

You can export a subset of zoom levels, use the 'xyz' scheme, and omit empty (completely blank PNG or completely white JPG) tiles:

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

Note:

  • not recommended for large tile packages, as this will potentially create a large number of directories and files.
  • 'mixed' format is not supported

Metadata / descriptive attributes

Basic attributes describing the tile package are extracted from configuration files in the tile package. These are typically populated from the user interface for the ArcGIS tile package tool:

  • name: autopopulated by ArcGIS tile package tool, based on filename of map document
  • description: optional field in ArcGIS tile package tool
  • summary: required field in ArcGIS tile package tool
  • tags: required field in ArcGIS tile package tool
  • credits: optional field in ArcGIS tile package tool
  • use_constraints: optional field in ArcGIS tile package tool

MBtiles metadata

The metadata table in the mbtiles file is created from the attributes of the tile package. Right now, any of these attributes can be overwritten to control the contents of this table:

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

Two additional attributes are exposed specifically for use in 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.

Changes:

0.8.0 (unreleased)

  • removed Python 2 support

0.7.0

  • added ability to drop empty tiles when exporting to mbtiles via drop_empty option
  • added ability to drop completely transparent tiles in addition to completely white or black tiles
  • added ability to calculate tile bounds from highest zoom level exported to mbtiles
  • corrected zoom levels for tilesets where tiles start at zoom levels greater than 0
  • added --tile-bounds option to command line interface to calculate bounds from tiles available at highest exported zoom level
  • added --drop-empty option to command line interface to drop empty tiles when creating mbtiles

Credits:

Tile package format is described here.

Inspired by:

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

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

tpkutils-0.8.2.tar.gz (15.8 kB view details)

Uploaded Source

Built Distribution

tpkutils-0.8.2-py3-none-any.whl (14.1 kB view details)

Uploaded Python 3

File details

Details for the file tpkutils-0.8.2.tar.gz.

File metadata

  • Download URL: tpkutils-0.8.2.tar.gz
  • Upload date:
  • Size: 15.8 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/1.1.13 CPython/3.10.5 Linux/5.13.0-1029-azure

File hashes

Hashes for tpkutils-0.8.2.tar.gz
Algorithm Hash digest
SHA256 4c42ebfcddcfad86e676ff5cc202b92dc4d2fb4f443b4822e32ca6d790c9f36e
MD5 585a6c1b285f26c5fa110aed7de5ee79
BLAKE2b-256 c8e013321fa056b9b7e66cac19f8b91abeca40c1c423a5e4a3bfd307cda79f2f

See more details on using hashes here.

File details

Details for the file tpkutils-0.8.2-py3-none-any.whl.

File metadata

  • Download URL: tpkutils-0.8.2-py3-none-any.whl
  • Upload date:
  • Size: 14.1 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/1.1.13 CPython/3.10.5 Linux/5.13.0-1029-azure

File hashes

Hashes for tpkutils-0.8.2-py3-none-any.whl
Algorithm Hash digest
SHA256 3fca561e69b5c619a315d6f458c983b6681ccdcfa9ee5a84925d94018329086c
MD5 0c34370c962018a9a6ae93b7000c63c4
BLAKE2b-256 7b831dc08fb8dd201c41ab95dc014bb16106e644f5042b70f4b2c836a16e2b7b

See more details on using hashes here.

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