Metadata-Version: 2.1
Name: Mbtiler
Version: 2.5.1
Summary: Mbtiler is a python toolbox to manipulate map tiles.
Home-page: https://github.com/Elmeslmaney/Mbtiler
Download-URL: http://pypi.python.org/pypi/Mbtiler/
Author: Elmeslmaney
Author-email: mohamedelmeslmaney00@gmail.com
License: LPGL, see LICENSE file.
Keywords: MBTiles,Mapnik
Classifier: Programming Language :: Python :: 3.5
Classifier: Natural Language :: English
Classifier: Topic :: Utilities
Classifier: Development Status :: 5 - Production/Stable
License-File: LICENSE
Requires-Dist: mbutil
Requires-Dist: requests
Provides-Extra: mapnik
Requires-Dist: Mapnik >=2.0.0 ; extra == 'mapnik'
Provides-Extra: pil
Requires-Dist: Pillow ; extra == 'pil'

*Mbtiler* manipulates tiles, builds MBTiles, does tiles compositing and arrange tiles together into single images.

Tiles can either be obtained from a remote tile service URL, from a local Mapnik stylesheet,
a WMS server or from MBTiles files.

For building MBTiles, Mbtiler embeds *mbutil* from Mapbox https://github.com/mapbox/mbutil at the final stage.
The land covered is specified using a list of bounding boxes and zoom levels.


.. image:: https://pypip.in/v/Mbtiler/badge.png
    :target: https://pypi.python.org/pypi/Mbtiler

.. image:: https://pypip.in/d/Mbtiler/badge.png
    :target: https://pypi.python.org/pypi/Mbtiler

.. image:: https://travis-ci.org/makinacorpus/Mbtiler.png
    :target: https://travis-ci.org/makinacorpus/Mbtiler

.. image:: https://coveralls.io/repos/makinacorpus/Mbtiler/badge.png
    :target: https://coveralls.io/r/makinacorpus/Mbtiler


=======
INSTALL
=======

*Mbtiler* is pure python and has no external dependency. ::

    sudo easy_install Mbtiler

However, it requires `mapnik` if the tiles are rendered locally. ::

    sudo aptitude install python-mapnik

And `PIL` to blend tiles together or export arranged tiles into images. ::

    sudo aptitude install python-imaging

=====
USAGE
=====

Building MBTiles files
======================

Remote tiles
------------

Using a remote tile service (OpenStreetMap.org by default):
::

    import logging
    from Mbtiler import MBTilesBuilder

    logging.basicConfig(level=logging.DEBUG)
        
    mb = MBTilesBuilder(cache=False)
    mb.add_coverage(bbox=(-180.0, -90.0, 180.0, 90.0), 
                    zoomlevels=[0, 1])
    mb.run()

Please respect `Tile usage policies <http://wiki.openstreetmap.org/wiki/Tile_usage_policy>`

Local rendering
---------------

Using mapnik to render tiles:

::

    import logging
    from Mbtiler import MBTilesBuilder
    
    logging.basicConfig(level=logging.DEBUG)
    
    mb = MBTilesBuilder(stylefile="yourstyle.xml", filepath="dest.mbtiles")
    mb.add_coverage(bbox=(-180.0, -90.0, 180.0, 90.0),
                    zoomlevels=[0, 1])
    mb.run()


And with UTFGrids:

::

    import logging
    from Mbtiler import MBTilesBuilder
    
    logging.basicConfig(level=logging.DEBUG)
    
    mb = MBTilesBuilder(stylefile="yourstyle.xml",
                        grid_fields=["field1", "field2", "field3", ...] ,
                        filepath="dest.mbtiles")
    mb.add_coverage(bbox=(-180, -90, 180, 90),
                    zoomlevels=[0, 1, 2, 3])
    mb.run()


From an other MBTiles file
--------------------------
::

    import logging
    from Mbtiler import MBTilesBuilder
    
    logging.basicConfig(level=logging.DEBUG)
    
    mb = MBTilesBuilder(mbtiles_file="yourfile.mbtiles", filepath="dest.mbtiles")
    mb.add_coverage(bbox=(-180.0, -90.0, 180.0, 90.0), 
                    zoomlevels=[0, 1])
    mb.run()


From a WMS server
-----------------
::

    mb = MBTilesBuilder(wms_server="http://yourserver.com/geoserver/wms", 
                        wms_layers=["ign:departements"], 
                        wms_options=dict(format="image/png", 
                                         transparent=True),
                        filepath="dest.mbtiles")
    mb.add_coverage(bbox=([-0.9853,43.6435.1126,44.0639]))
    mb.run()



Blend tiles together
====================

Merge multiple sources of tiles (URL, WMS, MBTiles, Mapnik stylesheet) together. *(requires python PIL)*

For example, build a new MBTiles by blending tiles of a MBTiles on top of OpenStreetMap tiles :

::

    mb = MBTilesBuilder(filepath="merged.mbtiles")
    overlay = TilesManager(mbtiles_file="carto.mbtiles")
    mb.add_layer(overlay)
    mb.run()

Or composite a WMS layer with OpenStreetMap using transparency (40%):

:: 

    mb = MBTilesBuilder(wms_server="http://yourserver.com/geoserver/wms", 
                        wms_layers=["img:orthophoto"])
    overlay = TilesManager(remote=True)
    mb.add_layer(overlay, 0.4)
    mb.run()


Export Images
=============

Assemble and arrange tiles together into a single image. *(requires python PIL)*

Specify tiles sources in the exact same way as for building MBTiles files.

::

    import logging
    from Mbtiler import ImageExporter
    
    logging.basicConfig(level=logging.DEBUG)
    
    ie = ImageExporter(mbtiles_file="yourfile.mbtiles")
    ie.export_image(bbox=(-180.0, -90.0, 180.0, 90.0), zoomlevel=3, imagepath="image.png")


Add post-processing filters
===========================

Convert map tiles to gray scale, more suitable for information overlay :

::

    from Mbtiler.filters import GrayScale
    
    ie = ImageExporter()
    ie.add_filter(GrayScale())

Replace a specific color by transparent pixels (i.e. color to alpha, *a-la-Gimp*) :

::

    from Mbtiler.filters import ColorToAlpha
    
    overlay = TileManager()
    overlay.add_filter(ColorToAlpha('#ffffff'))  # white will be transparent
    
    ie = ImageExporter()
    ie.add_layer(overlay)
    ...


Extract MBTiles content
=======================

:: 

    from Mbtiler.sources import MBTilesReader
    
    mbreader = MBTilesReader("yourfile.mbtiles")
    
    # Metadata
    print mbreader.metadata()
    
    # Zoom levels
    print mbreader.zoomlevels()
    
    # Image tile
    with open('tile.png', 'wb') as out:
        out.write(mbreader.tile(z, x, y))
    
    # UTF-Grid tile
    print mbreader.grid(z, x, y, 'callback')



Manipulate tiles
================

::

    from Mbtiler import MBTilesBuilder
    
    # From a TMS tile server
    # tm = TilesManager(tiles_url="http://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png")
    
    # From a MBTiles file
    tm = TilesManager(mbtiles_file="yourfile.mbtiles")
    
    tiles = tm.tileslist(bbox=(-180.0, -90.0, 180.0, 90.0), 
                         zoomlevels=[0, 1])
    for tile in tiles:
        tilecontent = tm.tile(tile)  # download, extract or take from cache
        ...

Cache tiles are stored using TMS scheme by default (with ``y`` value flipped). It can be changed to WMTS (a.k.a ``xyz``) :

::

    tm = TilesManager(your_sources_options, cache=True, cache_scheme="wmts")


Run tests
=========

Run tests with nosetests (if you are working in a virtualenv, don't forget to install nose in it!):

::
    
    cd Mbtiler
    nosetests

The Mapnik stylesheet for the test about grid content comes from <https://github.com/springmeyer/gridsforkids>


=======
AUTHORS
=======

    * Mathieu Leplatre <mathieu.leplatre@makina-corpus.com>
    * Sergej Tatarincev
    * Ã‰ric BrÃ©hault
    * Waldemar Osuch
    * Isabelle Vallet
    * Thanks to mbutil authors <https://github.com/mapbox/mbutil>


.. image:: http://depot.makina-corpus.org/public/logo.gif
    :target: http://www.makina-corpus.com

=======
LICENSE
=======

    * Lesser GNU Public License


=========
CHANGELOG
=========

2.5.1.dev0
==================

*


2.5.0 (2019-04-16)
==================

* Add support of Python 3.


2.4.1 (2019-03-13)
==================

* Do not try to get tiles again when tiles doesn't exist.


2.4.0 (2017-03-02)
==================

* Do not crash when overlay tile data is not a valid image
* Correctly generate metadata for zoom levels
* Add support for tms mbtiles
* Correct tile box calculation for case when floating point value is an integer
* Correctly generate metadata for zoom levels
* Use the full path to construct the cache directory, as otherwise different
  tiles sets on the same server are considered to be the same one
* Added a name metadata to prevent Maptiler crash


2.3.0 (2014-11-18)
==================

* Add headers to WMS sources if specified (thanks @sempixel!)


2.2.0 (2014-09-22)
==================

* Add delay between tiles downloads retries (by @kiorky)
* Add option to ignore errors during MBTiles creation (e.g. download errors)


2.1.1 (2013-08-27)
==================

* Do not hard-code ``grid();`` JSONP callback.

2.1.0 (2013-08-27)
==================

* Add TMS support (ebrehault)
* Add default subdomains argument for TileSource
* Add ability to set HTTP headers for tiles
* Fix file corruption on Windows (by @osuchw)

2.0.3 (2013-05-03)
==================

* Fix Mapnik signature on render()

2.0.2 (2012-06-21)
==================

* Prevent the whole image to be converted to grayscale
* Explicitly check http status code at tiles download

2.0.1 (2012-05-29)
==================

* Fix infinite loop on blending layers

2.0.0 (2012-05-25)
==================

* Rework cache mechanism
* Jpeg tiles support (#14)
* Remove use of temporary files
* Image post-processing (#11)

2.0.0-alpha (2012-05-23)
========================

* Refactoring of whole stack

1.8.2 (2012-03-27)
==================

* Fix Mapnik rendering

1.8.1 (2012-02-24)
==================

* Fix MBTiles cache cleaning

1.8 (2012-02-24)
================

* WMS support
* Tiles compositing

1.7 (2012-02-17)
================

* Catch Sqlite exceptions

1.6 (2012-02-08)
================

* UTF-Grid support for MBTiles files

1.5 (2011-12-07)
================

* Subdomain support for tiles servers
* Low level tiles manipulation
* Use i18n

1.4 (2011-10-17)
================

* Remove extra logging message of mbutil

1.3 (2011-09-23)
================

* Export set of tiles into single image

1.2 (2011-06-21)
================

* Raise exception if no tiles in coverages

1.1 (2012-04-18)
================

* Move internals to Mbtiler module
* Split projection into separate module

1.0 (2011-04-18)
================

* Initial working version
