GeoPakTile 2.1.0__tar.gz

geopaktile-2.1.0/LICENSE.md

@@ -0,0 +1,9 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Alex Webber
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

geopaktile-2.1.0/PKG-INFO

@@ -0,0 +1,121 @@
+Metadata-Version: 2.4
+Name: GeoPakTile
+Version: 2.1.0
+Summary: Create a Geopackage XYZ Tile layer.
+Keywords: GIS,Geopackage,Tiles,XYZ,gpkg
+Author: apwebber
+Author-email: apwebber <39490780+apwebber@users.noreply.github.com>
+License-Expression: MIT
+License-File: LICENSE.md
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: typing-extensions>=4.0 ; python_full_version < '3.11'
+Requires-Dist: morecantile>=6.2.0
+Requires-Dist: numpy>=2.2.6
+Requires-Dist: requests>=2.34.2
+Requires-Dist: pillow>=12.3.0
+Requires-Python: >=3.10
+Project-URL: Homepage, https://github.com/apwebber/GeoPakTile
+Project-URL: Documentation, https://github.com/apwebber/GeoPakTile
+Project-URL: Repository, https://github.com/apwebber/GeoPakTile.git
+Project-URL: Issues, https://github.com/apwebber/GeoPakTile/issues
+Description-Content-Type: text/markdown
+
+# GeoPakTile
+
+For writing geopackage XYZ raster tile layers, with support for using arbitrary grid systems, and for converting them to Cloud Optimized GeoTIFFs (COGs).
+
+Geopackage XYZ files can use any tile grid system, this is often defined by a server's GetCapabilities response where a TileMatrixSet defines the data co-ordinate system, the extent, the number of rows and columns in each zoom lever, and the corner co-ordinates for each zoom level. This package contains a tool for parsing the GetCapabilities XML into a [morecantile](https://github.com/developmentseed/morecantile) `TileMatrixSet`, and then for writing tiles to a new or existing geopackage.
+
+## Examples
+
+Write tiles to a new geopackage using web mercator (similar to mbtiles), where tiles is a list of (z, x, y, bytes). `tms` is a morecantile `TileMatrixSet` - the standard web mercator can be obtained with `morecantile.tms.get('WebMercatorQuad')`
+
+```python
+from geopaktile import GeoPakTile
+
+# Here, a list of tiles are read from a local path, the bytes and co-ordinates are stored as tuples in a list:
+# You might get these tiles from a tile server or anywhere else. Adjust accordingly.
+
+tiles = [
+    (z, x, y, path.read_bytes()),
+    (z2, x2, y2, path2.read_bytes()),
+    (z3, x3, y3, path3.read_bytes()),
+    ...
+]
+
+with GeoPakTile(test_gpkg, tms=morecantile.tms.get('WebMercatorQuad'), mode='rwc') as gpkg:
+    gpkg.add_tiles(tiles)
+```
+
+Open a geopackage in read only mode and see if it contains certain tiles. A TileMatrixSet isn't required for read-only mode.
+
+```python
+from geopaktile import GeoPakTile
+
+with GeoPakTile(test_gpkg, mode='ro') as gpkg:
+    assert gpkg.has_tile(z, x, y)
+    result = gpkg.has_tiles([(z, x, y), (z1, x1, y1)])
+```
+
+
+Parse a GetCapabilties xml to provide the TileMatrixSet for writing a geopackage:
+
+```python
+from geopaktile import parse_capabilities
+
+tms_set = parse_capabilities(xml)
+tms = tms_set[0] # you'll need to know which one you want, or use:
+
+tms = get_tile_matrix_set(xml, identifier = '1km') # an identifier that you know is defined in the xml
+```
+
+
+Convert a geopackage tile layer to a Cloud Optimized GeoTIFF. The highest zoom level becomes the full resolution image, and the lower zoom levels become the COG's overviews:
+
+```python
+from geopaktile import gpkg_tiles_to_cog
+
+gpkg_tiles_to_cog("tiles.gpkg", "tiles.tif")
+
+# Clip to a bounding box, given here in longitude/latitude
+gpkg_tiles_to_cog(
+    "tiles.gpkg",
+    "clipped.tif",
+    bbox=(-0.1, 51.45, 0.05, 51.52),
+    bbox_crs="EPSG:4326",
+)
+```
+
+### TileMatrixSet models
+
+Tile Matrix definitions use the [morecantile](https://github.com/developmentseed/morecantile) package (`morecantile.TileMatrixSet`, `TileMatrix`, etc.) so any morecantile TileMatrixSet (built-in or custom-loaded) can be passed to `GeoPakTile`. The XML parser returns morecantile `TileMatrixSet` objects.
+
+### XML Parser
+
+The xml parser has been tested on NASA GetCapabilties XML and some others, if you come across any that doesn't work then please raise an issue or fix and pull request.
+
+### Converting to COG
+
+`gpkg_tiles_to_cog` copies each zoom level's own pixels into the COG as an overview, rather than letting GDAL resample new overviews from the full resolution image, so every overview keeps the scale of the zoom level it came from. It works with any tile grid where each zoom level halves the pixel size of the one below, such as `WebMercatorQuad` and most grids from GetCapabilities documents.
+
+The output extent defaults to the tiles present at the highest zoom level, or can be set with `bbox` (in the layer's CRS, or in `bbox_crs` if given). The extent is expanded slightly so that it lines up with whole pixels at the zoom levels used as overviews.
+
+A zoom level can only be copied directly if its pixel grid lines up with the output extent. For small extents, the coarsest zoom levels often don't line up, and are left out by default. Pass `resample_unaligned=True` to include them by resampling them onto the extent, down to an overview 1 pixel across. A warning lists any zoom levels that were resampled. The method is set with `resampling` (`"bilinear"` by default; any [rasterio Resampling](https://rasterio.readthedocs.io/en/stable/api/rasterio.enums.html#rasterio.enums.Resampling) name such as `"nearest"` or `"average"` works).
+
+Other options:
+
+| Argument | Default | Description |
+| --- | --- | --- |
+| `table` | the only tile table | Tile table to convert, needed if the geopackage has more than one. |
+| `min_zoom`, `max_zoom` | all zoom levels with tiles | Zoom levels to include. `max_zoom` sets the full resolution. Without `resample_unaligned`, setting `min_zoom` expands the extent to line up with that zoom level's pixels, which can make the output much larger. |
+| `bands` | `"RGBA"` | `"RGBA"` makes missing tiles transparent. `"RGB"` makes them black, and is required for JPEG compression. |
+| `compress` | `"DEFLATE"` | Any GDAL COG compression, such as `"ZSTD"`, `"LZW"`, `"WEBP"` or `"JPEG"`. |
+| `blocksize` | the geopackage tile width | Internal tile size of the COG. |
+| `overwrite` | `False` | Replace an existing output file. |
+
+COG conversion requires [rasterio](https://rasterio.readthedocs.io/), which includes GDAL's COG driver in its wheels.

geopaktile-2.1.0/README.md

@@ -0,0 +1,94 @@
+# GeoPakTile
+
+For writing geopackage XYZ raster tile layers, with support for using arbitrary grid systems, and for converting them to Cloud Optimized GeoTIFFs (COGs).
+
+Geopackage XYZ files can use any tile grid system, this is often defined by a server's GetCapabilities response where a TileMatrixSet defines the data co-ordinate system, the extent, the number of rows and columns in each zoom lever, and the corner co-ordinates for each zoom level. This package contains a tool for parsing the GetCapabilities XML into a [morecantile](https://github.com/developmentseed/morecantile) `TileMatrixSet`, and then for writing tiles to a new or existing geopackage.
+
+## Examples
+
+Write tiles to a new geopackage using web mercator (similar to mbtiles), where tiles is a list of (z, x, y, bytes). `tms` is a morecantile `TileMatrixSet` - the standard web mercator can be obtained with `morecantile.tms.get('WebMercatorQuad')`
+
+```python
+from geopaktile import GeoPakTile
+
+# Here, a list of tiles are read from a local path, the bytes and co-ordinates are stored as tuples in a list:
+# You might get these tiles from a tile server or anywhere else. Adjust accordingly.
+
+tiles = [
+    (z, x, y, path.read_bytes()),
+    (z2, x2, y2, path2.read_bytes()),
+    (z3, x3, y3, path3.read_bytes()),
+    ...
+]
+
+with GeoPakTile(test_gpkg, tms=morecantile.tms.get('WebMercatorQuad'), mode='rwc') as gpkg:
+    gpkg.add_tiles(tiles)
+```
+
+Open a geopackage in read only mode and see if it contains certain tiles. A TileMatrixSet isn't required for read-only mode.
+
+```python
+from geopaktile import GeoPakTile
+
+with GeoPakTile(test_gpkg, mode='ro') as gpkg:
+    assert gpkg.has_tile(z, x, y)
+    result = gpkg.has_tiles([(z, x, y), (z1, x1, y1)])
+```
+
+
+Parse a GetCapabilties xml to provide the TileMatrixSet for writing a geopackage:
+
+```python
+from geopaktile import parse_capabilities
+
+tms_set = parse_capabilities(xml)
+tms = tms_set[0] # you'll need to know which one you want, or use:
+
+tms = get_tile_matrix_set(xml, identifier = '1km') # an identifier that you know is defined in the xml
+```
+
+
+Convert a geopackage tile layer to a Cloud Optimized GeoTIFF. The highest zoom level becomes the full resolution image, and the lower zoom levels become the COG's overviews:
+
+```python
+from geopaktile import gpkg_tiles_to_cog
+
+gpkg_tiles_to_cog("tiles.gpkg", "tiles.tif")
+
+# Clip to a bounding box, given here in longitude/latitude
+gpkg_tiles_to_cog(
+    "tiles.gpkg",
+    "clipped.tif",
+    bbox=(-0.1, 51.45, 0.05, 51.52),
+    bbox_crs="EPSG:4326",
+)
+```
+
+### TileMatrixSet models
+
+Tile Matrix definitions use the [morecantile](https://github.com/developmentseed/morecantile) package (`morecantile.TileMatrixSet`, `TileMatrix`, etc.) so any morecantile TileMatrixSet (built-in or custom-loaded) can be passed to `GeoPakTile`. The XML parser returns morecantile `TileMatrixSet` objects.
+
+### XML Parser
+
+The xml parser has been tested on NASA GetCapabilties XML and some others, if you come across any that doesn't work then please raise an issue or fix and pull request.
+
+### Converting to COG
+
+`gpkg_tiles_to_cog` copies each zoom level's own pixels into the COG as an overview, rather than letting GDAL resample new overviews from the full resolution image, so every overview keeps the scale of the zoom level it came from. It works with any tile grid where each zoom level halves the pixel size of the one below, such as `WebMercatorQuad` and most grids from GetCapabilities documents.
+
+The output extent defaults to the tiles present at the highest zoom level, or can be set with `bbox` (in the layer's CRS, or in `bbox_crs` if given). The extent is expanded slightly so that it lines up with whole pixels at the zoom levels used as overviews.
+
+A zoom level can only be copied directly if its pixel grid lines up with the output extent. For small extents, the coarsest zoom levels often don't line up, and are left out by default. Pass `resample_unaligned=True` to include them by resampling them onto the extent, down to an overview 1 pixel across. A warning lists any zoom levels that were resampled. The method is set with `resampling` (`"bilinear"` by default; any [rasterio Resampling](https://rasterio.readthedocs.io/en/stable/api/rasterio.enums.html#rasterio.enums.Resampling) name such as `"nearest"` or `"average"` works).
+
+Other options:
+
+| Argument | Default | Description |
+| --- | --- | --- |
+| `table` | the only tile table | Tile table to convert, needed if the geopackage has more than one. |
+| `min_zoom`, `max_zoom` | all zoom levels with tiles | Zoom levels to include. `max_zoom` sets the full resolution. Without `resample_unaligned`, setting `min_zoom` expands the extent to line up with that zoom level's pixels, which can make the output much larger. |
+| `bands` | `"RGBA"` | `"RGBA"` makes missing tiles transparent. `"RGB"` makes them black, and is required for JPEG compression. |
+| `compress` | `"DEFLATE"` | Any GDAL COG compression, such as `"ZSTD"`, `"LZW"`, `"WEBP"` or `"JPEG"`. |
+| `blocksize` | the geopackage tile width | Internal tile size of the COG. |
+| `overwrite` | `False` | Replace an existing output file. |
+
+COG conversion requires [rasterio](https://rasterio.readthedocs.io/), which includes GDAL's COG driver in its wheels.

geopaktile-2.1.0/pyproject.toml

@@ -0,0 +1,50 @@
+[project]
+name = "GeoPakTile"
+version = "2.1.0"
+description = "Create a Geopackage XYZ Tile layer."
+readme = "README.md"
+authors = [
+    { name = "apwebber", email = "39490780+apwebber@users.noreply.github.com" }
+]
+license = "MIT"
+license-files = ["LICENSE.md"]
+keywords = ["GIS", "Geopackage", "Tiles", "XYZ", "gpkg"]
+requires-python = ">=3.10"
+classifiers = [
+    "Development Status :: 4 - Beta",
+
+    # Specify the Python versions you support here.
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+]
+dependencies = [
+    "typing_extensions>=4.0; python_version < '3.11'",
+    "morecantile>=6.2.0",
+    "numpy>=2.2.6",
+    "requests>=2.34.2",
+    "pillow>=12.3.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/apwebber/GeoPakTile"
+Documentation = "https://github.com/apwebber/GeoPakTile"
+Repository = "https://github.com/apwebber/GeoPakTile.git"   
+Issues = "https://github.com/apwebber/GeoPakTile/issues"
+
+[project.scripts]
+geopaktile = "geopaktile:main"
+
+[build-system]
+requires = ["uv_build>=0.11.2,<0.12.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest",
+    "diskcache",
+    "rasterio",
+    "rio-cogeo>=6.0.0",
+]

geopaktile-2.1.0/src/geopaktile/__init__.py

@@ -0,0 +1,8 @@
+from geopaktile.geopaktile import GeoPakTile as GeoPakTile
+from geopaktile.gpkg_to_cog import gpkg_tiles_to_cog as gpkg_tiles_to_cog
+from geopaktile.xml_parser import get_tile_matrix_set as get_tile_matrix_set
+from geopaktile.xml_parser import parse_capabilities as parse_capabilities
+
+
+def main():
+    print("Command line usage has not been implemented.")

geopaktile-2.1.0/src/geopaktile/__main__.py

@@ -0,0 +1,4 @@
+from geopaktile import main
+
+if __name__ == "__main__":
+    main()