ungarj / tilematrix

helps handling tile pyramids

Tilematrix

Tilematrix handles geographic web tiles and tile pyramids.

The module is designed to translate between tile indices (zoom, row, column = ZYX) and map coordinates (e.g. latitute, longitude).

Tilematrix supports metatiling and tile buffers. Furthermore it makes heavy use of shapely and it can also generate Affine objects per tile which facilitates working with rasterio for tile based data reading and writing.

It is very similar to mercantile but besides of supporting spherical mercator tile pyramids, it also supports geodetic (WGS84) tile pyramids.

Installation

Use conda to install the latest stable version:

conda install -c conda-forge -y tilematrix

Use pip to install the latest stable version:

pip install tilematrix

Manually install the latest development version

pip install -r requirements.txt
python setup.py install

Documentation

• API documentation
• examples

CLI

This package ships with a command line tool tmx which provides the following subcommands:

• bounds: Print bounds of given Tile.
• bbox: Print bounding box geometry of given Tile.
• tile: Print Tile covering given point.
• tiles: Print Tiles covering given bounds.

Geometry outputs can either be formatted as WKT or GeoJSON. For example the following command will print a valid GeoJSON representing all tiles for zoom level 1 of the geodetic WMTS grid:

$ tmx -f GeoJSON tiles -- 1 -180 -90 180 90
{
  "type": "FeatureCollection",
  "features": [
    {"geometry": {"coordinates": [[[-90.0, 0.0], [-90.0, 90.0], [-180.0, 90.0], [-180.0, 0.0], [-90.0, 0.0]]], "type": "Polygon"}, "properties": {"col": 0, "row": 0, "zoom": 1}, "type": "Feature"},
    {"geometry": {"coordinates": [[[0.0, 0.0], [0.0, 90.0], [-90.0, 90.0], [-90.0, 0.0], [0.0, 0.0]]], "type": "Polygon"}, "properties": {"col": 1, "row": 0, "zoom": 1}, "type": "Feature"},
    {"geometry": {"coordinates": [[[90.0, 0.0], [90.0, 90.0], [0.0, 90.0], [0.0, 0.0], [90.0, 0.0]]], "type": "Polygon"}, "properties": {"col": 2, "row": 0, "zoom": 1}, "type": "Feature"},
    {"geometry": {"coordinates": [[[180.0, 0.0], [180.0, 90.0], [90.0, 90.0], [90.0, 0.0], [180.0, 0.0]]], "type": "Polygon"}, "properties": {"col": 3, "row": 0, "zoom": 1}, "type": "Feature"},
    {"geometry": {"coordinates": [[[-90.0, -90.0], [-90.0, 0.0], [-180.0, 0.0], [-180.0, -90.0], [-90.0, -90.0]]], "type": "Polygon"}, "properties": {"col": 0, "row": 1, "zoom": 1}, "type": "Feature"},
    {"geometry": {"coordinates": [[[0.0, -90.0], [0.0, 0.0], [-90.0, 0.0], [-90.0, -90.0], [0.0, -90.0]]], "type": "Polygon"}, "properties": {"col": 1, "row": 1, "zoom": 1}, "type": "Feature"},
    {"geometry": {"coordinates": [[[90.0, -90.0], [90.0, 0.0], [0.0, 0.0], [0.0, -90.0], [90.0, -90.0]]], "type": "Polygon"}, "properties": {"col": 2, "row": 1, "zoom": 1}, "type": "Feature"},
    {"geometry": {"coordinates": [[[180.0, -90.0], [180.0, 0.0], [90.0, 0.0], [90.0, -90.0], [180.0, -90.0]]], "type": "Polygon"}, "properties": {"col": 3, "row": 1, "zoom": 1}, "type": "Feature"}
  ]
}

Print WKT representation of tile 4 15 23:

$ tmx bbox 4 15 23
POLYGON ((90 -90, 90 -78.75, 78.75 -78.75, 78.75 -90, 90 -90))

Also, tiles can have buffers around called pixelbuffer:

$ tmx --pixelbuffer 10 bbox 4 15 23
POLYGON ((90.439453125 -90, 90.439453125 -78.310546875, 78.310546875 -78.310546875, 78.310546875 -90, 90.439453125 -90))

Print GeoJSON representation of tile 4 15 23 on a mercator tile pyramid:

$ tmx -output_format GeoJSON -grid mercator bbox 4 15 15
{"type": "Polygon", "coordinates": [[[20037508.342789203, -20037508.3427892], [20037508.342789203, -17532819.799940553], [17532819.799940553, -17532819.799940553], [17532819.799940553, -20037508.3427892], [20037508.342789203, -20037508.3427892]]]}

Conda Publishing

Use bot pull requests generated with every release at tilematrix-feedstock repository for releasing new versions on conda-forge.

License

MIT License

Copyright (c) 2015-2022 EOX IT Services

tilematrix's Issues

make release 1.0

Addition/hobby project: add h3 hexagonal grids

Add hexagonal grids implementation, resources for start below

• https://towardsdatascience.com/uber-h3-for-data-analysis-with-python-1e54acdcc908
• https://uber.github.io/h3-py/intro.html

naming convention

update names such as pixelsize, resolution, etc.

e.g.:
from geopackage:

• matrix_width: Number of columns (>= 1) in tile matrix at this zoom level
• matrix_height: Number of rows (>= 1) in tile matrix at this zoom level
• tile_width: Tile width in pixels (>= 1)for this zoom level
• tile_height: Tile height in pixels (>= 1) for this zoom level
• pixel_x_size: In SRID units
• pixel_y_size: In SRID units

add CLI

Add a command line interface for following usecases:

tile:

• from tile index dump tile bbox as WKT or GeoJSON
• from point / xy coordinates dump tile bbox as WKT or GeoJSON
• from bounds dump tiles bboxes as WKT or GeoJSON

WKT output can be used in QGIS using the QuickWKT plugin, GeoJSON output can be dumped into a file and read by any GIS software.

add custom grids to documentation

rounding error causes snap_bounds() to fail

the following test fails at zoom 15:

def test_snap_bounds_edge_cases():
    # as zoom level increases, so increases the potential rounding errors
    tp = TilePyramid("geodetic")
    for zoom in range(18):
        snapped = snap_bounds(bounds=tp.bounds, tile_pyramid=tp, zoom=zoom)
        assert snapped == tp.bounds

at some point the check whether a given point hits the border between two tiles fails which subsequently causes the snap_bounds function to return a tile outside of the tile matrix

make buffers permanent

like BufferedTilePyramid in mapchete.tile

move documentation to readthedocs

try to get rid of heavy depdendencies

pixel_y_size should be negative value

bad intersection check on `tiles_from_geom()`

Tiles which intersect with a Polygon on its border get yielded although in fact they don't realy intersect (i.e. share a common area) with the geometry:

https://github.com/ungarj/tilematrix/blob/master/tilematrix/_tilepyramid.py#L229

use

if prepared_geometry.intersection(tile.bbox()).area

instead of

if prepared_geometry.intersects(tile.bbox()):

Note that we only are allowed to do this on "Polygon" and "MultiPolygon" geometries.

make objects iterable

iterating through TilePyramid yields TileMatrix which yields Tile objects

Mercartor Output, doesnt specify crs in GeoJSON file

How it is:

{
"type": "FeatureCollection",
"features": [
{"geometry": {"coordinates": [[[1066449.4186347763, 6271505.296742128], [1066449.4186347763, 6281289.2363626305], [1056665.4790142737, 6281289.2363626305], [1056665.4790142737, 6271505.296742128], [1066449.4186347763, 6271505.296742128]]], "type": "Polygon"}, "properties": {"col": 2156, "row": 1406, "zoom": 14}, "type": "Feature"},
...

How it should be:

{
"type": "FeatureCollection",
"crs": { "type": "name", "properties": { "name": "urn:ogc:def:crs:EPSG::3857" } },
"features": [
{"geometry": {"coordinates": [[[1066449.4186347763, 6271505.296742128], [1066449.4186347763, 6281289.2363626305], [1056665.4790142737, 6281289.2363626305], [1056665.4790142737, 6271505.296742128], [1066449.4186347763, 6271505.296742128]]], "type": "Polygon"}, "properties": {"col": 2156, "row": 1406, "zoom": 14}, "type": "Feature"},
...
I suspect, this might be an issue for the mapchete Geotiff Outputs, as well. Please double-check the writer driver if there is any.

Petr

add "srs" parameter to get tiles

for tiles_from_bounds(), tiles_from_bbox(), tiles_from_geom() functions

use NamedTuple for tile IDs

use tile_shape instead of tile_size

in order to support non-square tiles

tiles_from_geom() fails when providing a Point geometry

add __geo_interface__() to Tiles

https://gist.github.com/sgillies/2217756

python 3 support

enable geojson file output from TilePyramid, maybe add to CLI

E.G.:

import geojson
from tilematrix import GridDefinition, TilePyramid

mollweide_bounds = (-18041000.0, -9000000.0, 18041000.0, 9000000.0)

# import math
# print(math.gcd(int(mollweide_bounds[2]), int(mollweide_bounds[3])))

mollweide_10m_grid = GridDefinition(
    grid="custom", shape=(9000, 18041), is_global=True,
    bounds=mollweide_bounds,
    srs={'wkt': 'PROJCS["World_Mollweide",GEOGCS["GCS_WGS_1984",DATUM["WGS_1984",SPHEROID["WGS_1984",6378137,298.257223563]],PRIMEM["Greenwich",0],UNIT["Degree",0.017453292519943295]],PROJECTION["Mollweide"],PARAMETER["False_Easting",0],PARAMETER["False_Northing",0],PARAMETER["Central_Meridian",0],UNIT["Meter",1],AUTHORITY["EPSG","54009"]]'}
    )

# print(mollweide_10m_grid)

mollweide_10m_tmx = TilePyramid(grid=mollweide_10m_grid, tile_size=200, metatiling=16)

print(mollweide_10m_tmx)

print(f"pixel_x_size: {mollweide_10m_tmx.pixel_x_size(zoom=0)}")
print(f"pixel_y_size: {mollweide_10m_tmx.pixel_y_size(zoom=0)}")


mollweide_100m_tmx = TilePyramid(grid=mollweide_10m_grid, tile_size=20, metatiling=16)

print(mollweide_100m_tmx)


print(f"pixel_x_size: {mollweide_100m_tmx.pixel_x_size(zoom=0)}")
print(f"pixel_y_size: {mollweide_100m_tmx.pixel_y_size(zoom=0)}")


mollweide_1000m_tmx = TilePyramid(grid=mollweide_10m_grid, tile_size=2, metatiling=16)

print(mollweide_1000m_tmx)


print(f"pixel_x_size: {mollweide_1000m_tmx.pixel_x_size(zoom=0)}")
print(f"pixel_y_size: {mollweide_1000m_tmx.pixel_y_size(zoom=0)}")



with open("/mnt/data/mollweide100m.geojson", "w") as f:
    f.write("{\n" '"type": "FeatureCollection",')
    f.write("\n" '"crs": { "type": "name", "properties": { "name": "urn:ogc:def:crs:ESRI::54009" } },')
    f.write("\n" '"features": [')
    for tile in mollweide_100m_tmx.tiles_from_bounds(zoom=0, bounds=mollweide_bounds):
        gj = "    %s,\n" % geojson.Feature(
            geometry=tile.bbox(),
            properties=dict(zoom=tile.zoom, row=tile.row, col=tile.col),
        )
        f.write(gj)
    f.write("]\n" "}")

custom grids can cause non-squared pixels

non-square pixel sizes are not properly supported

include pytest & CI

• pytest
• travis
• coveralls

merge count_tiles() and tiles_from_geom() methods

also, maybe add len() methods?