pytileproj

A python package for working with projected tiling systems.

Projected tiling systems define a tiling scheme for multiple levels (tiling or zoom levels) in a certain projection. The whole concept can be disentangled into the following components:

• projection: In pytileproj, a projection is represented via a CRS definition (EPSG, PROJ4, WKT, ...) and a projection zone defining the validity of coordinates (optional).
• tiling: A tiling is put on top of the projection to subdivide space into smaller units a.k.a. tiles. Tilings can be either regular or irregular:
  • irregular: Tiles can have arbitrary shapes and the overall tiling does not need to cover a certain extent. The only restriction is that tiles are not allowed to intersect.
  • regular: Tiles need to have the same shape and the regular tiling needs to fill a certain extent (no holes). The regular tiling follows the OGC standard.
• tiling_system: Multiple tilings representing a hierarchy and covering the same extent are grouped into a tiling system.
• grid: Multiple tiling systems with the same tiling scheme but different projections are grouped into a grid. This allows to represent grid systems like the Equi7Grid.

How does geospade fit into the geospatial stack?

pytileproj heavily relies on morecantile and extends its capabilities into a more generic framework for representing geospatial datacubes. As long as compliance is possible, pytileproj follows OGC standards, but it is not limited to web map representations of tiling systems, e.g. a quadtree.

Installation

This package can be installed via pip:

pip install pytileproj

If you want to use pytileproj's visualisation features, then you can install the required optional dependencies with:

pip install pytileproj[vis]

If you want to export tile tables and shapefiles, then you need to install the geo extension:

pip install pytileproj[geo]

Contribute

We are happy if you want to contribute. Please raise an issue explaining what is missing or if you find a bug. We will also gladly accept pull requests against our master branch for new features or bug fixes.

Development setup

For development you can either use a conda/mamba or uv environment. After that you should be able to run uv run pytest to run the test suite.

uv (recommended)

Here is an example using only uv for creating the environment and managing dependencies.

First, install uv:

wget -qO- https://astral.sh/uv/install.sh | sh

Next, create your virtual environment, e.g.

uv venv --python 3.12

Finally, you can add all required and optional dependencies to it:

uv pip install -r pyproject.toml -e . --all-extras

mamba

Here is an example using mamba together with uv for managing dependencies.

First, install conda and set the path:

wget "https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-$(uname)-$(uname -m).sh" -O miniforge.sh
bash miniforge.sh -b -p $HOME/miniforge
export PATH="$HOME/miniforge/bin:$PATH"

Next, create a virtual environment:

conda create -n pytileproj python=3.12 mamba
source activate pytileproj
mamba install -c conda-forge uv

Finally, use uv to install all other dependencies and pytileproj itself, e.g.:

uv pip install -r pyproject.toml -e . --all-extras
uv pip install -e . --no-deps

Guidelines

If you want to contribute please follow these steps:

• fork the pytileproj repository to your account
• clone the repository
• make a new feature branch from the pytileproj master branch
• add your feature
• please include tests for your contributions in one of the test directories. We use pytest so a simple function called test_my_feature is enough
• submit a pull request to our master branch

Citation

If you use the software in a publication then please cite it using the Zenodo DOI. Be aware that this badge links to the latest package version.

Please select your specific version here to get the DOI of that version. You should normally always use the DOI for the specific version of your record in citations. This is to ensure that other researchers can access the exact research artefact you used for reproducibility.

You can find additional information regarding DOI versioning here.