/pyquadkey2

🌐 Python implementation of geographical tiling using QuadKeys

Primary LanguagePythonApache License 2.0Apache-2.0

🌍 pyquadkey2

Documentation

This is a feature-rich Python implementation of QuadKeys, an approach to geographical tiling, popularized by Microsoft to be used for Bing Maps.

In essence, the concept is to recursively divide the flat, two-dimensional world map into squares. Each square contains four squares as children, which again contain four squares and so on, up centimeter-level precision. Each of these squares is uniquely identifiable with a string like 021030032.

For more details on the concept, please refer to the original article.

muety/pyquadkey2 originates from a fork of buckhx/QuadKey, which is not maintained anymore. It builds on top of that project and adds:

  • ✅ Several (critical) bug fixes
  • ✅ Python 3 support
  • Type hints for all methods
  • ✅ Higher test coverage
  • ✅ Cython backend for improved performance
  • ✅ 64-bit integer representation of QuadKeys
  • ✅ Additional features and convenience methods

Installation

Requirements

This library requires Python 3.10 or higher. To compile it from source, Cython is required in addition.

Using Pip

$ pip install pyquadkey2

Pip installation is only tested for Linux and Mac, yet. If you encounter problems with the installation on Windows, please report them as a new issue.

From archive

$ wget https://github.com/muety/pyquadkey2/releases/download/0.3.1/pyquadkey2-0.3.1.tar.gz
$ pip install pyquadkey2-0.3.1.tar.gz

From source

Prerequisites (Linux)

  • gcc
    • Fedora: dnf install @development-tools
    • Ubuntu / Debian: apt install build-essential
  • python3-devel
    • Fedora: dnf install python3-devel
    • Ubuntu / Debian: apt install python3-dev
    • Others: See here

Prerequisites (Windows)

  • Visual C++ Build Tools 2015 (with Windows 10 SDK) (see here)

Build

# Check out repo
$ git clone https://github.com/muety/pyquadkey2

# Create and active virtual environment (optional)
$ python -m venv ./venv
$ source venv/bin/activate

# Install depencencies
$ pip install -r requirements.txt

# Compile
$ cd src/pyquadkey2/quadkey/tilesystem && python setup.py build_ext --inplace && cd ../../../..

# Install as module
$ pip install .

Developer Notes

Unit Tests

python tests/__init__.py

Release

See here.

pip install setuptools wheel auditwheel
python -m build
cd dist
auditwheel repair *.whl
twine upload --repository testpypi wheelhouse/* ../*.tar.gz

License

Apache 2.0

Buy me a coffee